Skip to main content
A retriever is a named search configuration on a knowledge base. It decides how an end user’s question finds the right passages, how much surrounding context each match keeps, and how many results reach the agent. Every question follows the same path through a retriever, and each stage of that path is a setting you can change.
A question moves through the query transform, the search strategy, the results-to-retrieve cap, the re-rank refinement and the results-to-keep limit before reaching the agent.

​
Many retrievers, one live default

A knowledge base can hold several retrievers side by side. The retriever carrying the Default badge is the live default, and it answers every live query. The other retrievers exist to be compared. You can test any indexed retriever, run it in an experiment, and promote it with Make default from its card menu. Promotion swaps the live default without rebuilding anything. Configure a retriever describes the Retriever tab, its cards, and every notice it can show.

​
Presets and the custom path

Add retriever opens a picker with three ready-made presets, one per search strategy. The picker recommends Vector search as the right first choice for most agents.
The Add a retriever picker with the Vector search, Keyword + vector blend, Keyword / exact terms and Custom retriever cards
The fourth card, Custom retriever, opens the Build from scratch dialog. There you choose the index, the chunking, the embedding model, the query transform, the search strategy, and the refinement yourself. The rest of this page explains what those choices mean.

​
Search strategies

The Search setting picks how a retriever matches text. The meaning-based strategies read the Embedding model setting. OpenAI · 3-small is the default. The two Cohere models show Not available right now when the Cohere provider is unavailable.

​
Query transforms

A retriever can transform the question before it searches. The Query setting selects the transform, and each option carries a short description.

​
Chunking and parent context

Documents are split into chunks before indexing, and the Index setting controls how. Two options ship today. Contextual chunks and Summary index appear disabled as “(coming soon)”. Standard chunks cuts documents into fixed-size pieces, with an overlap so sentences are not cut at the boundaries. Parent-child indexes small child chunks for precise matching. At answer time, each matched child is swapped for its larger parent, so the agent receives the wider section around the match. Long documents keep their context this way.
A side-by-side contrast of standard chunking into fixed-size pieces with overlap and parent-child chunking where small indexed children are swapped for their larger parents.

​
Re-ranking and result limits

Results to retrieve caps how many passages reach the agent for each question. More passages give the agent more to work with but cost more tokens. The Refinement setting adds an optional second pass. Choose Re-rank top results to reorder a wider set of passages with a more accurate model. The Passages to re-rank field sets the size of that wider set. The Results to retrieve field keeps only the best of them. When the count is still at its default of 5, choosing re-ranking raises it to 20, since re-ranking works best with a wider net. Re-ranking requires the Cohere provider and trades a little latency for cleaner input to the agent.

​
Indexes and serving

A retriever stays out of the agent’s Knowledge tool until its first index build finishes, and you cannot test or compare it before then.
How a retriever index moves between Not indexed, Indexing, Ready, Needs reindex, Updating index and Error
Retrievers with the same indexing settings can share one index. When a knowledge base has several retrievers, each card shows an index letter, such as Index A. Retrievers with the same letter share one index, and reindexing any of them rebuilds it for all. Changing a setting under How it’s indexed rebuilds the index, and the retriever keeps answering from the old one until the new one is ready. A stale retriever never goes silent. When documents change after a build, the retriever keeps answering from the index it already has. The amber “needs reindexing” alerts exist to tell you that live answers are behind your documents. Each card carries an Auto or Manual badge for its reindex mode. With Auto, a scheduled crawl starts the reindex, while your manual edits always wait for a reindex you start. While any retriever is building its index, the knowledge base locks document changes with the tooltip Locked while a retriever is building. See Manage documents for the reindex flow.

​
The chunk limit

Every index stores your documents as chunks. On the Free plan, the organization can store up to 1,000 chunks across all its knowledge bases. Premium and Enterprise plans have no chunk limit by default.
  • Each stored chunk counts once.
  • Retrievers with the same index settings share one index, so they count once. A retriever with a different chunk size or embedding model stores another copy and counts again.
  • A deleted document frees its chunks at the next reindex of its retriever.
At the limit, indexing keeps the documents that fit and skips the rest. Your agents keep answering from what is already stored. Only new content waits until you free up chunks or upgrade. See The chunk limit for the screens.

​
Testing a retriever by hand

Test retriever in a card’s menu opens a dialog that searches that one retriever and shows which chunks it retrieves. With Media search on, it also shows the media it ranks. For the steps, see The Test retriever dialog. Each result carries a Score badge that ranks results within this retriever only. Each search strategy scores on its own scale, so scores are not comparable across retrievers.

​
Measuring retrieval quality

Hand testing shows single answers, while the Dataset and Experiments tabs measure quality across many questions at once. See Measure retrieval quality.

​
Deleting is reversible

A deleted retriever moves to Recently deleted for 30 days. If no other retriever uses its index, Tars removes the index immediately. A restored retriever shows Needs indexing, and the restore message asks you to reindex it before it can answer. The reindex reuses the index if another retriever still uses it. Organization admins can also purge a deleted retriever immediately with Delete forever. The last indexed retriever of a knowledge base cannot be deleted. Index another retriever first.