Parameters
The user identifier to fetch context for. An id you have not written memories for returns an empty result; it is not an error.
Optional conversation identifier. When provided, results are biased toward memories relevant to the active conversation and the SDK can inject periodic user summaries (every fifth fetch in a conversation) into the response. When supplied, it must be a valid UUID (e.g.
str(uuid.uuid4())) registered via record_message.One or more search queries to find relevant user memories. If omitted, the response returns the user’s profile in
profile with empty memory lists when one exists. A user without a profile follows the normal retrieval path. A single fetch searches at most 5 queries; with more, the first five are searched and the response’s retrieval.warnings says so. Send the rest in another fetch.Maximum number of memory items to return. Defaults to
10. Maximum 50. The same limit applies when the anticipation cache answers the fetch.How many items each search query may contribute when
search_query holds more than one. Without it, a query with many strong matches can take every place and a query with a single weaker match gets none. max_results stays the ceiling on the whole response: three queries at 5 each under max_results=10 return ten, not fifteen. The same allocation applies to an anticipation-cache hit. Ignored with a single query. Optional; when omitted, the best max_results items overall are returned. In JavaScript and TypeScript, pass it as max_results_per_query (or maxResultsPerQuery).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.
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.The moment the question is being asked, for example
"2023-03-11". Synap resolves a time the question names (“in March”, “two months ago”) from that moment instead of from now, which matters when you replay a past conversation. Lenient: "2023-03-11", "2023/03/11 21:26" and "2023/03/11 (Sat) 21:26" all parse, and anything unreadable silently falls back to now instead of failing the read. Not used in summary mode. Python 0.5.4 and later. JavaScript and TypeScript 0.5.4 and later, as query_date (or queryDate).How the memories come back. Pass
"ranked": you get one list, items, with the most relevant memory first across every type. Each item carries its type (category), its place (rank, from 1) and the score it was ranked by (metadata.rank_score). Quotes from your source conversations and documents come back as their own type, "excerpts", placed by their own score. You can pass the list to your model as it is: there is nothing to merge or sort.The typed lists (
facts, preferences, …) are filled either way, with one difference: the quotes from your source conversations and documents are in excerpts and not in facts, so code that reads only facts no longer sees them. The list is in rank order, but when the token budget is exceeded the cut keeps whole memory types in a fixed order, so it does not always keep the best items overall. In JavaScript and TypeScript, pass it as response_shape (or responseShape).Customer identifier the user belongs to. Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B. Required for B2B instances. On a B2C instance (
user_context_isolation: "equals_customer") it must be omitted: sending it returns HTTP 400.The level of your scope ladder to read at, for example
{"customer": "acme", "team": "payments", "user": "dana"}. Use the same customer and user as customer_id and user_id. Usually not needed: once a user has been placed at a level, by a write or a fetch that named the full path, the ids alone reach their whole chain. Send it the first time, or when the same user id sits under more than one level. Every level above the one you name must be named. A path is refused (400) if it has a gap, or if nested scoping is off or the ladder has not been accepted. In summary mode the path is checked but does not change what is read. Python 0.4.6 and later. JavaScript and TypeScript 0.4.4 and later, as scope_path (or scopePath)."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 only user_id, customer_id, include_profile and last_n_conversations are used. The search parameters, query_date and max_results_per_query are ignored, and scope_path is checked but not used. customer_id is required on B2B.Returns
AContextResponse with the following fields:
With
response_shape="ranked": every memory once, most relevant first across types. Each item has id, rank (1 is best), category (facts, preferences, episodes, emotions, temporal_events or excerpts), content, metadata.rank_score (higher is better), confidence, the date fields and matched_queries. Empty with by_type.With
response_shape="ranked": the quotes from your source conversations and documents, as their own list. With by_type they are filed under facts.Array of fact memories relevant to the query. Each includes
content, confidence, entities, source, and relevance_score. Every memory item also carries matched_queries: the search_query strings that found it, in the order you sent them. A result of a subquery the server wrote names the query it came from. In JavaScript and TypeScript, read it as matchedQueries.Response metadata including
correlation_id, source (cache | cloud | anticipation), ttl_seconds, and retrieved_at.Summary mode only: the caller profile (
attributes, overview, extras, meta, plus .raw). None outside summary mode.Summary mode only: a list of
ConversationSummaryModel (per-call summary, classification, analysis, summary_status, timestamps). None outside summary mode.Example
Ranked results
Withresponse_shape="ranked", read items in order. The most relevant memory comes first, whatever its type.
Raises
InvalidInputError: whenmode,precision_levelorresponse_shapeis not an accepted value.InvalidInputError: whenuser_idis empty (Python 0.5.13 and later; all JavaScript versions).InvalidInputError: whencontext_modeis not"in-conversation"or"conversation-summary", orlast_n_conversationsis not an integer from 0 to 20.InvalidInputError: on a B2B instance whencustomer_idis missing (the server refuses it with 400).CustomerIdNotAcceptedError, a subclass ofInvalidInputError: whencustomer_idis passed on a B2C instance (Python 0.5.12 and JavaScript 0.5.11 and later).AuthenticationErrorwith the message “SDK not initialized”: when called beforeawait sdk.initialize()(Python). JavaScript resolves the client’s identity on the first call instead.AuthenticationError: when the API key is invalid or revoked.
See also
sdk.customer.context.fetch: customer-scoped contextsdk.client.context.fetch: organizational (client) contextsdk.context.fetch: unified scope-chain fetch