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

Conversation-Summary Mode (Conversation Start)

fetch() and user.context.fetch() accept context_mode="conversation-summary": the conversation-start read for async integrations. Instead of retrieving item lists, it assembles the user’s profile plus summaries of their last n conversations (what each was about and how it progressed). It runs no search and no LLM work (it returns the stored profile and precomputed summaries), so it is fast enough to fire the moment a conversation begins, before your agent’s first reply.
The profile half of this mode is on by default. See the User Profile guide for defining your critical-attribute schema (or opting out per instance).
Behavior notes:
  • Requires user_id. On B2B instances customer_id is also required (the same user identifier under two different customers refers to two different people).
  • search_query, mode and precision_level are ignored: this is an assembly, not a retrieval.
  • In the unified sdk.fetch, the three summary params are forwarded only to the user-scope sub-fetch.
  • last_n_conversations=0 with include_profile=False is valid: you get an empty result, not an error.
  • A conversation whose summary hasn’t landed yet reports summary_status="pending" (or "failed"); the conversation still appears in the list.
The call-end counterpart is conversation.ingest_transcript. Full reference: fetch and user.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.