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.