# Memory Engineering

> 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.

- Skill: `danyuchn/memory-engineering` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add danyuchn/memory-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danyuchn/memory-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: danyuchn (https://skillmd.com/u/danyuchn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danyuchn/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`.