One of the most powerful upgrades you can give any AI developer
Introduction
AI coding assistants are dazzling on a single file and surprisingly lost on a large one. Point a capable agent at a mature, multi-package codebase and you watch the same pattern every session: it greps for a symbol, opens a dozen files to work out how they fit together, and burns a large slice of its context window simply rediscovering the shape of the system before it can do any actual work.
That orientation phase — the crawling, the grepping, the file-by-file reconstruction of structure the codebase already encodes — is the single biggest waste of tokens in most AI-assisted workflows. And it repeats every session, because nothing persists.
The fix is straightforward: give the agent a map. Model your codebase as a knowledge graph and let the agent query the map instead of crawling the territory. This article explains what that looks like, why it works, and what it actually finds when you run it on a real system.
TL;DR
A code-graph should map your architecture not just your code.
Converting grep to graph minimises token usage and saves you time.
Find bugs, security mistakes, and omissions in your codebase in seconds.
Plan upgrades quickly and with far more accuracy.
Using deep-memory's vocabulary simplifies usage for your AI.
Use deep-memory free.
Check out the full example code-graph-guide.md
What is a code-graph
A code-graph is a graph database representation of your system. I use the word system and not code deliberately — the real power comes from driving architectural insights, not just building a faster file search.
Code graphs are becoming popular. There are some impressive repositories where the author has scripted a process to mirror a codebase into a graph DB, capturing files, imports, and call relationships. That approach is useful for dependency visualisation. But mirroring syntax only scratches the surface.
What separates a useful code-graph from an elaborate directory listing is intentional modelling. You decide what entities matter to your architecture — commands, services, API routes, database tables, tests, authorisation checks, validation rules — and you define the relationships that carry meaning: implements, depends-on, guards, covers, throws. The graph is built against your conventions, not a generic notion of "code." That specificity is what makes absence detectable, and absence is where the real value hides.
The Power of Insights in a code-graph
The real value isn't the graph itself — it's the questions it answers in one query that would otherwise require a mass of grepping. And often the most important answer is the relationship that isn't there.
Security holes show up as missing edges. You can see which routes run an authorisation check — and, more importantly, which don't. The absence of a "checks access" edge on a route that reaches real business logic is a hole you'd never spot by reading files one at a time.
Defence-in-depth gaps become obvious. When a guard lives only at the route and not on the command beneath it, the graph shows it — so you know before you add a second caller that bypasses the check.
Dead and dangerous code surfaces instantly. Permission targets nothing enforces, validators no scenario uses, database tables no code reads — all are just nodes with no incoming edges.
Untested risk is ranked, not guessed. You can list destructive operations with no test covering them, turning "we should test more" into a concrete, prioritised backlog.
Blast radius is one traversal away. Before changing anything you can see everything that depends on it — callers, routes, docs, tests — so planning is faster and regressions are rarer.
Hot spots and choke points are visible. The most-depended-on services and most-accessed tables tell you where a change ripples widest and where to focus review and hardening.
Architecture rules become checkable. Intended conventions (e.g. "only the data layer touches SQL") turn into queries, so violations are caught in CI instead of code review.
New developers ramp up faster. A newcomer can ask "what calls this, what guards it, what tests it?" and get an answer in seconds instead of reverse-engineering it from source.
It scales where people don't. These insights hold across thousands of files and hundreds of routes — exactly the scale at which manual review quietly misses things.
We dogfood this on our own codebase
The best way to understand what a code-graph actually does is to see it working on a real system.
At Utaba we use Deep Memory — our own open-source library — to build a live code-graph of the UCM platform itself. UCM is the product we ship; the code-graph is how our team and our AI coding agents navigate it. We build UCM with the very capability we offer to customers.
Here is what it has found and done.
Blast-radius analysis — in one query. Before modifying a core UCM service, the graph returned the full dependency picture: 35 commands rely on that service. One query, no file reads. That list became the review checklist before the change landed.
Security audit — zero false alarms. We asked: which public API endpoints reach a command with no permission check? The graph returned exactly four — all legitimate sign-in and service-discovery routes. No surprises buried in the list, no manual triage needed. That kind of signal, at that precision, from a text search is not realistic.
Dead code caught automatically. The graph recently flagged 24 validation rules that were defined but never used — the kind of quiet accumulation that is invisible in day-to-day work and would only surface in a dedicated audit, if at all. It also caught a documentation example that had silently gone stale.
Planning a new feature from graph queries, not file reads. When planning a new capability, our AI agents check the graph first: Does this already exist? What will it affect? Are we duplicating something? These are graph queries, not guesswork. They consistently stop wasted effort and accidental duplication before a line is written.
Token efficiency — the quiet win. Instead of an AI agent reading dozens of files to understand a dependency chain, one near-instant query returns the precise answer. Less reading means fewer tokens, lower cost, and faster, more accurate responses. On a large codebase the saving is not marginal — the orientation phase is often the single largest consumer of context, and the graph collapses it.
One detail worth highlighting: roughly 80% of the graph builds itself with no AI involved. Most relationships are already declared in the code — imports, interface implementations, route registrations — so they are mined deterministically. Fast, exact, and free. The AI handles the edges that require interpretation; the extractor scripts handle everything mechanical.
Building a code-graph with deep-memory
The implementation is a set of small, independent extractor scripts feeding a single reconciling orchestrator. Each extractor owns one layer of the model (packages, providers, tools, docs, tests, modules, errors) and is a pure function: it reads source with a real parser — never regex — and returns plain node and edge descriptors with no knowledge of the graph store.
The script runs automatically on each build, or on-demand. It should take just a few seconds because it reconciles delta changes, not a full rebuild.
There is a full example you can point your AI at to build its own specialised code-graph for your codebase. The guide walks through the vocabulary, the extractor pattern, and how to wire the orchestrator — an afternoon's work to have it running on your own system.
Conclusion
AI coding agents do not struggle with large codebases because they cannot read. They struggle because they have no map. Every session, they reconstruct the same structural knowledge from scratch — at your cost in tokens, latency, and their finite attention.
Build the map once, and every session after pays it back. Navigation becomes one query instead of twenty file reads. Security gaps surface as missing edges, not missed audits. Architecture rules move from wiki pages nobody re-reads to queries any agent can run on demand.
The practical starting point: clone the deep-memory repo, read the code-graph guide, and point an AI agent at the example scripts. It is open source and designed to be adapted to your codebase in a single session.
If you are working on a larger system and want to talk through what this would look like applied to your architecture, get in touch.