Ingestion and retrieval modes

mode= appears on two different axes. Label which one you mean:

Axis	Parameter	Values	What it does
Ingestion	`memories.create(mode=...)`	`fast` · `long-range`	Nothing today: the server accepts either value, and both run the same ingestion pipeline
Retrieval	`...context.fetch(mode=...)`	`fast` · `accurate`	How much work a read does to assemble context

The retrieval mode is the one that changes results. The ingestion mode is accepted by the server, but nothing downstream reads it, so fast and long-range extract the same memories at the same speed. See Ingestion mode below and Types and enums.

Quick comparison

Aspect	Fast	Accurate
Retrieval latency	Lower	Higher
Search method	Vector search (no graph traversal, no LLM subquery decomposition)	Vector search + graph traversal + LLM subquery decomposition + reranking
Ranking signals	Cosine similarity	Similarity + recency + graph centrality + confidence
Relationship awareness	Direct matches only: no graph traversal	Follows graph edges from the entities in your query and its best matches, with LLM-written sub-queries
Compute cost	Lower	Higher
Best for	Real-time chat, simple queries, high throughput	Complex queries, summaries, relationship-aware context

The two modes are not mutually exclusive. Use fast for the hot path of a live conversation and switch to accurate for specific high-value queries, all within the same application and the same Synap Instance.

Building a real-time chatbot or voice agent? Start with fast retrieval, then switch specific queries to accurate as needed, no architecture change required.

Fast mode

The recommended default for real-time, conversational agents where low latency matters more than exhaustive search.

Fast retrieval

Fast retrieval searches the vector store only. It never traverses the knowledge graph, and it skips the LLM-driven subquery decomposition and reranking that accurate mode adds. That keeps latency low for the hot path of real-time conversations.

Query embedding

The query is converted into a vector embedding, consistent with the embeddings created during ingestion.

Vector similarity search

The embedding is compared against stored memory embeddings using cosine similarity, scoped to the applicable scope levels (user, customer, client) based on the provided user_id and customer_id.

Ranking

Results are ranked by cosine similarity. No LLM-driven decomposition or reranking pass is applied.

Return

The top-k results (per the configured budget) are returned as structured context.

conversation_id must be a valid UUID. Generate one with str(uuid.uuid4()) and reuse it for every turn in the same conversation.

import uuid

conversation_id = str(uuid.uuid4())  # one UUID per conversation, reused across turns
context = await sdk.conversation.context.fetch(
    conversation_id=conversation_id,
    user_id="user_123",
    search_query=["What do we know about Project Atlas?"],
    mode="fast",
)

for fact in context.facts:
    print(f"[{fact.confidence:.2f}] {fact.content}")

import { randomUUID } from 'node:crypto';

let conversation_id = randomUUID();  // one UUID per conversation, reused across turns
const context = await sdk.conversation.context.fetch({
  conversation_id: conversation_id,
  user_id: 'user_123',
  search_query: ['What do we know about Project Atlas?'],
  mode: 'fast',
});

for (const fact of context.facts ?? []) {
  console.log(`[${(fact.confidence ?? 0).toFixed(2)}] ${fact.content}`);
}

import { randomUUID } from 'node:crypto';

let conversation_id = randomUUID();  // one UUID per conversation, reused across turns
const context = await sdk.conversation.context.fetch({
  conversation_id: conversation_id,
  user_id: 'user_123',
  search_query: ['What do we know about Project Atlas?'],
  mode: 'fast',
});

for (const fact of context.facts ?? []) {
  console.log(`[${(fact.confidence ?? 0).toFixed(2)}] ${fact.content}`);
}

What fast retrieval skips, relative to accurate: graph traversal (following relationship edges from the entities in the best matches to connected facts), LLM subquery decomposition (breaking a complex query into focused sub-queries to widen coverage) and reranking (an extra pass that reorders candidates for relevance). Broad, multi-part questions may therefore retrieve less complete context: those are the cases to send to accurate mode.

Accurate mode

Prioritizes thoroughness and quality over speed. It adds LLM-driven refinement on retrieval, producing richer, more connected context.

Accurate retrieval

Accurate retrieval starts from the same vector search as fast and adds three steps: graph traversal, LLM-driven subquery decomposition and reranking, together with multi-signal ranking.

Query embedding & vector search

Same as fast mode: embed the query, find candidates by cosine similarity.

LLM subquery decomposition and graph traversal

Every search query you send is searched (up to 5 per fetch); the first one is also the query the sub-queries are written from. The query is decomposed into focused sub-queries that expand the entities and angles explored. Entities from the query and top vector results seed graph traversal, following relationship edges to connected entities, related facts, and context. Querying “Project Atlas” reaches Sarah Chen, James, the database migration, the Q3 deadline, and Maria’s budget approval.

Cross-engine merging

Vector and graph results are merged into one candidate set; duplicates removed, scores normalized to a common scale.

Multi-signal ranking

Candidates are ranked on semantic similarity, recency, graph centrality, and extraction confidence, weighted into a final relevance score.

Return

The top-k results are returned as structured context, enriched with entity and relationship metadata.

import uuid

conversation_id = str(uuid.uuid4())  # one UUID per conversation, reused across turns
context = await sdk.conversation.context.fetch(
    conversation_id=conversation_id,
    user_id="user_123",
    search_query=["What do we know about Project Atlas, including who is involved and what decisions have been made?"],
    mode="accurate",
)

for fact in context.facts:
    print(f"[{fact.confidence:.2f}] {fact.content}")
    if fact.entities:
        print(f"  Entities: {', '.join(e.canonical_name for e in fact.entities)}")
    if fact.relationships:
        print(f"  Relationships: {', '.join(str(r) for r in fact.relationships)}")

import { randomUUID } from 'node:crypto';

let conversation_id = randomUUID();  // one UUID per conversation, reused across turns
const context = await sdk.conversation.context.fetch({
  conversation_id: conversation_id,
  user_id: 'user_123',
  search_query: ['What do we know about Project Atlas, including who is involved and what decisions have been made?'],
  mode: 'accurate',
});

for (const fact of context.facts ?? []) {
  console.log(`[${(fact.confidence ?? 0).toFixed(2)}] ${fact.content}`);
  if (fact.entities) {
    console.log(`  Entities: ${(fact.entities ?? []).map((e) => e.canonical_name).join(', ')}`);
  }
  if (fact.relationships) {
    console.log(`  Relationships: ${(fact.relationships ?? []).map((r) => str(r)).join(', ')}`);
  }
}

import { randomUUID } from 'node:crypto';

let conversation_id = randomUUID();  // one UUID per conversation, reused across turns
const context = await sdk.conversation.context.fetch({
  conversation_id: conversation_id,
  user_id: 'user_123',
  search_query: ['What do we know about Project Atlas, including who is involved and what decisions have been made?'],
  mode: 'accurate',
});

for (const fact of context.facts ?? []) {
  console.log(`[${(fact.confidence ?? 0).toFixed(2)}] ${fact.content}`);
  if (fact.entities) {
    console.log(`  Entities: ${(fact.entities ?? []).map((e) => e.canonical_name).join(', ')}`);
  }
  if (fact.relationships) {
    console.log(`  Relationships: ${(fact.relationships ?? []).map((r) => str(r)).join(', ')}`);
  }
}

What graph traversal adds

The same query, fast vs accurate:

Fast mode results
Accurate mode results

Returns memories that directly mention “Project Atlas”:

[0.92] Project Atlas timeline may need to shift to Q4. Q3 deadline flagged as infeasible.
[0.87] Project Atlas kickoff meeting scheduled for January 15th.
[0.81] User asked about the current status of Project Atlas.

Useful, but limited to direct mentions.

Returns the same direct mentions plus connected context discovered through graph traversal:

[0.92] Project Atlas timeline may need to shift to Q4. Q3 deadline flagged as infeasible.
[0.89] Sarah Chen from engineering is concerned about the Q3 deadline for Project Atlas.
       Entities: Sarah Chen (person, engineering)
       Relationship: Sarah Chen --[concerned_about]--> Project Atlas timeline
[0.85] James from DevOps estimates three more weeks for the infrastructure database migration
       that is blocking Project Atlas.
       Relationship: database migration --[blocks]--> Project Atlas
[0.82] Maria approved budget for two additional engineers from the platform team to
       accelerate Project Atlas delivery.
       Relationship: Maria --[approved]--> additional engineering budget
[0.78] The platform team currently has six engineers and is working on the API gateway redesign.

Traversal followed edges from Project Atlas to Sarah Chen, James, Maria, and the platform team. The last result (the platform team’s workload) was discovered by traversing to the platform team entity, even though it never mentions Project Atlas.

The relationship edges that accurate retrieval can follow depend on what extraction found in your content, not on the ingestion mode: fast and long-range writes go through the same pipeline.

Ingestion mode

memories.create, memories.batch_create (on each document) and memories.create_from_file take a mode of long-range (the default) or fast. In the current release the server accepts either value and nothing downstream reads it, so both run the same ingestion pipeline: the choice does not change what is extracted, how deeply entities are resolved or how long a write takes. You can leave mode out.

await sdk.memories.create(
    document=(
        "User: Let's revisit the Project Atlas timeline. I spoke with Sarah Chen "
        "from engineering yesterday, and she's concerned about the Q3 deadline. The "
        "infrastructure team hasn't finished the database migration yet, and James "
        "from DevOps says they need at least three more weeks.\n"
        "User: Note that we might bring in two engineers from the platform team to "
        "help accelerate. Maria approved the budget for that yesterday."
    ),
    document_type="ai-chat-conversation",
    user_id="user_123",
    # mode="long-range" is the default; "fast" currently behaves the same
)

await sdk.memories.create({
  document:
    "User: Let's revisit the Project Atlas timeline. I spoke with Sarah Chen " +
    "from engineering yesterday, and she's concerned about the Q3 deadline. The " +
    "infrastructure team hasn't finished the database migration yet, and James " +
    "from DevOps says they need at least three more weeks.\n" +
    "User: Note that we might bring in two engineers from the platform team to " +
    "help accelerate. Maria approved the budget for that yesterday.",
  document_type: 'ai-chat-conversation',
  user_id: 'user_123',
  // mode: 'long-range' is the default; 'fast' currently behaves the same
});

Extraction reads the conversation and produces entities (Sarah Chen, James, Maria, Project Atlas), relationships (Sarah —[concerned_about]—> Atlas timeline; Maria —[approved]—> budget) and facts (migration incomplete, three-week estimate, Q3 flagged infeasible). A write is not available for retrieval until it finishes; track it with memories.status.

Precision level

mode isn’t the only retrieval knob. Context fetch also accepts an optional precision_level parameter: a second, independent axis that controls how tightly results are filtered before they’re 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.

The refinement pass filters candidates rather than finding them, so dropping to medium never shrinks what’s searched. What changes is how precisely the output is filtered: expect an occasional loosely-related item in exchange for a faster response. precision_level is orthogonal to mode: combine it with either fast or accurate. For real latency on your instance, see Dashboard → Usage.

Choosing a mode

Use fast for…

Real-time conversations where the user is waiting: fast retrieval is rarely the bottleneck; LLM generation dominates response time.
Single-topic queries answerable from one memory chunk (“What is our refund policy?”, “When is Alice’s birthday?”).
High-frequency retrieval on every message, at scale: the lower compute cost matters.
Latency-sensitive apps: voice agents, real-time collaboration.

Upgrade to accurate for…

Complex, multi-entity queries: “Summarize everything about Project Atlas, who’s involved, and what’s been decided.”
Relationship queries: “How is Sarah connected to the infrastructure migration?”
Comprehensive summaries / briefings that must not miss context (latency is acceptable since they aren’t time-sensitive).
High-value interactions: escalations, renewals, executive conversations.

Mixing modes in practice

Most production apps read with fast by default and switch to accurate for the queries that justify it:

async def get_context(conversation_id, user_id, query, is_complex=False):
    return await sdk.conversation.context.fetch(
        conversation_id=conversation_id,
        user_id=user_id,
        search_query=[query],
        mode="accurate" if is_complex else "fast",
    )

A simple keyword heuristic is a reasonable starting point for automatic selection (tune it to your query patterns, or use a lightweight classifier):

def should_use_accurate_mode(query: str) -> bool:
    complex_indicators = [
        "summarize", "everything about", "full briefing",
        "who is involved", "related to", "connected to",
        "all the details", "comprehensive", "overview of",
        "history of", "timeline for",
    ]
    q = query.lower()
    return any(indicator in q for indicator in complex_indicators)

Next steps

Context Fetch SDK

Full SDK reference for retrieval methods and mode selection.

Runtime Ingestion

How runtime ingestion fits into the agent loop.

Memory Architecture

Configure ingestion and retrieval defaults in your memory architecture.

Entity Resolution

How extraction resolves entities and builds the knowledge graph.

Start here

Connecting to Synap

The memory model

Memory architecture (MACA)

How memory is processed

Ingestion and retrieval modes

Quick comparison

Fast mode

Fast retrieval

Accurate mode

Accurate retrieval

What graph traversal adds

Ingestion mode

Precision level

Choosing a mode

Mixing modes in practice

Next steps

Context Fetch SDK

Runtime Ingestion

Memory Architecture

Entity Resolution

​Quick comparison

​Fast mode

​Fast retrieval

​Accurate mode

​Accurate retrieval

​What graph traversal adds

​Ingestion mode

​Precision level

​Choosing a mode

​Mixing modes in practice

​Next steps

Context Fetch SDK

Runtime Ingestion

Memory Architecture

Entity Resolution

Quick comparison

Fast mode

Fast retrieval

Accurate mode

Accurate retrieval

What graph traversal adds

Ingestion mode

Precision level

Choosing a mode

Mixing modes in practice

Next steps