personal-health-records · diff
v1.0.0 to v1.0.0
1 added, 1 removed. Audit A to A.
---
name: personal-health-records
description: >
Connect your health records from any US health system via HealthEx, pull your
complete clinical history, analyze it with Claude, and optionally export to a
personal de-identified FHIR store with automated data quality curation via
HealthClaw Guardrails. Supports Epic, Cerner, CommonWell, Carequality, and
most major US EHR networks. Triggers when a user asks to connect health records,
pull medical history, review lab results, check immunizations, identify care
gaps, or export data to a personal FHIR store.
version: 1.0.0
- author: Eugene Vestel (fhiriq.com)
+ author: HealthClaw contributors
license: MIT
tools:
required:
- HealthEx:get_health_summary
- HealthEx:get_conditions
- HealthEx:get_labs
- HealthEx:get_immunizations
- HealthEx:get_medications
- HealthEx:get_allergies
- HealthEx:get_vitals
- HealthEx:get_procedures
- HealthEx:search
- HealthEx:update_and_check_recent_records
optional:
- healthclaw-local:fhir_seed
- healthclaw-local:fhir_read
- healthclaw-local:fhir_search
- healthclaw-local:fhir_get_token
- healthclaw-local:curatr_evaluate
- healthclaw-local:curatr_apply_fix
- healthclaw-local:fhir_commit_write
references:
healthex: https://healthex.io
healthclaw: https://github.com/aks129/HealthClawGuardrails
smart_health_connect: https://github.com/aks129/SmartHealthConnect
fhir_spec: https://hl7.org/fhir/R4
us_core: https://hl7.org/fhir/us/core
---
# Personal health records — HealthEx + HealthClaw
Connect your health records from any US health system, pull your complete clinical history, analyze it with Claude, and optionally store it in a personal FHIR data store with data quality curation.
**Standards:** All resources use **FHIR R4** with **US Core v6.1** profiles — the production standard used by US health systems. The `/r6/fhir` URL path in HealthClaw is a legacy route prefix from the project's experimental R6 ballot resource support; the actual clinical data (Conditions, Observations, Immunizations, etc.) is R4 and validated against US Core required fields.
---
## Setup (do this once)
### 1. Connect HealthEx in Claude.ai
1. Go to **claude.ai → Settings → Integrations**
2. Find **HealthEx** and click **Connect**
3. Authorize with your HealthEx account (create one free at healthex.io if needed)
4. In HealthEx, connect your health systems: Epic, Cerner, CommonWell, Carequality, and most major US health networks are supported
5. Return to Claude — the HealthEx tools are now active in this session
To verify: ask Claude *"Check when my health records were last updated"* — it will call `HealthEx:update_and_check_recent_records` and confirm your connection.
### 2. Optional: Connect HealthClaw for local FHIR store
If you want to store, curate, and own a local de-identified copy of your records:
```bash
# Clone the HealthClaw Guardrails repo
git clone https://github.com/aks129/HealthClawGuardrails
cd HealthClawGuardrails
# Start the local stack (Flask guardrail proxy + MCP server + Redis)
cp .env.example .env # edit with your STEP_UP_SECRET and ANTHROPIC_API_KEY
docker-compose up -d --build
# Confirm healthy
curl http://localhost:5000/r6/fhir/health
```
Add to `.mcp.json` in the repo root so Claude Code picks it up:
```json
{
"mcpServers": {
"healthclaw-local": {
"type": "http",
"url": "http://localhost:3001/mcp",
"headers": { "X-Tenant-ID": "my-health" }
}
}
}
```
---
## Zero-setup demo (no install required)
A public Railway instance is pre-seeded with sample clinical data so you can try the full guardrail stack — MCP tools, curatr data quality, PHI redaction, step-up auth — without cloning anything.
### Claude Desktop
Add this to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"healthclaw-demo": {
"type": "streamable-http",
"url": "https://healthclaw.up.railway.app/mcp",
"headers": { "X-Tenant-ID": "desktop-demo" }
}
}
}
```
Restart Claude Desktop, then try:
```
Use the healthclaw-demo tools. Get a step-up token, then search for all
Patients in the store. Read the Condition and Observations for the patient.
Run curatr_evaluate on the Condition — it has an ICD-9 code that should be flagged.
```
### Claude Code
Add to `.mcp.json` in any project directory:
```json
{
"mcpServers": {
"healthclaw-demo": {
"type": "http",
"url": "https://healthclaw.up.railway.app/mcp",
"headers": { "X-Tenant-ID": "desktop-demo" }
}
}
}
```
### What's in the demo tenant
The `desktop-demo` tenant is auto-seeded on first deploy with:
| Resource | Details |
|---|---|
| Patient | Maria Elena Rivera, DOB 1985-03-15, Boston MA |
| Condition | Diabetes mellitus — **ICD-9 code 250.00** (intentionally deprecated, triggers curatr flag) |
| Observation | Glucose 180 mg/dL, HbA1c 8.1%, BP 138/88 mmHg |
| MedicationRequest | Metformin 500 MG Oral Tablet (RxNorm 860975) |
The ICD-9 code is intentional — it demonstrates the curatr `icd9-deprecated` detection pattern. Ask Claude to evaluate it and propose a fix to ICD-10-CM E11.9.
### Re-seed anytime
The seed endpoint is idempotent and additive:
```bash
# HTTP — call the running server
curl -X POST https://healthclaw.up.railway.app/r6/fhir/internal/seed \
-H "Content-Type: application/json" \
-d '{"tenant_id": "desktop-demo"}'
# Or via MCP tool
fhir_seed(tenant_id="desktop-demo")
```
### Direct API access (no MCP)
The REST API works without MCP too:
```bash
BASE=https://healthclaw.up.railway.app/r6/fhir
# Health check
curl $BASE/health
# Search patients
curl "$BASE/Patient?_count=10" -H "X-Tenant-Id: desktop-demo"
# Read a specific resource
curl "$BASE/Condition/<id>" -H "X-Tenant-Id: desktop-demo"
```
---
## How to pull your health data
### Quick summary (start here)
Ask Claude:
```
Get my health summary
```
Claude calls `HealthEx:get_health_summary` — returns your active conditions, recent labs,
current medications, allergies, immunizations, and clinical visits in one shot.
Use this as a fast overview before pulling specific categories.
---
### Pulling specific categories
Each category tool paginates backwards through time. Claude handles pagination
automatically — you just specify how many years of history you want.
**Standard pulls (ask Claude these directly):**
```
Get all my conditions from the last 10 years
Get all my lab results since 2014
Get my complete immunization history
Get my medications from the last 5 years
Get all my allergies on record
Get my vital signs from the last 3 years
Get my procedures and surgeries
```
**For Claude Code — explicit pagination pattern:**
When pulling a full history, Claude must paginate until no more data is available.
The response includes a `beforeDate` hint when more pages exist. Claude must keep
calling until pagination stops:
```
Pull my complete condition history going back 15 years. Use get_conditions with
years=12, then check the pagination info in the response — if it says more data
is available, call again with the beforeDate from the response and years set to
cover the remaining range. Keep paginating until all data is retrieved.
```
---
### Full export (all categories, all history)
This pulls everything in one session — conditions, labs, immunizations, allergies,
vitals, medications, procedures — with full pagination across all categories.
```
Pull my complete health history across all categories going back 15 years.
For each category, paginate fully until all data is retrieved.
Summarize what was found: count of records per category, date range covered,
any data gaps or missing values you notice.
```
Expected output: a structured summary of everything in your record across
all connected health systems, with counts by category and date range.
---
## Analysis workflows
### Care gaps and preventive screening
```
Based on my health records, identify any preventive care I may be overdue for.
Consider my age, gender, conditions, and immunization history.
Reference USPSTF guidelines for screening recommendations.
```
Claude checks your records against standard preventive care schedules:
- Colorectal cancer screening (colonoscopy, Cologuard) — USPSTF: age 45+
- Annual flu vaccine — last shot date vs current season
- COVID boosters — series completion and recency
- Lipid panel, HbA1c, blood pressure — based on age/risk factors
- Cancer screenings — mammogram, PSA, skin exam based on demographics
---
### Lab trend analysis
```
Pull my lab results for the last 5 years and identify any values that
have been trending in a concerning direction, even if still within
normal range. Flag anything that has been consistently at the edge
of the reference range.
```
```
Compare my most recent labs to my results from 2 years ago.
What has changed? What looks better, what looks worse?
```
---
### Medication review
```
Review my medication history for the last 5 years.
Identify: any medications that were started then stopped (and why if documented),
any dosage changes over time, and any gaps in chronic medication coverage.
```
---
### Condition timeline
```
Build a chronological timeline of my medical conditions from first
documented to present. For each active condition, note how long I've
had it and whether there is documented treatment.
```
---
### Cross-system reconciliation
When you have records from multiple health systems (e.g., AHN + UPMC),
discrepancies are common. Claude can find them:
```
I have records from multiple health systems. Look for any contradictions
or inconsistencies across my records — same test with different results,
conflicting diagnoses, or the same information recorded differently.
Flag anything that needs reconciliation.
```
---
### Pre-appointment preparation
```
I have an appointment with [specialist type] on [date] for [reason].
Pull my relevant health history and prepare a summary I can bring.
Include: relevant conditions, current medications, recent labs, and
any questions I should ask based on gaps in my record.
```
---
### Second opinion research
```
I was diagnosed with [condition]. Pull everything in my record related
to this diagnosis — symptoms, test results, treatments tried — and
summarize the clinical picture. What does my record show about
how this was worked up?
```
---
## Export to personal FHIR store (HealthClaw pipeline)
If you want to store your data locally with de-identification and quality curation:
### Option A — Automated export (one command)
Requires the HealthClaw repo cloned and running (see Setup above):
```bash
# Get your HealthEx auth token from:
# Claude.ai → Settings → Integrations → HealthEx → copy OAuth Bearer token
HEALTHEX_AUTH_TOKEN=<your_token> python scripts/export_healthex_mcp.py \
--patient-id my-health-id \
--tenant-id my-health \
--years 15 \
--import \
--step-up-secret $STEP_UP_SECRET
```
This runs the full pipeline:
1. Pulls all HealthEx categories with pagination
2. Maps to US Core R4 FHIR resources
3. Removes PHI (name, address, phone) while preserving clinical data and dates
4. Pre-tags data quality issues for curatr review
5. POSTs the bundle to your local HAPI store through the guardrail proxy
6. Creates a context envelope with SHA-256 provenance hashes
### Option B — Claude-assisted export (no auth token needed)
Ask Claude to build the bundle from the live session pull:
```
Pull all my health data across all categories, fully paginated.
Then build a FHIR R4 transaction bundle with de-identified US Core resources.
Remove my name, address, and phone but keep my date of birth, gender,
and all clinical codes (SNOMED, ICD-10, LOINC, CVX).
Pre-tag any data quality issues you find with curatr meta annotations.
Write the bundle to healthclaw-bundle-[today's date].json.
```
Then import it:
```bash
python scripts/import_healthex.py \
--bundle-file healthclaw-bundle-<date>.json \
--tenant-id my-health \
--step-up-secret $STEP_UP_SECRET
```
### After import — curatr data quality review
In Claude Code with the local stack running:
```
Search my FHIR store for resources tagged with curatr flags.
For each flagged resource, explain the issue in plain language
and propose a fix. Wait for my confirmation before applying any fix.
```
Claude will:
1. Call `curatr_evaluate` on flagged resources
2. Present each issue with plain-language explanation
3. Propose the exact field change needed
4. Apply approved fixes with `curatr_apply_fix`
5. Create a Provenance record for each fix recording your stated intent
6. Generate an immutable AuditEvent trail of all changes
---
## Common data quality issues Claude will find
When pulling from US health systems, these patterns appear frequently:
| Issue | Severity | Example |
|---|---|---|
| Smoking history contradiction | High | AHN says Never, UPMC says Former — same LOINC code, different encounters |
| Antibody titer flagged H | Medium | Hep B S Ab 59.38 mIU/mL flagged High — this is immune protection, not pathology |
| Missing lab result | Low | Test ordered, no result value in imported record — incomplete C-CDA parse |
| ICD-9 code still present | Critical | Condition coded 250.00 (ICD-9) instead of E11.9 (ICD-10) — retired Oct 2015 |
| Active condition, no treatment | Medium | Psoriasis active since 2017, no MedicationRequest or Procedure linked |
| Duplicate immunizations | Low | Same CVX code, same date, from two different health system imports |
Claude detects all of these automatically during export and presents them for your review.
---
## Telehealth and Telegram access (openclaw bot)
If you want to access your health data on mobile via Telegram:
```bash
# Add bot token to .env
TELEGRAM_BOT_TOKEN=<get from @BotFather>
# Start the openclaw service
docker-compose --profile openclaw up -d openclaw
```
Bot commands:
- `/health` — health summary
- `/conditions` — active conditions list
- `/labs` — most recent lab per test
- `/curatr` — list pending data quality issues
- `/curatr fix <issue>` — start a fix with patient attestation
- `/approve` — confirm pending write (step-up authorization)
The Telegram bot reads from and writes to the same local FHIR store as Claude Code.
Every `/approve` creates the same Provenance record as a Claude Code curatr fix.
---
## What HealthEx covers
HealthEx connects to the US health data exchange networks (CommonWell, Carequality, eHealth Exchange) and pulls from any participating EHR system including:
- Epic (most major academic medical centers and health systems)
- Cerner/Oracle Health
- MEDITECH
- athenahealth
- AllScripts
- Most major US payers (via USCDI claims data)
Not yet covered: dental records, mental health records from standalone behavioral health systems, records from health systems that have not joined national exchange networks.
---
## Privacy and data ownership
- HealthEx reads your records read-only via SMART on FHIR — it cannot modify records in your EHR
- The HealthClaw local store runs on your machine — your data never leaves your network unless you configure an external upstream
- PHI fields (name, address, phone, facility MRN) are removed before storage
- All reads and writes are logged in an immutable AuditEvent trail
- You control every curatr fix — nothing is applied without explicit confirmation
- Delete your tenant data at any time: `DELETE /r6/fhir/tenant/my-health`
---
## Troubleshooting
**HealthEx tools not available**
- Go to Claude.ai Settings → Integrations → confirm HealthEx shows Connected
- If it shows an error, click Reconnect and re-authorize
**Records seem incomplete**
- Call `HealthEx:update_and_check_recent_records` — it returns a URL to trigger a fresh sync
- Health systems batch-sync on different schedules; allow 24 hours after connecting
**HealthClaw read tools return 400**
- Confirm local stack is running: `curl http://localhost:5000/r6/fhir/health`
- Confirm `.mcp.json` has `X-Tenant-ID` header set
- Confirm Claude Code is opened from the repo root so `.mcp.json` is loaded
**Import fails with step-up error**
- Token TTL is 5 minutes — run `fhir_get_token` immediately before `import_healthex.py`
- Confirm `STEP_UP_SECRET` in `.env` matches what the Flask server is using
---
## Reference — HealthEx tool quick reference
| Tool | Use when | Key params |
|---|---|---|
| `get_health_summary` | First call, overview | none |
| `get_conditions` | Diagnoses, medical history | `years`, `beforeDate` |
| `get_labs` | Test results, bloodwork | `years`, `beforeDate` |
| `get_immunizations` | Vaccination history | `years`, `beforeDate` |
| `get_medications` | Prescriptions, dosages | `years`, `beforeDate` |
| `get_allergies` | Drug/food/env allergies | `years`, `beforeDate` |
| `get_vitals` | BP, weight, BMI, HR | `years`, `beforeDate`, `vitals[]` |
| `get_procedures` | Surgeries, imaging, scopes | `years`, `beforeDate` |
| `search` | Cross-category keyword lookup | `query`, `limit` |
| `update_and_check_recent_records` | Check sync status | none |
All paginated tools return a `beforeDate` hint in their response when more data exists.
Always paginate to completion before concluding a category is fully retrieved.