Retrieval (RAG) overview

What retrieval (RAG) is

Retrieval-augmented generation, usually shortened to RAG, means looking things up before answering. Paqad builds a search index of your project. Before the AI works on a request, it searches that index and hands the AI a few short passages that look relevant, instead of the AI reading whole folders to find them.

In Paqad, retrieval is optional and off by default. Without it, the agent reads and searches files itself, which is the normal behaviour of AI coding tools. Retrieval is an extra layer on top of that, never a replacement, and it never blocks your prompt.

Turning it on and off

paqad-ai rag init --provider local   # switch on and build the index
paqad-ai rag status                  # show the settings and index state
paqad-ai rag rebuild                 # force a full rebuild
paqad-ai rag clear --yes             # delete the index and switch retrieval off

rag init writes rag_enabled, the provider and the model to .paqad/.config, then builds the index. The --provider option takes local, openai or voyageai. See paqad-ai rag for every subcommand and option.

How it works, step by step

1. Indexing. Paqad splits eligible files into chunks at natural boundaries such as functions and classes. It turns each chunk into an embedding, a list of numbers that captures what the text is about, so similar texts end up close together. Chunks and embeddings are stored in .paqad/vectors/.
2. A background refresh. When you send a prompt on a host with a prompt hook, Paqad starts paqad-ai rag refresh-context in the background. It updates the index for files that changed, then runs a search.
3. The search. The query is your prompt when one was recorded, otherwise the list of files being changed. Paqad combines two signals: similarity of meaning (the embeddings) and exact keyword matches (a method called BM25). It merges the two rankings into one list.
4. A confidence floor. Only passages scoring at least rag_similarity_threshold (default 0.75) are delivered normally. If none clears it, up to two passages scoring at least rag_relief_floor (default 0.35) are delivered and labelled low-confidence. Below that, nothing is delivered, and the context file says so with the best score it saw.
5. Delivery. Results go into the ## Retrieved context section of .paqad/context/session-context.md: at most five passages of up to 1,200 characters each. When there are more than five, Paqad lists up to twelve file and line pointers instead of the text. The section tells the AI to treat these as hints and check the live files.

What gets indexed

A file is indexed only if it passes four filters, applied by a script in this order:

1. File type. Markdown, YAML and JSON files, the source file types your stack pack declares, and a few named files such as Dockerfile and Makefile.
2. Hard exclusions. Anything under .paqad/, AI tool folders such as .claude/ and .cursor/, lockfiles, and the entry files Paqad generates for AI tools.
3. Ignore rules. Paths matched by your .gitignore files, common build and dependency folders such as node_modules and dist, folders your stack pack excludes, and .env files.
4. File checks. Symbolic links, empty or binary files, files that are not valid UTF-8, files with fewer than 50 visible characters, and files larger than rag_max_file_size (default 153,600 bytes) are skipped.

You can adjust the filters in .paqad/rag.ignore.yaml. See Narrowing what retrieval can return.

Where your data is stored and sent

• Local provider (default). Paqad runs a small embedding model on your machine, Xenova/all-MiniLM-L6-v2 unless you pick the larger code-tuned option. The model is downloaded once into ~/.paqad/models and runs offline after that.
• OpenAI or Voyage AI. If you choose one of these, the text of each chunk is sent to that provider to be embedded. Keys come from OPENAI_API_KEY or VOYAGE_API_KEY in your environment, or from .paqad/secrets.env, which Paqad creates with owner-only file permissions where the system allows.
• The index itself holds the chunk text and stays in .paqad/vectors/. Paqad's own .paqad/.gitignore excludes vectors/ and secrets.env, so each developer builds their own index.
• Git. While retrieval is on, the background refresh also checks whether your base branch has moved on the remote. At most about every ten minutes it runs git ls-remote, and git fetch only when the remote branch has changed.

Checking that it helps

paqad-ai rag probe "your question" shows the top scores for a query before the confidence floor is applied, which helps you see why retrieval stayed quiet. paqad-ai rag eval --mode feature-off-vs-on compares retrieval on and off against a built-in test set and exits with code 1 when retrieval lowers quality or adds tokens without improving task success. These are script checks; they do not ask an AI to judge.