MedSift: Health AI Assistant for Individuals and Families

English

MedSift is a personal and family health assistant.

Its core role is not to replace doctors, nor to serve as an internal hospital system, but to solve the last mile between everyday health management at home and actual entry into the hospital care process.

Many users know that something feels wrong for themselves or their family members, but still do not know:

• what should be recorded first
• whether they should go to the hospital soon
• what symptoms, medications, and test information should be organized before a visit
• how to clearly explain scattered health information

MedSift is designed for exactly that middle stage, from noticing a problem at home to preparing for medical care. It helps individuals and families organize information through natural conversation, continuously track household health risks, and make pre-visit and post-visit management more connected.

It does not replace medical diagnosis. Instead, it helps users prepare better before a visit, communicate more clearly during care, and continue family health management afterward.

MedSift also doubles as a healthcare data-science workbench: it ships with clinical text mining, interpretable risk modelling, data-quality normalization, and anomaly detection that run directly over the structured family archive (see Data Science & ML).

What MedSift Can Do Today

• Organizing family medical records, symptoms, medications, and reports
• Guiding pre-visit triage before a hospital visit
• Tracking blood pressure, glucose, and other time-series health metrics
• Running household risk scans and medication-related checks
• Generating diet and daily routine guidance based on existing records
• Scheduling reminders for medication, follow-up, and recurring health tasks
• Extracting structured clinical entities, scoring interpretable risk, and flagging anomalies from the archive

Key Characteristics

• For individuals and families: built around household use, not hospital-side workflow systems
• Collects information during conversation: everyday conversation with the agent can naturally become structured health information capture
• Bridges the care gap: supports the stage from "I feel unwell" to "I am ready to seek care"
• Privacy-first and local-first: sensitive health data stays local by default
• Skill-driven: medical, health, record, data-science, and automation skills can be extended with custom SKILL.md
• Multi-channel and multi-model: supports chat channels and multiple LLM providers

Core Architecture

MedSift is designed as a closed-loop personal and family health system built around four core ideas:

• Built-in medical skills: the system starts with ready-to-use skills for pre-visit triage, reminders, risk monitoring, report ingestion, record export, and health metric tracking
• Skill extension and self-update: MedSift can discover, load, install, and maintain new skills so capabilities can evolve with real household needs
• Skill safety checks: skills are not only loaded, but also filtered through metadata, requirement checks, and privacy-oriented execution rules
• Structured family archive: all long-term household health information is organized as structured family records instead of scattered chat messages

This makes MedSift more than a chatbot. It becomes a looped health workflow:

• daily interaction updates the family archive
• archive data activates relevant skills and reminders
• skills help prepare before a hospital visit
• hospital outcomes are written back into the archive
• the updated archive drives future monitoring and support

Closed-Loop System

flowchart TD
    A[Daily family health conversations] --> B[MedSift orchestration and routing]
    B --> C[Automatically update the structured family health archive]
    B --> D[Call the extensible skill library with safety checks]
    C --> D
    D --> F[Pre-visit preparation with record export and triage]
    F --> G[In-person care and diagnostic reports]
    G --> H[Automatically update family records after the visit]
    H --> C
    C --> I[Ongoing family health monitoring and support]
    I --> A

Loading

Built-in Skills

Category	Skill	Purpose
Medical	medclaw-pretriage	Pre-hospital and pre-visit triage guidance
Medical	medication-reminder	Medication reminders with record sync
Medical	risk-monitoring	Daily household health risk scan (rule-based + optional ML mode)
Medical	drug-interaction-check	Medication interaction checks using the DDInter database
Medical	medical-record-export	Medical record export
Medical	medical-report-ingest	Medical report ingestion and summarization
Health	diet-routine-guidance	Diet, sleep, and routine guidance
Health	health-metrics	Time-series health metrics and trend charts
Data Science	clinical-entity-extraction	Clinical NER and concept tagging over medical text
Data Science	data-quality-normalizer	Entity resolution, unit/ontology normalization, validation
Data Science	metric-anomaly-detection	Statistical + IsolationForest anomaly flags on vitals
Data Science	model-explainability	Plain-language SHAP explanations for risk predictions
Data Science	weak-supervision-labeler	Programmatic training-label generation from labeling functions
Data Science	archive-search	BM25 + dense hybrid search over the family archive
Data Science	experiment-eval	Model metrics, calibration, A/B testing, significance tests
Records	memory	Long-term memory plus structured family archive
Records	family-medical-record	Structured records for household members
Tools	cron	Scheduled tasks and reminders
Tools	skill-finder / clawhub	Skill discovery and installation
Other	weather, github, tmux, summarize	Supporting utility skills

See each skill folder's SKILL.md for behavior and scope. Privacy and data minimization rules are defined in medsift/templates/AGENTS.md.

Data Science & ML

MedSift includes a self-contained ML library at medsift/ml/ that operates on the local family archive (family/<member_id>/record.md, symptoms.md, medications.md, metrics/*.jsonl, reports/). All processing stays local, consistent with the privacy rules.

Module	Purpose
medsift/ml/features.py	Feature engineering from records + metric time series
medsift/ml/synth.py	Synthetic cohort generator (clearly labeled) for training/demos
medsift/ml/models.py	Interpretable risk model: logistic baseline → gradient boosting, cross-validation, calibration
medsift/ml/explain.py	SHAP / coefficient explanations rendered as plain language
medsift/ml/anomaly.py	Robust z-score / IQR / EWMA + IsolationForest on vitals
medsift/ml/quality.py	Fuzzy entity resolution, unit/date normalization, validation with audit trail
medsift/ml/textmining.py	Clinical entity extraction (spaCy/scispaCy with regex fallback)
medsift/ml/evaluation.py	Metrics, calibration, bootstrap CIs, McNemar's test, A/B testing
medsift/ml/search.py	BM25 lexical search + optional dense vectors

Heavy libraries are optional. Install the data-science extra to enable them:

pip install -e ".[datascience]"

The DS skills degrade gracefully: if an optional library is missing, the skill reports the missing dependency instead of failing.

Example Conversation

You: Hi, I'm alex. What's your name?

🩺 medsift
Hello, alex! I'm MedSift, your health assistant. What can I help you with?

You: When I woke up this morning, I found that my nose was blocked and I felt a little dizzy. I took some cold-relief granules.

🩺 medsift
I have recorded the symptoms you had this morning, including a blocked nose and dizziness, as well as the cold-relief granules you took.
If you have any other symptoms or need further advice, please let me know!

You: My father has hypertension and is taking captopril. Can he take ibuprofen now?

🩺 medsift
There is a moderate interaction between the captopril your father is taking and ibuprofen. Ibuprofen may reduce the blood-pressure-
lowering effect of captopril and may also cause fluid retention, which can affect blood pressure. In addition, long-term use of ibuprofen
may have adverse effects on kidney function.

If he needs to use ibuprofen, it is recommended to closely monitor his blood pressure and kidney function during use. It is best to do
this under a doctor's guidance.

You: I want to take my father to the hospital. Please help me export his medical record.

🩺 medsift
I have successfully exported your father's medical record. You can find the file at the following path:
.medsift/workspace/family/father/doctor_export_20260318.md

Local Deployment and Quick Start

git clone <your-repository-url> medsift
cd medsift
pip install -e .
# optional: enable the data-science skills
pip install -e ".[datascience]"
medsift onboard
medsift agent

Edit ~/.medsift/config.json to at least configure:

• providers for your API keys
• agents.defaults.model for the model you want to use
• channels if you want Telegram, Feishu, QQ, Email, or other integrations

Start the gateway when you want channel integrations:

medsift gateway

Config and Paths

• Config file: ~/.medsift/config.json
• Workspace: ~/.medsift/workspace by default
• Environment variable prefix: MEDSIFT_

Use --config when running multiple isolated instances.

Common CLI Commands

Command	Description
medsift onboard	Initialize config and workspace
medsift agent	Start local chat
medsift gateway	Start the multi-channel gateway
medsift status	Show current status
medsift channels login	Link supported channels such as WhatsApp

Docker

docker build -t medsift .
docker run -v ~/.medsift:/root/.medsift --rm medsift onboard
docker run -v ~/.medsift:/root/.medsift -p 18790:18790 medsift gateway

You can also use the included docker-compose.yml.

Project Structure

medsift/
├── agent/       # loop, context, memory, skills, tools
├── ml/          # data-science library (features, models, explain, anomaly, quality, textmining, evaluation, search)
├── skills/      # built-in medical, health, data-science, and utility skills
├── channels/    # chat integrations
├── providers/   # LLM providers
├── config/      # config and path helpers
├── cron/        # scheduled tasks
├── heartbeat/   # recurring tasks
└── cli/         # CLI commands

Documentation

• SECURITY.md
• docs/DATA_SCIENCE.md
• docs/CHANNEL_PLUGIN_GUIDE.md

TODO

• Voice interaction support
• Automatic speaker identification
• Recommend suitable care settings based on symptoms and preliminary triage

MedSift is intended for education, research, and technical exchange. It is a health support assistant, not a replacement for professional diagnosis or treatment.