> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Model Cheat Sheet

> One screen for the whole mental model: the identifiers, the two write paths, the four fetch interfaces, and the two mode pairs. Bookmark this.

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](/concepts/memory-scopes#clients-and-instances). |
| [**Instance**](/concepts/memory-scopes#clients-and-instances) (`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).                                    |

<Note>
  **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](/concepts/memory-scopes#b2c-vs-b2b-which-scopes-apply-to-you).
</Note>

## The two write paths

| Write API                                                                            | Use it for                                                 | Cost / weight                      | Registers a conversation?                                         |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------- |
| [`sdk.conversation.record_message(...)`](/sdk-reference/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(...)`](/sdk-reference/memories/create)                         | Long-term knowledge: docs, facts, profiles, bulk ingestion | Heavier (full extraction pipeline) | No                                                                |

<Warning>
  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.
</Warning>

**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](/sdk/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=...)`](/sdk-reference/context/user-fetch)                         | Everything tagged to that user            | `user_id` (+ `customer_id` on B2B)                      |
| [`sdk.customer.context.fetch(customer_id=...)`](/sdk-reference/context/customer-fetch)             | Everything tagged to that customer/tenant | `customer_id`                                           |
| [`sdk.client.context.fetch(...)`](/sdk-reference/context/client-fetch)                             | Everything at the client level            | the API key's client                                    |
| [`sdk.conversation.context.fetch(conversation_id=...)`](/sdk-reference/conversation-context/fetch) | A single registered thread                | a `conversation_id` **registered via `record_message`** |

<Note>
  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](/sdk/error-handling#contextnotfounderror).
</Note>

## 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](/concepts/retrieval-modes). |
| **Ingestion**                                | `fast` · `long-range`         | How deeply a write is processed. See [Runtime ingestion](/concepts/how-ingestion-works#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`.

```python theme={null}
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"])
```

<Card title="Going deeper" icon="book-open" href="/concepts/memories-and-context">
  The full memory model: memory types, lifecycles, entity resolution, and [MACA](/concepts/memory-architecture).
</Card>