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; not accepted 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 Who uses this agent? when you create it (B2C and Internal: user_id only; B2B and Agent-to-Agent: both), and shows as Type on the Instances list. 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 → record_message for the conversation (Synap turns recorded turns into long-term memory for you), and memories.create only for content that is not a recorded turn. Use one path per conversation: recording a conversation and also ingesting the same text extracts it twice. See Conversations and transcripts.

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 search only, with no graph traversal and no LLM decomposition. `accurate` = vector search + graph traversal + LLM subquery decomposition + reranking (more compute, wider/higher-quality results). Both pull from the same memory. See Retrieval modes.
Ingestion	`fast` · `long-range`	Nothing today: both run the same pipeline. See Ingestion mode.

…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"])

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();

let conversation_id = randomUUID();  // 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)
const ctx = await sdk.user.context.fetch({
  user_id: 'user_123',
  search_query: ['seating preferences'],
});

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();

let conversation_id = randomUUID();  // 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)
const 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.

Start here

Connecting to Synap

The memory model

Memory architecture (MACA)

How memory is processed

Memory Model Cheat Sheet

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

Going deeper

The identifiers (scope chain)

The two write paths

The four fetch interfaces

The two mode pairs