Short answer: use repo-local memory when the knowledge belongs in version control and should travel through code review. Use external memory when you need private or cross-repository continuity without adding files, churn, or agent-managed notes to business repositories.
Two local-first models
Both approaches can use plain Markdown and work without a cloud service. The difference is authority and ownership—not whether the files are readable.
| Concern | Repo-local memory | Tracebook external memory |
|---|---|---|
| Location | Inside each business repository | Under a separate local knowledge root |
| Git review | Natural: memory changes appear in PRs | Separate from business-code diffs |
| Clone portability | Travels automatically with the repository | Same remote resolves to one local project identity; root must be available |
| Private context | Must be excluded or carefully governed | Local by default and not committed with source |
| Cross-project knowledge | Usually copied or linked manually | Explicit project, domain, pattern, and system scopes |
| Repository noise | Memory updates can add review churn | Zero business-repository writes |
When repo-local is the better design
- The entire team should review every memory change alongside code.
- The knowledge is part of the repository's public or contractual documentation.
- New clones must receive the same memory with no external setup.
- Your agent host already has a small, effective path-scoped instruction system.
When external memory is the better design
- You do not want agents writing operational notes into business repositories.
- Personal debugging context, local environment facts, or incident conclusions should stay outside source control.
- Several repositories participate in one system and need explicit relationships without copying files.
- You want knowledge lifecycle and health state to evolve independently from product releases.
A deliberate hybrid
The boundary does not have to be absolute. Put public architecture documents, accepted ADRs, and team instructions in the repository. Keep working conclusions and governed agent memory externally. When an external conclusion becomes a product contract, graduate it into the repository and update the memory to cite that authoritative document.
Do not leave the same rule as two unrelated “current” facts. Decide which surface is authoritative, then point the other surface to it.
Tracebook's explicit boundary
Tracebook never installs a memory directory, hook, configuration file, or generated instruction into a business repository. Its runner validates that capture requests do not use scratch files inside either the business repository or governed knowledge root. This is a safety property, not a claim that repo-local memory is universally worse.