A Monorepo Is a Knowledge Graph

Split related code across repositories and its shared graph becomes something you must reconstruct; a graph-aware monorepo turns that knowledge into working infrastructure for developers, continuous integration and AI.

A monorepo has an underappreciated quality: it remembers.

Not as a grand semantic model of everything, but as an operational dependency graph whose edges the build can use.

Every import, project reference and build target contributes to a live model of the system. Add a graph-aware build tool and the repository can answer practical questions: what depends on this, what must run, and where can a change travel?

That is the best case for a monorepo. It does not merely put code in one place. It turns knowledge about how software fits together into infrastructure used by ordinary development.

Repositories are often split for reasons that sound architectural but are mostly administrative. Team autonomy does not require separate history. Independent deployment does not require separate source. An acquisition needs an explicit integration decision, not permanent isolation by default. Access control should follow the smallest genuinely restricted boundary, not every line on the organisation chart. A repository boundary is an expensive way to express an organisational preference.

After enough repository-by-default decisions, a global question becomes strangely difficult: if this changes, what else might break?

The ambition behind a knowledge graph is reasonable: create a machine-readable map of repositories, services, dependencies, owners and deployments. People and AI agents can then discover what exists, understand an unfamiliar system, estimate the blast radius of a change and find the right team during an incident.

The mistake is not building that map. It is rebuilding source and build relationships that a graph-aware monorepo already maintains through everyday work.

So one team builds a software catalogue. Another crawls source code for dependencies. A third generates documentation. Someone adds a graph database to reconnect the pieces. Then AI is given tools for asking the graph where the code lives.

The result can be sophisticated. It is also a little like dividing a library among a thousand locked cupboards and commissioning an excellent map room next door.

The map room may be useful. A monorepo gives it fewer cupboards to reconcile and a stronger map to begin with.

The Graph Comes With the Work

An app imported a library. A build required another build to finish first. A project reference had consumers. Splitting related code across repositories removed none of those relationships. What it often removed was a shared transaction in which they could be changed and tested together.

A federated build can reproduce much of this by pinning repository revisions and joining their graphs. It must still build the revision-coordination machinery that one repository supplies by default, and a cross-repository change is still not one source commit.

Static analysis reconstructs imports. Parsers infer endpoints and message topics. Scheduled jobs check for drift. Language models turn fragments into plausible flows. Service owners are then asked to correct the result.

No individual response is ridiculous. Together they can form a second software estate whose job is to observe the first.

I have already made the broader case for why a monorepo matters. Here the narrower question is what knowledge repository fragmentation forces us to reconstruct.

Make the Graph Operational

A monorepo alone is merely a large folder. The useful combination is a monorepo and a graph-aware build system, such as Nx, Bazel, Buck or Pants.

Nx is a useful example. Its Project Graph represents projects and dependencies; Nx combines it with task configuration to construct the Task Graph that selects and orders work. Configured rules can enforce dependency boundaries, and the model is available to other tools. First-party integrations cover TypeScript, .NET through MSBuild and Java through Gradle. Polyglot does not have to mean polyrepo.

The difference is the maintenance bargain. A catalogue can keep descriptors near code, but duplicated facts still require two representations. Imports, project references and build manifests change with the software; continuous integration uses them before merge.

Our Nx monorepo contains Angular, .NET, iOS, Android and Kotlin Multiplatform code. One affected calculation selects builds, tests and checks for Angular and .NET, while native projects retain their own toolchains. Not every cross-language relationship becomes an edge. A polyglot monorepo is a shared source boundary, not a universal graph.

We still keep steering and domain documentation for accessibility, design systems and server-side rendering. Machines maintain what the build can know; people explain what requires judgement.

The build graph is not infallible. Nx says its calculations are only as accurate as their edges. Reflection, runtime configuration, HTTP calls and undeclared message flows can escape it. A missing edge may under-select tests instead of failing the build.

But use places the graph under pressure. A bad edge can produce a visible failure, a wrong cache hit or a missed test. An independently reconstructed graph can be wrong while every build remains green. For facts the build already governs, that is weaker authority.

Block provides a useful bounded example. In March 2026 it described moving roughly 450 Cash App JVM services and libraries into a monorepo. A core-library change used by hundreds of services reached a green build in ten minutes. Two years earlier, the same kind of change had required days of coordination across dozens of repositories.

Moving the books was not free. The work included a seven-month pilot, an 18-month migration, shared Gradle plugins, flaky-test control, merge queues and a custom IntelliJ plugin. Some outliers stayed outside. The monorepo did not delete platform work. It moved work from reconstruction into build infrastructure, where it could prevent a bad change rather than document one later.

Give AI the Operational Graph

Humans hid the cost of fragmented context rather well. We called it coordination, onboarding, release management or knowing whom to ask.

AI makes part of the cost visible as tool calls, retrieval time and tokens. On a cross-repository change, an agent must discover which repositories matter, retrieve summaries, resolve contradictions and eventually inspect the source.

A monorepo does not make the whole codebase fit inside a prompt. Nor should it. It makes a maintained dependency graph available for selecting the small part that matters.

There is evidence for the value of that structural context, although not for the sweeping claim that monorepos make agents cheap. Microsoft Research's CodePlan combined dependency analysis with language models for repository-wide changes. Five of seven repositories passed its validity checks; baselines given similar context but no dependency-led planning passed none. That supports the graph, not a particular repository topology.

The monorepo hypothesis is narrower: if the graph used for builds can also localise an agent's work, there is less source context to reconstruct elsewhere. Test that claim. Give the same cross-cutting tasks to agents with and without the operational graph. Count discovery calls, tokens, elapsed time, affected-project accuracy and successful changes.

Context engineering is valuable. Context reconstruction is the tax to measure.

Add Finer-Grained Graphs

Nx works mainly at project and task level. It can know that an Angular app depends on a TypeScript library, that an API depends on a .NET project and which builds or tests a change should trigger. It does not normally know that PlaceOrder calls ReserveStock, which controller handles a route or which methods appear to have no callers.

That is what a semantic or abstract syntax tree (AST) based code graph can add. The public Codebase Memory MCP, for example, indexes functions, classes, calls and routes for structural search and tracing. This is finer-grained knowledge than a build graph, not a replacement for it.

Would such a tool benefit a monorepo? Yes. Revision coherence becomes the default rather than another integration problem. The build graph can narrow the search to affected projects; the code graph can trace relevant symbols inside them. If analysis finds a source-evidenced dependency relevant to building or testing, validate it and promote it into the operational graph so continuous integration can use it next time.

The distinction is authority. Let the build graph govern what continuous integration selects and orders. Let the code graph help people and agents navigate how the source appears to work. Do not make the observational graph rediscover project boundaries, commands and dependencies that the operational graph already maintains.

Neither static graph can tell us which version is serving traffic now. Contracts and infrastructure describe intended interfaces and topology. Deployment systems describe what was deployed; telemetry describes what was observed during a stated time window. People describe purpose, ownership and risk.

A central service can still join and present those views, and it may own curated facts such as purpose and criticality. Its job becomes smaller and more honest: connect facts owned elsewhere without copying their authority. Backstage's own guidance describes its catalogue as a cache rather than the ultimate source of truth.

People should maintain the facts that require judgement. Ownership, purpose and criticality qualify. Project dependencies, toolchains and build commands usually do not; branch rules belong in source-controlled policy that continuous integration can enforce. If a machine can derive or validate a fact during normal development, asking a person to maintain a second copy is not governance. It is hope with a form attached.

Deterministic still does not mean true. A parser can misunderstand the same convention perfectly every week. Static analysis can omit a runtime dependency. A grounded language model can add an unsupported claim. The point is authority, not certainty: calculate what can be calculated, query what can be queried, and generate prose only where explanation helps.

Build Outwards From the Monorepo

One monorepo need not contain the whole company. Security, legal access, lifecycle and genuine product boundaries remain good reasons to separate code. At very large scale, source control, build performance and merge throughput become platform problems of their own.

Uber offers the appropriate warning. Its core code lives in a few language-oriented monorepos. In an analysis of 500,000 changes to its Go monorepo, 1.4 per cent affected more than 100 services and 0.3 per cent affected more than 1,000. Uber built cross-service rollout orchestration to contain the risk. A coherent graph can reveal a blast radius. It can also give you one.

The sensible unit of consolidation is not the company. It is the boundary inside which code frequently needs to change and be validated together. A connected Java estate might form one monorepo. A product spanning Angular, .NET and shared contracts might form another. The objective is not to win a competition for the fewest repositories.

Start with a strongly related slice of the estate. Put it behind one operational build graph and ask the real discovery, dependency and change-impact questions. Measure what it answers, what it misses and what it costs. Then add deployment, telemetry and human context for facts that exist only there.

What remains is the real knowledge problem. It may justify a code graph, runtime graph and catalogue, each with clearer authority because it starts from a coherent source and build foundation.

The map room is valuable. It works best when the books that change together already share a shelf, and the shelf updates the map whenever they move.