What it is

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
│   │   │   └── _raw.json       ← structured entity + relationships
│   │   └── hypertension/
│   └── resolved/
├── medications/
│   ├── current/
│   │   └── metformin_1000mg
│   └── discontinued/
├── allergies/
├── labs/
│   └── latest/
├── timeline/
├── family_history/
└── sources/

Navigation Pattern

The VFS is designed for progressive discovery:

→ browse_patient("/patient/abc/")
← conditions/ medications/ allergies/ labs/ timeline/ family_history/ 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
\_raw.json structured entity + relationships

→ 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.

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.

The VFS patient ID is returned in every ingest response as patient.id. To look it up later, call GET /patients/{registryKey} and read patient.id from the response.