Skip to main content
Everything you need to hold in your head, on one page. Each row links to the full reference.

​
The identifiers (scope chain)

From broadest to narrowest. A memory can be tagged with several of these and is then retrievable through any matching scope.
IdentifierFormat / sourceWhat it scopes
Client (cli_<hex16>)Your organization / applicationContains one or more instances. See Clients & Instances.
Instance (inst_<hex16>)Resolved from your API key (not passed per call)One isolated memory environment (e.g. prod vs staging).
Customer (customer_id)Passed per call on B2B instances; auto-resolved on B2CYour B2B tenant. Memories are visible to all users in that customer.
User (user_id)Passed on every callYour end-user. Memories stay private to that user.
Conversation (conversation_id)Passed on conversation-scoped calls; must be a valid UUIDA single chat thread. Registered only by record_message (see below).
B2C vs B2B: B2C instances need only user_id (customer_id is auto-resolved); B2B instances pass user_id under a customer_id. The shape is set per-Instance by the User Relationship setting in the Dashboard. See Memory scopes.

​
The two write paths

Write APIUse it forCost / weightRegisters a conversation?
sdk.conversation.record_message(...)Turn-by-turn chat — persist each user/assistant turnLighterYes — this is the only call that registers a conversation_id
sdk.memories.create(...)Long-term knowledge — docs, facts, profiles, bulk ingestionHeavier (full extraction pipeline)No
Passing conversation_id inside memories.create(metadata=...) does not register the conversation — metadata is stored but not indexed for scope resolution. Only record_message creates the conversation row that conversation.context.fetch reads from.
Which do I use?
  • Turn-by-turn chat history → record_message
  • Long-term knowledge (a document, a profile, an imported fact) → memories.create
  • Production chat agent → both: record_message for the transcript, memories.create for durable knowledge. See the cost & dedup note in Ingestion.

​
The four fetch interfaces

Each reads from one scope. A memory tagged with multiple identifiers is retrievable through any matching interface.
Fetch interfaceReadsAnchored by
sdk.user.context.fetch(user_id=...)Everything tagged to that useruser_id (+ customer_id on B2B)
sdk.customer.context.fetch(customer_id=...)Everything tagged to that customer/tenantcustomer_id
sdk.client.context.fetch(...)Everything at the client levelthe API key’s client
sdk.conversation.context.fetch(conversation_id=...)A single registered threada conversation_id registered via record_message
Fetching a brand-new or never-ingested scope returns an empty ContextResponse (facts == [], etc.), not an error — this is the normal cold-start path. A malformed (non-UUID) conversation_id raises InvalidInputError. See Error handling.

​
The two mode pairs

Two different mode= axes — label which one you mean:
AxisValuesWhat changes
Retrieval (...context.fetch(mode=...))fast (default) · accuratefast = vector + graph, no LLM decomposition. accurate = vector + graph + LLM subquery decomposition + reranking (more compute, wider/higher-quality results). Both pull from the same memory. See Retrieval modes.
Ingestionfast · long-rangeHow deeply a write is processed. See Runtime ingestion.
import uuid
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK()
await sdk.initialize()

conversation_id = str(uuid.uuid4())  # must be a valid UUID

# Write path 1 — register + persist a turn
await sdk.conversation.record_message(
    conversation_id=conversation_id,
    user_id="user_123",
    role="user",
    content="I prefer window seats.",
)

# Write path 2 — durable knowledge
await sdk.memories.create(
    document="Customer is a Gold-tier member since 2021.",
    document_type="ai-chat-conversation",
    user_id="user_123",
)

# Fetch — user scope, fast mode (default)
ctx = await sdk.user.context.fetch(user_id="user_123", search_query=["seating preferences"])

Going deeper

The full memory model — memory types, lifecycles, entity resolution, and MACA.