await sdk.customer.context.fetch(
customer_id,
conversation_id=None,
search_query=None,
max_results=10,
types=None,
mode="fast",
)
Parameters
The customer identifier to fetch context for. Required on B2B; auto-resolved on B2C — see B2C vs B2B. Optional conversation identifier. When provided, results are biased toward memories relevant to the active conversation. When supplied, it must be a valid UUID registered via record_message. One or more search queries to find relevant customer memories. If omitted, returns the most recent and highest-confidence customer-scoped memories.
Maximum number of memory items to return. Defaults to 10. Maximum 50.
Filter results to specific memory types. If omitted, all types are included.| Value | Description |
|---|
fact | Factual information about the customer organization |
preference | Customer organizational preferences |
episode | Significant events within the customer organization |
emotion | Sentiment and emotional context within the organization |
temporal_event | Time-bound events (project deadlines, fiscal year, etc.) |
Retrieval mode that controls the speed-quality tradeoff — the retrieval axis (fast vs accurate) of Retrieval Modes.| Value | Description |
|---|
fast | Vector search only. Lower latency. Default. |
accurate | Full vector + graph + re-ranking. Higher quality, higher latency. |
Returns
A ContextResponse with the following fields:
Array of fact memories relevant to the query.
Array of preference memories.
Array of episode memories.
Array of emotion memories.
Response metadata including total_results, query_time_ms, tokens_used, scope, and mode.
Example
from maximem_synap import MaximemSynapSDK
sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()
context = await sdk.customer.context.fetch(
customer_id="cust_acme_corp",
search_query=["project management tools", "engineering stack"],
max_results=5,
types=["fact", "preference"],
mode="accurate",
)
for fact in context.facts:
print(f"[{fact.confidence:.2f}] {fact.content}")
{
"facts": [
{
"id": "mem_cust_f1a2b3c4",
"content": "Acme Corp uses Jira for project management and Slack for communication",
"confidence": 0.94,
"entities": [
{ "canonical_name": "Acme Corp", "type": "organization", "entity_id": "ent_acme001" }
],
"source": {
"ingestion_id": "ing_cust_7a8b9c0d",
"document_type": "ai-chat-conversation",
"document_created_at": "2025-01-12T14:30:00Z"
},
"relevance_score": 0.92,
"scope": "customer"
},
{
"id": "mem_cust_d5e6f7a8",
"content": "Engineering team uses Python 3.11 and PostgreSQL for all services",
"confidence": 0.91,
"entities": [
{ "canonical_name": "Acme Corp Engineering", "type": "team", "entity_id": "ent_acme_eng" }
],
"source": {
"ingestion_id": "ing_cust_0a9b8c7d",
"document_type": "document",
"document_created_at": "2025-01-08T09:00:00Z"
},
"relevance_score": 0.88,
"scope": "customer"
}
],
"preferences": [
{
"id": "mem_cust_b9c0d1e2",
"content": "Team prefers detailed code reviews over quick approvals",
"confidence": 0.87,
"entities": [],
"source": {
"ingestion_id": "ing_cust_7a8b9c0d",
"document_type": "ai-chat-conversation",
"document_created_at": "2025-01-12T14:30:00Z"
},
"relevance_score": 0.79,
"scope": "customer"
}
],
"episodes": [],
"emotions": [],
"metadata": {
"total_results": 3,
"query_time_ms": 187,
"tokens_used": 456,
"scope": {
"customer_id": "cust_acme_corp",
"client_id": "cli_a1b2c3d4e5f67890"
},
"mode": "accurate"
}
}
Customer-scoped memories take priority over client-scoped memories when they cover the same topic, following the scope chain priority rules. To merge customer and client context in a single call, use sdk.context.fetch. 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 customer_id does not exist for this instance.
See also
