Skip to main content
await sdk.user.context.fetch(
    user_id,
    conversation_id=None,
    search_query=None,
    max_results=10,
    types=None,
    mode="fast",
    customer_id=None,
)
Fetch context scoped to a single end user. User-scoped memories capture personal facts, preferences, and history that the SDK has accumulated for this user across their conversations. Use this on the server before composing a prompt so the model can ground its response in what you already know about the person.

​
Parameters

​
user_id
string
required
The user identifier to fetch context for. Must match a user_id you’ve previously ingested or initialized a conversation for.
​
conversation_id
string
Optional conversation identifier. When provided, results are biased toward memories relevant to the active conversation and the SDK can inject periodic user summaries into the response. When supplied, it must be a valid UUID (e.g. str(uuid.uuid4())) registered via record_message.
​
search_query
string | string[]
One or more search queries to find relevant user memories. If omitted, returns the most recent and highest-confidence user-scoped memories.
​
max_results
integer
Maximum number of memory items to return. Defaults to 10. Maximum 50.
​
types
string[]
Filter results to specific memory types. If omitted, all types are included.
ValueDescription
factFactual information about the user
preferenceStated or inferred user preferences
episodeNotable events from the user’s history
emotionSentiment and emotional context
temporal_eventTime-bound events (deadlines, appointments, recurring dates)
​
mode
string
Retrieval mode that controls the speed-quality tradeoff — the retrieval axis (fast vs accurate) of Retrieval Modes.
ValueDescription
fastVector search only. Lower latency. Default.
accurateFull vector + graph + re-ranking. Higher quality, higher latency.
For real per-mode latency on your instance, see Dashboard → Usage.
​
customer_id
string
Customer identifier the user belongs to. Required on B2B; auto-resolved on B2C — see B2C vs B2B. Required for B2B instances. For B2C instances, this is auto-resolved from user_id and can be omitted.

​
Returns

A ContextResponse with the following fields:
​
facts
array
Array of fact memories relevant to the query. Each includes content, confidence, entities, source, and relevance_score.
​
preferences
array
Array of preference memories.
​
episodes
array
Array of episode memories.
​
emotions
array
Array of emotion memories.
​
temporal_events
array
Array of time-bound event memories.
​
metadata
object
Response metadata including correlation_id, source (cache | cloud | anticipation), ttl_seconds, and retrieved_at.

​
Example

import uuid
from maximem_synap import MaximemSynapSDK

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

context = await sdk.user.context.fetch(
    user_id="user_jane_doe",
    conversation_id=str(uuid.uuid4()),  # must be a valid UUID
    search_query=["dietary restrictions", "favorite restaurants"],
    max_results=5,
    types=["fact", "preference"],
    mode="accurate",
)

for fact in context.facts:
    print(f"[{fact.confidence:.2f}] {fact.content}")

for pref in context.preferences:
    print(f"prefers: {pref.content}")

​
Raises

  • InvalidInputError — when mode is not "fast" or "accurate".
  • SDKNotInitializedError — when called before await sdk.initialize().
  • AuthenticationError — when the API key is invalid or revoked.
  • ContextNotFoundError — when user_id does not exist for this instance.

​
See also