conversation.context.fetch

await sdk.conversation.context.fetch(
    conversation_id: str,
    search_query: Optional[List[str]] = None,
    max_results: int = 10,
    types: Optional[List[str]] = None,
    mode: str = "fast",
    precision_level: str = "high",
    user_id: Optional[str] = None,
    customer_id: Optional[str] = None,
) -> ContextResponse

Retrieves the context Synap has built up for a single conversation: facts surfaced from earlier turns, user preferences, episodic memories, emotional cues, and temporal events. Use this to assemble grounding material before generating the next assistant turn. Passing user_id (and customer_id) is strongly recommended: it scopes the in-process anticipation cache to that user so bundles prefetched for one user can never be served on another user’s lookup. These will become required in a future release.

Parameters

str

required

The conversation to fetch context for. Must be a valid UUID (e.g. str(uuid.uuid4())), the same id you used when recording the conversation’s messages.

List[str]

Optional list of query strings to bias retrieval. When omitted, the most relevant recent context is returned.

int

default:"10"

Maximum number of items to return per context type.

List[str]

Context types to include. Defaults to all available types (facts, preferences, episodes, emotions, temporal events).

str

default:"fast"

Retrieval mode: the retrieval axis (fast vs accurate) of Retrieval Modes:

"fast": direct query, lower latency. Best for in-the-loop prompt assembly.
"accurate": LLM-enhanced queries, higher quality at higher latency. Best when you can afford the extra latency.

For real per-mode latency on your instance, see Dashboard → Usage.

str

default:"high"

Controls how precisely results are filtered before they’re returned:

"high": results go through an additional relevance-refinement pass before being returned. Default.
"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.

str

External user id. Strongly recommended: scopes anticipation cache lookups to the right user and avoids deriving scope from a not-yet-written conversation row.

str

External customer id, forwarded alongside user_id for the same scoping reason. Required on B2B; auto-resolved on B2C. See B2C vs B2B.

Returns

A ContextResponse containing the retrieved context.

List[Fact]

Facts learned about the user during this conversation.

List[Preference]

Stated or inferred preferences relevant to this conversation.

List[Episode]

Episodic memories tied to this conversation.

List[Emotion]

Detected emotional signals.

List[TemporalEvent]

Time-anchored events relevant to the conversation.

Dict[str, Any]

Compacted/summary context for this conversation, when available.

ResponseMetadata

Correlation id, source (cache or cloud), TTL, and retrieval timestamp.

Example

import uuid
from maximem_synap import MaximemSynapSDK

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

# reuse the same conversation_id you recorded messages under
conversation_id = str(uuid.uuid4())

ctx = await sdk.conversation.context.fetch(
    conversation_id=conversation_id,
    search_query=["dinner plans", "dietary restrictions"],
    max_results=5,
    mode="fast",
    user_id="user_alice",
    customer_id="customer_acme",
)

for fact in ctx.facts:
    print(fact.content)

Raises

InvalidInputError: when mode is not "fast" or "accurate".
InvalidInputError: when precision_level is not "high" or "medium".
AuthenticationError: when the API key is missing or invalid.
NetworkError: when the SDK cannot reach Synap.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation