Is the Key to Understanding Code Treating it as a Graph?

Why Code-as-Text Doesn’t Work for Genuine Understanding

Major engineering orgs claim that as much as 30% to 75% of their new code is AI-generated, which does nothing to help the ongoing challenges of first-time onboarding for codebases and the updating of existing codebases for newly-hired engineers and growing teams (as well as for agentic coding assistants).

As generating code becomes free, understanding what any of it does becomes much more costly, and updating it becomes significantly more complex. Developer Vitali Avagyan asserts that the key to understanding code, particularly code across different languages, is to stop thinking of it as lines of plain text, and to treat it as a relational graph, which is the basis of his open-source project code-graph-rag.

Vitali Avagyan discusses using GraphRAG to parse repos with Memgraph. Image courtesy Memgraph

Viewing Code as a Retrievable Graph

Avagyan notes that when you hand a codebase to one of today’s coding assistants, it’ll often treat it as a text artifact. “Then, it traverses the code base with a grep or possibly some kind of agentic search. As you might imagine, that can become inefficient, especially considering some of the questions you might typically have about a codebase.”

The creator gives the example of asking an agent to find the longest nested function call in your codebase. Today’s agents will search through the imports and invocations and do some counting, a task that LLMs aren’t great at. “But if you already have a graph that represents all core relationships between methods and functions, you or an AI agent can just write a Cypher query that will calculate it for you in milliseconds.” The creator suggests that treating codebases as graphs in this way can conserve both tokens and time.

The creator clarifies, “that doesn't mean you should use [text] or [graphs] exclusively. They can be used in conjunction with each other. You can have grep, other types of search, and graph search together. Then, given that the AI has both contexts, it will decide which way to go.”

The creator suggests that the project specifically addresses the dichotomy between graph search and traditional text search/grep. “The first part of the project is how you go from code to graph. The second is an assistant that has a context of a graph, but it also has all the tools that typical coding agents or harnesses have. I also use it alongside my other coding harnesses. For some problems, it can find solutions faster and more accurately.”

Accounting for Variation Across Languages, Frameworks

The creator clarifies that precisely mapping codebases to graphs requires a correct build for each framework and programming language. “Even with an underlying technology like Tree-sitter, which parses the abstract syntax tree and gives you all the syntactic relationships, it's not still enough because there’s so much variety between languages and frameworks.”

Avagyan’s approach was to unify the variety within a single graph ontology that worked across multiple languages, from which he designed the project to let users map relationships within a monorepo, even those that contain multiple languages (the project currently supports more than a dozen). With such precise relationships properly mapped, users can use Cypher or another query language (or some sort of tool to map natural language to a query language) to query any part of a codebase as a graph, and compare against semantic search.

“Obviously, this has lots of benefits. If you ask a question about a specific function or a service with semantic search, it looks at the vector similarity and brings you some functions, some of which may have relevant names, but may not be relevant to your actual query. But using graphs, if you can translate your intent into Cypher (with the help of AI), you can basically pinpoint which function you are looking for.” The creator clarifies that the project also supports semantic search as an add-on to support things like code comments, and that in practice, graph parsing and semantic search tend to be complementary.

Making Code Graphs Deterministic with AST

As he sought to ensure the project yielded reliable graph representations, Avagyan found that asking LLMs to one-shot graph representations didn’t quite work. “[The LLMs] hallucinated some relationship edges and nodes. So, the project uses Tree-sitter parsers for different languages, which give you the basic relationships you can extract from AST as something of a unified way of using any type of language.”

“Obviously, there are so many considerations when you go into specifics, like finding call relationships. Each language has its own specific intricacies, like how polymorphism works.” The creator notes that tracking all the nuances isn’t necessarily covered by existing deterministic open-source tools either. What is even more difficult is the runtime behavior of the code. That's why recent efforts have been placed to trace call relationships apparent at runtime and merge them into the same graph with statically-derived ones.”

“And from there, we run thousands of test cases to ensure there are no regressions every time a new functionality is added. Every new functionality or bugfix is accompanied by a handful of new tests.” The creator suggests the project continuously runs more than 7,000 unit/integration tests using red/green test-driven development. Over time, the combination of hand-built code and agent-powered testing and development has proven to be effective. “At the beginning, I spent so much time on architecting [the project], setting the right relationships, that sort of thing, to ensure the foundation was ‘right.’ But when the foundation is ‘right,’ AI is great at doing the rest.”

Bottlenecks and Resource Management

The creator suggests that the project is continuing to improve on traditional challenges in graph-based projects, which have historically not always been particularly responsive. “I would say storage has never been a problem. With this project, I spent significant time optimizing the build process of going from codebase to graph. (I actually optimised the build time by more than 5x with a separate repo I built that optimizes user-defined codebase segments against specific metrics like speed within accepted memory constraints. The agent then "autosearches" the best code among competing candidates while running the build against the ground-truthed evaluation cases which you or your agents have collected or constructed yourself.)”

“I would say that a practical use of code-graph-rag is dead code detection. If you have vibe coded your repo, or it’s otherwise in a state that you don't know exactly what's happening because there are so many abstractions or code duplications, or that code isn’t reachable. For example, there is a code graph command that will check the reachability of all your code. If some are not reachable, they’re likely candidates [for being dead code and potentially getting deleted].”

“Otherwise, I don't think storage is a problem. The project uses Memgraph as a GraphDB and it's really fast, it runs in memory and you can deploy using Docker containers, and that would be enough to deploy locally, and the project has the building blocks for bigger deployments to the cloud. So far, it seems to scale well (people have even graphed the Linux kernel) and I haven’t seen any real degradation in speed when it comes to querying graphs.”

Avagyan notes that some users come to the project looking for performance and cost gains as well. “Some people claim that the project is as much as 65% more cost-efficient than traditional agentic coding and search, and I can’t verify those numbers myself. I can say that I’ve observed the project to be very fast, and it seems more fault-tolerant in a way.”

“Let’s say the project fails in one Cypher query? Then it can just repeat it, and with that query, you can gain lots of context up front, very fast. And that failure is less costly compared to if AI were to go and perform its own search, realize it was searching in the wrong place, then go to another place...you can imagine how things would accumulate really fast.”

“To be honest, the goal of the project was never cost reduction, but I think it’s a byproduct, since you get the accuracy of a graph and the accuracy of an MCP and agent to invoke the correct tools to query the graph.

Real-World Use Cases for Graphing a Codebase

The creator calls out onboarding new engineers as a key use case for the project. “People tell me that using the project has significantly reduced onboarding times because it can gather information about different aspects of a monorepo codebase and give that directly to new junior engineers.”

“Since we recently added FLOWS_TO, READS_FROM and WRITES_TO relationships in a graph, it’s now easy to analyze the relationships between microservices in your codebase as well. (I’ve actually been approached by security companies about using the project for security detection use cases across large codebases, which is a natural fit as tracing how data moves through a system is exactly what those relationships capture.)”

So you can see why companies are adopting the project as part of their onboarding tools. You could use it as an MCP server in Claude Code or any other harness or just use Cypher queries to search your codebase before even starting any agentic exploration. This approach is quick and gives you a really good grasp of a codebase, without getting sidetracked to other areas that may not be as important.”

Avagyan notes growing interest among teams managing heavyweight ERP systems with some flavor of Python, as well as ongoing requests around app development. “Dart is already supported and includes Flutter widget structure.”

Why Aren’t Enterprises Already Graphing Their Codebases?

The creator suggests that graphing codebases is a useful approach for any organization, but the timing might not be quite right for large-scale enterprises that are slow to embrace change. “I believe many companies, including major AI vendors like Cursor or Anthropic, have been experimenting with graph-based approaches, if not for codebase mapping, then for use cases like memory management.”

Avagyan notes that those companies may be hitting a stumbling block. “I think one problem companies may be having is accuracy.”

“You can get really far with one language, maybe with a toy example using a tool like Tree-sitter. But jobs that require you to unify graphs across different languages, and build usable and accurate relationships over top of them, and making sure it can work at scale, that’s different. For example, a monorepo is a living creature that changes every minute: People commit and delete code and so on. So your graph needs to keep up with that. It needs to recalculate [those relationships] with every change, every drop, every addition. The project has a graph updater designed specifically to make this real-time syncing possible.”

The creator suggests that while he spent the better part of a year building a system that could dynamically map and remap graph representations of codebases without significant latency, not every org is on the same page. “Even doing something like this with AI agents will take some time, and will cost internal resources. And people don’t always have patience for these things and may want to see a one-shot solution instead. But I think the approach will get more momentum and I think many companies will adopt it eventually.”

Learnings from Building

When asked what his most important learnings from the project are, Avagyan offers a few suggestions. “One, which I think is most important, is to just build something for yourself that you would like to have. That's pretty much how this project was born. Because I was dealing with [the challenges of managing a] monorepo, and at first, I just wanted to visualize it and understand its complexity. I looked for solutions to see if there was a good product for me. I didn't find one, so I decided I would build it myself, and after releasing it publicly, it turned to be useful for other people.”

“Second, I would recommend building things from the perspective of thinking about what you do every day and how you can accelerate what you do and be more performant with your tools.” The creator notes another open-source project of his, Croft, as an example. “I’m a VS Code user, but I enjoy terminal as well, so I found myself going back and forth between VS Code, Neovim, Zed and other alternatives. I found myself thinking there should be a better way, so I built a VS Code clone in the terminal with Rust to make it super-fast. I’ve been using it every day myself and I would recommend others try it out.”

“Finally, I’d recommend finding a distribution channel for your work. Even the greatest product on earth won’t necessarily be noticed if you just put it on GitHub and leave it there. You need to promote it. I was fortunate enough to have worked with the founder of Daily Dose of Data Science when I was working on my own startup back in 2023. I got coverage for my product in this popular newsletter, which might have been the trigger that helped it ‘go viral’ on GitHub the first time. That said, I have also tried many other channels like Hacker News, LinkedIn and X posts, giving talks (including this session with Memgraph), but eventually, the project started trending again on GitHub organically. I guess it might have to do with the ‘right solution at the right time’ phenomenon.”

The Future of Codebases: Built and Managed by AI?

From his experience building the project, Avagyan advises anyone working in a technical capacity to learn how to orchestrate. “Software engineering is changing faster than people think. The ability to orchestrate things will be important no matter what. By that, I mean knowing many different technologies: Their strengths and weaknesses, the scalability of each thing, and when to use what.”

“For example, in order to deploy applications at scale, you might need a Kubernetes cluster. You shouldn’t have to be a highly skilled DevOps engineer to know that as AI can help you there, but you would need to know when to use it, and what the pros and cons are. That will help you to have this overarching, holistic view of what it's like to build a highly scalable software engineering system.”

“You need to understand how the distributed systems work, and the code-graph-rag project fits really well here to help you ask architectural questions and locate potential bottlenecks, like dead code or other opportunities for optimization.”

“It’s about having this type of ‘systems thinking,’ an understanding of system design architecture and the underlying principles of the technologies. Not just knowing what Redis is, but also understanding what caching is and why it’s important. You’re going to need to apply that understanding when you think your system actually needs caching!”

“So I think orchestration will be important for quite some time, because AI is still not at the level of fully, autonomously orchestrating large-scale systems that will work smoothly and without any problems. We are not there yet.”