customer.context.fetch

await sdk.customer.context.fetch(
    customer_id,
    conversation_id=None,
    search_query=None,
    max_results=10,
    types=None,
    mode="fast",
    precision_level="high",
)

Retrieve context scoped to a specific customer organization. Customer-scoped memories are visible to all users within that customer. This is useful for fetching shared organizational knowledge, company policies, and team-wide context.

Parameters

string

required

The customer identifier to fetch context for. Required on B2B; auto-resolved on B2C. See B2C vs B2B.

string

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.

string | string[]

One or more search queries to find relevant customer memories. If omitted, returns the most recent and highest-confidence customer-scoped memories.

integer

Maximum number of memory items to return. Defaults to 10. Maximum 50.

string[]

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

string

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.

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

string

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

Value	Description
`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.

Returns

A ContextResponse with the following fields:

array

Array of fact memories relevant to the query.

array

Array of preference memories.

array

Array of episode memories.

array

Array of emotion memories.

object

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}")

Response

{
  "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".
InvalidInputError: when precision_level is not "high" or "medium".
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.

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

Raises

See also

​Parameters

​Returns

​Example

​Raises

​See also

Parameters

Returns

Example

Raises

See also