memory-engineering

# Memory Engineering Give an agent a memory it can trust: rules for **what to write down, where it goes, and when it gets deleted**. The system is three verbs applied to four memory types. Subtraction is the governing philosophy — the default answer to "should this be remembered?" is **no**, and deletion gets equal billing with writing, because bloated memory is how agents get slow, contradictory, and wrong. ## The three verbs | Verb | Question it answers | Rules file | |---|---|---| | **WRITE** | Does this deserve to exist? (admission test: *if this line were gone, would the agent make a mistake?*) One fact per file, with its **why**. | `references/write-rules.md` | | **ROUTE** | Where does it live? Working = session (not persisted) · Episodic = journal · Semantic = fact files + index, one home per fact · Procedural = instruction layers, task-specific bulk demoted to skills. | `references/routing.md` | | **PRUNE** | When does it die? Wrong → now. Done → archive. Unused ~60–90 days → challenge. Index capped (~150 lines). | `references/prune.md` | Read the relevant rules file before acting; do not improvise thresholds. ## Mode selection Infer the mode from the request; announce it in one line only if ambiguous. ### Mode: bootstrap — "set up a memory system for me" 1. **Interview first, create nothing yet.** Ask, in the user's language: what they mostly use the agent for; what they re-explain every session; what the agent has gotten wrong that must never repeat. Three to five questions, then stop. 2. **Apply WRITE** to their answers: only facts passing the admission test become memories. Reject the rest out loud — showing what you did *not* write teaches the system's philosophy better than any doc. 3. **Create the minimum**: an index from `templates/MEMORY-template.md`, fact files from `templates/fact-template.md` (each with type, description, why, how-to-apply), and — only if the user has an instruction file — a suggested slim-down, shown as a diff, applied only on approval. 4. Expect 3–8 memories, not 20. A small system gets used. ### Mode: audit — "audit my memory" / "my CLAUDE.md is a mess" 1. **Read everything first**: instruction files, memory directory, any rules/skills dirs the user names. Never audit from a partial read. 2. **Scan for six defect classes**, each finding cited with file:line — never report a count without evidence: duplicates (one fact, several homes) · contradictions (two answers to one question) · zombies (unused ~60–90 days, fails re-admission) · misrouted (task-specific procedure in the always-loaded layer; events sitting in instruction files) · missing-why (rules that cannot be safely pruned later) · index defects (content pasted into the index, or index over cap). 3. **Report, then wait.** Output the findings grouped by class with a proposed action per finding (merge / delete / archive / demote to skill / add why). **Apply nothing without approval** — deletions are the user's call, always. 4. On approval, apply the accepted actions and show the resulting tree. ### Mode: maintain — "run the memory sweep" Run the weekly sweep in `references/prune.md` (journal→fact sync, archive done items, contradiction scan, zombie pass, index audit). Same rule: propose deletions, apply on approval. ### Ambient behavior — "remember this" When the user asks to remember something mid-task: 1. Run the admission test. If it fails, say why in one line and offer the alternative (it's derivable / it's session-only / it's already recorded at X). 2. If it passes, ROUTE it, write the fact file **with its why**, add the index line, and confirm in one line: what was written, where. 3. If it duplicates or contradicts an existing memory, update that file instead of creating a second home — and say so. ## Output discipline Be concrete and cite files. Show trees and diffs, not essays. When rejecting a memory candidate, one line of reason, not a lecture. Never delete without approval. Never create structure the interview did not justify. ## Scope Works on file-based agent memory: instruction files (`CLAUDE.md`, `AGENTS.md`), memory directories, rules and skills folders. Examples use Claude Code conventions. Out of scope: vector stores and retrieval infrastructure — this skill fixes curation, which is where most setups actually fail. Worked example of a full transformation: `examples/before-after.md`.