VFS Paths
Complete reference for all Virtual File System path patterns, file types, and slug derivation rules.
VFS Paths
The Virtual File System (VFS) exposes the resolved patient graph as a navigable directory tree. All paths are relative to the patient root. Content is materialized lazily from the live graph on each request. Nothing is stored as pre-rendered files.
Entity types
Each entity in the resolved graph has a type that determines which VFS category it lives in. Internal infrastructure types (encounter, device) are used by the pipeline but are not exposed through the VFS.
| Type | VFS path | Description |
|---|---|---|
condition | /conditions/active/, /conditions/resolved/ | Diagnoses, problems, and clinical findings |
medication | /medications/current/, /medications/discontinued/ | Drugs, dosages, and administration records |
lab | /labs/ | Laboratory observations and results |
allergy | /allergies/ | Allergy and intolerance records |
encounter | /encounters/{year}/ | Clinical encounters, organized by year |
family_history | /family_history/ | Conditions recorded as family history |
insurance | /insurance/ | Coverage and payer information |
directive | /directives/ | Advance directives and consent records |
Statuses
Conditions and medications carry a status field that determines which subdirectory they appear in.
| Status | Applies to | VFS subdirectory |
|---|---|---|
active | conditions, medications | /conditions/active/, /medications/current/ |
resolved | conditions | /conditions/resolved/ |
inactive / stopped | medications | /medications/discontinued/ |
The pipeline infers status from textual cues ("hx of", "history of", "resolved", "in remission") when not explicitly provided in the source. Conditions coded as family history are moved to /family_history/ during post-processing regardless of how they were originally coded.
Slug derivation
Directory names within the VFS are slugs derived from entity display names:
- Lowercased
- Spaces and most special characters replaced with underscores
- Standard medical punctuation preserved where unambiguous
For example: "Type 2 Diabetes Mellitus" → type_2_diabetes_mellitus, "HbA1c" → hba1c.
LOINC slugs used in lab trend paths use the same rule applied to the LOINC long common name.
Path reference
Root
| Path | Type | Returns |
|---|---|---|
/ | directory | Top-level category directories with one-line descriptions |
Conditions
| Path | Type | Returns |
|---|---|---|
/conditions/ | directory | active/ and resolved/ subdirectories |
/conditions/active/ | directory | All active condition slugs with status previews |
/conditions/resolved/ | directory | All resolved condition slugs with status previews |
/conditions/{status}/{slug}/ | directory | _story.md and _raw.json for this condition |
/conditions/{status}/{slug}/_story.md | file | Full longitudinal condition narrative |
/conditions/{status}/{slug}/_raw.json | file | Raw entity JSON with codes and typed relationships |
{status} is one of active or resolved.
Medications
| Path | Type | Returns |
|---|---|---|
/medications/ | directory | current/ and discontinued/ subdirectories |
/medications/current/ | directory | Currently active medication slugs |
/medications/discontinued/ | directory | Discontinued medication slugs |
/medications/{status}/{slug} | file | Medication detail: name, dosage, prescriber, period, RxNorm code |
{status} is one of current or discontinued. Medications are leaf files. They do not have _story.md or _raw.json sub-paths.
Labs
| Path | Type | Returns |
|---|---|---|
/labs/ | directory | latest entry and trends/ subdirectory |
/labs/latest | file | Most recent value per LOINC code across all lab entities, sorted by result date descending |
/labs/trends/ | directory | One slug per LOINC code with recorded lab history |
/labs/trends/{loinc-slug} | file | Full chronological time series for a single LOINC code with computed trend direction (based on last three values) |
Allergies
| Path | Type | Returns |
|---|---|---|
/allergies/ | directory | All allergy slugs |
/allergies/{slug} | file | Allergy detail: substance, reaction, severity, onset |
Directives
| Path | Type | Returns |
|---|---|---|
/directives/ | directory | All advance directive slugs |
/directives/{slug} | file | Directive detail: type, status, effective date, document title |
Encounters
Encounters are organized by year. Orphan encounters (no linked conditions, no clinical notes) are filtered from listings but preserved in the graph.
| Path | Type | Returns |
|---|---|---|
/encounters/ | directory | Year subdirectories that contain at least one encounter |
/encounters/{year}/ | directory | Encounter files for that year |
/encounters/{year}/{slug}.md | file | Encounter detail: date, class, provider, linked conditions, notes |
Encounter slugs are date-prefixed for stable ordering: 2023-05-15-cardiology-a716fe12.
Insurance
| Path | Type | Returns |
|---|---|---|
/insurance/ | directory | All insurance coverage slugs |
/insurance/{slug} | file | Coverage detail: payer, plan name, member ID, group number, effective period |
Family history
| Path | Type | Returns |
|---|---|---|
/family_history/ | directory | All family history slugs |
/family_history/{slug} | file | Family history detail: condition, relation, onset if recorded |
Timeline
| Path | Type | Returns |
|---|---|---|
/timeline/ | directory | Year subdirectories that contain events |
/timeline/{year}/ | directory | Event slugs for that year |
/timeline/{year}/{event-slug} | file | Single event detail: type, date, description, source |
Events include encounters, procedures, lab draws, and immunization administrations. Each occurrence is preserved as a distinct timeline entry. Events are not deduplicated.
Sources
| Path | Type | Returns |
|---|---|---|
/sources/ | directory | One slug per ingested source document |
/sources/{doc-slug} | file | Document metadata: type, origin, date, and any narrative sections extracted from the document |
All ingested FHIR bundles, CDA documents, and registered unstructured documents appear here. Narrative sections from CDA documents (sections that had free text but no structured entries) are included in the document file.
Memory
| Path | Type | Returns |
|---|---|---|
/memory/ | directory | Agent-accumulated observations and insights |
The memory section is written by AI agents that use Patient Memory as a backend. It stores durable observations that should persist across sessions. Not populated by the ingestion pipeline.
File types
_story.md
A prose Markdown narrative assembled from the entity's fields, codes, and relationships. For conditions, this is the primary high-value path for multi-hop clinical questions: it includes onset, active and discontinued medications (with dosages), monitoring labs (with trend direction), complications, comorbidities, and a timeline of key events.
Typically 300–800 tokens in narrative format.
_raw.json
The raw ClinicalEntity JSON, including all field values, all clinical codes from all contributing sources, and all typed relationship edges (both explicit and inferred). Does not include the full ProvenanceTrace. Use GET /patients/{patientId}/resolution for provenance detail.
Typically 200–500 tokens.
Read format and token budget
All file paths can be read via GET /patients/{patientId}/read?path=.... The format query parameter controls output verbosity:
| Format | Output | Approx. tokens |
|---|---|---|
narrative | Prose Markdown | 300–800 |
structured | Full JSON | 200–500 |
compact | Key facts only | 50–150 |
The token_budget parameter sets an approximate upper bound. Use it in multi-step agent workflows where context window budget is tracked explicitly.
Browse vs. read
| Operation | Endpoint | Use when |
|---|---|---|
| Browse | GET /vfs?path=... | Discovering what exists at a path (returns directory children or inline file content) |
| Read | GET /read?path=... | Fetching a specific file with format control (always returns { content: string }) |
For directory paths, browse and read return the same children listing. For file paths, read gives explicit format and token budget control; browse returns the file content at the default format.
See Browse and Read VFS Paths for usage examples.