ctx_search
Query a unified FTS5 knowledge base of your indexed content and auto-captured session memory.
ctx_search recalls anything already in storage — content you indexed plus the
session memory captured for you automatically — instead of re-reading the source.
You ask in natural language, and the matching sections come back ranked, so the
relevant passage enters context rather than the whole file.
It searches one unified store. That store holds the outputs you gathered with a batch step, the documents you fetched from the web, the content you indexed by hand, and the decisions, prompts, and constraints captured across this session and prior ones. A single call reaches all of it.
When to use it
Reach for ctx_search first, before you re-open a file or re-run a command. If
the answer is somewhere in storage, search returns it directly. Batch every
related question into one call: the queries array is built for fan-out, so ten
questions cost one round trip instead of ten.
After a resume, search before you ask the user anything. Session memory persists, so the prior request, the last decision, and known constraints are usually one query away.
Parameters
| Parameter | Required | Description |
|---|---|---|
queries | no* | Array of questions. Batch every related question in one call. |
limit | no | Results per query. Default 3. |
sort | no | relevance (BM25 within the current session, the default) or timeline (chronological across this session, prior sessions, and persistent memory). |
source | no | Filter to a labelled source. Partial match. |
contentType | no | Restrict to code or prose. |
project | shared mode only | Omit for this session's project, global to span every project in the shared store, or an absolute path for a specific one. |
* The schema marks queries as optional, but in practice you always pass at
least one — an empty call returns nothing useful.
project exists only in shared-store (multi-project) mode — when
CONTEXT_MODE_PROJECT_DIR is set in the host's environment at launch. In the
default per-project store the field is absent from the tool schema entirely, so
the model cannot pass it. The mode is decided by that environment variable, not
by which host or install method you use.
Ranking
Results are scored with Reciprocal Rank Fusion across two matchers — Porter stemming and trigram matching — so a query lands whether it shares a word stem or just a character pattern with the stored text. Proximity reranking then favors passages where your query terms sit close together, and Levenshtein typo correction recovers near-miss spellings. The effect is that paraphrased and slightly misspelled queries still find the right chunk.
Example
This call batches three related questions and reads them back in chronological order, which is the right mode when you want the sequence of what happened rather than the single best match.
ctx_search(
queries: [
"What did we decide about the retry budget?",
"Which constraint did the user set on the API client?",
"What was the first request this session?"
],
sort: "timeline",
limit: 5
)To narrow the search, add source to restrict results to one labelled origin, or
set contentType to code when you only want code chunks.
When not to use it
Search only returns what was stored. If the data was never captured, search finds nothing — gather it first with a batch step or index it with ctx_index, then search. A zero-result response means the content is not in storage yet, not that it does not exist.