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 (device) are used by the pipeline but are not exposed through the VFS.

Two VFS categories are not entity-backed and so do not appear above: /memory/, which holds conversation-derived memories, and /sources/, which holds the documents the record was assembled from. Both are covered under Path reference.

Statuses

Conditions and medications carry a status field that determines which subdirectory they appear in.

Conditions coded as family history (Z80–Z84, or a display naming a relative) are reclassified and appear under /family_history/ 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.

Paths under /sources/ are the exception: document handles are hash-derived and section file names carry an identity suffix, because a document title is not unique. Browse those levels rather than constructing them.

Path reference

Root

Conditions

{status} is one of active or resolved.

_narratives/ is always listed, reporting 0 narratives when nothing links to the condition.

A narrative leaf is the narrative's title followed by one section per verdict — worst first — carrying the reasoning behind that verdict against this condition. structured returns the same fields as JSON, with the model that produced the reasoning; compact returns the line the directory previews.

No part of a leaf is verbatim note text. For the wording a clinician recorded, read the document itself under /sources/ — the leaf does not name which one, so this is a search rather than a link.

The condition directory has no separate file for entity fields. Read the condition path itself with format=structured to get the field set, the clinical codes, and the typed relationship edges as JSON.

Medications

{status} is one of current or discontinued. Medications are leaf files. They do not have _story.md or any other sub-path.

Labs

Allergies

Directives

Encounters

Encounters are organized by year. Orphan encounters (no linked conditions, no clinical notes) are filtered from listings but preserved in the graph.

Encounter slugs are date-prefixed for stable ordering: 2023-05-15-cardiology-a716fe12.

Insurance

Family history

Social history

Timeline

Events include encounters, procedures, lab draws, and immunization administrations. Each occurrence is preserved as a distinct timeline entry. Events are not deduplicated.

Memory

Each file is a Markdown list. Every entry includes the verbatim statement, the date it was recorded, and the session it came from. Memories are populated when memory generation is triggered on a session, not by ingestion. See Memory.

Sources

Every other category answers a clinical question. This one is a raw view of the inputs: what a named document says, as ingested. Use it when the question is phrased against a document — what the latest endocrine note listed, when a referral was declined — rather than against a condition or medication. It is not a bibliography for the other categories: no path leads from a fact to the document it was derived from. It is still where the verbatim wording lives — a narrative leaf under a condition carries reasoning, not note text — but getting from one to the other means finding the document here yourself.

Documents are grouped by title because a record repeats a title across many documents; a flat listing of an 87-document record spends most of itself on near-duplicate rows. Within a title, documents are ordered newest first, so the latest note of a kind is the first entry.

Ordering uses the document's authoring time. Clinical time is not inferred from an authoring date, so it is unavailable for most source documents.

Names are generated, not guessable: a document handle is hash-derived, and a section file name is its title plus a short identity suffix. Browse a level before reading into it.

Two limits apply:

• A title lists at most 100 documents. Any remainder is reported as a _more entry stating how many were withheld. Withheld documents are not reachable by another path.
• Content is returned as ingested. Sections originating from marked-up documents read back with their markup, and line structure is preserved rather than reflowed.

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. It closes with a ## Narratives section linking each entry under _narratives/, with the verdicts that narrative holds. The section is omitted in compact.

Typically 300–800 tokens in narrative format.

Read format and token budget

All file paths can be read via GET /v1/patients/{patientId}/read?path=.... The format query parameter controls output verbosity:

structured on an entity path returns the ClinicalEntity: all field values, all clinical codes from all contributing sources, and all typed relationship edges (both explicit and inferred). It does not include the full ProvenanceTrace — use GET /v1/patients/{patientId}/resolution for provenance detail.

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

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.