> 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/developer-guide/operations/reference/memory-architecture.md). # Memory Architecture & API Mapping The Classic API documents its post-processing resources with four layer labels, L0-L3. This page maps those Classic labels to the endpoints you can use and then distinguishes the Platform API's current world-model memory surface. {% hint style="info" %} **Classic API.** This memory architecture applies to Classic API user models. The Platform API uses the [World Model](/developer-guide/platform-api/data-world-model.md) for patient data; a short pointer to its memory query endpoints appears at the end of this page. {% endhint %} {% hint style="info" %} **Classic terminology.** L0-L3 is a Classic API compatibility model, not the current Platform conceptual model. Platform documentation describes conversation evidence, episodic observations, a bounded semantic user model, and separately projected structured clinical state. See [Functional Memory](https://docs.amigo.ai/agent/memory). {% endhint %} ## The Four Layers ```mermaid %%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 30, "rankSpacing": 50}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%% flowchart TB L0["L0: Raw Transcripts"] L1["L1: Extracted Memories"] L2["L2: Episodic User Models"] L3["L3: Global User Model"] L0 -->|extract-memories| L1 L1 -->|generate-user-models| L2 L2 -->|aggregate| L3 style L0 fill:#F1EAE7,stroke:#D7D2D0,color:#100F0F,stroke-width:2px style L1 fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px style L2 fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px style L3 fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:2px ``` | Layer | Name | Description | API Access | | ------ | -------------------- | ------------------------------------------------------- | ------------------- | | **L0** | Raw Transcripts | The complete conversation message history | Direct via REST API | | **L1** | Extracted Memories | Atomic facts and observations pulled from conversations | Direct via REST API | | **L2** | Episodic User Models | Per-conversation structured models of the user | Internal only | | **L3** | Global User Model | Aggregated, evolving model across all conversations | Direct via REST API | ## Layer-by-Layer API Mapping ### L0: Raw Transcripts Raw transcripts are the unprocessed conversation messages. Retrieve them using the conversation messages endpoint. **Endpoint:** `GET /v1/{org}/conversation/{conversation_id}/messages/` {% tabs %} {% tab title="Python SDK" %} ```python from amigo_sdk import AmigoClient from amigo_sdk.models import GetConversationMessagesParametersQuery with AmigoClient( api_key="your-api-key", api_key_id="your-api-key-id", user_id="your-user-id", organization_id="your-org-id" ) as client: response = client.conversations.get_conversation_messages( conversation_id="conv_abc123", params=GetConversationMessagesParametersQuery(), ) for msg in response.messages: print(f"[{msg.sender}] {msg.message}") ``` {% endtab %} {% tab title="curl" %} ```bash curl -s "https://api.amigo.ai/v1/${ORG_ID}/conversation/${CONVERSATION_ID}/messages/" \ -H "Authorization: Bearer ${API_KEY}" ``` {% endtab %} {% endtabs %} ### L1: Extracted Memories After a conversation ends, post-processing extracts atomic facts (memories) from the transcript. These are the building blocks that feed into higher layers. **Endpoint:** `GET /v1/{org}/user/{user_id}/memory` The SDKs do not wrap this endpoint - call it directly over REST. {% tabs %} {% tab title="Python" %} ```python import requests resp = requests.get( f"https://api.amigo.ai/v1/{ORG_ID}/user/{USER_ID}/memory", headers={"Authorization": f"Bearer {API_KEY}"}, ) resp.raise_for_status() for memory in resp.json()["memories"]: print(f"Memory: {memory['content']}") ``` {% endtab %} {% tab title="curl" %} ```bash curl -s "https://api.amigo.ai/v1/${ORG_ID}/user/${USER_ID}/memory" \ -H "Authorization: Bearer ${API_KEY}" ``` {% endtab %} {% endtabs %} ### L2: Episodic User Models Episodic user models are per-conversation structured representations generated during post-processing. They capture what the system learned about the user in that specific conversation. {% hint style="warning" %} **No direct API access.** L2 models are internal to Amigo's processing pipeline. They are consumed automatically when building the L3 Global User Model. You do not need to (and cannot) read or write them directly. {% endhint %} ### L3: Global User Model The Global User Model is the aggregated, continuously evolving representation of a user across all their conversations. It is organized by dimensions (e.g., "Medical History", "Communication Preferences") and includes supporting insight references. **Endpoint:** `GET /v1/{org}/user/{user_id}/user_model` {% tabs %} {% tab title="Python SDK" %} ```python with AmigoClient( api_key="your-api-key", api_key_id="your-api-key-id", user_id="your-user-id", organization_id="your-org-id" ) as client: user_model = client.users.get_user_model(user_id="user_12345") for entry in user_model.user_models: print(f"[{entry.dimensions[0].description}] {entry.content}") ``` {% endtab %} {% tab title="curl" %} ```bash curl -s "https://api.amigo.ai/v1/${ORG_ID}/user/${USER_ID}/user_model" \ -H "Authorization: Bearer ${API_KEY}" ``` {% endtab %} {% endtabs %} See [User Models](/developer-guide/classic-api/core-api/users/user-models.md) for the full response shape and dimension details. ## Enriching the User Model You can supplement Amigo's automatically generated user model with facts from your own systems using the `additional_context` field on the user update endpoint. **Endpoint:** `POST /v1/{org}/user/{requested_user_id}` ```python import requests resp = requests.post( f"https://api.amigo.ai/v1/{ORG_ID}/user/{USER_ID}", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={ "additional_context": [ "Tony's average fasting glucose over the past week is 105 mg/dL.", "Tony exercises three times a week (mostly swimming).", "Tony prefers morning appointment times.", ] }, ) resp.raise_for_status() ``` {% hint style="info" %} **`additional_context` is additive.** Each call appends new facts. Amigo processes and integrates them into the user model over time. Provide concise, self-contained sentences with units and dates where relevant. {% endhint %} See [User Models: Update Additional Context](/developer-guide/classic-api/core-api/users/user-models.md#update-additional-context-quick-start) for formatting guidance and examples. ## Knowing When Memories and Models Update Memories (L1) and user models (L2/L3) are generated asynchronously during post-processing after a conversation ends. Use the **`conversation-post-processing-complete`** webhook event to know exactly when each stage finishes. **Webhook payload:** ```json { "type": "conversation-post-processing-complete", "post_processing_type": "extract-memories", "conversation_id": "conv_abc123", "org_id": "org_xyz", "idempotent_key": "d41d8cd98f00b204e9800998ecf8427e" } ``` **Post-processing types relevant to memory:** | `post_processing_type` | Memory Layer Affected | What Happened | | ---------------------- | --------------------- | -------------------------------------------------------------------------------------------------- | | `extract-memories` | L1 | New memories extracted from the conversation | | `generate-user-models` | L2 and L3 | Episodic model built internally and global model (L3) updated - only L3 is retrievable via the API | ### Practical Pattern: React to New Memories ```mermaid %%{init: {"theme": "base", "themeVariables": {"actorBkg": "#083241", "actorTextColor": "#FFFFFF", "actorBorder": "#083241", "signalColor": "#575452", "signalTextColor": "#100F0F", "labelBoxBkgColor": "#F1EAE7", "labelBoxBorderColor": "#D7D2D0", "labelTextColor": "#100F0F", "loopTextColor": "#100F0F", "noteBkgColor": "#F1EAE7", "noteBorderColor": "#D7D2D0", "noteTextColor": "#100F0F", "activationBkgColor": "#E8E2EB", "activationBorderColor": "#083241", "altSectionBkgColor": "#F1EAE7", "altSectionColor": "#100F0F"}}}%% sequenceDiagram autonumber participant App as Your Application participant Amigo as Amigo API participant WH as Webhook Endpoint App->>Amigo: Conversation ends (finish) Amigo-->>Amigo: Post-processing begins Amigo->>WH: conversation-post-processing-complete
(extract-memories) WH->>Amigo: GET /user/{id}/memory Amigo-->>WH: Updated memories Amigo->>WH: conversation-post-processing-complete
(generate-user-models) WH->>Amigo: GET /user/{id}/user_model Amigo-->>WH: Updated user model ``` 1. A conversation finishes (the user or your app calls the finish endpoint). 2. Amigo runs post-processing asynchronously. 3. Your webhook endpoint receives `extract-memories`, so you can now fetch updated L1 memories. 4. Your webhook endpoint receives `generate-user-models`, so you can now fetch the updated L3 user model. See [Webhooks](/developer-guide/classic-api/webhooks.md) for setup instructions and signature verification. ## Platform API: Entity Memory The Platform API stores what agents learn about a person in the workspace's event-sourced World Model rather than a separate memory store. Long-lived facts live as **enrichment values** on an entity: * `GET /v1/{workspace_id}/world/entities/{entity_id}/enrichment` returns the current value for each enrichment key on an entity, with confidence, source, and effective time. * `GET /v1/{workspace_id}/world/entities/{entity_id}/enrichment/{key}/history` returns the full audit trail for one key, including superseded values. * Enrichment keys are managed under `/v1/{workspace_id}/world/enrichment-keys`. Tagging a person key with `memory_extract` (a description is required) makes it a workspace-custom memory dimension that the conversation extractor infers from transcripts after each session. These endpoints are available to any Platform API consumer with a workspace API key. For the endpoint reference and the underlying data model, see the [Data & World Model documentation](/developer-guide/platform-api/data-world-model.md). For the conceptual memory model, see [Functional Memory](https://docs.amigo.ai/agent/memory). ## Summary Table Classic API endpoints for each memory task: | What You Want to Do | API Endpoint | When Available | | ------------------------------------ | ------------------------------------------------------------ | -------------------------------------------- | | Read raw conversation messages | `GET /v1/{org}/conversation/{id}/messages/` | During and after conversation | | Read extracted memories for a user | `GET /v1/{org}/user/{user_id}/memory` | After `extract-memories` post-processing | | Read the global user model | `GET /v1/{org}/user/{user_id}/user_model` | After `generate-user-models` post-processing | | Add external facts to the user model | `POST /v1/{org}/user/{requested_user_id}` | Any time | | Know when memories/models are ready | Subscribe to `conversation-post-processing-complete` webhook | After conversation ends | For Platform API entity memory, see the [Data & World Model documentation](/developer-guide/platform-api/data-world-model.md). --- # 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/developer-guide/operations/reference/memory-architecture.md?ask=&goal= ``` `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.