> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/agent/memory.md).

# Memory

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

{% hint style="success" %}
**For developers:** See [Memory Architecture](https://docs.concurrence.com/developer-guide/operations/reference/memory-architecture) for API resources and [Data & World Model](https://docs.concurrence.com/developer-guide/platform-api/data-world-model) for entity enrichment.
{% endhint %}

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](#design-direction-object-memory) 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

```mermaid
%%{init: {"theme":"base","fontFamily":"Inter, sans-serif","themeVariables":{"fontFamily":"Inter, sans-serif","fontSize":"16px","background":"#FAF8F6","primaryColor":"#F1EAE7","primaryTextColor":"#1A1817","primaryBorderColor":"#D7D2D0","secondaryColor":"#FDFCFB","tertiaryColor":"#F6F2F0","lineColor":"#575452","textColor":"#3D3937","clusterBkg":"#FDFCFB","clusterBorder":"#E8E2DF","edgeLabelBackground":"#FAF8F6","actorBkg":"#F1EAE7","actorTextColor":"#1A1817","actorBorder":"#D7D2D0","actorLineColor":"#575452","signalColor":"#575452","signalTextColor":"#3D3937","labelBoxBkgColor":"#F1EAE7","labelBoxBorderColor":"#D7D2D0","labelTextColor":"#3D3937","loopTextColor":"#3D3937","noteBkgColor":"#F6F2F0","noteBorderColor":"#D7D2D0","noteTextColor":"#3D3937","activationBkgColor":"#F1EAE7","activationBorderColor":"#D7D2D0","altSectionBkgColor":"#FAF8F6","altSectionColor":"#3D3937"}}}%%
flowchart LR
    transcript["Completed conversation<br/>transcript"] --> episodic["Episodic observations<br/>net-new, source-linked"]
    episodic --> semantic["Semantic user model<br/>bounded consolidation"]
    connector["Connector and EHR records"] --> clinical["Structured clinical state<br/>deterministic projection"]
    semantic --> current["Current entity enrichment"]
    clinical --> current
    current --> session["Later agent session"]
```

| 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 Concurrence](/platform-overview/evaluating-amigo.md#evaluate-memory-on-tasks-that-need-continuity) 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.

{% hint style="info" %}
For text-thread persistence within a conversation, including frozen plans and recent turns, see [Text Sessions](/channels/text-sessions.md#durable-conversation-model). Conversation persistence and cross-session functional memory are separate mechanisms.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.concurrence.com/agent/memory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.