Memory Architecture & API Mapping

Four-layer memory model (L0-L3) mapped to Classic API endpoints, plus where to find Platform API memory queries.

Amigo's Functional Memory system uses a four-layer architecture to build, store, and refine knowledge about each user. This page maps those layers to the Classic API endpoints you use to read and influence them, and points to where the Platform API's memory query surface is documented.

Classic API. This memory architecture applies to Classic API user models. The Platform API uses the World Model for patient data; a short pointer to its memory query endpoints appears at the end of this page.

Conceptual vs. API documentation. The four-layer model (L0-L3) comes from Amigo's Conceptual Documentation. This page bridges those concepts to the REST API you interact with as a developer.

The Four Layers

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/

Python SDK

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}")

curl

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.

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']}")

curl

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.

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.

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

Python SDK

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}")

curl

See User Models 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}

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()

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.

See User Models: Update Additional Context 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:

{
    "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

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 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. For the conceptual memory model, see Functional 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.