Memory

How source-linked observations and bounded models preserve useful context, with scoped recall when an agent needs detail from earlier interactions.

For developers: See Memory Architecture for API resources and Data & World Model for entity enrichment.

Functional memory develops useful, source-linked understanding over time. It helps an agent carry context into later interactions and retrieve supporting detail when the loaded model is insufficient. The world model anchors that understanding to an entity and workspace; the active session uses it alongside current records and conversation history.

Three operations explain the person-memory workflow:

• Observe - Interpret a completed conversation against the current understanding and extract useful new information.
• Consolidate - Integrate observations into a bounded user model with references to supporting evidence.
• Recall - Search earlier observations and conversations when the current task needs more detail.

The compact model gives the agent a starting point. Exact operational facts, such as appointment availability, still come from the appropriate data tools. A generated interpretation does not acquire the authority of a clinical record merely because it is remembered.

Memory, World Data, and Working Context

Layer	Purpose	Example
Source evidence	Retain what was recorded and where it came from	A conversation turn or connected system record
Derived memory	Summarize useful context, changes, and interaction patterns	A person's preferences and reported barriers
Structured world data	Preserve typed facts and relationships for retrieval and operations	An appointment's time, status, and associated person
Working context	Supply the information used in the current interaction	Recent turns, selected enrichment, state guidance, and tool results

The subject of a memory must be distinguished from the person speaking. An operator discussing a patient does not make that observation a memory about the operator. The person-recall path below uses the session's resolved subject, within its workspace.

The world model owns reusable object facts, relationships, and factual resolution. Memory derives useful understanding from eligible evidence. Applications own their task notes and operational state; the reasoning runtime owns the context used during execution. These responsibilities do not require separate stores, and generating a summary does not create a second authority for the underlying record.

The implemented extraction, consolidation, and recall path described below is person-scoped. The object-memory design direction extends these ideas to other objects; it is separate from this current contract. Confirm any private-preview object types, sources, and views for the intended deployment.

Implemented Memory Model

Layer	What It Contains	How It Is Produced
Conversation record	The source transcript and turn history	Stored as conversation evidence
Episodic observations	Net-new or surprising information from a completed conversation	Extracted from the transcript in the context of the current user model
Semantic user model	An integrated narrative of patterns, changes, and interaction preferences	Consolidated from the current model and a bounded set of recent observations
Structured clinical state	Current conditions, active medications with doses, and allergies from connected records	Deterministically projected from world-model events

The semantic user model and structured clinical state reach the agent through the same current-enrichment surface, but they have different provenance and confidence. Structured connector-derived context outranks model-generated memory when both compete for the same key.

Post-Conversation Processing

After a conversation ends:

1. The platform associates the completed transcript with the resolved workspace entity.
2. The episodic extractor compares the conversation with the current user model and records net-new observations with source references.
3. The semantic consolidator updates the integrated user model from the current model plus a bounded window of recent observations.
4. The enrichment fold selects the current values, retaining confidence, source, effective time, and supporting lineage.
5. A later session loads the current enrichment alongside the rest of its world-model context.

Processing is asynchronous. Information said in the current conversation remains available in that conversation's turn history, but it may not appear as cross-session memory until post-conversation processing succeeds.

Episodic Observations

Episodic observations capture information that may matter later, such as:

• Communication preferences and engagement patterns
• Goals, motivations, and barriers
• Emotional or behavioral changes over time
• Patient-reported context not already represented in the current user model

These observations are model-generated. They retain references to supporting conversation evidence and remain bounded by the configured memory dimensions, but they are not guaranteed to capture every detail or to be clinically authoritative.

Semantic User Model

The semantic layer integrates episodic observations into a concise narrative rather than appending an unbounded history. Consolidation uses:

• The current user model
• Recent observations since the previous consolidation
• A bounded lookback of observations relevant to the model's pattern themes

The result can describe trajectories such as rising, falling, stable, or changed behavior. Consolidation requires a non-empty set of supporting observation references and instructs the model to preserve safety-relevant signals. Those references help trace a generated model; their presence alone does not verify that every sentence is supported or that every important detail survived consolidation. The user model should not replace authoritative clinical records or runtime safety rules.

Structured Clinical State

The platform also derives a deterministic clinical_state enrichment from connected clinical data:

• Active conditions
• Active medications and available dose information
• Allergies

Conditions and medications use bounded summaries with visible overflow markers. Allergies are not truncated. This projection is connector-derived rather than extracted from conversation text, so it carries a higher confidence tier than model-generated memory.

Custom Memory Dimensions

Workspaces can add conversation-memory targets through enrichment keys tagged for memory extraction. A custom memory key must:

• Apply to person entities
• Use a valid snake_case identifier
• Include a non-empty description that defines what to extract
• Use the string value type
• Avoid shadowing a platform-provided key

Custom dimensions join the same extraction and validation path as platform defaults. A workspace with no custom dimensions continues to use the default memory targets. Custom dimensions are bounded to the behavioral precision tier; they do not become authoritative clinical state.

Define a dimension around information that will change how a later interaction is handled. For example, describe scheduling constraints and the reasons the person gives, including changes over time, rather than asking for a generic conversation summary. Test the definition with a new preference, a correction, and an interaction that contains nothing relevant. These are authoring and evaluation practices; adding a dimension does not guarantee complete extraction or retrospective processing of all earlier conversations.

Retrieval and Session Context

The agent receives the current user model and other selected enrichment at session start. It can still query the world model or connected tools for detailed operational and clinical data when needed. Functional memory does not eliminate retrieval, guarantee complete recall, or load every historical transcript into the prompt.

Use memory for durable interaction context and patterns. Use authoritative data tools for current appointments, medications, clinical records, and other facts where freshness or source authority matters.

Recall Beyond the Loaded Model

When the memory-expansion tool is exposed in a supported session, the agent can search the resolved person's observation history, prior conversation turns, or both. This is useful when the summary says that scheduling is difficult but the agent needs to recover the reason given in an earlier interaction.

Recall is read-only and scoped by the server to the session's resolved person and workspace. The model supplies a topical query, an optional observation dimension, a search scope, and a bounded result limit. It cannot select another person's history by supplying an identifier.

The search uses keyword or phrase matching and returns recent matches first. It caps the history searched, the number of results, and returned text length. It can therefore miss an older detail, a different phrasing, or context outside a returned excerpt. It is not a semantic relevance ranking or an exhaustive history review.

Result	Meaning	Recommended workflow response
Matching observations or turns	Detail was found within the searched history	Check source, speaker, and time before using it
No matches	The bounded query found no matching records	Refine the query, use an authorized data tool, or ask for the missing information
No resolved person	The session has no subject whose memory can be searched	Resolve the subject through the supported identity workflow
Temporarily unavailable	The recall path could not serve the request	Continue with sufficient existing evidence or use the workflow's fallback

An empty or unavailable result is not evidence that an event never happened. Retrieved agent speech is also not an independent confirmation of what a person reported or what an external system did.

The task itself can reveal a need for retrieval: a required field, newly mentioned object, or correction may matter even when the loaded summary contains no cue to search. Do not use the summary as the only checklist of what evidence could be missing.

A Changed Preference Across Interactions

Suppose the loaded model describes a morning appointment preference, but the person now says, "I work nights now, so afternoons are better."

1. Use the correction as current conversation context and clarify any ambiguity relevant to the task.
2. If earlier detail matters, recall supporting observations or conversation turns instead of inferring them from the summary.
3. Check live availability through the scheduling tool; the remembered preference supplies context for that lookup.
4. After the interaction, asynchronous extraction and consolidation can incorporate the change into later-session memory.

Verify the later enrichment before assuming the update is available to another session. Separate the time the conversation ended, the time memory processing completed, and the time the served context reflected the change. A processing schedule alone is not an end-to-end freshness guarantee.

Design Direction: Object Memory

The proposed extension organizes memory around an object, its evidence, and task-specific views. A study, specimen, aliquot, and experiment run retain distinct identities and histories. A view may be a narrative, exact fields, a relationship map, or a few orientation cues. Several views can use the same evidence for different tasks.

General object-memory derivation, project subscriptions, state-entry preload, and the full correction contract below are extensions to the person-memory path. They are design requirements, not guarantees supplied by the current recall tool.

Evidence and Corrections

Observe, consolidate, and recall remain the main operations, with a broader evidence contract:

Concern	Required behavior in the proposed design
Attribution	Keep the subject, speaker, and observer distinct; retain original source identity when an object mapping changes
Meaning and time	Preserve source revisions, effective time, units, and conditions; distinguish measurements, reports, and inferences
Supporting evidence	Check that material claims are supported by eligible records with the correct subject, revision, and meaning; the previous summary is context, not new support
Corrections	Invalidate affected views and pending use after a correction, withdrawal, identity change, or incompatible definition change; rebuild before dependent work proceeds
Publication	Accept a rebuilt view only while its dependencies still match, so an older computation cannot restore invalidated understanding
Coverage	Make incomplete, stale, unavailable, and no-match results distinguishable; retain evidence outside a processing limit as pending or explicitly excluded

A repeated measurement can be meaningful even when its value is unchanged. Importing that same measurement repeatedly does not create independent confirmation. Later arrival also does not automatically make a record supersede an earlier observation: the time and conditions of the claim still matter.

Access and retention apply to derived views and retrieved context as well as source records. Related objects and shared projects do not grant access. The proposed correction and erasure process must account for indexes, caches, traces, and serving views; a historical or pinned view remains subject to withdrawal and access rules.

Context Required by a Task

A project would identify relevant objects, relationships, and views. A Context Graph state would declare which view it needs, which decision depends on it, what makes it valid, and the fallback when it is unavailable. These declarations describe proposed execution support, not additional fields in today's public Context Graph contract.

Required context and preloaded context are independent. A required view can load while unrelated work continues; the dependent decision waits until its prerequisites are satisfied. Existing valid context can be reused. Reasoning may discover another information gap and request scoped evidence within the task's budget. Model confidence cannot waive a prerequisite.

For example, a proposed read-only study comparison would begin with the study and run identities, then retrieve each run's inputs, values, units, recorded conditions, and applicable method and analysis revisions. Individually recent records may still be incompatible. An unexplained normalization difference would trigger additional retrieval. If a handling record were corrected before the comparison completed, affected pending conclusions would need reconsideration before release. The answer would separate supported differences from inferred causes and unresolved questions.

Execution and Longer-Term Improvement

The execution loop uses accepted knowledge for the current task and retains new evidence and outcomes. A slower improvement loop would examine repeated work and propose reusable views, dimensions, or resolution rules. A useful comparison that repeatedly requires the same reconstruction is a candidate for this review.

The slower loop remains a design direction. Proposed definitions need an owner, evaluation, explicit acceptance, and a rollback path before later work uses them. Background behavior selection within an interaction is still execution; it does not establish learning across interactions. Automatic production-definition changes are outside this design phase.

Evaluate a compact view against source retrieval and their combination on a stated task. Compression, repeated agreement, and successful replay do not prove completeness or causality. Reprocessing history cannot recover a measurement that was never recorded. See Evaluating Amigo for the evidence to collect.

Safety and Auditability

• Source preservation - Conversation records remain the evidence behind extracted observations.
• Lineage - Semantic claims point back to supporting episodic observations.
• Confidence separation - Generated memory does not silently outrank structured connector-derived context.
• Workspace isolation - Memory is scoped to the entity and workspace that produced it.
• Bounded context - Consolidation and prompt loading stay bounded rather than growing with the full conversation history.

Memory can improve continuity, but it is not a guarantee of perfect recall or a substitute for clinical verification. Safety decisions must continue to use the platform's runtime controls and authoritative data sources.

For text-thread persistence within a conversation, including frozen plans and recent turns, see Text Sessions. Conversation persistence and cross-session functional memory are separate mechanisms.