The Patient Graph
How the Context Engine builds the patient graph from ingested records and keeps every decision traceable.
The patient graph holds everything the Context Engine knows about one patient and each ingestion updates the graph incrementally. Every record fed into the engine is kept as an extracted copy of what its source stated. Facts, relationships and narratives the engine derives are built on top of those copies.
Recorded Memory adds four kinds of information to the graph.
| Kind | What it holds | How the engine treats it |
|---|---|---|
| Facts | Persistent state, such as a diagnosis, a medication regimen or an allergy | Merged across sources into one fact per real-world concept |
| Clinical events | Point-in-time occurrences, such as an encounter, a lab result or an administered dose | Kept as each source stated them and never merged, since each has one source |
| Narratives | Prose from clinical documents | Kept as written, grouped by meaning and related to the facts they discuss |
| Relationships | Typed links between facts, events and narratives, such as a drug and what it treats | Inferred by the engine after merging and kept up to date on each ingestion |
Each node and edge type in the diagram is defined in From Theory to Practice. Learned memories also live in this graph and are covered in How Interactions Become Memory.
How the engine merges records into facts
A patient's hypertension can arrive as SNOMED CT code 38341003 in a FHIR bundle, as ICD-10 code I10 in a CDA summary and as "HTN" in a third source. One condition can also be recorded as "Hyperlipidemia" in one place and "Hyperlipidemia due to type 2 diabetes" in another. Comparing codes or text alone either misses these duplicates or merges records that describe different things.
The first step is classification. Each record is assigned a type, such as condition, medication or allergy, based on how its source structures it. Classification also corrects records a source might file under the wrong type, such as a family history or an implanted device recorded as a condition.
Then, new records are compared to others and to the patient's existing records to identify duplicates. Comparison is done using a cascade of escalating checks.
- Source record match. The engine checks whether both records are the exact same record from the same source, ingested again.
- Code match. The engine compares the codes of both records within a shared code system, such as SNOMED CT or ICD-10. For medications, it also compares the ingredients each one is made of, down to the salt form.
- Normalized text match. The engine compares the text after expanding abbreviations, separating a condition from qualifiers such as its cause or stage, and splitting a medication into ingredient, dose, frequency and route.
- Model adjudication. A model reviews the pairs the previous checks could not settle, reading each record's text, codes and source.
If a pair is still undecided after the cascade, it will be persisted as two separate facts, because a wrong merge in a patient record does more harm than a duplicate. Every comparison ends with a decision to merge or not and a confidence level.
When elements of a merged record disagree, the engine settles the disagreement field by field.
- One fact can take its status from one source and its dose from another.
- For each field, the engine scores every source's value based on how recent and how reliable the source is, and the fact keeps the highest-scored value.
- Codes are combined from every source. The fact's time span runs from the earliest start to the latest end.
- Every verdict is kept on the fact, as described in How every decision stays traceable.
How facts and events are related
Source records rarely express existing relationships explicitly. It is common to see a bundle hold a metformin prescription, a type 2 diabetes diagnosis and an HbA1c result with no relationship between them. The engine infers those relationships after merging, across the whole record, so a medication ingested today can be related to a condition ingested last year.
The engine relies on an internal clinical knowledge base, a curated catalog of standards and terminologies including SNOMED CT, ICD-10-CM, LOINC and more. This allows the engine to understand which drugs treat which conditions, how conditions relate to each other and which lab tests monitor which conditions.
The engine infers four kinds of relationship today.
| Relationship | Between | Inferred from |
|---|---|---|
prescribed_for | A medication and the condition it treats | The knowledge base's drug indications |
monitors | A lab result and the condition it tracks | The knowledge base's lab-to-condition mappings |
Condition relationships, such as has_complication and progression_of | Two conditions | The knowledge base's condition relationships |
occurred_during | A condition and an encounter | Timing, when the condition began or was recorded near the encounter |
Each relationship records how it was inferred and how confident the engine is in it. The engine keeps relationships up to date as new data is ingested.
Condition stories leverage these relationships to show each condition's medications, monitoring labs and complications, so agents quickly get the full picture without having to navigate the graph.
How text from documents becomes narratives
A clinical document often carries free text beside its coded data, such as an assessment, a plan or a paragraph explaining why a medication was stopped. Facts and clinical events come from the coded data, and narratives come from the free text.
The engine renders each extracted text as a passage of plain text so it can be compared with others. Today each extracted text, such as one section of a CDA document, becomes a single passage. The engine then compares passages by meaning and groups the ones that speak to the same thing into a single narrative with a title and a short summary, so a finding restated across a year of notes becomes one narrative.
Each narrative is checked against the facts it speaks to and related to them through one of three relationships, the same three that relate a learned memory to a fact.
| Relationship | What it means |
|---|---|
corroborates | The text agrees with what the fact holds |
enriches | The text adds context the fact does not carry |
conflicts | The text contradicts the fact |
A narrative never modifies the fact it relates to. Conflicts are reported instead of hidden.
The narratives related to a condition are listed under that condition in the VFS and at the end of its condition story. The original wording is under /sources/. Narrative content is not in the search index, so search queries do not find a phrase that only appears in a document as text.
Narratives do not add facts today
A narrative relates to facts without adding facts of its own. The facts it is checked against come from the document's coded content.
How every decision stays traceable
Every fact keeps the source records it was merged from, and every comparison keeps its decision and evidence, including why two records that look alike stayed separate. All of it is readable through the graph operations, so every ingestion can be audited.
"Conflict" means two different things in the graph, and the engine only settles one of them.
| Conflict | Where it is recorded | Settled | Effect on the fact |
|---|---|---|---|
| Between the sources merged into a fact | On the fact, per field | Yes, one source's value won | The fact holds the winning value |
| From a narrative or a learned memory | On a conflicts relationship | No, both stay standing | None, the fact is unchanged |
A fact's record describes the patient's record as it stands now and is updated whenever new data reshapes the fact. The decisions are append-only, so you get the full decision history behind a fact upon inspection.
Audit the Patient Graph shows how to follow these records through the graph operations.
How Records Become Memory
How the Context Engine turns records from systems of record into a patient graph, and what you get back when you send them.
Ingestion
What happens between a 202 and a settled submission: staging, the work that follows, how re-sending the same content behaves, and what each status actually tells you.