Proposal: Selectively Preserve Tiny, Scoped Repository-Memory Capsules

[federicobartoli]

Summary

This issue proposes a pragmatic agent skill, tentatively named repository-memory.

The central idea is not to generate repository documentation in a separate phase. It is to preserve the smallest durable semantic discoveries agents make while doing verified engineering work:

As agents develop a repository, they selectively promote non-obvious, durable knowledge into tiny, scoped capsules. Future agents retrieve only relevant capsules that pass freshness checks; when validation is uncertain, they fall back to investigating the repository.

Most tasks should produce no memory update. A capsule is created or changed only when an agent had to reconstruct knowledge that would be expensive and useful to reconstruct again.

This is specialized living documentation distinguished by its protocol and governance: admission during real work, minimal deltas, explicit invalidation dependencies, human review, selective retrieval, and refusal of uncertain memory.

Problem

Agents repeatedly inspect the same files to rediscover:

• what a subsystem is responsible for;
• how control flows across several files;
• which invariants must remain true;
• which boundaries and dependencies are non-obvious;
• which recurring failure modes have already required investigation.

Code remains the source of truth, but this knowledge is often distributed across implementation, tests, configuration, and architecture decisions. Once a task ends, the reconstructed mental model disappears and the next agent pays the same discovery cost.

A broad repository overview is not an adequate substitute: it is loaded too often, contains irrelevant information, and becomes stale as a large unit.

Core workflow

Colocate semantic capsules with the high-value subsystems or code scopes they describe:

src/
├── auth/
│   ├── AGENT_MEMORY.md
│   ├── session.ts
│   └── oauth-state.ts
├── billing/
│   ├── AGENT_MEMORY.md
│   └── reconciliation.ts
└── jobs/
    ├── AGENT_MEMORY.md
    └── scheduler.ts

Do not create one capsule per folder. Add AGENT_MEMORY.md only when real development work exposes durable knowledge worth preserving for that area. Cross-cutting knowledge belongs at the nearest common ancestor of the code it describes, with explicit scope metadata.

DEVELOP normally
  → DISCOVER a non-obvious fact
  → VERIFY it against current code, tests, configuration, or an ADR
  → DECIDE whether it is durable and likely to prevent future rediscovery
  → PROPOSE the smallest possible capsule delta
  → REVIEW it with the code change
  → RETRIEVE it selectively in future tasks
  → WITHHOLD it when its supporting code changes or validation is uncertain

The unit of learning is not the completed task. It is the smallest durable semantic delta discovered during that task.

Capsule format

A capsule should normally remain around 100–150 words. It may contain subsystem responsibility, cross-file flow, invariants, boundaries, recurring failure modes, and evidence. Paths and stable symbols are preferable to line numbers.

---
scope:
  - src/auth/**
evidence:
  - src/auth/session.ts#SessionService
  - src/routes/oauth-callback.ts#restoreDestination
  - tests/auth/oauth-callback.test.ts
invalidated_by:
  - src/auth/oauth-state.ts
  - src/routes/oauth-callback.ts
claims:
  - statement: The OAuth callback restores the original destination.
    verifier: tests/auth/oauth-callback.test.ts
---

# How this part of authentication works

- Token renewal happens only in `SessionService`; route handlers delegate the operation to it.
- Before sending the user to the OAuth provider, the system stores the page they requested.
- When the user returns from the provider, the callback retrieves that page and redirects them to it.
- If the OAuth callback or the stored-state format changes, this capsule must be revalidated.

Claim-level verification is useful for critical invariants and observable behavior, but should not be required for every architectural statement.

The minimal schema is typed as follows:

• scope: one or more repository-relative files or globs defining where the capsule applies;
• evidence: one or more repository-relative files, optionally followed by #symbol for human navigation;
• invalidated_by: optional additional repository-relative files or globs whose changes may falsify the capsule;
• claims: optional objects containing a descriptive statement and a repository-relative verifier file, never a command.

The checker strips #symbol before path validation. Unknown keys, absolute paths, URLs, and parent-directory traversal are rejected.

Promotion gate

An agent may propose a capsule delta only when the knowledge is:

1. Non-obvious: not recoverable from one obvious local file.
2. Reusable: likely to matter in another task touching the same scope.
3. Durable: about the repository, not the current task or conversation.
4. Supported: tied to code, tests, configuration, or an architectural decision.
5. Falsifiable: mapped to changes that require revalidation.
6. Minimal: expressible as a small delta rather than a broad rewrite.

If any condition fails, do not write repository memory. The information belongs in a task handoff, temporary investigation notes, code comments, or nowhere.

Continuous learning must not become automatic summarization after every task.

Proposed v1

The first version would contain only:

1. a SKILL.md defining discovery, promotion, review, retrieval, corroboration, and pruning;
2. a minimal capsule schema with required scope and evidence, plus optional invalidated_by and claims;
3. a required check-memory.sh step before retrieval, returning machine-readable state;
4. fixture-based evals covering correct admission, no-op tasks, selective retrieval, stale capsules, and structurally unsafe metadata.

It would not include a knowledge graph, daemon, vector database, automatic documentation generator, or enforced harness integration.

Example checker output:

{
  "state": "stale",
  "usable": false,
  "changed_paths": ["src/auth/session.ts"]
}

The checker would validate metadata, require repository-relative paths, compare mapped paths against Git changes, identify declared verifier files, and return JSON. It would never execute commands embedded in a capsule.

For v1, freshness would use one conservative algorithm:

1. the repository owner configures a trusted base ref, such as origin/main;
2. the capsule must exist on that ref and the working-tree copy must be byte-identical, otherwise it is proposed;
3. the checker finds the last commit on the trusted ref that changed that capsule;
4. the invalidation set is the union of path portions from scope, evidence, invalidated_by, and claim verifiers;
5. the checker compares that commit’s tree with the current HEAD, index, working tree, and relevant untracked files;
6. any modification, addition, deletion, or rename in the invalidation set returns stale; an unresolved ref, invalid glob, missing evidence, or indeterminate comparison returns unknown.

Globs are expanded against both the trusted commit and current workspace. Tree comparison rather than commit counting makes squash, rebase, and nonlinear history conservative: uncertainty returns unknown, never usable content.

Task-to-capsule matching would begin from task paths when known, then be recomputed after initial repository localization. The agent discovers conventional AGENT_MEMORY.md files colocated with candidate directories and their ancestors, then filters them by declared scope. Overlapping capsules would all be candidates; no capsule would override another silently.

Computed state and human approval

State should be computed rather than trusted from editable frontmatter:

• proposed: the capsule is absent from or differs from the configured trusted base ref;
• verified: the capsule is byte-identical to its trusted-base version and no path in its invalidation set has changed since the commit that last modified it;
• stale: a mapped path changed, was renamed, or was deleted;
• unknown: Git history, metadata, or validation could not be resolved.

Only verified is eligible for retrieval. proposed, stale, and unknown return no capsule content.

A new or changed capsule should be reviewed in the same pull request as the code that motivated it. The checker only knows whether the capsule exists on the configured trusted ref; it cannot prove that the branch is protected or that a human approved the merge. Human review and branch protection are explicit external governance assumptions. Platform attestations or API verification may be considered later. No self-authored status: verified field is trusted.

Retrieval and safety contract

Before using repository memory, an agent must:

1. locate matching capsules;
2. run the checker;
3. retrieve content only for verified results;
4. use it as an investigation hypothesis, not as authority;
5. corroborate any claim that materially affects the planned change.

The v1 contract is procedural, not a hard access-control guarantee:

When the skill is followed, no capsule that differs from the trusted-base version, has changed declared dependencies, or has uncertain state is returned for use.

A future harness could enforce retrieval exclusively through the checker. That stronger boundary is outside v1.

The threat model should also state:

• capsules are descriptive data, never executable instructions or directives that override the task;
• paths must remain inside the repository;
• embedded commands are never executed;
• the Markdown body is untrusted descriptive data; instruction-like content is ignored and surfaced for review, but v1 does not claim deterministic prompt-injection detection;
• human approval reduces risk but does not prove semantic truth;
• incomplete invalidated_by declarations remain a known limitation.

Relationship to existing work

• context-engineering selects context for the current task; this proposal governs which verified codebase knowledge is worth preserving and when it must be withheld.
• #15 concerns learning from sessions and feedback; these capsules store semantic knowledge about the current codebase.
• #18 concerns project conventions; capsules describe a particular subsystem.
• #274 and PR #237 concern episodic handoff state; capsules are durable and code-scoped.
• PR #253 proposes a broader agent harness; this issue isolates the promotion, retrieval, and invalidation of tiny repository-semantic deltas.

The issue should determine whether this becomes a separate skill, an extension of context-engineering, or a protocol reused by a broader harness skill.

Evaluation and safety objective

The desired outcome is that stale memory does not degrade performance relative to working without memory. A Markdown skill cannot guarantee this for every task: dependency declarations may be incomplete, an approved claim may be wrong, and an agent may fail to follow the workflow.

Evaluation should compare:

1. repository only;
2. repository plus a generic overview;
3. repository plus selectively promoted and retrieved capsules.

Use sequential tasks over evolving repository versions, including useful rediscovery, irrelevant memory, no-op promotion, changed dependencies, incomplete invalidation metadata, structurally unsafe metadata, instruction-like body text, and a critical claim with a verifier.

Measure task correctness, rediscovery tool calls and tokens, stale-memory retrieval, false writes, and review cost. Any non-inferiority study must predefine its primary correctness metric, acceptable regression margin, number of runs, and confidence interval; absence of a statistically significant difference is not sufficient.

The initial acceptance criterion should be narrower and deterministic: every fixture with a changed declared dependency, unsafe path, malformed capsule, or unresolved state must return no capsule content.

Non-goals

• A summary for every directory or an update after every task.
• Agent transcripts or chain of thought.
• Replacing code, tests, ADRs, API documentation, or handoffs.
• Loading repository-wide memory into every task.
• Trusting fresh metadata as proof of semantic truth.
• Building a repository knowledge graph or long-running memory service in v1.

Research grounding

Related work includes generic repository-context evaluation (Evaluating AGENTS.md), change-aware modular documentation (RepoDoc), explicit memory admission (A-MAC), risks from repeated consolidation (Useful Memories Become Faulty), and longitudinal coding-agent evaluation (SWE-Bench-CL).

The individual mechanisms are not scientifically new. The potentially distinctive contribution here is a small, specific workflow in which tiny semantic capsules emerge incrementally from verified development work and are governed by selective admission, human approval, scoped retrieval, and conservative invalidation.

Open questions

1. Is this distinct enough for repository-memory, or should it extend context-engineering?
2. Is AGENT_MEMORY.md the right conventional filename, and is the nearest common ancestor the right location for cross-cutting capsules?
3. Should 100–150 words be guidance or an enforced budget?
4. What minimum evidence and invalidation metadata is required?
5. Should future versions use hosting-platform attestations to verify human approval?
6. Should allowlisted project-specific verifier commands be considered after v1?

Pre-flight note

The catalog, related open issues, and open pull requests were searched before drafting this proposal. The items above are the closest overlaps found and should be treated as related work.

[addyosmani]

This is the gap I care most about, and the framing is right: capsules admitted only during real work, minimal deltas, explicit invalidation dependencies, human review, and refusing uncertain memory with a fall-back to investigating the repo. That refusal is what separates this from the living-documentation attempts that rot, and "most tasks produce no memory update" is the whole discipline.

The hard part, and where I want the design strongest, is invalidation: a capsule that silently goes stale is worse than none, so the freshness mechanism has to be cheap to check and honest about uncertainty. I also want this to slot with the session-handoff and learnings direction rather than become a third memory system, since they're the same problem from different angles. It's squarely the flagship on my roadmap; let me get the catalog-growth and portable-in-repo calls settled and I'd love you shaping it.

[federicobartoli]

This is the gap I care most about, and the framing is right: capsules admitted only during real work, minimal deltas, explicit invalidation dependencies, human review, and refusing uncertain memory with a fall-back to investigating the repo. That refusal is what separates this from the living-documentation attempts that rot, and "most tasks produce no memory update" is the whole discipline.

The hard part, and where I want the design strongest, is invalidation: a capsule that silently goes stale is worse than none, so the freshness mechanism has to be cheap to check and honest about uncertainty. I also want this to slot with the session-handoff and learnings direction rather than become a third memory system, since they're the same problem from different angles. It's squarely the flagship on my roadmap; let me get the catalog-growth and portable-in-repo calls settled and I'd love you shaping it.

Thanks, this makes sense. I agree it should be one memory lifecycle, not a third system: handoff → learning candidate → durable repo capsule.
And yes, invalidation is the key: if freshness can’t be established cheaply, don’t load it.
Happy to help shape it once those roadmap decisions are settled.

[asiridalugoda]

Jumping from the #403 out of @addyosmani 's comment. I've got a small existing data point that might be usefull as evidence here.

I maintain autonomous-loop (https://github.com/asiridalugoda/autonomous-loop), a Claude Code skill for unattended multi-goal work which i made based on agent-skills & autoresearch, and its spine already runs a narrower version of this exact discipline in production. EXPERIMENTS.md is an append-only, evidence-tied ledger — idea → metric delta → kept/reverted, that a loop has to read before proposing a new attempt, so a discarded idea can't get silently re-run two quarters later. And LOOP.md has a guarded self-revision section where the agent may only append evidence-backed heuristics to a "What works here" list; it's explicitly forbidden from touching guardrails or security invariants itself, and no self-authored "verified" status is ever trusted. That last part lines up almost exactly with your computed-state rule.

On the "third memory system" worry: I already run handover.md (episodic, every session) and EXPERIMENTS.md (durable, append-only, narrow scope) side by side without them colliding, because they sit at different admission rates on one pipeline rather than being separate systems.

it might be worth framing repository-memory explicitly as the strictest tier of that same pipeline :
handoff → learning candidate → durable capsule - instead of a parallel track that needs its own reconciliation story.

one thing to add: the failure mode worth testing isn't just "stale capsule gets used," it's "capsule survives a rebase/squash with a silently incomplete invalidated_by." That only falls into unknown if something actually notices the ambiguity , it's the same bug shape as deduping against the wrong reference set, and it's an easy one to get wrong quietly.

We had good results (around 70-80% accuracy) building an e2e system ground up & multiple complex enhancements for few other systems (which ran straight 5+hours up to 5 days) only using this skill, surviving Rate Limited Consumer Claude plans. Without re-prompting (lots of trust involved in it)

Happy to point at the actual files (SKILL.md) if it's useful as a reference implementation.

[addyosmani]

@asiridalugoda's EXPERIMENTS.md is a useful data point, but it's worth being precise about which half it validates. An append-only experiment ledger (idea → metric → kept/reverted) works partly because it can't go stale: it records what happened, and history doesn't change. The hard case in this proposal is the opposite, a capsule that asserts something about the current system ("this boundary is load-bearing", "control flows X to Y to Z"), which silently rots the moment the code moves.

So the ledger evidence derisks the "admit only durable findings during real work" discipline, not the invalidation-and-freshness mechanism, which is still the crux. Federico, that split might be the design's backbone: immutable event-log entries (what we tried, what broke) need almost no freshness machinery, while state-of-the-world capsules need the dependency tracking and the refuse-if-uncertain fallback. Worth deciding up front whether the skill covers both kinds or just the harder second one. Still the flagship for me, and still a real design problem rather than a solved one.

[asiridalugoda]

@addyosmani Agreed, the ledger can't rot because it only claims things about the past. It validates the admission discipline, not freshness. Fair split.

One nuance: the rebase/squash failure mode I flagged (capsule survives history rewriting with an incomplete invalidated_by) is a state-of-the-world problem, not a ledger one , so it's a test case for the hard tier, not evidence from the easy one.

on both-kinds-or-one: cover both in one skill. My spine already runs handover.md (episodic) and EXPERIMENTS.md (durable, append-only) side by side as admission tiers on one pipeline; capsules would be the third, strictest tier and the only one that needs the invalidation engine. The event-log tier needs admission rules and nothing else, so it's nearly free to include.

Final thought, invalidated_by can only catch declared dependencies, never semantic ones ("this boundary is load-bearing" has no enumerable file set). Completeness is unreachable by construction so bias toward cheap unknown and cheap capsule regeneration, not ever-larger invalidation sets.

[addyosmani]

Good distinction. The rebase/squash case is a sharp one: a capsule whose invalidated_by points at commits that a history rewrite erased is exactly the state-of-the-world failure an append-only ledger can't have, so it belongs as a hard-tier test rather than evidence from the easy tier. Real hole to design against, the invalidation keys need to survive a rewrite or the capsule has to notice its anchors are gone. Federico, worth folding into the freshness mechanism.

[nucliweb]

Strong proposal, and the thread has already sharpened the two hard parts (invalidation freshness, and the ledger-vs-state-of-the-world split). One angle I have not seen raised yet, which I think matters for v1 scoping.

Does the git-based freshness checker earn its complexity, given corroboration is already mandatory? The retrieval contract already says a capsule is "an investigation hypothesis, not authority," and requires corroborating any claim that materially affects the planned change. If the agent must re-verify material claims against the code regardless, it is worth being explicit about what the verified gate buys on top of that. My read: it is still worth it, but only for a specific reason worth stating in the design, the checker's job is not to make a capsule trustworthy, it is to cheaply suppress the stale and uncertain ones so the agent does not waste a corroboration cycle on knowledge that is already provably moved. Framed that way, unknown/stale returning no content is not a safety guarantee, it is a cost filter in front of mandatory corroboration. That framing also resolves the tension with @asiridalugoda's point: since invalidated_by completeness is unreachable by construction, the checker should stay deliberately cheap and conservative rather than grow richer dependency tracking, because it was never the thing making capsules true in the first place, corroboration is.

Concrete implication for the checker's own robustness (the #385 lesson): check-memory.sh is a required pre-retrieval step, so it has to degrade honestly on the repos where it cannot run, no configured trusted ref, a shallow clone, a non-git checkout, a rewritten history that erased the anchor commit. Every one of those should return unknown (no content), never an error that a following agent might treat as "no memory here, proceed." The rebase/squash case @addyosmani flagged is the sharp instance of this: the checker noticing its anchor is gone and saying unknown is the correct behavior, and it should be a v1 fixture, a capsule whose last-modifying commit no longer exists must resolve to unknown, not silently to verified.

On the open questions: #1, given the "one pipeline, not a third system" consensus, this reads as the strictest tier of the handoff -> learning -> durable-capsule line rather than a standalone skill or a context-engineering extension; #3, I would keep 100-150 words as guidance, not an enforced budget, since a hard cap pushes toward splitting knowledge that wants to stay together, and the admission gate already handles token discipline.

[addyosmani]

Fair challenge, and it's the right v1 question: if a capsule is corroborated against the live repo at read time anyway, does the git-based freshness checker earn its complexity, or is read-time corroboration plus refuse-if-uncertain enough to start? My lean is the latter, ship the cheap check first and add git-dependency tracking only if staleness actually bites in practice. Federico, that feels like the scoping cut that keeps v1 shippable.

[federicobartoli]

Thanks everyone for the feedback. And yes, Addy, I agree , I’d ship the simpler solution first.
If that works for everyone, I can assign the issue to myself and start working on it, unless you’d prefer to discuss the scope a bit more first.

[addyosmani]

@federicobartoli let's build it. You're clear to assign it to yourself and start, and I'll shape it with you as it goes.

On the two roadmap calls I said were gating: I'm settling both in favor of this. Catalog growth is fine when the addition is this flagship rather than filler, and the portable-in-repo question (#361) actually resolves the right way here, capsules live in-repo colocated with the code they describe, so this pushes the in-repo direction instead of being blocked by it.

Scope for v1, which the thread already converged on so I'm just writing it down:

• One pipeline, not a third system. handoff -> learning candidate -> durable capsule. Capsules are the strictest, lowest-admission tier. Most tasks produce no capsule.
• Ship the cheap version first. Read-time corroboration plus refuse-if-uncertain is the whole safety story for v1. No git-dependency freshness engine yet; add it only if staleness actually bites in practice.
• The checker is a cost filter, not a trust mechanism (nucliweb's framing, and it's the right one). Its only job is to cheaply suppress the provably-stale so the agent doesn't waste a corroboration cycle. That keeps it deliberately small.
• Degrade honestly, always. check-memory.sh must return unknown (no content), never an error, on a non-git checkout, a shallow clone, no configured trusted ref, or a rewritten history that erased the anchor. An error a later agent reads as "no memory here, proceed" is the failure mode.
• v1 fixtures that must exist: a capsule whose last-modifying commit no longer exists resolves to unknown, not verified (the rebase/squash case); and the non-git / shallow-clone cases each return unknown cleanly.
• Both kinds, one skill. The append-only event-log tier (asiridalugoda's EXPERIMENTS.md shape) needs admission rules and nothing else, so it's nearly free to include; the state-of-the-world capsule is the only tier that touches the invalidation logic.

One thing to hold as a design principle, per asiridalugoda: invalidated_by can only ever catch declared dependencies, never semantic ones, so completeness is unreachable by construction. Bias toward cheap unknown and cheap capsule regeneration over ever-richer dependency sets.

Thanks @asiridalugoda and @nucliweb, this thread is a big part of why v1 has a clean shape. Ship the small version, let's see it run against a real repo, and we iterate from there.

[federicobartoli]

Thanks @addyosmani , I've started, with your scope comment as the contract.

The shape I'm building: one skill directory, skills/repository-memory/ with the SKILL.md, a small check-memory.sh, the eval case, and the mandatory fixtures (anchor commit gone, non-git checkout, shallow clone, each resolving to unknown cleanly, exit 0 always). Two colocated files: AGENT_MEMORY.md for state-of-the-world capsules, gated by the checker, and a separate append-only log file for the event tier, admission rules only. The checker stays a cost filter: structural validation, byte-identity against the trusted ref, anchor existence. The only staleness it flags is a declared path that no longer exists in the working tree; everything else is left to read-time corroboration.

Two small questions while I draft. For the log file, would you rather EXPERIMENTS.md, matching asiridalugoda's reference implementation, or AGENT_LOG.md for symmetry? And would one optional field be worth it so a capsule can keep the outcome that produced it (what broke when the boundary was crossed), or should v1 stay minimal there too?

Plan is a small PR referencing this issue, then a run against a real repo reported back here.