Virtual File System

The Virtual File System (VFS) exposes the clinical knowledge graph as a familiar directory structure. An agent that has never seen this patient can discover what's there by browsing without upfront knowledge of the data structure required.

Path Structure

/patient/{id}/
├── conditions/
│   ├── active/
│   │   ├── type_2_diabetes_mellitus/
│   │   │   ├── _story.md       ← longitudinal condition narrative
│   │   │   └── _narratives/    ← narratives a verdict links to this condition
│   │   └── hypertension/
│   └── resolved/
├── medications/
│   ├── current/
│   │   └── metformin_1000mg
│   └── discontinued/
├── allergies/
├── directives/
├── encounters/
│   └── 2026/
│       └── 2026-06-15-cardiology-a716fe12.md
├── timeline/
├── labs/
│   ├── latest
│   └── trends/
├── insurance/
├── family_history/
├── social_history/
├── memory/
│   ├── symptom.md
│   ├── adherence.md
│   ├── concern.md
│   └── preference.md
└── sources/
    └── progress_note/           ← documents sharing one title, newest first
        └── 9165c47b/
            └── progress_notes_a3f21b08.md   ← one section of one document

Every directory above sources/ answers a clinical question — what conditions, what medications. sources/ is a raw view of the inputs those answers were assembled from, browsable as documents rather than as facts. It is not a bibliography for the directories above it: nothing leads from a condition or medication to the document it came from. See VFS Paths.

It is also the verbatim layer: every narrative in the tree is a reading of prose stored here, and this is the only place the wording as it was originally recorded can be read.

Documents are grouped by title rather than listed flat (for example sources/progress_note/). This facilitates progressive discovery by agents.

Navigation Pattern

The VFS is designed for progressive discovery:

→ browse_patient("/patient/abc/")
← conditions/ medications/ allergies/ directives/ encounters/ timeline/ labs/ insurance/ family_history/ social_history/ memory/ sources/

→ browse_patient("/patient/abc/conditions/active")
← type_2_diabetes_mellitus/ active since 2016
hypertension/ active since 2019
chronic_kidney_disease/ stage 3b, active

→ browse_patient("/patient/abc/conditions/active/type_2_diabetes_mellitus/")
← \_story.md longitudinal condition narrative
  \_narratives/ 2 narratives · 1 conflicting

→ read_patient("/patient/abc/conditions/active/type_2_diabetes_mellitus/\_story.md")
← # Type 2 Diabetes Mellitus
Status: Active since 2016-03
...

The _story.md file is a pre-assembled longitudinal narrative that contains onset, current medications, monitoring labs, and complications in a single read. See Condition Stories for the full structure. The _narratives/ directory beside it holds the narratives a verdict links to this condition — clinical prose from the ingested documents, each read carrying the reasoning behind its verdicts.

No graph query knowledge needed. The agent navigates what's there.

Content Formats

The read_patient tool accepts a format parameter to control verbosity:

Virtual, Not Physical

No files exist on disk. Every path has a resolver function that materializes content from the graph on demand. This means:

• Content is always current. No synchronization needed
• Token budget is enforced at the rendering layer
• The VFS can be extended with new paths without changing the underlying data model

Patient ID in Paths

The {id} segment in VFS paths (e.g., /patient/abc/) is the VFS patient ID, which is the patient.id extracted from the ingested record. For FHIR, this is the Patient.id inside the bundle. For CDA, it is the patient ID from the recordTarget header.

This is distinct from the registry key, the identifier you supply at ingest time in REST ingest routes (/patients/{registryKey}/...). The two can differ.

To look it up, call GET /v1/patients/{registryKey} and read id from the response. An ingest receipt does not carry it: extraction runs after the response, so the record has not been read yet when the receipt is written.