An AI agent answers from the passages that its search returns, so when the prompt contains a wrong passage, the agent gives a wrong answer. In every guide in this section you start from a failure that a person would notice, such as a wrong torque figure, a citation that the source does not contain, another client's leave policy, or an allergen list that is a week out of date. You then build the files that fix it, and you can execute them against a real index before you adopt any of them.
The failures that users meet in production have ordinary causes. The authors of a 2026 paper on production retrieval systems trace the gap between a clean prototype and a reliable deployment to three root causes, which are data staleness, tenant data leakage, and what they call query composition explosion (arXiv 2605.03275). Three of the guides below are about those causes, and the other five are about what a model does with the passages that it receives.
Narsil executes each query inside your own process, so in every guide you start an engine and search it from one file, with no server to set up. Read Getting started first for the install and the first index, since the code in every guide below depends on that setup.
What one search returns
Each guide is about a different part of what query returns.
await narsil.query(indexName, { term, highlight, facets, limit })hits[ ]
idCite it as the reference that a reader can look up.documentQuote the passage from the fields that the projection keeps.scoreCompare hits within this one search, and never across searches.highlightsFind the exact sentence through its snippet and its character offsets.
count, countExactTell the reader how many documents match, and whether the count is exact.facetsOffer the model the values that it can narrow the search by.coverageCheck how many partitions time out or fail before you trust a count or a ranking.
Before you start
In every guide you start an engine with createNarsil and write documents into a typed index, and Indexes and documents has the details of both. In the isolation guide you query the engine over a network through the server from the HTTP server page, and in the hybrid guide you embed the text with the adapter from Embedding adapters.
In every guide, a ToolLoopAgent from the ai SDK sends its requests to a scripted mock model, which means the code prints the same words on your machine as it does in each panel. To let a real model choose the tool calls, pass its name in place of the mock.
Sirannon stores the rest of an AI agent's memory, which is the session's working state and a record of each action that the agent takes, in one database file for each agent. You can connect the two with the steps in Retrieval with Narsil on the Sirannon site.
The guides
- In Cite the passage behind an answer, you give each answer the rule's reference and the character offsets of its sentence, and check the model's quote against the stored field.
- With Give a model a search tool, the model fills in the search text, while your application fixes the projection, the limit, and the filter values.
- In Keep each agent to its own index, every client gets an index of its own, and an
onRequesthook restricts each token to the one index in its request path. - In Fit the passages in a context budget, you measure the characters that a tool returns, and you see what happens to an answer when you choose a snippet cap without reading the field.
- In When the index has no good match, you require every term with
termMatch: 'all', count the loose matches withpreflight, and return a status for the answer to state. - With Keep the index current, you write every change as an update or a removal, and wait for the worker copies before the next query.
- In Record every search, one plugin on the engine records every query and every preflight, whichever tool sends it.
- In Search by wording and by meaning, you add the customer's own words to the catalogue and fuse the keyword and vector rankings.