The first fifty solution notes feel useful. The next five hundred can become another repository to search. In compound engineering large codebase work, the problem is not whether Markdown is good or bad. It is whether each type of context is represented in a form that matches the questions agents need to answer.
Markdown remains the right format for explanations, decisions, and operating guidance. Large systems also need current structural links: which modules depend on a changed package, which implementations satisfy an interface, and which tests exercise a path. Those links should complement repository memory, not replace it.
Why Large Codebases Stress Markdown Memory
Markdown is organized for reading, while an agent often needs to traverse relationships. A document can say that the billing service calls a ledger adapter, but it cannot automatically show every caller, the revision on which the statement was true, or whether a second document disagrees.
That is the central scaling problem in compound engineering large codebase work: durable prose remains valuable, while structural questions need revision-scoped evidence.
Scale makes four problems visible:
- Discovery: relevant notes are distributed across directories and use different vocabulary.
- Granularity: one document mixes repository-wide rules with a one-version workaround.
- Freshness: the explanation remains after symbols, modules, or ownership boundaries move.
- Collision: several teams document the same subsystem from different perspectives.
Compound Engineering's current ce-compound skill writes a focused durable learning to solutions/, and ce-compound-refresh can inspect the collection for staleness and overlap. [CE-COMPOUND-20260724] [CE-REFRESH-20260724] Those controls improve document hygiene. They do not turn prose into a revision-aware map of the repository.
For the underlying graph concept, see Knowledge Graph for AI Coding Assistants. For a layer-by-layer decision, use CLAUDE.md vs Knowledge Graph.
What Markdown Notes Still Do Well
Markdown is excellent when the answer needs judgment rather than traversal. It can explain why a migration was staged, which incident revealed a design weakness, or why a tempting fix was rejected. Those are durable narratives with context that a call graph cannot infer.
Use concise repository instructions for rules that should affect most sessions. Anthropic documents CLAUDE.md as an instruction mechanism loaded into Claude Code context and recommends keeping it concise. [ANTHROPIC-MEMORY-20260724] Use solution documents for validated problem-solution records that should be retrieved when a related issue appears. Use architecture decision records for decisions whose alternatives and consequences matter beyond one fix.
Claude Code auto memory is a separate host feature; it is not the same thing as Compound Engineering's solution-document layer.
Good notes state their scope. They identify a subsystem, the repository revision or release window, the evidence that validated the conclusion, an owner, and an invalidation condition. A note titled “Queue retries” is weak. A record titled “Prevent duplicate settlement after queue redelivery” with affected paths, tests, and version assumptions is useful repository memory.
Prose should own meaning. It should not pretend to be an exhaustive index of the code.
What Large Systems Need Beyond Notes
Large repositories need a structural index that can answer bounded questions against the current revision. Useful relationships include:
The awkward search phrase Compound engineering large codebase GitHub points to a reasonable evaluation task: inspect the current official repository rather than assuming an older guide describes the present plugin. The pinned repository used for this article documents the current command and skill surface. [CE-README-20260724]
- package imports package;
- function calls function;
- type implements interface;
- endpoint reaches handler and service;
- test covers symbol or route;
- owner maintains directory;
- solution document concerns subsystem.
This is a proposed external layer, not a documented feature of Compound Engineering. Each relationship should carry provenance: source file, line or symbol identifier, commit, extraction method, and confidence where static resolution is incomplete. Access scope matters too. A cross-repository link must not expose a private service name to a user who cannot read the source repository.
The result is not “all company knowledge in a graph.” It is a narrower, testable map of relationships an agent otherwise has to rediscover. Human explanations remain in Markdown. The graph helps select the relevant code and documents.
How Structured Links Improve Repository Memory
Consider a task to change an authorization policy. A text search finds the policy name and several old incident notes. A revision-aware structural query can add the middleware that calls it, the endpoints that reach the middleware, the tests connected to those paths, and the solution record for a previous regression.
The agent can then retrieve a small evidence bundle instead of reading every nearby file. In a proposed Graphify-assisted workflow, Graphify is one possible external code graph layer that returns structural candidates with provenance. It is not an official integration with Compound Engineering, and the agent must verify high-impact links against the repository before changing code.
Structured links also make disagreement visible. If a solution document says service A owns validation while the current call path places it in service B, the system should surface a conflict rather than silently choose. That conflict becomes a review task: either the note is stale, the graph extraction is wrong, or the architecture drifted without documentation.
This division of labor is the useful pattern: graph for retrieval and traversal, prose for reasoning, source code and tests for final verification.
Limits and Maintenance Risks
Structured memory has its own maintenance cost. Dynamic dispatch, generated code, reflection, runtime configuration, and feature flags can produce incomplete or misleading links. Branches can diverge. Renames can preserve behavior while breaking identity. An index built on yesterday's main branch should not be presented as fact for today's release branch.
The maintenance plan should name an operator, a subsystem reviewer, an incident path, and a maximum acceptable lag for each indexed repository.
Define freshness as a service-level property. Record the indexed commit, expose ingestion failures, and reject or qualify queries when the requested revision is outside the index. Sample important links against source code, especially around security, billing, migrations, and destructive operations.
Avoid measuring success only by graph size. More nodes can mean more noise. Better measures include time to verified evidence, irrelevant files opened, stale claims detected, corrections after review, and coverage of the subsystem under test. Compare the same task, revision, agent, and model configuration before attributing an improvement to the memory layer.
Finally, set deletion and retention rules. Removing a repository or branch should remove derived facts and embeddings. Historical links can be useful for incident review, but they should be clearly separated from current retrieval.
FAQ
When should notes become structured data?
Convert a claim when agents repeatedly need to filter, traverse, compare, or validate it across many artifacts. Keep the explanation in prose, but represent stable identifiers and relationships as structured facts. A one-off decision rationale does not need a graph node simply because it can have one.
Who validates architecture links?
The team that owns the affected boundary should validate high-impact links. A platform team may operate the index and its extraction rules, while service owners review samples and investigate conflicts. Links used for security, data integrity, or migrations should be checked against code and tests before action.
How often should repo memory be rebuilt?
Rebuild structural facts whenever the required freshness contract would otherwise be violated—often on relevant commits or merges, not an arbitrary calendar schedule. Review prose on ownership changes, upgrades, incidents, and stated expiry conditions. The indexed revision should always be visible.
What is a compound engineer?
In this context, it is an engineer who turns completed work into reusable inputs for later work: clearer plans, reviewed changes, and durable solution records. The current Compound Engineering plugin encodes parts of that workflow, but the role is broader than any one tool. [CE-README-20260724]
Conclusion
Large codebases do not outgrow Markdown. They outgrow using Markdown for every context problem. Keep rules, explanations, and validated solutions in concise, owned documents. Add a proposed external structural layer when agents need revision-aware traversal across code and related records.
Reliable repository memory is not the largest archive. It is the smallest evidence set that lets an agent find the relevant structure, understand the prior reasoning, and verify both against the current code.
Leave a Reply