Skip to main content
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",
    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

​
conversation_id
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.
​
search_query
List[str]
Optional list of query strings to bias retrieval. When omitted, the most relevant recent context is returned.
​
max_results
int
default:"10"
Maximum number of items to return per context type.
​
types
List[str]
Context types to include. Defaults to all available types (facts, preferences, episodes, emotions, temporal events).
​
mode
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.
​
user_id
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.
​
customer_id
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.
​
facts
List[Fact]
Facts learned about the user during this conversation.
​
preferences
List[Preference]
Stated or inferred preferences relevant to this conversation.
​
episodes
List[Episode]
Episodic memories tied to this conversation.
​
emotions
List[Emotion]
Detected emotional signals.
​
temporal_events
List[TemporalEvent]
Time-anchored events relevant to the conversation.
​
conversation_context
Dict[str, Any]
Compacted/summary context for this conversation, when available.
​
metadata
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".
  • AuthenticationError — when the API key is missing or invalid.
  • NetworkError — when the SDK cannot reach Synap.

​
See also