What adaptive depth is
When retrieval is switched on, Paqad searches an index of your project for passages that might help the AI. Retrieval (RAG, short for retrieval-augmented generation) is explained in the RAG overview. Adaptive depth decides how wide that search should be for each request: skip it, run a normal search, or run a deeper one. A script makes this choice from a few signals about the request. No AI model is involved.
You do not switch adaptive depth on or off. It runs whenever retrieval runs. The one number you can change is the base size of a search, rag_top_n.
The three depths
| Depth | What happens | Candidates fetched |
|---|---|---|
none | No search at all. Nothing is embedded or queried. | 0 |
standard | A normal search. | rag_top_n (default 20) |
deep | A wider search for broad or risky work. | Three times rag_top_n (default 60) |
"Candidates" are possible matches before the confidence floor is applied. Most of them are usually filtered out, and the AI receives at most five passages (or a list of up to twelve file pointers) either way. The deeper search simply gives the ranking more to choose from.
How the depth is chosen
The rules are checked in this order, and the first one that matches wins:
nonewhen the request is an investigation of trivial or low complexity.nonewhen the change is trivial and limited to a single file.deepwhen complexity is high or very high, when the change is system-wide, or when risk is high.standardin every other case.
What happens in the background refresh
In paqad-ai 1.91.1, the passages the AI actually sees are gathered by a background job, paqad-ai rag refresh-context. That job does not have a complexity or risk rating for the request. Instead it judges breadth from the files being changed, where a "module" means the first two parts of a file path, such as src/billing:
| Files being changed | Treated as | Depth |
|---|---|---|
| None or one file | single file | standard |
| Several files in one module | single module | standard |
| Two or three modules | multi-module | standard |
| Four or more modules | system-wide | deep |
Because the job has no complexity rating, the none depth does not occur on this path. When the change is wide, the job searches deeper.
The package also contains a second, library-level context loader that can step up one depth when a search returns fewer than three usable passages. In 1.91.1 no command or hook calls that loader, so this step-up does not affect what your AI tool receives.
Settings you can change
Set these in .paqad/.config or through the matching environment variable:
rag_top_n(PAQAD_RAG_TOP_N): the base number of candidates, default 20. Deep searches fetch three times this.rag_similarity_threshold(PAQAD_RAG_SIMILARITY_THRESHOLD): the score a passage needs to be delivered with normal confidence, default 0.75.rag_relief_floor(PAQAD_RAG_RELIEF_FLOOR): the lower score for the fallback of up to two low-confidence passages, default 0.35.
To see how real scores compare with these thresholds on your project, run paqad-ai rag probe "your query".
Why it matters
Skipping retrieval for small, self-contained work avoids spending time and tokens on a search that would not help. Searching wider for broad changes gives the ranking a better chance of finding related documentation. In both cases the delivered context stays capped, so a deep search does not flood the AI's working memory.