A Monorepo Is a Knowledge Graph

Part One of two. Split related code across repositories and you must reconstruct its shared graph. A graph-aware monorepo can reduce the time and tokens AI spends rediscovering it.

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 is raw material for a live model. A graph-aware build tool turns that material into an operational graph that 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.

AI makes the cost of missing structure measurable. An agent spends more time finding repositories and more tokens retrieving context that the build could have selected. A better graph should reduce both without lowering the change success rate. Lower token use can also reduce usage-based AI spend.

Some repository boundaries are real. Restricted access, separate legal ownership, different lifecycles and software that rarely changes together can justify separate source. The expensive mistake is using a repository boundary when the only boundary is the organisation chart. Team autonomy and independent deployment do not, by themselves, require separate history.

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

A knowledge graph is the natural response: 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.

Build the map, but begin with the sources that already govern the work. Let the repository and build own source and build facts. Add code, deployment, runtime and human overlays only for questions they cannot answer.

The duplication then compounds. 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. Where that machinery is absent, reconstruction begins.

Nx is an open-source monorepo platform and build system. Its team has now commercialised that reconstruction path as Polygraph. Polygraph indexes repositories and connects them through packages and APIs, then gives agents a cross-repository graph, persistent sessions and coordinated pull requests and continuous integration. Nx calls the result a synthetic monorepo. This is useful for boundaries that must remain. It is also revealing: scattered repositories require extra machinery to recover context that one repository supplies by construction. Polygraph can coordinate several commits; it cannot turn them into one atomic source change. Nor does a monorepo supply all the semantic context and workflow that Polygraph adds.

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 consequence is how much 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 or the experimental Maven integration. Polyglot does not have to mean polyrepo.

Reading the Nx 23 source makes the shape reassuringly plain. Plugins can discover projects, add dependencies and enrich metadata; nx graph can export the resulting model as JSON. That makes the workspace graph available to other tools, although durable consumers still need a versioned contract rather than assume every exported field will remain stable.

That machine-readable model changes 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.

On 17 August 2026, our Nx export contained 1,091 project nodes and 9,946 captured project dependencies. It modelled the TypeScript, Angular and .NET estates in detail, but saw the native code only as two wrappers.

The empty native row identifies the next piece of platform work: let Gradle report Android and Kotlin project dependencies, and build the equivalent project adapter for Xcode. Source co-location gives both integrations one checkout by default; modelling turns it into a useful operational graph.

Even a complete operational graph would not explain everything. 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 missing or incorrectly declared edge can cause a missed test or stale cache reuse; an unnecessary edge usually causes extra work. An independently reconstructed graph can be wrong while every build remains green. For facts the build already governs, that is weaker authority.

Block shows both the gain and the cost. 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.

Let the Agent Query the Build

The fragmentation tax becomes acute on a cross-repository change. An agent must discover which repositories matter, retrieve summaries, resolve contradictions and eventually inspect the source. Humans hid the same cost rather well, calling it coordination, onboarding, release management or knowing whom to ask.

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.

Two studies show what dependency graphs add, although neither compares monorepos with polyrepos. The final July 2024 CodePlan paper reports that its generated changes built without errors and made the expected code edits in five of seven repositories; baselines using similar context without dependency-led planning did so in none. In a January 2026 preprint, the Repository Intelligence Graph authors report that deterministic build-and-test maps improved mean accuracy by 12.2 per cent and reduced completion time by 53.9 per cent across three agents and eight repositories. CodePlan tests repository editing; Repository Intelligence Graph tests structured architecture questions.

The narrower claim is this: when the build graph can also localise an agent's work, other systems have less context to reconstruct. Test raw source, the operational graph, a fine-grained code graph and both graphs together. Count discovery calls, token use, elapsed time, change-selection accuracy, change success rate and indexing cost. Otherwise a code graph may receive credit for relationships the build already knew.

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

An agent can query the graph through nx show project, machine-readable command output or a thin API. Model Context Protocol may provide another adapter; the operational graph should outlive every interface, as I argue in The CLI Will Outlive Your MCP Server.

Know Where the Operational Graph Stops

Nx maps projects and tasks, not method calls, implementations or routes. A semantic Code Graph can supply that detail, but it should remain advisory. Let the Project Graph select work; let the Code Graph trace symbols inside it; let compilers and tests challenge the inference.

A monorepo lets both graphs begin from the same checkout. A shared service may cache their indexes, but every answer must identify its source state and extraction rules. A developer's current checkout must outrank a stale central snapshot.

Part Two asks whether Nx should provide the revision, project and cache contract for this missing resolution without turning its Project Graph into a general knowledge platform.

The same authority test applies beyond source. Each graph should claim only what its evidence can support.

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. Backstage draws much the same boundary: its catalogue is meant to capture human mental models rather than an exhaustive inventory, and its FAQ warns that cataloguing every dependency is not a good fit. Its job becomes smaller and more honest: connect facts owned elsewhere without copying their authority.

That division leaves people to 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.

Even so, authority is not certainty. 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. Calculate what can be calculated, query what can be queried, and generate prose only where explanation helps.

Build Outwards From the Monorepo

The same discipline applies to repository scope. 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 shows why that boundary matters. 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.

That suggests a practical starting point. Take a strongly related slice of the estate and make its operational build graph the source-and-build foundation. Test it against raw source; record what it answers, misses and costs. Require every additional graph to name the question it answers, the authority it consumes and the cost of keeping it current. Then add deployment, telemetry and human context for facts that exist only there.

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.