fetch

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

str

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.

str

User scope identifier. Threaded into the conversation-scope sub-fetch so per-user privacy filtering applies.

str

Customer scope identifier. Required on B2B; auto-resolved on B2C. See B2C vs B2B. Required for B2B deployments where customer-scoped context is in use.

list[str]

Search queries applied to all queried scopes. Defaults to None (no query-side filtering).

int

Maximum results per scope. The merged total may be higher across scopes. Defaults to 20.

list[str]

Memory types to include. Defaults to None, which means all types.

str

Retrieval mode: the retrieval axis (fast vs accurate) of Retrieval Modes. "fast" (default) or "accurate".

str

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.

bool

Include the conversation’s compacted history plus recent messages in the result. Defaults to True. Only effective when conversation_id is also provided.

list[str]

Explicitly limit which scopes to query (e.g. ["user", "customer"]). Defaults to None, which queries every scope for which an identifier was provided.

bool

Annotate each item with its source scope in the formatted_context output. Defaults to False.

str

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

bool

Summary mode only: include the caller profile. Defaults to True.

int

Summary mode only: how many previous conversations to summarize. Defaults to 1. Range 0–20.

Returns

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

UserProfileModel | None

Summary mode only: the caller profile (attributes, overview, extras, meta). None outside summary mode.

list[ConversationSummaryModel] | None

Summary mode only: previous-conversation summaries. None outside summary mode.

str

Pre-formatted context block you can drop straight into an LLM prompt. Honors include_scope_labels and include_conversation_context.

list[str]

The scopes that were actually queried for this call, in order.

dict[str, str]

Mapping from item ID to the scope that produced it after deduplication.

object | None

When include_conversation_context=True and a conversation_id was supplied, the conversation’s compacted history and recent messages. None otherwise.

Example

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.

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.

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 for the full SDK exception hierarchy.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

Parameters

Returns

Example

Conversation-summary mode (call start)

Raises

See also

​Parameters

​Returns

​Example

​Conversation-summary mode (call start)

​Raises

​See also

Parameters

Returns

Example

Conversation-summary mode (call start)

Raises

See also