Giving Coding Agents a Map: Symbol-Level RAG With tree-sitter, Qdrant and SQLite

Oper18 — Thu, 06 Aug 2026 09:04:29 +0000

Your coding agent doesn’t know your codebase. That’s the actual bug.

An agent without context doesn’t write bad code. It writes someone else’s code.

You ask for a new endpoint and get a fresh error-handling pattern, a second HTTP client, validation inlined in the handler when the whole repo does it in a service, a raw query in a project that’s been behind a repository interface for two years. It compiles. It passes review only if nobody’s paying attention. And every one of those diffs makes the next generation slightly worse, because now there are two patterns in the repo instead of one.
Fewer tokens aren’t the problem I care about. The problem is that the agent has no idea how this project does things.
So I built nav — a Go CLI (~10k LOC, GPL-3.0) that indexes a repository into semantic code units and feeds the relevant ones to the agent before it writes a line of code.

Symbols, not chunks

Go, Python, TypeScript, and JavaScript. tree-sitter parses each file and extracts real definitions using per-language queries: in Go, that’s functions, methods with their receiver, structs, interfaces, and consts; in Python, functions and classes; in TS/JS, functions, methods, classes, and interfaces. Symbols below a minimum line count are dropped.
No sliding windows. A retrieved unit is always a complete definition the agent can imitate, not the back half of one function glued to the front of the next.

Enrichment, grounded in the project

Each symbol goes to an LLM (qwen3-coder by default, with fallbacks on rate limit) for four things: a dense summary, 3–6 tags, a one-sentence business context—the why, not the implementation—and 1–4 responsibilities.
Here’s the detail that matters: before summarising anything, a full index generates a project-level README from the source, then passes it as shared context into every per-symbol prompt.
So the summary for create_user is written by a model that already knows what the product is. You get “registers a tenant admin during onboarding” instead of “creates a user.”
Everything structural stays deterministic. Calls and imports come from the AST. called_by is a post-index pass. layer (controller / service / repository / model / middleware / util) and framework come from path and import heuristics. The LLM writes the prose; it never touches the graph.

What actually gets embedded

Not the raw source, but a rendered block: symbol, type, module, signature, layer, framework, purpose, business context, responsibilities, imports, calls, called_by, and then the code.
That’s what makes “where do we hash passwords” return UserService.create_user rather than every function with password in it.
It’s also why the retrieved context carries the architecture with it: the agent sees the layer, the callers, and the dependencies in the same block as the code.
Vectors and the payload live in Qdrant, one collection per project, with filtered search—nav search "auth" --type method --layer service --threshold 0.70.

SQLite does the bookkeeping

Alongside Qdrant, there’s a per-branch SQLite database at .nav/nav-.db holding three things: a chunk manifest (content_hash vs embedded_hash), the knowledge graph as nodes and edges, and metadata.
The manifest means re-embedding only happens when a symbol’s content actually changes. Reformat a file, pay nothing.
The graph holds pkg:, file:, and sym: nodes with defines, calls, and imports edges, plus Go-specific embeds and implements heuristics. It answers nav graph callers, nav graph deps, and top fan-in queries without touching the vector store.
Per-branch is deliberate—the set of symbols genuinely differs across branches. A new branch records its parent and inherits the ancestor’s embeddings through a resolved branch chain, so creating a feature branch doesn’t trigger a reindex.

Two injection points

SessionStart hands the agent a digest built directly from the graph: every package, every file, symbol counts, capped at ~8k tokens. It stops the session from opening with find, ls, and tree.
UserPromptSubmit runs a lazy sync in-process, embeds the prompt, retrieves the top five results above a 0.72 cosine threshold, and injects a block capped at 4k tokens.
Sync runs behind a file lock with a four-second wait. If another sync already holds the lock, the hook answers against a slightly stale index instead of making you wait.
The same core runs for Claude Code, Qwen Code, Cursor, and OpenCode. A Git pre-commit hook keeps the index warm and always exits with 0, so it can never block a commit.
A stale index means yesterday’s conventions. That’s exactly why sync happens on the prompt path rather than on a cron schedule.

No numbers yet

Gen 1 github.
I’m not going to invent a “40% fewer tokens” figure — that isn’t even the metric.
What I’m building an evaluation for is conformance: does the generated code use the abstractions that already exist in the repo, or reinvent them?
Part 2 is where I’ll share those results, including the cases where nav didn’t help.
If you’re running agents against a mature codebase, what are you doing to keep them aligned with your project’s conventions? CLAUDE.md only scales so far.

DEV Community: Oper18