Agent Architecture Weekly

Monorepo Architecture Under AI Agent Workloads

Repo boundaries cap what agents can see, change, and remember.

Sponsored by Graphide

Agent Architecture Weekly Editors
· 9 min read · Updated
Cover illustration for “Monorepo Architecture Under AI Agent Workloads”
Agent Workflow Patterns · October 12, 2026 · 9 min read · 2,077 words

An AI agent working in a polyrepo hits three walls before it writes a single function: a read wall, a write wall, and a memory wall. Each one is a structural limit on what the agent can see, touch, or recall, and each is set by the shape of the repository, not by the capability of the model. A monorepo is a context strategy, not a storage convention. The decision about how many repositories a codebase lives in determines, in advance, how much of the system an agent can reason about when it generates code, and that decision now carries consequences it never carried when humans wrote every line.

The older argument for monorepos centered on developer ergonomics: shared libraries, a single CI pipeline, atomic commits across packages. Those benefits mattered, but they were conveniences. A human engineer missing cross-repo context could ask a colleague, check a wiki, or simply remember the decision from six months earlier. An agent has none of that. It has the context window it's given and the repository boundary it's confined to, and nothing else. A skilled developer can compensate for a fragmented codebase with institutional memory and judgment, but an agent is simply stuck with whatever the repository boundary gives it. That shift turns architecture from an optional quality factor into a direct constraint on output. The three walls, read, write, and memory, are what follow from that shift, and each one deserves examination on its own terms.

The read wall's degradation of agent output in a polyrepo

The read wall produces a specific and recognizable failure: code that looks correct in isolation and is wrong in context. An agent working inside one repository loads the files relevant to its task into its context window, and in a polyrepo, the definitions it would need from somewhere else, shared types, utility functions, component contracts, simply aren't there. The agent doesn't know they're missing. It either reimplements them from scratch, inconsistently, or leaves out a constraint it never saw.

Spectro Cloud's experience building PaletteAI supplies a concrete instance of this failure. An agent updated the application to read Kubernetes secrets that a non-admin role should not have been able to access, an RBAC mistake with real security consequences. The automated code reviewer caught the problem, but only because the backend role definitions and the UI change that exposed them sat inside the same pull request. The bug wasn't a reasoning failure. It was a visibility failure: the information needed to catch it existed, but it was split across a boundary nothing in the agent's context crossed.

The write wall's block on atomic change

Where the read wall limits what an agent knows, the write wall limits what it can do in a single, atomic action, and it does so at precisely the moment an agent's speed would matter most. Nx documents the mechanics: a change that touches multiple repositories requires separate, coordinated pull requests, careful backwards-compatibility management, and a sequence of merges that a human has to track across teams. An agent can write the code for each piece of that change. It cannot make the change happen as one event, because the repository boundaries force it to be several events, stitched together by people.

That coordination tax lands hardest on exactly the work that would benefit most from agent speed: upgrading a shared library across every consumer, migrating an API, running a large-scale refactor across a dependency graph. These are the tasks agents are structurally suited to execute quickly, and they are the tasks the write wall makes the most expensive to attempt. In a real organization, with approval queues, separate team ownership, and the context switches that come with waiting on someone else's review cycle, that gap widens.

The more consequential effect is the work that teams quietly write off and never attempt. When cross-repo coordination is expensive enough, teams quietly write off certain refactors and migrations as not worth the overhead, and that decision gets made before anyone evaluates whether an agent could have done the work in an afternoon. A polyrepo doesn't just slow down cross-cutting changes; it removes them from consideration. The write wall's real cost is the counterfactual work nobody counts, and it disappears from any measurement precisely because it was never attempted.

The memory wall's effect on multi-session agent work

The memory wall is the least visible of the three and the most corrosive to work that spans more than a single sitting. Nx calls the phenomenon the "Memento Problem": an agent updates Repo A on Monday, a developer opens Repo B on Thursday, and the agent has no memory of what it decided earlier in the week or why. Every repository boundary doubles as a knowledge boundary. The developer has to reconstruct and re-explain context that, in a coherent system, should never have been lost.

A monorepo changes the character of the mistakes an agent makes. Coherent mistakes are detectable mistakes. That's the quieter but more important advantage of unified memory: not fewer errors, but errors a team can actually find.

The same failure mode scales beyond individual sessions. Memory loss compounds: it's the mechanism by which a mistake made once becomes a mistake made everywhere.

What AGENTS.md does for agent context in a monorepo

Explicit context files like AGENTS.md are one of the clearest tools teams have for closing the gap the three walls open, but they only work at full strength when the repository structure gives them one authoritative home. AGENTS.md is built to provide project-specific instructions and context to an agent working in a codebase, according to Spectro Cloud's account of building PaletteAI, and a monorepo is what lets that file do its job cleanly: one canonical set of conventions, ownership boundaries, and intent, sitting at the top level, with subdirectories that inherit from it rather than duplicate it. In a polyrepo, the same effort has to be copied into every repository separately, and because nothing forces those copies to stay synchronized, they drift apart almost immediately.

The payoff from getting this right appears when an agent doesn't have to search for context it should have been handed directly, spending less effort establishing the ground truth of the system and more effort on the actual task. The standard itself is also maturing past a single company's convention. Spectro Cloud points to the Agentic AI Foundation, which now stewards the Model Context Protocol, AGENTS.md, and Goose as shared open standards, giving teams a common format.

The same logic extends to documentation. AGENTS.md and co-located docs are the same structural principle, applied twice: give the agent one place to look, and make sure that place is complete.

Where monorepo structure alone breaks down at scale

None of this means a monorepo is a solved problem once adopted. It removes the three walls, but it introduces a different set of pressures that only appear once an organization's codebase and agent usage both grow large. Every commit an agent makes potentially touches the entire dependency graph. Error patterns that would have stayed isolated in separate repos now propagate across the whole system. And CI infrastructure built with a human committer in mind, someone who sleeps, who commits a few times a day, who stops when a review comes back with changes requested, was never designed for an agent that doesn't do any of those things.

Scale imposes a hard limit that no amount of model improvement removes: a repository with 400,000 files cannot fit inside any context window, no matter how large that window grows. Finite context is a fixed property, and the real engineering question isn't how to eliminate the constraint but how to index and navigate the dependency graph so an agent can find the relevant slice of a very large system without loading all of it. Reviewers, too, can be fooled by consistency: when an agent generates structurally similar code across several modules, a human reviewer recognizes the familiar shape and approves it, and the same architectural flaw gets waved through multiple times before the repetition itself raises a flag.

CI amplification is its own distinct risk. That's a fair point, and it applies specifically to retrieval. It doesn't touch the write wall or the memory wall, because neither one is a retrieval problem. Sequencing a multi-repo change across teams and preserving decisions across sessions are coordination and persistence problems, and architectural drift is a governance problem, not a search problem. Better retrieval narrows one gap and leaves the other two exactly where they were. Structural enforcement remains necessary regardless of how good the model gets at finding files.

CI enforcement as the mechanism that keeps architectural intent intact at agent speed

Enforcement is the piece a monorepo makes possible but does not provide on its own. A monorepo's single-repo visibility is a necessary condition for a reviewer, human or automated, to catch a cross-boundary problem. It is not, by itself, the thing that catches it.

The answer practitioners are converging on is to extend CI itself with checks that detect architectural violations, code duplication, dependency misuse, and deviations from whatever constraints an organization has set, making the build system the arbiter of structural correctness. That shift matters because of where the knowledge gap actually sits: the agent that wrote the code had the full conversation context, the prompt, the files it touched, the reasoning behind each choice, and the human reviewer sees none of that, only a diff that looks plausible but was produced from a partial view of the system. Automated enforcement that operates on the dependency graph itself, rather than on the diff a pull request presents, closes that gap at the structural level instead of hoping a reviewer catches it by inspection.

The principle underneath the synthetic monorepo concept

Step back from the repository format itself: what an agent needs is read completeness, atomic write, and continuous memory, and a single repository is simply one way, not the only way, to deliver those three properties. Nx's concept of the synthetic monorepo makes this explicit. Most organizations cannot or will not consolidate years of codebase history into one repository, so Nx built Polygraph, a meta-harness that connects multiple repositories into a single dependency graph without physically moving any code, lets a cross-repo change get orchestrated as one atomic event, and gives an agent continuous memory across sessions and machines regardless of which repository it happens to be working in at a given moment.

The synthetic monorepo doesn't argue that an actual monorepo has no advantage. What the concept demonstrates is that the three properties are the real requirement, and a repository boundary is one mechanism among several for delivering them. The same logic underlies the broader idea of treating a live, structured graph as the source of truth for a codebase, whether that codebase sits in one repository or forty. What a developer steering an agent needs is a current, navigable map of what the system actually contains and what the agent just changed within it.

That reframes the developer's role in an agent-driven workflow. The job isn't reading every line an agent produces, a task that stopped being feasible once agent output volume passed what a human reviewer can meaningfully absorb. The job is holding the architectural intent that the agent has no independent way to maintain on its own, and steering from a map of the system rather than scrolling through its output line by line. Agents generate code faster than any manual review process can follow, in a monorepo or out of one, and the only durable answer to that fact is to make a system's structure enforceable at the speed code gets written, rather than asking agents to slow down to match the speed at which humans used to check their work.

Current verification workflow

Dependency information can help explain a change’s reach, while CI still needs to establish the outcome of the tests it is responsible for running. Graphide CI runs existing GitHub Actions jobs on Graphide runners, using warm caches, and splitting long test steps only where a check shows every result stays the same, to reduce waiting while preserving the pass/fail verdict. A failing test fails the job. Graphide review is a separate product that presents changed behavior and findings with evidence; it does not block merging on its own. Consult the current documentation for supported workloads and limitations.

Product information updated November 5, 2026 to reflect Graphide’s current CI and review products.

Sources

  1. Confucius Code Agent: Scalable Agent Scaffolding for Real-World Codebases

More in Agent Workflow Patterns