Claude Code is amnesiac. Understand-Anything cures it.

Every session, Claude Code reopens your codebase like a visitor who has never set foot in it. It reads the README, unfolds the package.json files, walks the tree with ls -R, fires off greps on terms it guesses at, opens whole files to reconstruct what it had already reconstructed the day before. On a personal project of fifteen files, this is invisible. On an enterprise codebase of fifty thousand lines, it’s cost item number one; well ahead of response length or prompt verbosity.

An open-source project published on GitHub in March 2026 offers another path. It’s called Understand-Anything, it runs on Claude Code, Codex, Cursor, Copilot and Gemini CLI, and its ambition isn’t to optimise tokens. Its ambition is to change what an agent does when it encounters your code. And behind the apparent gadgetry of “one more plugin” sits an architectural shift no one has yet named in French.

Claude Code reads your code like a human who has never opened an IDE

An experienced developer joining a project doesn’t open every file one by one. They interrogate the architecture: where authentication lives, how requests flow, which layers depend on what. They navigate by concepts, not by paths. That’s what a modern IDE does with its symbolic indexing: Goto Definition, Find Usages, Call Hierarchy. No one writes code by running grep every thirty seconds; except Claude Code.

Claude Code’s System Prompt, whose fast-execution directive that supplants deep reflection I’ve already dissected, pushes the agent to act before it has mapped anything out. And since it has no prior symbolic index, it acts by exploring. On a fresh codebase, that’s ten to twenty files ingested before the first line is written. Every session reproduces this work. Every session bills for it.

The problem isn’t the agent’s voracity. The problem is that we’re asking it to understand a complex structure while presenting it with a flat file system. Code, unlike an article or a PDF, is not a text. And treating it as a text is the design error that makes blind exploration inevitable.

What code has on top of text: a structure that scoffs at chunking

Classic RAG rests on a chain I’ve detailed elsewhere: you split the corpus into pieces, turn them into vectors, store them, retrieve them by cosine similarity. This mechanism works on text, where semantic proximity is an honest heuristic: two paragraphs about the same subject stand a good chance of having neighbouring embeddings.

On code, the heuristic collapses. Two homonymous functions in two unrelated modules produce close vectors. An abstract class and its concrete implementation can be far apart in vector space when they’re literally the same thing for anyone trying to understand the architecture. The auth.middleware.js that calls JwtService.verify() that inherits from BaseAuthService isn’t a semantic chain: it’s a call graph, an inheritance graph, a dependency graph, all superimposed. Token chunking makes this topology disappear. Cosine doesn’t know an inheritance exists. Re-ranking doesn’t know a function is called.

I’ve already argued that the vector database established itself as the default answer to RAG not because it was universally superior, but because it arrived at the right moment and inherited the aura of LLMs. On code, this observation turns brutal: the right representation is neither a BM25 index nor a vector database. It’s a graph. A graph of symbols, relations, layers. And this graph already exists; every IDE silently builds it each time a project opens. Making it available to an AI agent is, on close inspection, the bare minimum.

Understand-Anything: anatomy of a GraphRAG over AST

The Understand-Anything project, published by Yuxiang Lin under an open-source licence, does precisely what any serious code agent should do: it indexes the codebase upstream and materialises its structure in a queryable file. Concretely, the user installs the plugin via the Claude Code marketplace (/plugin marketplace add Lum1104/Understand-Anything), then runs the /understand command at the project root.

What happens next isn’t trivial. A five-phase pipeline runs locally: DETECT identifies the languages and frameworks present, SCAN walks the tree and extracts the symbols, ANALYZE mobilises specialised agents to understand the implicit relations, MERGE consolidates the partial analyses, SAVE persists the result to .understand-anything/knowledge-graph.json. The result isn’t a file listing or a vector database. It’s a graph with, in the current version, twenty-one node types (function, class, file, domain, flow, step, entity, claim, source, topic, article…) and thirty-five edge types (structural, behavioural, data flow, dependencies, semantic, infrastructure, domain, knowledge).

This graph is then accessible in two ways: a local web dashboard, which displays the codebase as a navigable map with automatic grouping by architectural layer (API, Service, Data, UI, Utility), and (above all) the Claude Code agent itself, which queries the graph instead of attacking the file system directly. When you ask “which parts handle authentication?”, Claude doesn’t run a grep -r auth. It queries the nodes whose type or edges point to the relevant domain.

This is, word for word, GraphRAG applied to code. The difference from Microsoft Research’s textual GraphRAG is that the graph doesn’t derive from entity extraction over a corpus of prose: it derives from a deterministic structural analysis (AST parsing) augmented by agents that spot the implicit relations; the ones a syntactic parser doesn’t see, like the conceptual relation between a service and its indirect consumer via dependency injection.

The agents that build the graph: the mise en abyme

This is where the architecture gets interesting. The /understand command isn’t a monolithic script. It orchestrates five specialised agents, and /understand-domain adds a sixth dedicated to extracting business flows. Each agent has its narrow responsibility: a detection agent, a file-analysis agent, a relation-extraction agent, a consolidation agent, a review agent that catches abandoned nodes and unknown types, and, for the domain version, an agent that extracts the business concepts.

This breakdown isn’t an implementation detail. It’s the mise en abyme of the very definition of the agent that I set out in “RAG is dead, long live the Agent”: a model that reasons, tools to act, a memory to make progress, a loop to iterate. Each of Understand-Anything’s sub-agents ticks the four boxes within its scope. And the pipeline itself, considered as a whole, is a meta-agent that orchestrates the six.

This decomposition reveals something we rarely see this cleanly: specialisation by sub-agent isn’t an optimisation nice-to-have, it’s what makes the task feasible. Asking a single generalist agent to read the whole codebase, extract the symbols from it, guess the implicit relations, consolidate, review and produce a coherent JSON; that’s exactly what Claude Code does today without a graph. And it’s precisely what we’re trying to avoid. The pipeline demonstrates that the right unit of execution isn’t the LLM, it’s the narrow-mission agent, multiplied and orchestrated.

The graph as a versioned asset: the break no one names

Here is the point I searched for in vain in the documentation, in the LinkedIn threads and in the usage feedback: Understand-Anything’s knowledge graph is not a volatile index. It’s written to .understand-anything/knowledge-graph.json, and the documentation explicitly recommends committing it to the Git repository; with git-lfs beyond ten megabytes. A post-commit hook (/understand --auto-update) updates it incrementally at each commit, so it stays in sync with the code it describes.

This detail changes everything. In classic enterprise RAG, the index is infrastructure: a vector database hosted somewhere, which has to be maintained, periodically re-indexed, monitored, backed up. It’s a system. In Understand-Anything, the index is a file. It lives in the repo like package-lock.json or Cargo.lock. It’s versioned, diffable, shareable, reproducible. When a new developer clones the project, they get the graph at the same time as the code. When a PR modifies the architecture, the graph is modified in the same commit.

It’s the conceptual equivalent of a schema.lock applied to knowledge: a versioned contract that says here is the map shared between the human developers and the AI agent, and as long as this file hasn’t changed, everyone is working from the same map. The dependency lock-file guarantees you install the same library versions as your colleagues. The committed knowledge graph guarantees that Claude Code reasons about the same architecture as you. It’s the same reproducibility mechanism, extended to the project’s semantics.

It’s a major shift. The project’s structured knowledge is no longer a peripheral service, it’s an artefact of the project itself. The graph becomes executable documentation. And this documentation is consumed not by a human who reads it, but by an agent who queries it.

This connects, from another angle, with what I wrote about MCP as an architecture problem: for a given project, you don’t need dynamic tool discovery, you need deterministic navigation in a finite, known space. Understand-Anything materialises that space in a JSON. No more rediscovering at each session what the graph already knows.

Why it’s consistent with “RAG is dead, long live the Agent”

Let’s revisit the thesis. In classic RAG, the knowledge base is a wall: it stands between the LLM and the world, and the model merely receives pre-filtered chunks that it assembles into an answer. In the agentic model, the knowledge base becomes one tool among others that the agent calls when it needs to, in the order it decides, with parameters it chooses.

Understand-Anything applies exactly this pattern to code. Before: Claude Code receives (or demands) file dumps, which it mentally aggregates to reconstruct the architecture. After: Claude Code has a queryable graph, which it consults in a targeted way. The codebase is no longer in its context. It is reachable from its context. That’s the fundamental switch.

And this switch isn’t an implementation detail: it’s the condition for long sessions to become viable again. As long as understanding the code consists of reading it, every session is a reset. When understanding the code consists of navigating it via a persistent graph, the session becomes incremental. To borrow the formula on persistent memory, amnesia becomes optional.

What it really consumes: the comparative economics

Let’s be honest about the numbers, because marketing feedback quickly turns rose-tinted. Understand-Anything’s initial indexing mobilises LLM agents that run on the model of the CLI invoking them; Claude Sonnet for Claude Code, GPT for Codex, Gemini for Gemini CLI. On a medium-sized codebase, that’s several hundred thousand tokens consumed at indexing, the equivalent of half a day of intensive use billed all at once.

The trade-off to weigh is this: either indexing goes through a high-end model and the graph captures implicit relations with finesse (at the price of a real upfront investment) or you redirect the CLI to a local model via ANTHROPIC_BASE_URL (Ollama, llama.cpp), and indexing becomes free but quality drops. A local Llama 3.x misses the subtle inferences a Sonnet catches: functions semantically linked with no direct call, inheritances crossing several layers of abstraction, dependencies injected via a DI container. And a graph with holes is worse than no graph at all; the agent believes it, and it’s wrong.

In the enterprise, the friction is often more institutional than technical: installing an Ollama on a dev machine goes through the security teams, who block it or impose an approved model list. The pragmatic scenario remains shared cost: index once via a paid API, commit the graph, then exploit it at marginal cost for the whole team. The indexing bill becomes a project investment, not a recurring per-developer cost.

Once the graph is built, Claude Code’s queries replace whole-file reads with targeted node lookups.

The real gain depends on three variables: the size of the codebase (the effect is linear, even super-linear beyond a certain threshold), the type of task (a debug targeted on one function gains less than a refactoring touching several layers), and the length of the session (on a short session, the initial indexing overhead may never be amortised; on a session of several hours, the saving is mechanical). The honest rule of thumb: under a thousand files, the benefit is marginal. Above that, it becomes structuring.

Add to this the complementarity with Anthropic’s prompt caching: the two mechanisms attack different costs. Caching reduces the cost of repeated tokens (system prompt, instructions, stable context. The graph reduces the volume of exploratory tokens) the file reads the agent does to understand. The two are additive, and enabling one doesn’t replace the other.

The real gain, however, isn’t counted in dollars saved. It’s qualitative: Claude Code stops fumbling, its answers gain in relevance because they rest on the real structure of the project rather than on an approximate reconstruction. It’s an improvement in the quality of the agent, of which the cost reduction is a side effect.

The limits (because there are some)

All this deserves a cold shower. Understand-Anything is an open-source project from March 2026, evolving fast, whose maturity isn’t that of an integrated Anthropic product. Several weaknesses are known.

First, the quality of the graph depends on the model used for indexing. The analysis phases mobilise agents that rely on an LLM; a weak model produces a graph with shaky relations, missing nodes, mis-attributed types. The review phase (assemble-reviewer) corrects some of the problems but doesn’t solve everything. On a high-end model, quality is decent; on a small local model, it drops.

Next, graph-code synchronisation can silently drift. If the post-commit hook crashes, if a developer commits without triggering it, if a badly resolved merge breaks the JSON, the graph diverges from the code. And a desynchronised graph is worse than no graph: it makes the agent trust a false map. The update discipline is non-negotiable.

Third, the added value drops on atypical codebases: scripts, configurations, infrastructure-as-code, poorly delimited polyglot projects. The AST no longer has a stable meaning, the standard node types no longer capture the relations that matter. On a DevOps repo mixing Terraform, Ansible, Bash and docker-compose, the graph risks revealing nothing you didn’t already know.

Fourth, the graph describes what exists, not what’s to come. When you tackle a radical overhaul (moving from a monolith to micro-services, breaking an obsolete abstraction layer, migrating to a new architecture), the graph is a map of the present that is precisely what you’re setting out to dismantle. If the agent relies on it to propose changes, it optimises within the coherence of the current topology; the very one you want to leave. The risk: an over-docile assistant becomes a factor of architectural conservatism, suggesting patches where you ought to rebuild. The safeguard is doctrinal rather than technical: during an overhaul, the graph serves to understand what you’re breaking, not to prescribe what you’re building. And if you’re counting on the agent to conceive a new architecture, that’s probably a sign it isn’t its job.

Fifth, no native multi-repo handling. Many organisations don’t live in a monorepo: their technical knowledge is scattered across ten, twenty, a hundred separate repositories: one per micro-service, one per internal client, one per shared library. Understand-Anything works today on one repository at a time. The .understand-anything/knowledge-graph.json is local to the repo. No federation between projects, no cross-repo resolution of HTTP calls between services, no “graph of graphs” that would materialise the distributed architecture. The Subdomain graph merging feature (Phase 0) that the project offers only solves the merging of several subdomains within a single repo. For a team that thinks in micro-services, it’s a structuring limit and a reminder that the project, six months old in May 2026, hasn’t yet matured on this front.

The ecosystem, for its part, is heading in this direction. In late April 2026, an adjacent project named GitNexus published exactly what’s missing here: an MCP-native knowledge graph engine, which exposes its graphs via a standardised MCP server and handles several indexed repositories in parallel. Whether convergence comes from an evolution of Understand-Anything, a win for GitNexus, or a shared MCP standard between competing projects, the trajectory is set. The graph will become a service exposed via MCP, exactly as the architectural analysis I set out on MCP as a question of architecture, not protocol let us anticipate.

Finally, and most importantly: a graph doesn’t replace good code design. If your project is a plate of spaghetti with circular dependencies, thousand-line classes and unstable naming conventions, Understand-Anything will produce you a plate of spaghetti in JSON. The tool makes legible what is legible. It doesn’t refactor in your place.

How to integrate it into a clean Claude Code workflow

The integration draws on what you’ve already documented elsewhere in your stack, and that’s where the advantage compounds.

A minimal CLAUDE.md stops describing the architecture in prose: it simply points to the knowledge graph and tells the agent to query it first. You save the hundreds of lines that manual description used to cost, and above all you gain in freshness; the graph is up to date, your prose never is.

A dedicated Skill explains to Claude when to invoke /understand rather than setting off exploring. That’s the very role of Skills as I’ve described them: a conditional trigger that mobilises a specialised competence. The frontmatter specifies that the Skill activates on architectural queries, on cross-module refactoring tasks, on questions of the type “where does logic X live?”.

A PostToolUse hook triggers /understand --auto-update after every commit that touches the code, guaranteeing the graph never drifts from the repository. To go further, a PreToolUse hook can intercept the Read, Grep and Glob commands and redirect the agent to the graph when the query can be satisfied by it.

You’ll notice what’s happening: none of these points is a rewrite of the existing guides. They’re activations of what your documentation stack already covers. That’s what makes this integration impossible to reproduce for someone who hasn’t laid the foundations upstream.

Code is no longer a text, and the agent no longer reads

The conclusion taking shape spills beyond Understand-Anything. The conceptual break is that the codebase becomes a queryable object rather than a read one. And that the agent is no longer a fast reader but an informed navigator.

This doesn’t stop at code. The pattern (a structured index, versioned, queried by an agent) holds for SQL schemas, for technical documentation, for API contracts, for infrastructure. Everywhere a project’s knowledge today takes the form of flat text scattered between Confluence, Notion, GitHub Wiki and file-header comments, there exists a structured version just waiting to be extracted and made available.

Token optimisation, which fills the tech listicles month after month, is a weak signal. The strong signal is that a whole generation of tools that treated knowledge bases as libraries to devour is giving way to tools that treat them as maps to traverse. And the difference between an agent that devours and an agent that traverses isn’t a few per cent on the bill. It’s the difference between an assistant that simulates competence and an assistant that rests on a shared map of the project.

For the rest, the GitHub repository awaits your clone and your /understand. The entry ticket is free. The cost of not trying, on the other hand, keeps climbing with every session.