Local-first RAG for coding agents
Developer-tooling prototype
A local-first retrieval plugin that gives coding agents a way to search project context. The work connects configurable source indexing, local embeddings and vector search, returning passages with references to their source.
Search project context, not every document
A coding agent needs context from project files and documentation, but including every document in every request makes context selection an all-or-nothing choice.
This prototype separates collecting source material from retrieving it. An index holds searchable passages, so the agent can request selected context and inspect where it came from.
Source indexing and traceable retrieval
Indexing requires an explicit confirmation argument before the tool calls the indexer. This guard makes indexing a deliberate tool operation, separate from a search request.
Files, documentation and configured web sources can be selected independently. Chunk size and overlap are passed into collection, making source coverage and passage boundaries configurable rather than fixed for every project.
The documented chunking approach uses tokens and document structure, including headings and paragraphs. Passages become the unit of retrieval instead of entire documents.
A local model embeds the collected chunks. A Postgres vector index stores those embeddings alongside source types and source references, keeping the search representation linked to its origin.
Search uses cosine distance and accepts source-type filters to distinguish files, documentation and web material. Returned passages include source references, so a reader can locate the original material and check its context.
- Sources
- Chunks
- Embeddings
- Vector index
- Retrieved context
Selected sources → confirmation → chunk collection → local embeddings → vector index → filtered search → referenced passages.
Trade-offs
Freshness and reindexing
Separate indexing and search tools let the agent query the collected material without starting a new collection. The trade-off is freshness: search reflects the indexed material, so source changes need reindexing before they can be reflected in retrieved passages.
Local embeddings keep the embedding step local and require a model and database in the configured environment. Web-source access and the coding-agent runtime remain separate data-handling boundaries to consider when choosing what to index and where to send retrieved context.
Chunking and retrieval
Smaller chunks narrow the context returned in each passage; larger chunks carry more surrounding material. Overlap helps retain neighboring context across boundaries at the cost of repeating material in the index. These settings need to suit the documents and questions the agent will work with.
Project scope and source judgment
The prototype focuses on the retrieval layer for coding agents: choosing sources, indexing passages and returning filtered context with source references.
Source references make a result traceable, not authoritative. Before relying on a passage, the reader or agent needs to check its relevance and whether the original source has changed since indexing.
Retrieved text is untrusted source content, not instructions that override the agent's task. The indexing confirmation guard controls when collection starts; it doesn't decide whether the content is safe to follow.