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"
- 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.
- 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.
- 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.
- Expect 3–8 memories, not 20. A small system gets used.
Mode: audit — "audit my memory" / "my CLAUDE.md is a mess"
- Read everything first: instruction files, memory directory, any
rules/skills dirs the user names. Never audit from a partial read.
- 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).
- 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.
- 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:
- 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).
- 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.
- 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.
1---2name: memory-engineering3description: "Use when an agent's memory needs to be built, audited, or maintained — the user asks to set up a memory system, complains the agent keeps forgetting or repeating mistakes, says the instruction file (CLAUDE.md/AGENTS.md) has grown bloated or contradictory, asks what should be remembered vs deleted, or says 'remember this'. Triggers: memory engineering, bootstrap a memory system, audit my memory, my agent forgets everything, CLAUDE.md is a mess, run the memory sweep, 建記憶系統, 健檢記憶, 清理記憶. Not a vector database or retrieval tool."4version: 0.1.05metadata:6 source: https://skillmd.com/skills/danyuchn/memory-engineering7---89# Memory Engineering1011Give an agent a memory it can trust: rules for **what to write down, where12it goes, and when it gets deleted**. The system is three verbs applied to13four memory types. Subtraction is the governing philosophy — the default14answer to "should this be remembered?" is **no**, and deletion gets equal15billing with writing, because bloated memory is how agents get slow,16contradictory, and wrong.1718## The three verbs1920| Verb | Question it answers | Rules file |21|---|---|---|22| **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` |23| **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` |24| **PRUNE** | When does it die? Wrong → now. Done → archive. Unused ~60–90 days → challenge. Index capped (~150 lines). | `references/prune.md` |2526Read the relevant rules file before acting; do not improvise thresholds.2728## Mode selection2930Infer the mode from the request; announce it in one line only if ambiguous.3132### Mode: bootstrap — "set up a memory system for me"33341. **Interview first, create nothing yet.** Ask, in the user's language:35 what they mostly use the agent for; what they re-explain every session;36 what the agent has gotten wrong that must never repeat. Three to five37 questions, then stop.382. **Apply WRITE** to their answers: only facts passing the admission test39 become memories. Reject the rest out loud — showing what you did *not*40 write teaches the system's philosophy better than any doc.413. **Create the minimum**: an index from `templates/MEMORY-template.md`,42 fact files from `templates/fact-template.md` (each with type,43 description, why, how-to-apply), and — only if the user has an44 instruction file — a suggested slim-down, shown as a diff, applied only45 on approval.464. Expect 3–8 memories, not 20. A small system gets used.4748### Mode: audit — "audit my memory" / "my CLAUDE.md is a mess"49501. **Read everything first**: instruction files, memory directory, any51 rules/skills dirs the user names. Never audit from a partial read.522. **Scan for six defect classes**, each finding cited with file:line —53 never report a count without evidence:54 duplicates (one fact, several homes) · contradictions (two answers to55 one question) · zombies (unused ~60–90 days, fails re-admission) ·56 misrouted (task-specific procedure in the always-loaded layer;57 events sitting in instruction files) · missing-why (rules that cannot58 be safely pruned later) · index defects (content pasted into the59 index, or index over cap).603. **Report, then wait.** Output the findings grouped by class with a61 proposed action per finding (merge / delete / archive / demote to62 skill / add why). **Apply nothing without approval** — deletions are63 the user's call, always.644. On approval, apply the accepted actions and show the resulting tree.6566### Mode: maintain — "run the memory sweep"6768Run the weekly sweep in `references/prune.md` (journal→fact sync, archive69done items, contradiction scan, zombie pass, index audit). Same rule:70propose deletions, apply on approval.7172### Ambient behavior — "remember this"7374When the user asks to remember something mid-task:75761. Run the admission test. If it fails, say why in one line and offer the77 alternative (it's derivable / it's session-only / it's already78 recorded at X).792. If it passes, ROUTE it, write the fact file **with its why**, add the80 index line, and confirm in one line: what was written, where.813. If it duplicates or contradicts an existing memory, update that file82 instead of creating a second home — and say so.8384## Output discipline8586Be concrete and cite files. Show trees and diffs, not essays. When87rejecting a memory candidate, one line of reason, not a lecture. Never88delete without approval. Never create structure the interview did not89justify.9091## Scope9293Works on file-based agent memory: instruction files (`CLAUDE.md`,94`AGENTS.md`), memory directories, rules and skills folders. Examples use95Claude Code conventions. Out of scope: vector stores and retrieval96infrastructure — this skill fixes curation, which is where most setups97actually fail. Worked example of a full transformation:98`examples/before-after.md`.