health-memex

Personal health data archive: consolidate medical records from multiple EHR systems into a single queryable SQLite database. Part of the *-memex ecosystem.

Query, analyze, and export your aggregated clinical data via CLI, MCP server (for LLM-assisted analysis), or self-contained HTML SPA.

Features

• Multi-EHR data consolidation: Import from Epic MyChart, MEDITECH Expanse, and athenahealth
• SQLite database: 17 clinical tables with full audit trail
• MCP server: 31 tools for LLM-assisted analysis with Claude
• Export formats: Self-contained HTML SPA, Arkiv (JSONL + README.md + schema.yaml)
• AI chat: Ask questions about your record in the HTML SPA via Claude, with inline charts (optional, requires proxy)
• Visit prep: See what's new since your last visit, directly in the SPA
• Print summary: One-page printable view for your doctor
• Personal notes: Tag and annotate any clinical record

Installation

pip install health-memex

# With MCP server support (for Claude integration)
pip install "health-memex[mcp]"

Development Setup

git clone https://github.com/queelius/health-memex.git
cd health-memex
pip install -e ".[dev,mcp]"

Quick Start

Load Data from EHR Exports

# Load from individual sources
health-memex load epic ~/exports/epic/
health-memex load meditech ~/exports/meditech/
health-memex load athena ~/exports/athena/

# Or load all at once
health-memex load all \
  --epic-dir ~/exports/epic/ \
  --meditech-dir ~/exports/meditech/ \
  --athena-dir ~/exports/athena/

Query and Inspect

# View database summary
health-memex summary

# Run SQL queries
health-memex query "SELECT test_name, value, result_date FROM lab_results ORDER BY result_date DESC LIMIT 10"

# What's new since your last visit
health-memex diff 2025-01-01

Export Your Data

# Self-contained HTML SPA with embedded SQLite (all data stays client-side)
health-memex export html --output summary.html
health-memex export html --output summary.html --embed-images --config health_memex.toml
health-memex export html --output summary.html --ai-chat --proxy-url https://proxy.example.com/v1/messages

# Arkiv universal record format (primary backup/restore, round-trip capable)
health-memex export arkiv --output ./arkiv/
health-memex export arkiv --output ./arkiv/ --embed

# Import from arkiv archive
health-memex import ./arkiv/ --db new.db
health-memex import ./arkiv/ --validate-only

MCP Server

# Start MCP server (matches ecosystem pattern: memex mcp, btk mcp)
health-memex mcp --db health_memex.db

Claude Code Configuration

{
  "mcpServers": {
    "health-memex": {
      "command": "python",
      "args": ["-m", "health_memex", "mcp", "--db", "/path/to/health_memex.db"]
    }
  }
}

Personal Notes

health-memex notes list --limit 20
health-memex notes search --tag oncology --query "CEA"

Supported EHR Sources

Database Schema

17 clinical tables, all dates ISO YYYY-MM-DD, every record carries a source field:

Configuration

health-memex init-config

Generates health_memex.toml with lab tests to chart based on what's in your database.

Upgrading from 2.x

3.0 changes two things you may notice:

• Arkiv exports from 2.x cannot be imported. Record URIs now use a durable content-hash unique_id instead of autoincrement row ids, so references survive database rebuilds. Your existing database is upgraded in place the first time 3.0 opens it; after that, run health-memex export arkiv again to replace any 2.x backup bundles.
• The default database moved from ./health_memex.db (relative to the current directory) to ~/.local/share/health-memex/health_memex.db (or $XDG_DATA_HOME/health-memex/), for the CLI and the MCP server alike. Set HEALTH_MEMEX_DB or pass --db to keep using an existing file.

Requirements

• Python 3.11+
• Dependencies: lxml, pyyaml
• Optional: mcp (FastMCP) for MCP server

Handling PHI responsibly

health-memex is a personal archive. The SQLite database, the arkiv bundle (records.jsonl plus README.md, schema.yaml, and media/), and the HTML SPA all contain Protected Health Information (PHI) in plaintext. Treat every exported artifact like a password file.

Minimum precautions:

• Keep the primary database on an encrypted volume (FileVault, LUKS, BitLocker, or similar).
• When sharing an arkiv bundle or an HTML SPA, wrap it in a password-protected .zip or GPG-encrypt it. health-memex export does not encrypt. That is the operator's responsibility.
• Never email a raw export, upload it to a generic file-sharing site, publish it on a public web server, or paste its contents into an arbitrary chat service.
• If you enable the --ai-chat feature in the SPA, remember that the chat routes your questions (which may quote lab values, diagnoses, and medication lists) through whatever proxy URL you configured. Use a proxy you control.
• When you no longer need an export, shred or secure-delete it rather than dropping it in the trash.

health-memex prints a PHI reminder to stderr after every export. The reminder is deliberate; please do not suppress it in scripts unless you know the destination path is already protected.

License

MIT