Why naive RAG fails for coding agents—and what Satori does instead

Finding relevant code is not the same as finding enough evidence to change it safely.

A search result can mention the right behavior and still omit the owner, surrounding contract, current file state, or callers that make the behavior understandable. That was the problem behind Satori: not how to return more snippets, but how to give a coding agent a shorter route from a question to inspectable source evidence.

Naive retrieval-augmented generation usually treats a repository like a long document. It cuts text into fixed windows, embeds those windows, and ranks them by similarity. That can help discovery, but similarity alone is a weak contract for an edit.

Where fixed windows lose code structure

Consider a window that begins halfway through a method. It may contain the error message an agent searched for while omitting the function signature, class owner, or file-level policy around it. The result is relevant, but it is not self-explanatory.

The opposite extreme is not safe either. A large class or function should not become one unbounded result just because a parser can identify its span. Agent-facing context still needs byte and disclosure limits.

The useful compromise is structural ownership with bounded content.

What Satori actually indexes

For supported languages, Satori extracts symbols and exact UTF-8 source spans. Those spans give chunks an owner such as a function, method, or class. Oversized symbols are still split into bounded overlapping chunks, and uncovered module-level text—imports, comments, and other top-level source—remains searchable separately.

That distinction matters. AST awareness informs boundaries and ownership; it does not mean every class is placed into one giant chunk or that every import is copied into every function.

Before retrieval, Satori builds search projections from the source plus stable metadata:

• repository-relative path
• language
• symbol kind and label
• parent breadcrumbs
• exact source content

This gives dense and lexical retrieval useful ownership signals without pretending metadata is source code.

Retrieval is more than dense similarity

Satori combines exact identifier evidence, BM25, and dense retrieval, then groups results around likely owners. The current local-first runtime uses Potion embeddings and LanceDB; connected and explicit local alternatives remain available. The model choice matters, but it is not allowed to erase lexical evidence or become the authority for source truth.

The result of search is therefore a lead with provenance, not a patch instruction. The agent can inspect an outline, follow advisory relationships, and open an exact symbol or bounded source span before changing anything.

The MCP contract matters as much as retrieval

The public MCP workflow is deliberately staged:

search_codebase
  -> follow recommendedNextAction
  -> file_outline or advisory call_graph when useful
  -> read_file for exact source evidence

continue_search can reveal more of the same frozen result set without rerunning retrieval. manage_index and list_codebases expose lifecycle and readiness state instead of making the agent guess whether an index is usable.

Satori does not expose a write-capable tool and cannot force the host agent to read before editing. The host environment owns mutation. Satori’s responsibility is narrower: report freshness honestly, bound the evidence it returns, recommend the next verification step, and refuse to present incompatible index state as ready.

The tradeoff

Structural retrieval adds real complexity. Language support varies, large symbols still need bounds, call relationships are advisory rather than compiler-grade proof, and source changes require explicit sync or reindex behavior.

Those limitations are better exposed than hidden. When exact symbol evidence is unavailable, the tool should degrade to bounded file evidence and say what is missing instead of fabricating certainty.

The takeaway

The problem with naive RAG for code is not simply that its chunks are the wrong size. It collapses ownership, freshness, retrieval, and verification into one similarity score.

AST-aware boundaries help, but they are only one layer. The stronger system keeps exact identifiers in the search path, tracks which source generation is active, points results toward real owners, and makes exact source inspection the obvious next action.

That is the boundary Satori is designed to own. The current Satori case study covers the local-first runtime, seven-tool surface, publication model, and measured evidence in more detail.