How Agents Get Patient Context
Why agents read a patient's memory through a file system, the three ways to read it, and why assembled context costs fewer tokens than raw records.
Context assembly is the read side of the Context Engine, where agents fetch only the parts of a patient's memory a task needs, as described in Memory formation and context assembly. Agents browse a patient's memory as a virtual file system.
Why a file system
The virtual file system takes its approach from coding agents. A coding agent working in a large repository lists directories, searches for names and opens only the files its task needs, which keeps its context window small and focused on the task. The virtual file system gives an agent the same way of working through a patient's memory.
An agent discovers the patient progressively. It lists the root folder to see which categories of information exist, opens a category such as conditions/active/, and reads the one file its task needs.
Ways to read a patient
An agent reads a patient's memory in three ways.
| Way | What it returns |
|---|---|
| Browse and read the VFS | Folders by clinical category, with a file per condition, medication, lab, encounter or source document |
| Read a condition story | One document assembling a condition's progression, medications, monitoring labs, complications and patient-reported context |
| Search | Paths and previews of the facts and events that match a keyword |
Agents reach all three through the engine's MCP server. Services that are not agents browse and read the same tree over REST. Search is only available through MCP.
Why assembled context costs fewer tokens
A complex patient's FHIR bundle alone can run to megabytes of JSON. With C-CDA documents, other clinical documents and claims data added, a single patient's chart can reach several gigabytes of raw data, which no context window can hold. Raw records also leave the clinical reasoning to the agent, which takes up additional space in its context window.
A condition story is built from the already resolved and connected patient graph. The format and token_budget parameters make it smaller, down to a one-paragraph compact summary for scanning many conditions, as described in Read a Condition Story.
Inspecting the graph
The graph endpoints of the REST API return the patient graph's nodes and edges directly. They are designed for people and review tools that audit how the engine reached its results, as described in Audit the Patient Graph.
Next steps
- Virtual File System for the folder structure an agent browses.
- Condition Stories for what a story assembles and why.
- Read a Condition Story to choose a format and a token budget.
- Search Patient Data to find facts and events by keyword.
- Connect an AI Agent to give your own agent the MCP tools.
- How the Engine Thinks About Data for the model behind context assembly.
- From Theory to Practice for the objects behind each file and search result.