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 structuredContextResponse 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 issdk.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.| Aspect | fast | accurate |
|---|---|---|
| Search method | Vector + graph (no LLM subquery decomposition) | Vector + graph + LLM subquery decomposition + reranking |
| Best for | Real-time chat, low-latency requirements | Complex queries, relationship-aware context |
| Ranking | Similarity + graph signals | Multi-signal ranking (similarity + recency + graph centrality + LLM rerank) |
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 optionalprecision_level parameter that controls how tightly results are filtered before they are returned.
precision_level | Behavior |
|---|---|
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. |
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.
Response Structure
TheContextResponse object contains structured memory types and metadata.
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 aPreference 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 insummary (not content), ranked by significance.
Emotions
Emotions capture detected emotional states and sentiment from interactions, scored byintensity.
Temporal Events
Time-bound events with explicit start and (optionally) end markers, e.g., “user’s subscription renews on 2026-08-12”.Response Metadata
EveryContextResponse includes metadata about the retrieval operation.
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.
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
Thesearch_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.No Query (Recency-Based)
Whensearch_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.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.