> ## 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.

# fetch

> Fetch and merge context across all relevant scopes in a single call.

```python theme={null}
await sdk.fetch(conversation_id=None, user_id=None, customer_id=None, search_query=None, max_results=20, types=None, mode="fast", precision_level="high", include_conversation_context=True, scopes=None, include_scope_labels=False, context_mode="in-conversation", include_profile=True, last_n_conversations=1)
```

The recommended entry point for framework integrations. `fetch()` queries every scope you provide an identifier for in parallel, deduplicates the merged items (first scope wins), attributes each item to its source scope, optionally folds in the conversation's compacted history plus recent messages, and returns a ready-to-inject `formatted_context` string. Pass it the identifiers you have on hand for the current turn (conversation, user, customer) and use the resulting `formatted_context` directly in your LLM prompt.

### Parameters

<ParamField path="conversation_id" type="str" required={false}>
  Conversation scope identifier. When provided, the conversation scope is queried and (unless disabled) the conversation's compacted history is included. Must be a valid UUID (e.g. `str(uuid.uuid4())`) [registered via `record_message`](/concepts/context-end-to-end#short-term-context).
</ParamField>

<ParamField path="user_id" type="str" required={false}>
  User scope identifier. Threaded into the conversation-scope sub-fetch so per-user privacy filtering applies.
</ParamField>

<ParamField path="customer_id" type="str" required={false}>
  Customer scope identifier. Required on B2B; auto-resolved on B2C. See [B2C vs B2B](/concepts/memory-scopes#b2c-vs-b2b-which-scopes-apply-to-you). Required for B2B deployments where customer-scoped context is in use.
</ParamField>

<ParamField path="search_query" type="list[str]" required={false}>
  Search queries applied to all queried scopes. Defaults to `None` (no query-side filtering).
</ParamField>

<ParamField path="max_results" type="int" required={false}>
  Maximum results per scope. The merged total may be higher across scopes. Defaults to `20`.
</ParamField>

<ParamField path="types" type="list[str]" required={false}>
  Memory types to include. Defaults to `None`, which means all types.
</ParamField>

<ParamField path="mode" type="str" required={false}>
  Retrieval mode: the retrieval axis (`fast` vs `accurate`) of [Retrieval Modes](/concepts/retrieval-modes). `"fast"` (default) or `"accurate"`.
</ParamField>

<ParamField path="precision_level" type="str" required={false}>
  Result precision: `"high"` (default) or `"medium"`. With `"high"`, 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`. For real latency on your instance, see **Dashboard → Usage**.
</ParamField>

<ParamField path="include_conversation_context" type="bool" required={false}>
  Include the conversation's compacted history plus recent messages in the result. Defaults to `True`. Only effective when `conversation_id` is also provided.
</ParamField>

<ParamField path="scopes" type="list[str]" required={false}>
  Explicitly limit which scopes to query (e.g. `["user", "customer"]`). Defaults to `None`, which queries every scope for which an identifier was provided.
</ParamField>

<ParamField path="include_scope_labels" type="bool" required={false}>
  Annotate each item with its source scope in the `formatted_context` output. Defaults to `False`.
</ParamField>

<ParamField path="context_mode" type="str" required={false}>
  `"in-conversation"` (default) returns the usual merged item lists. `"conversation-summary"` instead returns a caller `profile` plus summaries of the last `last_n_conversations` conversations: the call-start read for async integrations. Requires `user_id`. These three summary-mode params are forwarded **only** to the user-scope sub-fetch (the other scopes reject summary mode). In summary mode `search_query`, `mode` and `precision_level` are ignored (it is an assembly, not a retrieval), and `customer_id` is required on B2B.
</ParamField>

<ParamField path="include_profile" type="bool" required={false}>
  Summary mode only: include the caller profile. Defaults to `True`.
</ParamField>

<ParamField path="last_n_conversations" type="int" required={false}>
  Summary mode only: how many previous conversations to summarize. Defaults to `1`. Range 0–20.
</ParamField>

### Returns

A `UnifiedContextResponse` with merged items, scope attribution, and a `formatted_context` string ready for LLM injection.

<ResponseField name="profile" type="UserProfileModel | None">
  Summary mode only: the caller profile (`attributes`, `overview`, `extras`, `meta`). `None` outside summary mode.
</ResponseField>

<ResponseField name="conversations" type="list[ConversationSummaryModel] | None">
  Summary mode only: previous-conversation summaries. `None` outside summary mode.
</ResponseField>

<ResponseField name="formatted_context" type="str">
  Pre-formatted context block you can drop straight into an LLM prompt. Honors `include_scope_labels` and `include_conversation_context`.
</ResponseField>

<ResponseField name="scopes_queried" type="list[str]">
  The scopes that were actually queried for this call, in order.
</ResponseField>

<ResponseField name="scope_map" type="dict[str, str]">
  Mapping from item ID to the scope that produced it after deduplication.
</ResponseField>

<ResponseField name="conversation_context" type="object | None">
  When `include_conversation_context=True` and a `conversation_id` was supplied, the conversation's compacted history and recent messages. `None` otherwise.
</ResponseField>

### Example

```python theme={null}
import uuid
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()

# conversation_id must be a valid UUID; reuse the conversation's id
conversation_id = str(uuid.uuid4())

# Fetch everything for a conversation turn.
ctx = await sdk.fetch(
    conversation_id=conversation_id,
    user_id="user-456",
    customer_id="cust-789",
    search_query=["user preferences"],
)
prompt = ctx.formatted_context  # Drop into your LLM system prompt.

# Fetch only user + customer context (skip conversation scope).
ctx = await sdk.fetch(
    user_id="user-456",
    customer_id="cust-789",
    scopes=["user", "customer"],
)
```

### Conversation-summary mode (call start)

For async integrations, fire one summary-mode fetch at call connect, keyed by the caller's identity. It resolves a caller profile plus the last call's summary (no retrieval, pure assembly), and folds them into `formatted_context` as `## Caller Profile` and `## Previous Conversations` sections.

```python theme={null}
ctx = await sdk.fetch(
    user_id="+919812345678",
    context_mode="conversation-summary",
    include_profile=True,
    last_n_conversations=1,
)
prompt_block = ctx.formatted_context   # "## Caller Profile ..." + "## Previous Conversations ..."
```

The call-end counterpart is [`conversation.ingest_transcript`](/sdk-reference/conversation/ingest-transcript).

### Raises

* `InvalidInputError`: when `precision_level` is not `"high"` or `"medium"`.
* `AuthenticationError`: when the SDK has not been initialized (call `await sdk.initialize()` first).

Per-scope fetch failures are logged and skipped rather than raised, so a partial-scope outage still returns the scopes that succeeded. See [Error Codes](/sdk-reference/errors) for the full SDK exception hierarchy.

### See also

* [initialize](/sdk-reference/lifecycle/initialize): required before calling `fetch`.
* [as\_tool](/sdk-reference/lifecycle/as-tool): expose `fetch` to an LLM as a tool definition.