Memory Model Cheat Sheet

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.

Identifier	Format / source	What it scopes
Client (`cli_<hex16>`)	Your organization / application	Contains 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 B2C	Your B2B tenant. Memories are visible to all users in that customer.
User (`user_id`)	Passed on every call	Your end-user. Memories stay private to that user.
Conversation (`conversation_id`)	Passed on conversation-scoped calls; must be a valid UUID	A 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 API	Use it for	Cost / weight	Registers a conversation?
`sdk.conversation.record_message(...)`	Turn-by-turn chat: persist each user/assistant turn	Lighter	Yes: this is the only call that registers a `conversation_id`
`sdk.memories.create(...)`	Long-term knowledge: docs, facts, profiles, bulk ingestion	Heavier (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 interface	Reads	Anchored by
`sdk.user.context.fetch(user_id=...)`	Everything tagged to that user	`user_id` (+ `customer_id` on B2B)
`sdk.customer.context.fetch(customer_id=...)`	Everything tagged to that customer/tenant	`customer_id`
`sdk.client.context.fetch(...)`	Everything at the client level	the API key’s client
`sdk.conversation.context.fetch(conversation_id=...)`	A single registered thread	a `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:

Axis	Values	What changes
Retrieval (`...context.fetch(mode=...)`)	`fast` (default) · `accurate`	`fast` = 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.
Ingestion	`fast` · `long-range`	How deeply a write is processed. See Runtime ingestion.

…plus a precision knob: fetch calls also take precision_level — high (default) = results go through an additional relevance-refinement pass before being returned; medium = skips the refinement pass for faster responses (recall isn’t impacted — the same candidate memories are searched — but outputs are less precisely filtered). Independent of mode; combine with either fast or accurate.

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.

​The identifiers (scope chain)

​The two write paths

​The four fetch interfaces

​The two mode pairs

Going deeper

The identifiers (scope chain)

The two write paths

The four fetch interfaces

The two mode pairs