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

string
required
The user identifier to fetch context for. Must match a user_id you’ve previously ingested or initialized a conversation for.
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.
string | string[]
One or more search queries to find relevant user memories. If omitted, returns the most recent and highest-confidence user-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.
string
Retrieval mode that controls the speed-quality tradeoff: the retrieval axis (fast vs accurate) of Retrieval Modes.For real per-mode latency on your instance, see Dashboard → Usage.
string
Controls how precisely results are filtered before they’re returned.Independent of mode; combine with either fast or accurate. For real latency on your instance, see Dashboard → Usage.
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.
string
"in-conversation" (default) returns the usual item lists. "conversation-summary" instead returns a caller profile and summaries of the last last_n_conversations conversations: the call-start read for async integrations. In summary mode search_query, mode and precision_level are ignored, and customer_id is required on B2B.
boolean
Summary mode only: include the caller profile. Defaults to True.
integer
Summary mode only: number of previous conversations to summarize. Defaults to 1. Range 0–20.

Returns

A ContextResponse with the following fields:
array
Array of fact memories relevant to the query. Each includes content, confidence, entities, source, and relevance_score.
array
Array of preference memories.
array
Array of episode memories.
array
Array of emotion memories.
array
Array of time-bound event memories.
object
Response metadata including correlation_id, source (cache | cloud | anticipation), ttl_seconds, and retrieved_at.
UserProfileModel | None
Summary mode only: the caller profile (attributes, overview, extras, meta, plus .raw). None outside summary mode.
array | None
Summary mode only: a list of ConversationSummaryModel (per-call summary, classification, analysis, summary_status, timestamps). None outside summary mode.

Example

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 user_id does not exist for this instance.

See also