Code Graph RAG: Knowledge Graphs for Codebases

Code graph RAG is retrieval built on a parsed map of your codebase instead of a pile of text chunks. Rather than embedding files and hoping the nearest neighbours are relevant, it extracts functions, classes, methods and modules along with the edges between them, stores that as a graph, and answers questions by walking the structure.

vitali87/code-graph-rag is the implementation that put the term in front of people. Tree-sitter does the parsing, Memgraph holds the graph, and a CLI called cgr turns plain English into Cypher, retrieves the matching code, and can edit it. The repo opened on June 16, 2025 and sits at 3,116 stars as of August 10, 2026, with three releases in the two days before that: v0.0.584 and v0.0.586 on August 9, v0.0.589 on August 10. MIT licensed.

Key Takeaways:

• Thirteen languages parse fully, including Python, TypeScript, Rust, Go, Java, C, C++, C#, PHP, Lua and Dart. Ruby gets structural support through a pluggable ast-grep tier; Scala is still in progress.
• The graph is shared across every repository you index, which is the whole point for a monorepo and a trap when you run --clean, since that wipes every project in the graph, and not only the current one.
• It runs as an MCP server, so Claude Code and other MCP clients query and edit through it rather than around it.
• Dead-code detection comes free with the structure: walk call and reference edges from entry points and whatever you never reach is a candidate.
• Open source with a commercial tier. Managed cloud and air-gapped on-prem deployments are sold separately.

What code graph RAG does that vector search doesn't

Vector RAG chunks your files, embeds them, and retrieves whatever sits closest to the query embedding. For prose that works well. For code it degrades in a specific way that anyone who has tried it will recognise.

Ask "what calls validate_session, and what happens if it throws?" A vector index finds chunks that talk about sessions and validation, ranked by semantic similarity to a question about calling and throwing. It has no representation of calls. The caller might be in a file with no lexical overlap at all, and the chunk boundary might cut the function in half. You get plausible neighbours and miss the actual answer.

Code graph RAG knows the edge exists because the parser found it. Ask the same question and the query becomes a traversal: find the node, follow incoming call edges, return the sources. Precision comes from the AST rather than from embedding luck, and the answer either exists in the graph or it doesn't. There's no confidence score quietly hiding a miss.

The tradeoff is real and worth stating. Building the graph costs an indexing pass and needs a database running; embeddings need neither structure nor a parser that understands your language. Vector search also handles the fuzzy questions better, comments, docs, intent, which is why this project ships a semantic extra alongside the graph rather than treating the two as rivals.

Why monorepos break ordinary retrieval

Scale is one half of the problem. The other half is that a monorepo has boundaries a flat index cannot see.

Two services in the same repository can define User differently, and a chunk-based retriever will happily hand your agent both, or worse, one of them with no signal about which. Cross-language calls, a TypeScript frontend hitting a Go service, don't produce lexical overlap at all. Shared internal packages create the same symbol in a dozen import paths.

Code-Graph-RAG's answer is one language-agnostic schema across everything it parses. Functions, classes, methods and modules become nodes of the same type whatever language they came from, and the import and call edges connect across language boundaries. Every repo you index lands in the same graph, so a query can cross from your Python service into the Rust library it depends on without you stitching two indexes together.

That design decision explains the --clean warning too. Since one graph holds every project, resetting it takes them all down; the CLI asks for confirmation when other projects would be destroyed, which suggests someone learned this the noisy way.

How the graph gets built and queried

Two components, and the split matters more than it looks.

The parser is Tree-sitter based. It reads every source file and ingests functions, classes, methods, modules and their relationships into Memgraph under one schema. The RAG layer, codebase_rag/, is an interactive CLI that turns natural language into Cypher, runs it, retrieves matching code and drives editing.

Read the data flow and you'll notice the model never sees the whole codebase: Source -> Tree-sitter -> AST -> Memgraph, then Query -> model generates Cypher -> graph results -> answer. The LLM's job is writing a query and interpreting rows, not holding your repository in its context. That's a meaningfully different failure mode from stuffing files into a prompt, and it's the same argument that shows up throughout context engineering for agents: retrieve narrowly, reason on little.

Editing goes through AST-based surgical patching with a diff preview before anything is written. Structural search and replace uses ast-grep, so you match and rewrite by AST pattern rather than by regex across a whole codebase, and the same tier lets a new language join through a single YAML pattern file. Ruby arrived that way.

Setup is uv tool install "code-graph-rag[treesitter-full,semantic]", plus Docker, cmake and ripgrep. cgr daemon up brings up the packaged Memgraph and Qdrant stack, then cgr start --repo-path /path/to/repo --update-graph indexes a project.

Plugging it into a coding agent

The MCP server is the part most people will actually use, because it means you don't adopt a new interface at all.

Claude Code or any MCP client connects, and the agent gains tools for querying the graph and editing through it. The agent stops guessing which file to open. It asks the graph where a symbol lives, gets the real source back, and patches by AST rather than by rewriting a file it half-remembers. If you already run Codex-style agent workflows, this slots underneath them as a retrieval layer rather than replacing anything.

Worth being clear about what this doesn't fix. A graph tells an agent where things are; it doesn't tell it whether the change was right, doesn't run your tests, and doesn't keep working after you close the laptop. Retrieval quality is one layer of a working setup, and the architecture around the agent still has to carry the rest.

Doesn't a million-token context window solve this?

The question comes up every time a model ships a bigger window, and the answer is no for reasons that have nothing to do with capacity.

Pasting a monorepo into a prompt costs you money on every single turn, and cost scales with the repository rather than with the question. Retrieval costs you an indexing pass once. On a codebase of any real size that difference stops being an optimisation and becomes the difference between a workflow you can run all day and one you run twice and abandon.

Accuracy moves the same direction. Models degrade at finding a specific fact buried in a very long context, and a repository is the worst possible case: thousands of near-identical fragments, the same function name defined in four places, and the relevant edge sitting ten thousand tokens away from the thing it connects to. A code graph rag query returns four rows. The model reasons over four rows.

Then there's staleness. A pasted codebase is a snapshot of the moment you pasted it; a graph gets updated by re-running the sync, and Code-Graph-RAG documents real-time updates for exactly this reason.

None of which means the graph wins outright. Questions about intent, about why a decision was made, about what a comment implies, are not graph questions, and structure has nothing to say about them. The practical setup uses both: graph traversal for structure, semantic search for the fuzzy half, which is why the semantic install extra exists alongside the parser.

What it costs to run in practice

Three dependencies stand between you and a working install: Docker, cmake and ripgrep. Docker carries the most weight, since Memgraph and Qdrant both run through it, and cgr daemon up packages the stack so you never write a compose file.

Indexing time depends on how much code you point at it, and nobody publishes a benchmark, so measure your own repository rather than trusting a number from a blog post. The ongoing cost is model inference for Cypher generation and answer synthesis, which stays small per query precisely because the retrieved context is small.

Maturity signals are mixed in a way worth reading honestly. The project carries OpenSSF Scorecard and Best Practices badges, CI, Codecov and SonarCloud, which is more process rigour than most repos this size bother with. Against that, the version string is still v0.0.x fourteen months in and releases land several times a week, so the interface is not settled. Pin your version.

FAQ

What is code graph RAG?

Retrieval that queries a graph of entities and their relationships instead of ranking text chunks by embedding similarity. The retrieval step becomes a traversal, so relationships like "calls," "imports" and "inherits from" are first-class rather than something the model has to infer from nearby text. Applied to code, the entities are functions, classes, methods and modules, which is what separates code graph RAG from running a generic graph RAG pipeline over your files as if they were documents.

Does Code-Graph-RAG work with any language?

Thirteen languages parse fully: Python, TypeScript, TSX, JavaScript, Rust, Go, Java, C, C++, C#, PHP, Lua and Dart. Ruby has structural support (modules, functions, classes, imports) through the ast-grep tier, and Scala is in development. Adding a language through that tier takes a YAML pattern file rather than a hand-written parser.

Is Code-Graph-RAG free?

The project is MIT licensed and free to run yourself. You need Docker for Memgraph, plus cmake and ripgrep, and you pay whatever your model provider charges for the Cypher generation and answers. Managed cloud hosting and on-premise or air-gapped deployments are commercial offerings from the maintainers.

Do I need a graph database to use it?

Yes, Memgraph, but you don't have to stand it up yourself: cgr daemon up starts a packaged Memgraph and Qdrant stack through Docker. Qdrant is there for the semantic search extra, which complements graph traversal rather than replacing it.

Can Claude Code use it?

Yes, through the MCP server. Claude Code and other MCP clients connect to it and get tools for querying the graph and editing code, so the agent retrieves from real structure instead of guessing which files to open.