Codebase Summarization Agent for Large Monorepos

A codebase summarization agent for large monorepos needs more than a way to read files. It needs a persistent code graph as its memory substrate, with hierarchical summaries that explain the structure and durable memory that preserves decisions. That architectural choice separates an agent that accumulates understanding from one that burns context rediscovering relationships and still misses dependencies.

Why flat-text exploration breaks on large monorepos

The agent greps for an identifier, gets matches across dozens of files, and starts reading them one by one. An import leads it to another file, where a reference sends it off to search again. It tries to hold the relationships it has reconstructed in its context window while continuing to explore. On the next task, the same loop begins again. Each step pays the token cost of rediscovering structure that the previous exploration already traversed.

This is not merely a slow search process. Grep returns text matches, so the agent has to work out which are calls, dependencies, or uses of a name that have nothing to do with them. Agent4cs, published in July 2026, identifies the underlying problem as treating source code as flat text while underusing its interdependencies and hierarchy. In a monorepo, that weakness affects more than single files: it also affects cross-service call chains and code that uses shared libraries. A deprecated API's provenance is harder still, because matching its name does not explain how it came to exist or why it was replaced.

Why context windows alone cannot compensate for missing structure

A larger context window postpones the limit without removing the cost and latency of filling it with source on every query. Production agents consume far more input tokens than they produce, and large-repo exploration spends much of that input rediscovering how code fits together. Moving search into a subagent contains context pollution, but the exploration cost remains. Codebase Memory MCP's arXiv evaluation across 31 real-world repositories found that graph-based exploration used far fewer tokens and roughly half the tool calls of file-by-file exploration, while its answers were close in quality, though lower. Spare room in the context window also fails to keep architectural reasoning or what a team has learned about handling bugs across sessions. Agents need a queryable map of symbols and relationships.

What a persistent code graph gives the agent that text search cannot

A persistent code graph records the relationships that text exploration must otherwise reconstruct. Functions, classes, methods, routes, and imports become nodes, while calls, inheritance relationships, and cross-file dependencies become edges. Cross-package and cross-service HTTP route links are first-class edges. Finding what calls ProcessOrder therefore becomes a graph lookup instead of a search followed by file reads to validate each match. Persistence makes that lookup repeatable across sessions.

The graph also changes the agent's exploration vocabulary. An architecture overview provides orientation, while symbol search locates the named code element. Path tracing follows connections, and change-impact queries show what a change can reach. Cypher-like queries let the agent ask structural questions directly. Snippet retrieval then gives the agent the source it needs, including a single function body found by qualified name within a two-thousand-line file.

Codebase Memory MCP illustrates how the index can remain separate from language-model reasoning. Written in pure C and parsing through tree-sitter, it indexes the average repo in milliseconds and answers structural queries in under a millisecond, with zero LLM use in the indexing pipeline. Programmatic parsing saves the cost of a language-model pass each time the knowledge map has to be rebuilt. Its detect_changes tool accepts an uncommitted or branch-scoped git diff and returns the blast radius of reachable symbols.

How hierarchical, bottom-up summarization handles the scale problem the graph alone cannot

A graph can explain what calls what, but a reader also needs to understand what a subsystem does and why it exists. A separate summarization process is needed to write that account. A single pass cannot simply include every child-folder summary, because those summaries eventually exceed the available context themselves. Bottom-up summarization instead starts at the leaves and composes understanding upward. The repository's hierarchy bounds each step.

Agent4cs, developed by Siemens AG, Technical University of Munich, and King's College London, demonstrates this pattern as a research framework. Its summarization agent produces folder-level summaries, while a keyword-extraction agent identifies critical information from subfolders so important concepts propagate upward. A quality-assurance agent iteratively refines readability, coherence, and completeness. Evaluated against seven frontier models, Agent4cs improves semantic consistency across folder levels compared with two structured prompting baselines and reports a 38 percent gain in normalized keyword coverage rate. These results support the architectural pattern.

The division of work matters as much as the direction of travel. Compression alone can discard the concepts a parent summary needs, so keyword extraction gives their preservation an explicit role. Quality assurance then addresses whether the composed explanation is readable and complete. The resulting summaries interpret the repository, while the graph retains its connections.

Where hierarchical summarization degrades at the top of the tree

Bottom-up composition does not preserve every detail on its way to the root. Agent4cs reports that keyword coverage falls across layers as it gets harder to form higher-level abstractions. The repo-level summary is therefore the weakest artifact in the hierarchy. This is a structural limitation of compressing increasingly broad material. Treating the final summary as authoritative would hide the very dependencies the architecture was meant to expose.

The practical response is to invest in subsystem summaries two or three levels below the root, where understanding is most reliable and most useful for real tasks. Root summaries should serve as navigational aids that point toward those narrower accounts. When a broad summary omits a cross-service dependency, the graph can still answer a direct query about that connection. This gives the agent a way to move from orientation to evidence. The limitation sets a clear boundary on what a summary can establish.

Making the agent's understanding durable across sessions with persistent graph memory

An agent that reconstructs its index at every session has not made its structural understanding durable. Yet preserving the index alone is also insufficient, because code relationships do not record why an architectural choice was made. The graph can show the current arrangement without holding the reasoning that led to it. That reasoning needs explicit, structured external memory.

The code graph holds what exists and how it connects, while semantic memory holds decisions, rationale, open questions, and long-arc reasoning. Recent turns and active task context belong in a fast, in-context store. Architectural decisions belong in a persistent semantic or graph-backed store that survives session boundaries, machine restarts, and IDE closures. Neither layer replaces the other, and the developer must provision both.

Context compaction makes this separation especially important over months of work. A compacted account may keep a plan but lose the reasoning that made the plan make sense. The agent can then resume fluently without the connective tissue needed to interpret earlier choices.

How deterministic tools over a semantic tree extend the agent's reach across repositories

Across thousands of repositories, understanding structure is only part of the challenge. Applying a change also requires a repeatable execution method without manual coordination for every repository. Moderne's Moddy illustrates this separation by pairing natural-language conversation with tools over a Lossless Semantic Tree, or LST. The LST captures code structure, dependencies, and relationships beyond raw text and ASTs. Roughly equivalent to an IDE's internal code representation, it can also be serialized to provide codebase context beyond the file currently open.

In that architecture, OpenRewrite recipes are deterministic tools that the agent can choose and run. The agent identifies a suitable recipe, runs it across selected repositories, gathers structured results, and analyzes and clusters them. Probabilistic reasoning chooses and interprets the operation, while deterministic execution performs the transformation consistently. That separation matters because directly generated changes accumulate variance across repositories. Recipes make the change step auditable and reversible.

Moddy's legacy-database migration example makes the pattern concrete. Asked to migrate usage to PostgreSQL, it locates SQL across an organization's codebase, clusters the results, identifies proprietary legacy syntax, and surfaces recipes for the changes. The developer decides what to apply and retains visibility into the migration. The boundary between reasoning and execution applies whether a team uses a dedicated platform or builds its own tooling.

Choosing a graph indexing layer for a production monorepo agent

The indexing decision follows from the repository's language mix and the agent's actual work. Polyglot coverage determines how much structure the index can represent, while indexing latency determines how cheaply that representation can be refreshed. Queries must be fast enough for the agent to use structural lookups as it explores. Integration matters just as much, because an available graph tool is not necessarily one the model will choose. These properties are more useful selection criteria than a marketing benchmark alone.

For large, polyglot, performance-sensitive monorepos, codebase-memory-mcp fits the profile of production infrastructure with zero dependencies, near-instant queries, and passive injection through hooks. The hook pattern is the most transferable part of that design. Rather than waiting for the agent to choose a graph query over its familiar search tools, a hook enriches the tools it already prefers. This makes structured context part of the agent's normal behavior.

Deploying and operating the agent on a runtime built for persistent, scheduled work

Even a well-chosen graph and a sound summarization process need a runtime that keeps them useful. A graph that goes stale after a sprint can misrepresent the codebase it is meant to explain. Re-indexing must run on commit, on merge, or on a schedule tight enough to reflect the code when queried. Cheap indexing makes those updates practical, but the runtime must actually trigger them.

The same runtime must have durable storage that the memory layer can read from and write to across sessions. Architectural decisions, open questions, and reasoning built up over months need to survive even if an in-memory conversation is lost. Proactive execution also needs explicit support through events such as a new PR being merged, a dependency being updated, or a service boundary changing. Those events can cause the agent to update summaries and flag impacts without waiting for a prompt. Scheduled work and persistent state are what turn a manually invoked summarizer into infrastructure that accumulates understanding.

Putting the architecture together — the decisions that determine whether the agent is usable

A graph-first architecture commits the developer to more than adding another search tool. The indexing layer must work with the repository's languages, handle its size, and pass structural context through an integration the agent actually uses. Bottom-up, multi-agent summarization must then turn that structure into explanations without treating the root summary as ground truth. Subsystem summaries provide the useful detail, and graph queries supply connections that compression leaves out. Together, they give the agent both orientation and a way to inspect the underlying structure.

That understanding becomes durable only when structural memory is paired with a separate record of decisions and rationale. A monorepo makes these choices easier because the graph can see cross-service dependencies without inference at repository boundaries. The final commitment is to a runtime with event-driven re-indexing, persistent session state, and proactive execution. That infrastructure prevents the next task from becoming another expensive attempt to rediscover the same codebase.