Skip to main content

Overview

Context fetch is how your AI agent gets relevant context from stored memories. When your agent needs to know a user’s preferences, recall past conversations, or understand organizational context, it calls the retrieval API. Synap returns a structured ContextResponse containing facts, preferences, episodes, and emotions ranked by relevance to the query. Context fetch is designed to sit in your agent’s hot path: the fast mode is lower-latency than accurate, making it suitable for real-time conversation flows.
A brand-new conversation (or a user/scope with nothing ingested yet) returns an empty ContextResponse, not an error. The typed lists (facts, preferences, episodes, emotions, temporal_events) come back empty. Check for emptiness rather than catching an exception for the cold-start case. ContextNotFoundError is reserved for a context resource that is genuinely missing/removed, and a malformed (non-UUID) conversation_id raises InvalidInputError. See Error Handling for the per-method breakdown.

Conversation Context

The primary retrieval interface is sdk.conversation.context.fetch(). It returns context relevant to a specific conversation, enriched with memories from the user’s broader history.

Key parameters

conversation_id is the only required argument; it must be a valid UUID string (generate one with str(uuid.uuid4()) or reuse a UUID you already manage). The remaining arguments shape retrieval: search_query (one or more semantic queries, merged and re-ranked when you pass several), max_results (default 10), mode (fast or accurate; see Retrieval Modes below), and types. There is also an optional precision_level ("high", the default, or "medium"): "medium" gives you faster responses with less precisely filtered results — recall isn’t impacted. See Precision level below. For the types filter on conversation.context.fetch(), the accepted string values are the plural forms plus "all": "facts", "preferences", "episodes", "emotions", "temporal", and "all". Omitting types returns every type.
Full parameter reference → Every argument, including the recommended user_id / customer_id scoping hints, is documented field-by-field in conversation.context.fetch.

Retrieval Modes

Synap offers two retrieval modes that trade off latency against comprehensiveness.
Aspectfastaccurate
Search methodVector + graph (no LLM subquery decomposition)Vector + graph + LLM subquery decomposition + reranking
Best forReal-time chat, low-latency requirementsComplex queries, relationship-aware context
RankingSimilarity + graph signalsMulti-signal ranking (similarity + recency + graph centrality + LLM rerank)
Start with fast mode. Switch to accurate when you need relationship-aware context, such as queries that span multiple entities (“What did Alice say about the project Bob is leading?”).
Retrieval mode values (fast / accurate) are distinct from ingestion mode values (fast / long-range). They control different stages of the pipeline and are not interchangeable: passing "long-range" to context.fetch() or "accurate" to memories.create() will be rejected.

When to Use Each Mode

Use fast when...

  • You are in a real-time conversation flow
  • The query is about a single topic or entity
  • You need the lowest-latency retrieval path
  • You are retrieving frequently (e.g., every turn)

Use accurate when...

  • The query involves relationships between entities
  • You need context spanning multiple conversations
  • You are building a comprehensive summary
  • You can afford additional latency for LLM-driven query decomposition and reranking

Precision level

Every context fetch also accepts an optional precision_level parameter that controls how tightly results are filtered before they are returned.
precision_levelBehavior
highResults go through an additional relevance-refinement pass before being returned. Default.
mediumSkips the refinement pass for faster responses. Recall isn’t impacted — the same candidate memories are searched — but outputs are less precisely filtered.
precision_level is independent of both mode axes — combine it with either fast or accurate retrieval (it does not apply to ingestion). Passing any value other than "high" or "medium" raises InvalidInputError. For real latency on your instance, see Dashboard → Usage.
Keep high for most integrations; drop to medium on latency-critical hot paths where a few extra loosely-related items are acceptable.

Response Structure

The ContextResponse object contains structured memory types and metadata.
A ContextResponse is a bag of typed memory items: facts, preferences, episodes, emotions, and temporal_events, plus a metadata object. Each list is empty when nothing relevant was found, so iterate defensively. The examples below show the fields you reach for most often; the complete Pydantic signatures for every type live in the reference.
Full response reference → Response Shapes is the single source of truth for every field on Fact, Preference, Episode, Emotion, TemporalEvent, ContextResponse, and ResponseMetadata.

Facts

Facts are discrete, verified pieces of information extracted from memories.

Preferences

Preferences capture user likes, dislikes, and stated preferences. Note that the certainty signal on a Preference is strength (not confidence as on Fact), and the text is in content grouped by category.

Episodes

Episodes represent summarized narrative segments from past interactions. The narrative text is in summary (not content), ranked by significance.

Emotions

Emotions capture detected emotional states and sentiment from interactions, scored by intensity.

Temporal Events

Time-bound events with explicit start and (optionally) end markers, e.g., “user’s subscription renews on 2026-08-12”.

Response Metadata

Every ContextResponse includes metadata about the retrieval operation.
Log metadata.correlation_id for debugging and support inquiries. metadata.source tells you where the response came from ("cache", "cloud", or "anticipation"), and metadata.ttl_seconds is how long the local cache treats it as fresh.
metadata.compaction_applied is not a boolean. It is None when no compaction ran, or a CompactionLevel enum value when one did, so always test with if meta.compaction_applied is not None rather than a truthiness check. The strategy-named members (adaptive, aggressive, balanced, conservative) are the ones you’ll typically see on retrieval. See CompactionLevel for the full enum.

Scoped Retrieval

In addition to conversation-level retrieval, Synap provides scope-specific interfaces for retrieving memories at the user, customer, and client levels.

User Context

Retrieve all memories scoped to a specific user, across all their conversations.

Customer Context

Retrieve memories shared across all users within a customer (organization/tenant).

Client Context

Retrieve memories at the broadest scope, across all customers and users within your Synap client.
Scoped retrieval respects Synap’s scope hierarchy. User context includes user-scoped memories. Customer context includes customer-scoped memories visible to all users in that customer. Client context includes client-wide memories. Higher scopes never leak memories from narrower scopes unless those memories were explicitly created at the broader scope. See Memory Scopes for details.
Full parameter reference → Each scoped method has its own reference page with the complete argument list and per-scope types values: user.context.fetch, customer.context.fetch, and client.context.fetch.

The types Filter

Use the types parameter to retrieve only specific memory types. This reduces response size and processing time when you only need certain kinds of context.

Search Queries

The search_query parameter drives semantic search. Synap matches your queries against stored memories using both semantic similarity and graph relationships.

Single Query

Multiple Queries

When you provide multiple queries, Synap runs each independently and merges the results with deduplication and re-ranking.
Use multiple queries to broaden recall when a single query might miss relevant memories. For example, a user asking “What should I eat?” might benefit from queries about dietary preferences, allergies, and favorite cuisines simultaneously.

No Query (Recency-Based)

When search_query is omitted, retrieval returns the most recent and contextually relevant memories for the conversation without semantic filtering.

The .raw Property

For forward compatibility with future Synap API changes, every response object exposes a .raw property containing the unprocessed API response as a dictionary.
The .raw property is useful when Synap adds new fields to the API response that have not yet been mapped to typed SDK properties. You can access new fields immediately without waiting for an SDK update.

Full Example: System Prompt Injection

The most common use case for context fetch is injecting contextual memories into your LLM’s system prompt.
For long-running conversations, combine context.fetch() with get_context_for_prompt() for a hybrid approach: compacted history provides broad context while retrieval provides query-specific details. See the Context Compaction guide for examples of this pattern.

Next Steps

Entity Resolution

Learn how entities are resolved to improve retrieval quality.

Context Compaction

Compress context to reduce LLM token costs.

Ingestion

Feed more data into Synap to enrich retrieval results.

Memory Scopes

Understand how scope filtering affects retrieval boundaries.