Codebase indexing and retrieval in Onyx Code

Retrieval, so you stop pasting files into chat

Onyx Code indexes your workspace into a vector store on your disk, so that when you ask a question the relevant code is found and included for you. You do not have to know which file the answer is in, which is usually the reason you are asking.

The part worth being clear about: the index and the embedding model are both local. Building an index does not upload your repository to be embedded somewhere else, and the vector store is a file on your machine. That is the difference that matters if your code cannot leave the building, and it is why this works with the network off.

What actually happens on a chat turn

Retrieval is not magic and it is worth knowing the shape of it, because it explains both the good answers and the occasional miss.

1. Your message is embedded into a vector, locally.
2. That vector is compared against the store by cosine similarity.
3. The five most relevant code blocks are injected into the prompt alongside your question.

Five is a deliberate budget rather than a limit: context spent on marginally relevant code is context not spent on the code that matters. When a question is harder and needs a wider net, /workspace <query> raises it to fifteen for that turn.

Retrieval is one layer, not the only one. Onyx Code also searches your workspace directly, the way you would with grep, and the two are complementary: embeddings find code that is about the thing you asked, and search finds the exact string you named.

Why it knows the shape of your project immediately

Retrieval answers “which code is relevant to this question”. It does not answer “what is this project”, and a model that does not know that gives confidently generic advice.

So on your first chat in a workspace, Onyx Code builds a compact primer: the top-level layout, an excerpt of the README, and a summary of the manifest. It is injected into every system prompt, and it is small on purpose. Run /primer to see exactly what it contains or to refresh it after the project has changed shape.

Indexing, watching, and rebuilding

The index builds in the background when a workspace opens, then keeps itself current as you work. It persists across restarts, so you pay the build cost once rather than every morning.

• Watch mode updates the index incrementally as files change, so a file you edited a minute ago is retrievable now.
• /reindex rebuilds from scratch. Worth doing after a branch switch that moved a great deal of code, or if retrieval starts feeling stale.
• /reindex-clear wipes both the in-memory index and the snapshot on disk. This is the one to use when the goal is to leave nothing behind rather than to fix retrieval.

Indexing can be turned off entirely with onyxcode.index.enabled, and paths listed in a .onyxnoai file are excluded from AI features, which includes being indexed.

Which model does the embedding, and when to change it

The embedding model decides what retrieval can find, so it matters more than its low profile suggests. It is a different model from your chat model and is chosen separately.

• Jina v2 Base Code is the bundled default: code-tuned, and it runs on any machine with 4 GB of RAM. Most people should leave this alone.
• Nomic Embed Text v1.5 suits a workspace that is mostly prose rather than code.
• Nomic Embed Code gives the best retrieval quality, and asks for it: a 4.4 GB model needing 16 GB or more of RAM, which builds a larger and slower index. It is hidden on machines that cannot run it rather than offered and then disappointing.

Changing the embedding model means rebuilding the index, because vectors from one model are not comparable with vectors from another. That is a one-time cost, not a reason to avoid the change, but it is worth doing deliberately rather than mid-task.