Rule
Keep two records with different jobs. Your tracker records the work: intent, acceptance, decisions, status, and evidence links. Beads is one example; the tracker you already run works. A small set of reviewed project pages records the explanations and patterns worth reusing. Link the two so every reusable claim has a trail back to the work that tested it.
The model does not learn because a session ended. An agent can draft a page, propose links, and flag stale material. The draft stays in protected storage outside Git until a fresh reviewer answers two questions: does the evidence support the claim, and is it safe to disclose where the page will live? Only approved content enters the project .context/.
A saved page proves nothing yet. It earns its place when a later task reads it and the work comes out better for it. Count that, and keep the cases where reuse misled someone.
The Two Records
| Surface | What it records | Question it answers |
|---|---|---|
| Your tracker | Intent, acceptance, dependencies, status, decisions, and evidence links | What are we doing, and what happened? |
| Reviewed project context | Source-linked explanations, patterns, decisions, and maintenance notes | What should a future session know, and where did it come from? |
An issue tracker alone scatters reusable knowledge across closed work. A page alone can become a polished story detached from the evidence. The link between them makes the record inspectable.
Put It to Work
- Start from the tracker issue or other durable intent that names the work and acceptance.
- Do the work and record the result against that intent.
- Draft a lesson only when it generalizes beyond the task, and keep the draft outside Git.
- Get a fresh review of the draft's support and disclosure before it enters
.context/. - Make each page cite the issue, commit, verdict, or source that supports it, and name what would retire it.
- When a later task starts, read only the relevant page and recheck it against current sources.
- Open repair work when a page proves stale or wrong.
Most sessions should not create a page. Good candidates prevent a repeated mistake, preserve an architectural decision, or document a procedure another operator must run. Transcript dumps, status updates, and unsupported hunches stay out.
Where AgentOps Fits
AgentOps keeps this loop optional and off the path of the current change. A page can inform the next plan. It cannot change the verdict on the candidate in front of you, and a count of pages written says nothing about whether later work improved.
Failure Signal
- A page has no source or review date.
- Every session creates another page, including one-off status notes.
- A draft reached Git before anyone reviewed what it disclosed.
- Closed issues contain repeated lessons that nobody can find.
- A future task loads every page instead of the small relevant slice.
- A stale page stays authoritative because there is no repair path.
- The team counts pages written and calls it learning.
Done Looks Like
A later task reads one reviewed page, that page cites the work that supports it, the task shows the page helped, and a named repair path exists if the guidance stops being true.
In AgentOps 3.8: Memory reads reviewed .context/ pages with ordinary file tools, keeps drafts in protected storage, and admits approved content only after a fresh support-and-disclosure review.