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

# Memory

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

Functional memory carries useful context from one interaction into later sessions without treating a generated summary as a perfect patient record. It combines conversation-derived observations with structured context from connected systems, preserves source lineage, and loads the current result through the world-model enrichment path.

## Implemented Memory Model

```mermaid
flowchart LR
    transcript["Completed conversation\ntranscript"] --> episodic["Episodic observations\nnet-new, source-linked"]
    episodic --> semantic["Semantic user model\nbounded consolidation"]
    connector["Connector and EHR records"] --> clinical["Structured clinical state\ndeterministic 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. Each consolidated claim must retain lineage to supporting observations. Safety-relevant signals are carried forward explicitly, but the user model remains generated context and 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.

## 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.

## 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.amigo.ai/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.