Memory Architecture & API Mapping

Classic API L0-L3 memory labels mapped to their endpoints, plus the separate Platform API memory and world-model resources.

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.

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.

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.

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

curl -s "https://api.amigo.ai/v1/${ORG_ID}/conversation/${CONVERSATION_ID}/messages/" \
  -H "Authorization: Bearer ${API_KEY}"

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

curl -s "https://api.amigo.ai/v1/${ORG_ID}/user/${USER_ID}/memory" \
  -H "Authorization: Bearer ${API_KEY}"

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 Concurrence'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

curl -s "https://api.amigo.ai/v1/${ORG_ID}/user/${USER_ID}/user_model" \
  -H "Authorization: Bearer ${API_KEY}"

See User Models for the full response shape and dimension details.

Enriching the User Model

You can supplement Concurrence'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. Concurrence 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. Concurrence 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.

The optional Service-Scoped Memory path uses application-supplied memoryid context and versioned service dimensions. It requires provisioned processing and readers; it does not automatically replace person enrichment or the recall path.