Giving Cloud Coding Agents Institutional Codebase Knowledge

An agent that writes clean, well-reasoned code on its first day inside a repository often starts producing subtly wrong suggestions by the third week, because nothing about its environment retained what it learned. Cloud coding agents lose coherence across sessions because institutional codebase knowledge, the conventions, the architectural decisions, and the known failure patterns that make a codebase navigable, has no durable home in the agent's environment. The agent has no memory of prior sessions, no built-in sense of the team's established conventions, and no record of mistakes already made and corrected, so someone has to tell it, over and over, how the project works and what to avoid. This is an infrastructure gap, not a reasoning gap: the model brings general programming knowledge, but project-specific knowledge, the decisions and history that explain why the code looks the way it does, cannot be inferred from the code itself. A 1,000-line prototype fits comfortably in a single prompt, but a 100,000-line system does not, and the larger the system, the more institutional knowledge there is to lose between sessions. The costs are ordinary but real: agents repeat mistakes the team already fixed once, violate conventions nobody ever wrote down, and ship code that compiles cleanly while contradicting the design principles the team actually follows.

What "institutional knowledge" means in a codebase

Institutional knowledge is not the code itself. Four categories of knowledge make up that layer, and agents need all four even though none of them can be inferred from source code. Conventions cover naming patterns, module boundaries, and the idioms a team has settled on, the basic agreements about what the code should look like. Known failure patterns cover the debugging history, the categories of mistake a team has already made and corrected, so the same bug doesn't get reintroduced six months later. All four tend to live scattered across PR descriptions, design documents, Slack threads, and README files, when they are written down. A code search index can answer what a function does, but it cannot answer why the function exists, who last changed it, or which constraint made the current design the safe one to keep. Without that "why" layer, an agent fills in the gaps with a plausible guess, and the guess often violates a convention nobody ever wrote down for it to follow.

How manifest files work as a baseline

Instruction manifest files are the right place to start, but they are a floor, not a ceiling. Claude Code loads a file called CLAUDE.md at the start of every session, and that file is meant to carry bash commands, code style rules, and workflow instructions; Claude also keeps auto-memory notes that it writes itself, drawn from corrections and preferences it picks up during a session. Codex works differently, using a hierarchy of AGENTS.md files pulled from global and project-level scopes, where files closer to the working directory take precedence over more general ones, and the default combined limit on project instructions is 32 KiB. There is a practical ceiling here too: Claude Code's own system prompt already uses up a significant share of effective instruction capacity before compliance with additional instructions starts to degrade, which limits how much institutional context any single session can reliably hold. Left unmanaged, this is where manifests tend to fail structurally: teams keep adding to one file until it is too long to maintain, too broad to be precise about any one thing, and still missing the knowledge that only ever lived in PRs, tickets, and Slack threads.

Tiered context architecture: separating what the agent always needs from what it needs on demand

You get past the single-manifest ceiling by treating context not as one file but as a layered system, where documentation itself becomes load-bearing infrastructure instead of reference material written for humans to skim. This is the core structural move, and you can see the clearest test of it in a 108,000-line C# distributed system described in Vasilopoulos (2025), built around three distinct layers.

The first layer is a hot-memory constitution: a small, always-loaded set of conventions, retrieval hooks, and orchestration rules that stays compact enough to load into every session without crowding out everything else the agent needs to reason about. The second layer is a set of 19 specialized domain-expert agents, each responsible for a particular slice of the system, so that knowledge about one service or module doesn't have to compete for space with knowledge about another. The third layer is a cold-memory knowledge base of 34 on-demand specification documents, retrievable when a task calls for them but not loaded by default, so they never crowd the context window on tasks that don't need them.

Splitting hot and cold memory this way keeps the constitution small and precise while leaving the deep specifications available without them competing for space. Across 283 development sessions on the project, this structure produced a measurable effect: context propagated across sessions in a way that prevented failures and kept output consistent, and failure categories that occurred early in the project stopped recurring once the relevant knowledge got codified into the architecture. The model also maps naturally onto team structure, since different domain-expert agents can be owned by the teams responsible for the services or modules they cover, updated by the people who actually know that part of the system.

None of this works without a stable place to run it. Agents running inside isolated, preconfigured virtual machines have that kind of stable ground to work from; agents sharing environments with other processes, or boxed into thin, constrained sandboxes, do not, and that absence makes layered context much harder to implement in practice no matter how well the documentation layer itself is designed.

Why agent memory tooling beyond files is still immature

Static files are one end of the context spectrum. Most agents sit near the ephemeral end of that spectrum, because they lean on static configuration files for continuity between sessions. Claude Code's auto-memory, where the agent writes its own notes drawn from corrections made during a session, is a step in the direction of agent-managed memory, but those notes still live inside a file the agent appends to rather than a system that reasons over relationships between pieces of knowledge. True persistent memory would mean the agent actively manages and updates its own knowledge base over time, but mainstream coding harnesses don't yet offer that as a standard feature.

But flat retrieval runs into a structural problem that persistent files alone can't fix. The consequences compound in coding work specifically, where a hallucinated API signature or a wrong assumption about a type can waste hours of debugging before anyone traces it back to a bad retrieval.

Graph-structured memory addresses this directly. Graph-structured memory can recover why an API contract got locked in after a failed refactor, or which team decision explains a constraint sitting in the data model, the "why" layer that flat retrieval tends to miss. It also changes who benefits from the knowledge. The tooling here is still catching up to the need, but the direction is the right one: knowledge about code is shaped like a graph, and storing it that way is a better match for how the knowledge actually gets used.

What executable knowledge and validation-carrying representations add

Static documentation tells an agent what a decision was. It does not give the agent any way to check whether its own output actually respects that decision, and closing that gap is what executable knowledge is for. The idea treats code itself as a knowledge representation that carries its own verification: instead of relying on an agent to correctly interpret a paragraph of prose about an edge case, a team can encode the same constraint in a form that runs and returns a pass or fail. This matters because agents sometimes misread prose, especially prose about edge cases or boundary conditions or subtle architectural rules, but they cannot misread a test that fails.

In practice, you can see this across a few familiar forms of team infrastructure. Architectural fitness functions, automated checks that verify structural properties of the codebase as a whole, extend the same idea to the system level.

This fits into the tiered architecture as a third layer, standing alongside hot memory and cold memory, catching what even well-maintained documentation misses. The stakes are higher for agents running without a human in the loop. A background agent that returns a pull request has no one to ask when it hits an ambiguity, so executable validation becomes the mechanism that stops it from confidently shipping output that looks right but quietly isn't.

How the sandboxed environment shapes institutional context

Even well-built context infrastructure is useless if the environment running the agent can't execute a build, run a test suite, install a dependency, or check its own output. The environment is not a side concern sitting next to institutional codebase knowledge; it is half of what makes that knowledge durable. If you need production use with proprietary code, a dedicated microVM per agent workload, each with its own kernel, is a reasonable baseline.

Clean starts function as a form of context guarantee in their own right. Credential handling belongs to the same picture. When more than one engineer needs to inspect, continue, or review an agent's work in the same environment, that environment becomes a shared surface where teammates can see exactly what context the agent had and what it produced from it.

Replicas is one answer to this set of requirements.

Integrating context delivery into the workflows where engineering work starts

Context that lives in files and knowledge graphs only reaches an agent reliably if starting a run also triggers the right context assembly automatically. Left as a manual step, engineers will forget it, shorten it, or paste an outdated version, and institutional knowledge quietly becomes optional.

Ticket quality turns out to be a multiplier on all of this, since coding agents read ticket bodies as prompts. Triggering a run from a Slack message works the same way: when the relevant repository, branch, specification documents, and credentials get assembled automatically from the team's existing configuration, engineers can delegate work from the channel they're already using.

Linear offers one of the clearest examples of this working at scale. Ramp built a tool called Inspect on the Linear API, connecting specs, customer feedback, and code together, and the combination of workflow integration and context infrastructure now drives 75% of the pull requests Ramp merges. The accountability model Linear settled on for this kind of work keeps the human as the assignee on a ticket while the agent acts as a contributor, a workflow choice that also settles who owns context quality: the person who writes the ticket is responsible for the context the agent ends up working with.

GitHub and GitLab work as context surfaces in their own right, because a pull request is the natural output of a cloud agent run. Replicas supports triggering runs from Slack, Linear, GitHub, GitLab, its own dashboard, and through automations, schedules, webhooks, and the API, so the context assembled at run time draws from the same places the work was already scoped, without asking engineers to change how they operate day to day.

Measuring whether context infrastructure is working: what attribution and analytics reveal

Context infrastructure only improves if a team can trace a given piece of agent output back to the specific context that produced it. Attribution at the level of source, harness, model, and credential, for every run, is what separates genuine institutional learning from a team simply guessing at what worked. The clearest signal that context is working is an agent that stops repeating the same class of mistake across sessions, since that pattern suggests the relevant knowledge has actually been codified somewhere the agent can reach it. But without attribution tied to individual sessions, a team has no way to tell whether an improvement came from better context, a better model, a different harness, or plain luck.

Code quality problems become visible only as a lagging indicator, well after the mistakes that caused them. There's a volume effect compounding this problem, too: teams using agents now ship noticeably more pull requests than they did before, reviews are harder to keep pace with, and more changes reach production without a full human review pass. That makes context quality matter more rather than less, since there is less human inspection left to catch whatever the agent got wrong.

Full attribution makes a few things possible that guesswork cannot. It lets a team identify which manifest version, which specification document, or which knowledge graph state was active when a run produced particularly good or particularly bad output. Replicas provides analytics down to source, person, harness, model, credential, and the skills and MCP servers an agent reached for, across every minute an agent runs, giving teams the attribution layer needed to treat context infrastructure as something that can be measured and improved.

The return on this compounds over time. When teams close the loop between attribution and context improvement, they build up institutional knowledge in a form agents can use, and that lowers the cost of running agents well going forward. Context infrastructure built this way becomes a durable asset the team keeps drawing on, session after session, long after the engineer who first wrote a given piece of context has moved on to something else.