Collect. Connect. Communicate.
Taking Back Ownership of Your Health Records

The Problem

If you see three doctors — a primary care physician, a specialist, and a hospital system for an acute event — you have three separate medical records, in three separate portals, that have never spoken to each other. You can download each one as a FHIR bundle. But a raw FHIR export is a 20MB JSON file with thousands of resources, duplicates across every provider, conflicting values where one system says a medication is active and another says it was stopped at discharge.

The patient portal experience is designed for human browsing, not data ownership. There is no way to ask all three records simultaneously: What conditions am I being treated for? What is my HbA1c trend? Are there gaps between my diagnoses and my current medications?

This is not a data availability problem. Thanks to the 21st Century Cures Act, covered healthcare providers must make your records available in FHIR format on request. The data exists. The problem is that it is fragmented, dirty, and locked in a format designed for data exchange between institutions — not for personal use or AI-powered reasoning.

Collect. Connect. Communicate.

The Cascade Protocol approaches personal health data ownership as three distinct problems that must be solved in sequence.

Each step has a corresponding tool. Collect is a manual step you do once per provider: download your data export from the patient portal. Connect is handled by the cascade CLI: convert each FHIR bundle to RDF/Turtle, then reconcile across sources to detect and resolve duplicates and conflicts. Communicate is where the magic happens: a natural language agent that queries your pod and synthesizes answers across your entire health history.

The end product is what we call a Cascade Pod — a local, encrypted, portable knowledge graph of your health. It lives on your device. No data leaves your machine unless you explicitly export or share it. The AI agent that queries it runs locally too.

Why a CLI?

A few months ago, I wrote about how AI agents are driving a resurgence of the command line. The thesis: GUIs are designed for humans to click through; CLIs are designed for composition and automation. When you add an AI agent to the picture, the CLI becomes the shared interface between human and agent. The same cascade convert command you run in your terminal is callable by an agent with zero additional integration work.

This is not an accident. The Cascade CLI was designed from the start as an agent-callable interface. Every command produces structured output. Every flag has a clear semantic. The reconciler emits a machine-readable JSON report. The pod stores data in a graph format that any agent can traverse. You can wire the entire pipeline into an agentic workflow with a few lines of shell script, and that workflow is exactly as powerful as the one you would run manually.

Consider the alternative: a GUI health app that ingests your FHIR data and presents it in a dashboard. You can view it. You can scroll through it. But you cannot programmatically query across it. You cannot feed it to an AI agent. You cannot export it in a format that another tool can understand. The data is useful only within the walls of that application.

We are at the beginning of an era where agents will actively manage our digital lives. Scheduling appointments, tracking treatment adherence, flagging when a new medication conflicts with a known allergy, preparing summaries for specialist visits. Every one of these tasks requires structured, queryable, portable health data — not a locked dashboard. The CLI is the interface that makes this possible today, while the broader agent ecosystem catches up.

Walking Through the Demo

Let's make this concrete. The following is a real walkthrough using the Cascade CLI and a synthetic patient: Rogelio, a 64-year-old with Type 2 Diabetes, Hypertension, Diabetic Neuropathy, and Chronic Kidney Disease. He has FHIR exports from three providers: his primary care doctor, his endocrinologist, and a recent hospital discharge. Each export covers his full history with substantial overlap — and realistic conflicts.

$ ls -lh *.json
-rw-r--r-- 1 jed  36M  primary-care.json
-rw-r--r-- 1 jed  36M  endocrinology.json
-rw-r--r-- 1 jed  36M  hospital-discharge.json

$ python3 -c "import json; d=json.load(open('primary-care.json')); print(len(d['entry']), 'resources')"
13662 resources

$ for f in primary-care endocrinology hospital-discharge; do
    cascade convert $f.json --from fhir --to cascade \
      --source-system $f --passthrough minimal > $f.ttl
  done

Converted 12901 resources (fhir -> turtle)  [primary-care]
Converted 12901 resources (fhir -> turtle)  [endocrinology]
Converted 12901 resources (fhir -> turtle)  [hospital-discharge]

$ wc -l *.ttl
   85234 primary-care.ttl
   85234 endocrinology.ttl
   85234 hospital-discharge.ttl

$ cascade reconcile primary-care.ttl endocrinology.ttl hospital-discharge.ttl \
    --output merged.ttl \
    --report report.json \
    --trust hospital-discharge=0.95,endocrinology=0.90,primary-care=0.85

$ jq '{input, exact_dups, near_merged, conflicts, final}' report.json
{
  "input": 38703,
  "exact_dups": 25789,
  "near_merged": 412,
  "conflicts": 13,
  "final": 12490
}

$ cascade pod init my-health-pod
Initialized Cascade Pod at ./my-health-pod

$ cascade pod import my-health-pod merged.ttl
Imported 12490 records into my-health-pod

$ cascade pod info my-health-pod
Pod: my-health-pod
Records: 12,490
Data types: conditions (18), medications (24), lab-results (847),
            procedures (312), encounters (156), observations (9,133)
Encrypted: yes (AES-256-GCM)
Size: 4.2 MB

$ cascade-agent --script questions.txt

▶ What conditions am I being treated for?

  Rogelio is being actively treated for four primary conditions:
  Type 2 Diabetes Mellitus (diagnosed 2009), Essential Hypertension
  (2011), Diabetic Peripheral Neuropathy (2016), and Stage 3 Chronic
  Kidney Disease (2019). All four are currently active across all
  three provider records.

▶ What's my most recent HbA1c result and how has it trended?

  Most recent HbA1c: 8.4% (endocrinology, March 2026). There is a
  small but consistent divergence between primary care and
  endocrinology measurements — approximately 3% — likely reflecting
  different laboratory equipment. Adjusting for this, the underlying
  trend shows improvement from a peak of 9.1% in mid-2024 to the
  current 8.1–8.4% range.

▶ Are there any gaps between my diagnoses and current medications?

  One potential gap: Diabetic Peripheral Neuropathy is an active
  diagnosis, but there is no corresponding neuropathic pain medication
  (gabapentin, pregabalin, or duloxetine) in the active medication
  list. This may be intentional — not all neuropathy cases require
  pharmacotherapy — but it is worth raising at the next visit.

What You Actually Get

At the end of this workflow, you have something that did not exist before: a single, authoritative, queryable representation of your health history. Not a portal view. Not a PDF summary. A structured knowledge graph that:

• Preserves provenance. Every record knows where it came from. If two sources disagree, the reconciler records both values, tracks the conflict, and documents how it was resolved and why.
• Is portable. Export as a ZIP and take it anywhere. Import into another tool, share with a specialist, or use as the input for a specialized application.
• Is agent-native. The RDF graph format is self-describing. Any agent that loads your pod can reason about it without requiring a separate schema file or system prompt explaining what each field means.
• Stays on your device. The cascade CLI runs locally. The agent runs locally. Nothing leaves your machine unless you choose to export. There is no account to create, no cloud service to trust.

This is not a demo of a future capability. The CLI and agent are available today. The SDKs for TypeScript and Swift let you build applications that read and write Cascade Pods. A patient-facing iOS app built on the Swift SDK can import the same pod you built from the command line and display it with a proper UI, share summaries via QR code to a physician's intake system, and sync with HealthKit.

Try It Yourself

Everything shown here is open source and available on npm. Getting started takes about five minutes if you have Node.js installed.

# Install the CLI and agent
npm install -g @the-cascade-protocol/cli @the-cascade-protocol/agent

# Download a FHIR export from any patient portal, then:
cascade convert my-records.json --from fhir --to cascade > my-records.ttl
cascade pod init my-pod
cascade pod import my-pod my-records.ttl
cascade-agent

SDKs for application developers

If you are building a production health application rather than running CLI scripts, the Cascade SDKs handle the storage, encryption, and serialization layer so you can focus on your application logic.

• Swift SDK — for iOS, macOS, and watchOS applications. Handles local AES-256-GCM encrypted storage, HealthKit integration, and FHIR import. Used in production by POTS Check.
• TypeScript SDK — for Node.js and server-side applications. Full RDF graph I/O, pod management, and the same reconciliation engine used by the CLI.
• MCP Server — exposes a Cascade Pod as a Model Context Protocol resource, making it directly accessible to Claude, Cursor, and any MCP-compatible agent host.

Further reading

• Why RDF/OWL is the Right Foundation for Health AI Agents — the semantic grounding problem
• Provenance as a Compliance Primitive — how the W3C PROV-O model makes data lineage auditable
• Local-First is the Only Responsible Architecture for AI + Health Data — why zero-egress matters
• Cascade Protocol Documentation — vocabulary reference, getting started, and SDK guides