Contextual Retrieval

Have a model write a short context for every passage, so passages that lean on their document are found — what it costs, when it helps, and what we measured.

A passage cut from a document often leans on the rest of it. "Either party may terminate this agreement with 30 days' notice" does not say which agreement; in a base of forty contracts, a question about one supplier's notice period has forty identical clauses to choose from.

By default each passage is indexed after a line naming its document, date and section — free, and often enough. Contextual Retrieval goes further: while a document is indexed, a model reads it and writes one or two sentences placing each passage in it — "This clause is from the 2025 master services agreement between Acme and Globex Payroll, on terminating the payroll service." The context is indexed with the passage, so both the keyword and the meaning search see it.

It is off unless a base turns it on.

When it helps

Many documents with the same sections — contracts, policies, tickets, product sheets — where a passage does not name its subject.
Questions in other words than the documents. The context supplies words the passage lacks.

It helps least where documents already name themselves on every page, as reports and standards often do: there the free line carries most of what a context would add.

The way to know is to measure on your own documents. Turning it on builds a new index beside the old one, and Evaluate can run the same questions against both — the old index is kept for a week.

What we measured

On seven NIST publications (373 pages, cut into 1,219 passages), with 27 questions drafted from them — 11 asked plainly, 10 in other words, 6 needing two documents — embedded with text-embedding-3-small, no reranker, and contexts written by gpt-4.1-nano. The share of questions whose answer was in the top passages, as a search serves them:

Questions	Top 1	Top 3	Top 5	Top 10	MRR	nDCG@10
All 27	48% → 44%	56% → 67%	67% → 70%	70% → 74%	0.551 → 0.563	0.547 → 0.566
In other words (10)	20% → 20%		30% → 40%		0.237 → 0.287	0.275 → 0.337
Asked plainly (11)	73% → 64%		91% → 91%		0.795 → 0.773	0.824 → 0.808
Two documents (6)	50% → 50%		83% → 83%		0.625 → 0.639	0.495 → 0.501

The free line → Contextual Retrieval.

A small gain, mostly on questions asked in other words; answers missing from the top 10 fell from 30% to 26% of questions. With 27 questions every difference is one to three of them, and one plainly asked question lost its first place. These documents name themselves on every page, which is where the free line does best. Anthropic's published result — a third fewer misses — was on code and papers, with contexts written by Claude and 20 passages per search. Your documents will differ, which is why the measuring tool is built in.

The whole run cost $0.80 at list price ($0.78 of it the contexts), about $0.48 after OpenAI's cache discount, and took an hour on an entry-level OpenAI account, waiting out its rate limit.

What it costs

One model call per passage, so the cost follows the number of passages — how much text there is and how it is cut — not the number of pages.

Each call reads the passage's document: the whole document when it is up to 16,000 tokens; otherwise its first 1,500 tokens and the 12,000-token stretch around the passage. Every passage of the same stretch is asked with the same text first, so a provider that caches a repeated prompt start charges far less for the second call onward. Anthropic, Amazon Bedrock, OpenAI and DeepSeek do, on your own key.

On SynapseOrch Cloud, SynapseOrch's own Nova models are cached too: a stretch's first call writes it to the cache at no extra charge, and each call after it reads it at a quarter of the input price. With Nova Lite, the default, that is about $6 per 1,000 twenty-page documents, where paying for every stretch in full would be about $18. SynapseOrch's own Claude models are not cached yet.

The price is shown before anything is spent: turning it on rebuilds the index, and the settings show Writing contexts: 1,219 requests with … — $… before you save.

Turning it on

In the base's Settings, under Index, set Context for each passage to Contextual Retrieval: a model writes it, pick a Context model if you want one other than the default, and Save and rebuild.

The model is the first of:

the base's Context model;
Settings → Models → Knowledge → Contextual Retrieval model;
the workspace's default model — on SynapseOrch Cloud, Nova Lite.

A small, inexpensive model is enough. An embedding model or a CLI-session model is refused when you save. The index version records which model wrote its contexts, so changing the model — or turning Contextual Retrieval off again — is a rebuild too.

Each stretch's first context is written alone, so the provider can cache the shared text; the rest follow four at a time — on a self-hosted install, SYNAPSE_KNOWLEDGE_CONTEXT_CONCURRENCY sets how many. Reasoning is off for these calls, and each answer is at most 150 tokens.

When a context cannot be written

An empty, refused or cut-off answer is asked once more. If that fails too, the passage keeps the free line, and the report notes it.
A provider's rate limit is waited out, not failed — see Progress.
A provider that keeps failing fails the document: Failed, The model writing passages' context failed. Contexts already written are kept, so Retry writes only the rest. A refused key or an exhausted quota says so, and needs fixing first.
The budget or an empty wallet pauses the document, as for any indexing — see Budgets.