Prevent memory rot and bloat: writes have a gate, deletions have a path, the index has a cap
Entry points
Classify first, then act; for execution details seesectionEach entry point
- Write capture: consolidate session takeaways (single or batch) into memory entries
- Governance audit: inspect MEMORY/ and clean up (overturned by events / absorbed / contradictory / duplicate / vague / header residue / over budget)
- Initialize init: establish a MEMORY/ system for projects with no memory conventions
Queries ("is there X in memory") do not go through the entry-point flow: answer from the index if possible, only Read the body when details are needed; if there is no hit, say so explicitly and do not make things up
Input and output
| Entry point | Input | Output |
|---|---|---|
| capture | Corrections / pitfalls / conventions from the session (named by the user or extracted by the agent) | Entry files / short entries persisted after confirmation |
| audit | Project root (containing MEMORY/) | Inspection report (mechanical checks + governance candidates) + governance actions after item-by-item confirmation |
| init | Project root (no MEMORY/) | MEMORY/ skeleton created after confirmation + AGENTS.md reference section |
Execution principles
- Memory is a basis for decisions, not a log: only accept content where "if it were deleted, the next session would make a wrong decision"; never accept operational steps, task history, or anything derivable from code / documentation
- Propose first, then persist; deletion must be confirmed: both writes and deletions first produce a proposal, and files are only touched after the user agrees
- Merge first: there is always only one entry per topic; merge into and update it rather than adding a new one
- Absorb means delete: once an entry's content has gone into documentation / code / AGENTS.md, delete the entry itself (git can recover it)
- The index has a cap: the index resides permanently in context, so set hard numerical thresholds: before writing, compare line count and byte count, and block once the threshold is reached, without relying on self-discipline; the budget values and watermark rules use
assets/memory-index-template.mdas the SSOT - Placement red lines: project content only goes into the project MEMORY/; secrets / tokens / evaluations of people never enter memory: leaked secrets cannot be recalled, and evaluations of people will become fixed into the judgment of subsequent sessions
Workflow
Write capture
What is gated is agent autonomous writes(batch consolidation, proactive proposals); for a single "note this down" named by the user, the human is the gate, and this flow only adds the merge check and placement / format judgment. First Read ref/capture-workflow.md before acting (five gates, placement routing, write order, batch section)
Governance audit
A safety net to catch the rot that slips past the write gate. First Read ref/audit-workflow.md before acting (mechanical layer runs lint, judgment layer does event-driven review, three-tier ladder governance, numerical inspection report)
Initialize init
Do not proactively promote it; only propose it when the user names it, or when capture finds there is no placement. First Read ref/init-workflow.md Before acting (skeleton creation, AGENTS.md reference section)
Reference example
At the end of the session the user says, "organize this round's takeaways into memory": the agent finds at the git root MEMORY/, extracts candidates from this round and runs each through the five gates.
"Use uv for package management" (evidence: the user corrected npm usage), "always use Decimal for amounts" (evidence: the user explicitly agreed), both of these land as short entries;
"orders/ has upstream validation" hits the negative list (it can be read from the code), so it is not accepted. After the 2 proposed entries are confirmed by the user,
append them to MEMORY/MEMORY.md at the end of the corresponding group