Code-Graph-RAG: A Tree-sitter and Memgraph Pipeline for Querying Monorepos in Plain English

What problem it solves and who it is for

Code-Graph-RAG targets a specific pain: retrieving code by meaning and structure in a monorepo that mixes several programming languages. Standard vector-based RAG splits files into chunks and loses the relationships between functions, classes, and call sites. This project instead builds a knowledge graph where each function, class, method, and module is a node, and relationships between them are edges. That makes it possible to ask a question like "where is the retry logic for the HTTP client?" and get back the actual function, not a file fragment. The intended user is a developer or team working on a large, multi-language repository who wants to query, edit, and optimize code through a conversational interface. The README also mentions overlaying runtime behavior from test traces or eBPF profiles, which points at debugging and performance work as a secondary audience.

The mechanism: Tree-sitter parsing into a unified graph

The system has two stages. First, a Tree-sitter based parser reads every source file and extracts functions, classes, methods, modules, and the relationships between them. The output is stored in Memgraph under a single language-agnostic schema. That means a Python function and a Rust function end up in the same graph structure, which is what allows cross-language queries. Second, a RAG system turns natural language into Cypher queries, retrieves matching code from the graph, and drives AI-powered editing and optimization. The README shows a data flow: source code goes through the parser, then AST analysis, then into the Memgraph knowledge graph. A user query goes through an AI model that generates Cypher, which queries the graph, and the results become the answer. The key design choice is that retrieval is structured, not lexical. The graph also supports dead-code detection by walking call and reference edges from entry points, something a text-based search cannot do.

Getting it running: commands, prerequisites, and the version puzzle

Installation is via PyPI, with extras for all languages and semantic search. The recommended command is `uv tool install "code-graph-rag[treesitter-full,semantic]"` or the pipx equivalent. You need Python 3.12 or newer, Docker for Memgraph, `cmake`, and `ripgrep`. The quick start is two commands: `cgr daemon up` to start the packaged Memgraph and Qdrant stack, then `cgr start --repo-path /path/to/repo --update-graph` to parse and index. A second `cgr start` without the flag queries the existing graph. The versioning scheme deserves attention. Git tags exist for every merge, while GitHub Releases and PyPI only get every 50th version plus security fixes. So the newest tag on `main` usually runs ahead of the published release, often by tens of patch versions. If you install from PyPI, you get the newest release, not the newest tag. To run the latest code, you must install from git: `uv tool install "code-graph-rag[treesitter-full,semantic] @ git+https://github.com/vitali87/code-graph-rag@main"`. This split is intentional, but it means a user who wants a recent fix might not get it from the standard install.

Editing and optimization: AST-based patching with a preview

Beyond querying, the agent can edit code. The README describes "AST-based surgical patching" with a diff preview before anything changes. That is a meaningful safety feature: the edit is not a blind text replacement but is anchored to the abstract syntax tree, so it should respect language syntax. The agent can also optimize code against language best practices or your own coding standards. This turns the tool from a read-only search into a write-capable assistant. But the README does not explain the exact mechanism for how the agent decides what to patch, or how it validates that the patch compiles. The diff preview is a guard, but there is no mention of running tests or a build after the patch. That is a gap a cautious user should probe before letting it edit production code.

Runtime tracing: merging actual calls into the graph

A distinctive feature is `cgr trace`, which overlays runtime behavior. You can trace a test run or pull production eBPF profiles, and the calls that actually happened are merged into the graph. The README says this exposes dispatch that static analysis cannot see. That is a real advantage: static call graphs miss dynamic dispatch, virtual calls, or reflection. By merging runtime data, the graph becomes a hybrid of static structure and observed behavior. The README does not give details on how the trace data is formatted or how the merge handles conflicts with static edges. It also does not say whether the trace is per-language or works across all supported languages. This is an area where the documentation is thin, and a user would need to check the docs or experiment.

Limitations and failure modes

The most obvious limitation is the hard requirement for Docker and Memgraph. If you cannot run Docker in your environment, this tool is unusable. The Python floor of 3.12 also excludes older systems; the README notes that the piwheels build for Debian Bookworm fails because that system's Python is 3.11. The `--clean` flag is a dangerous failure mode: it deletes every project in the shared graph, not just the one you are re-indexing, and it asks for confirmation only when other projects would be destroyed. If you run it carelessly, you can wipe your entire index. The version cadence is another trap: installing from PyPI gives you a release that may be dozens of versions behind the latest tag, so you might miss a bug fix or a new language feature. Finally, the README lists Scala as in development and several languages (Ruby, Kotlin, Swift, etc.) as having only "structural support" through ast-grep. That means the graph depth for those languages is shallower, and queries that rely on full AST analysis may fail or return incomplete results.

Alternatives and how they differ

The obvious alternative is a vector-based RAG system that chunks code and uses embeddings for retrieval, such as a typical LangChain or LlamaIndex setup with a vector store. That approach is simpler to deploy: you do not need a graph database or a parser that understands multiple languages. It handles any text, including code, but it does not preserve structural relationships. A query like "what functions call this deprecated method?" is hard to answer with chunks because the answer requires graph traversal. Another alternative is static analysis tools like Semgrep or CodeQL, which do understand code structure but are not conversational and do not generate natural-language answers. CodeQL, for instance, uses its own query language and a database built from source, which is similar in spirit but not designed for RAG-based interaction. The difference is that Code-Graph-RAG combines the graph with an AI model that translates natural language into Cypher, which neither a vector store nor a traditional static analyzer does out of the box.

Maintenance, licensing, and what to verify before adopting

The project is under the MIT license, which is permissive and allows commercial use without copyleft obligations. The repository shows a high release cadence: three releases within a week in the sample (v0.0.670, v0.0.720, v0.0.770). That velocity means the project is actively maintained, but it also implies a moving target. Upgrading frequently could be necessary to get fixes, and the version gap between tags and PyPI releases adds friction. The README mentions a CI workflow, Codecov, SonarCloud, and a security check, which suggests some quality gates, but the exact coverage or test results are not given. Before adopting, verify the language support matrix for your specific languages, because full support is not universal. Test indexing time on a representative repository, since the README does not provide any performance numbers. And check the latest PyPI release to see how far behind the git tags it is, because that determines whether you need to install from source to get recent fixes.

Editorial conclusion

Adopt Code-Graph-RAG if you work on a monorepo with multiple languages and you need structural answers, dead-code analysis, or AST-based edits that plain-text retrieval cannot give you. Do not adopt it if you cannot run Docker and Memgraph, if your codebase is a single small project where grep and an IDE suffice, or if you need a stable, slowly changing tool. Before committing, verify the language support matrix for your exact languages, test the indexing time on a representative repository, and check the latest PyPI release cadence, since the newest git tag often runs far ahead of the published package.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes