Repo-Level vs Company-Level Context for AI Agents

Repo-level context holds the code. Company-level context holds the decision.

A founding engineer opens the root context file on a Tuesday and types a rule: weight the context budget toward this codebase's architecture, keep global company history out of it. The file gets committed, the agents load it. The rule holds.

Six months later, an engineer on an adjacent service writes the same rule from scratch, slightly differently, because the first file is invisible from her working tree. Three months after that, the team moves to a new harness, and the rule gets rebuilt a third time by whoever remembers it best.

Nobody contested the rule. Nobody overrode it. All three versions say the same thing. It kept getting rewritten because it was stored in a place only one repo at a time could see.

The rebuild tax is a storage-scope cost. You pay it when a company decision lives in a repo file that cannot outlive a migration or reach a second repo. The disagreement people blame for rewrite cycles is usually absent. The storage is the whole problem.

What company-level context can hold

Company-level context holds decisions that span repos and outlive migrations. Repo-level context holds the rest, and holds it well.

Codebase-specific rules belong in the repo: coding standards, tool configurations, architectural constraints that make sense only next to this code. AGENTS.md was designed for that job, and it does the job. If a rule loses its meaning when the codebase goes away, the root file is the right home for it. I have nothing to argue with there. The fix works at single-player scale, and keeps working at team scale for everything genuinely repo-scoped.

The failure is misfiling. The context-budget rule in the opening reads like a repo rule, so it went into the repo file. It is really a decision about how agents spend attention across a whole estate of repos. Written once per repo, it will be written three times, and the three versions will drift apart. Written once at company scope, it survives every migration and reaches every service.

Where repo scope stops

Two walls, both familiar to anyone who has switched harnesses.

The first is the harness switch. A rule that works in one harness is invisible in the next, because the next harness runs in a repo that never inherited the first file. The rule was sound. Its storage stopped at the repo boundary, and rewriting the rule does not move that boundary.

The second wall sits between agents. Agents that share context by reading the same file are coordinated. Connection asks for more, a substrate that agents read and write from the same place, so a decision one agent makes is available to another in a different repo, with nobody copying anything. The scope boundary is where coordination ends and connection has to begin.

Here is a test you can run in five minutes. Clone your repo and imagine the codebase gone. Which entries in your AGENTS.md still make sense? Every entry that survives is a company decision sitting in a repo file. The file is doing a job it was never shaped for, and doing it well does not change the shape.

What a company-wide context substrate adds

A company-wide context substrate holds a company-scoped decision once, legible across repos, and both people and agents read and write it.

Both halves have to be there. A store only humans write is a wiki, one agents reach through bespoke per-harness integration, and a decision an agent makes still needs a human to carry it across. A store only agents write is a silo the team never sees. The substrate pairs company-wide scope with humans and agents writing to the same surface. That is the whole conjunction.

Synthweave is the substrate we built for exactly this: snips, bases, and projects with hybrid search, read and written by humans and agents from the same place. The search matters more than it sounds. A decision has to be findable by an agent that was never told to load it, or you are back to per-repo loading with extra steps.

One precision note, because it is easy to overstate. Consequential agent writes, snip_rewrite and snip_patch specifically, are held as a proposal and never land until a human accepts them. Creation and metadata writes are ungated, and the gate depends on autoAccept being off. That is the exact coverage. I will not generalize it.

I run an AI-first brand studio on top of this substrate, production tools across multiple harnesses, and the scar is instructive. Before the move, every migration meant re-lifting brand-strategy decisions per tool: which persona a brand writes for, which claims are approved, which categories are off-limits in a market. The local rules files traveled fine. The brand decisions were company assets stored in the wrong place. Once they moved to the company-scoped substrate, the re-lifting stopped, and agents found the decisions through search instead of a per-repo load.

[REVIEW: PROCEED-WITH-WARN is active and operator review is required. Source B, a third-party citation on multi-repo context cost, was not confirmed at draft time, so the load-bearing claims above ride on operator experience alone.] [REVIEW: CLAIM NOT IN WHITELIST: the platform-as-proof scale claim about the studio's tool count has no approved register id and sits outside this article's approved claims whitelist. Retained, not removed, per operator instruction; requires operator disposition.]

We already version-control our AGENTS.md

Good, keep doing that. The discipline is real and I am not arguing against it.

The argument is about where the limit of that fix falls. Version control and review improve the quality of what is inside the file. They do not extend what the file can reach. A decision that must be legible to a second repo or the next harness cannot live in the first repo's file, no matter how well maintained, because the second repo and the next harness never open it. You already know how to write a good AGENTS.md. The question is which of its entries belong in a repo file at all.

The scan

Take ten minutes with your root file and sort every entry into two piles.

Pile one: rules specific to this codebase. They stay where they are. Pile two: decisions that should survive a migration or be readable from a second repo. Persona definitions, claim approvals, style verdicts, market restrictions. Those are company assets in the wrong place.

That second pile is what Synthweave was built to hold, a company-wide substrate with hybrid search, humans and agents both reading and writing. Moving the pile is a one-time job. Leaving it where it is costs a rewrite per repo per migration, indefinitely.

The third migration

It is coming, the way it always is. When it lands, the repo-scoped rules travel with the code. The company decisions stay where the next harness and the next repo can already find them.

The founding engineer writes the rule once, on a Tuesday. That Tuesday is the last one anyone spends on it.

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Repo-Level vs Company-Level Context for AI Agents" } </script>