Condition Stories

A condition story is a pre-computed Markdown narrative for a single clinical condition. It assembles all relevant information from the knowledge graph (onset, medications, labs, complications, monitoring status) into a single readable document. The relationships between conditions, medications, and labs are inferred by the clinical knowledge base.

Why condition stories?

A condition like Type 2 Diabetes Mellitus doesn't exist in isolation. Understanding it requires knowing:

• When it was first diagnosed and across which sources
• Which medications are currently treating it
• Which labs monitor its control
• Whether there are complications (CKD, neuropathy, retinopathy)
• Whether those complications are being adequately monitored

This information is distributed across multiple nodes in the graph. A condition story assembles it once so an agent can get a complete and coherent portrait of the condition in a single place.

Example

# Type 2 Diabetes Mellitus

**Status:** Active since 2016-03
**Codes:** SNOMED 44054006 · ICD-10 E11.9
**Sources:** 3 sources (FHIR Bundle, Summary_20230907.xml, Labs_2023.xml)

## Current Treatment

| Medication    | Dose       | Since   |
| ------------- | ---------- | ------- |
| Metformin     | 1000mg BID | 2016-04 |
| Empagliflozin | 10mg QD    | 2020-08 |

## Monitoring Labs

| Lab             | Latest    | Date       | In Range |
| --------------- | --------- | ---------- | -------- |
| HbA1c           | 7.1%      | 2023-09-07 | ✓        |
| eGFR            | 52 mL/min | 2023-08-15 | ⚠ Low    |
| Fasting glucose | 118 mg/dL | 2023-09-07 | ✓        |

## Complications

- **Chronic Kidney Disease (Stage 3b)**: active since 2021
  - Complication of: Type 2 Diabetes Mellitus
  - Monitored by: eGFR, urine albumin/creatinine ratio
  - Last eGFR: 52 mL/min (below target of ≥60)

Patient-reported context

When a symptom memory has been matched against the condition, the story includes a ## Patient-Reported section built from those relationships:

## Patient-Reported

### Conflicts with record

- "My blood sugar readings have actually been running closer to 180 some mornings"

### Corroborations

- "My fasting sugars have been running around 120 most mornings"

Entries are grouped by relationship type (conflicts, corroborations, additional context) and rendered from the memory's content. This section only appears when at least one matching memory exists; it never contains an empty header. adherence memories, which relate to medications rather than conditions, surface the same way on the medication's own file instead. See Memory for how memories are generated and matched to facts.

Source narratives

When a narrative has been adjudicated against the condition, the story ends with a ## Narratives section linking each one:

## Narratives

- [Insulin started](_narratives/2023-07-01_5f2c8a1b.md) — conflicts
- [Early diabetes review](_narratives/2019-03-14_9b7d0e34.md) — corroborates

Every line carries the narrative's title, the path to it, and the verdicts it holds against this condition (corroborates, enriches, conflicts) — so a contradiction in the record is one read away from the reasoning behind it. Paths are relative to the condition's own directory.

That read gives you the reasoning, not the note. A narrative's summary and its quote are on neither the leaf nor its structured form: they paraphrase the passage rather than the condition, and a budgeted read spends its last bytes there. For the wording a clinician recorded, read the document under /sources/.

The section appears only when at least one narrative links to the condition, and only in narrative format; compact omits it. The _narratives/ directory is listed whenever the condition is browsed either way, reporting 0 narratives when nothing links there. See VFS Paths.

Token budget

Condition stories respect the token_budget parameter. The story is rendered in full and then cut from the end — no section is selected over another — so the order sections appear in is the order a budget keeps them:

1. Status, onset, and codes
2. Progression timeline
3. Active and discontinued medications
4. Monitoring labs
5. Complications and related conditions
6. Encounters
7. Patient-reported memories
8. Links to the source narratives

The order is chosen so that cutting from the end costs the least: a low budget keeps the clinical picture and drops the cross-references that point at it. A compact format gives a one-paragraph overview; narrative gives the full story with tables.

Accessing condition stories

Via MCP (see MCP Tools):

read_patient("/patient/{id}/conditions/active/{condition}/_story.md")
read_patient("/patient/{id}/conditions/active/{condition}/_story.md", format="compact")

Via REST (see REST API reference):

GET /v1/patients/{patientId}/read?path=/conditions/active/type_2_diabetes_mellitus/_story.md&format=narrative

See Read a Condition Story for a practical walkthrough.