# Memory Engineering Skill — Give Your Agent a Memory You Can Trust
Everyone is posting the same diagram: agents need **working, episodic,
semantic, and procedural** memory. The diagram is right — and it is a map,
not a house. This skill is the house: an installable set of operating rules
that decides **what your agent writes down, where it goes, and when it gets
deleted**, plus two commands (`bootstrap` and `audit`) that apply those
rules to your actual setup in minutes.
## What you get after installing
Concretely, three things change:
1. **"Remember this" stops being a lie.** When you tell your agent to
remember something, it now runs an admission test (would forgetting this
cause a mistake?), routes it to the right layer, records the **why**,
and tells you what it wrote and where — instead of pasting another line
onto a 300-line instruction file.
2. **You can ask for a memory audit** and get a concrete report:
duplicated facts, contradictions, zombie entries nothing has used in
months, task-specific bulk taxing every session.
3. **Your always-loaded context gets smaller, not bigger, over time** —
because deletion is half the system, not an afterthought.
## The mental model: the popular terms, mapped to real files
| The term you saw on X | What it means | Where this skill puts it |
|---|---|---|
| Working memory | What matters right now | The session itself — deliberately **not** persisted |
| Episodic memory | What happened, when | An append-only journal (a few lines a day) |
| Semantic memory | Facts, decisions, preferences | One fact per file + a one-line-per-fact index; every fact lives in exactly **one** place |
| Procedural memory | How to do things | Instruction files, layered: always-loaded rules kept brutal, task-specific procedure demoted to skills |
Three verbs run the whole system:
- **WRITE** — the admission test: *"if this line were gone, would the agent
make a mistake?"* No → don't write it. Yes → write it **with its why**.
- **ROUTE** — the decision tree above: session / journal / fact file /
instruction layer.
- **PRUNE** — wrong → delete now; done → archive; unused for two months →
challenge it. Index capped so recall stays sharp.
## Before / After (the honest picture)
**Before** — one 312-line `CLAUDE.md` that absorbed everything for six
months: a critical "never push without asking" buried between a stale
meeting note and a fixed-in-May bug; two contradictory Postgres decisions;
40 lines of deploy steps taxing every session including the ones that
never deploy.
**After** — the same knowledge, layered:
```
project/
├── CLAUDE.md 28 lines: always-true rules + pointers
├── memory/
│ ├── MEMORY.md index — one line per fact
│ ├── never-push-without-asking.md (feedback, carries its why)
│ ├── postgres-14-freeze.md (the contradiction, resolved to ONE fact)
│ └── staging-dashboard.md (reference)
├── .claude/skills/deploy/SKILL.md the 40 deploy lines, loaded only when deploying
├── journal.md what happened, newest first
└── archive/ done things, out of the agent's context
```
And what a single memory looks like — small enough to delete safely,
complete enough to trust:
```markdown
---
name: never-push-without-asking
type: feedback
description: Never git push unless the user explicitly asks.
---
Never push to any remote unless the user explicitly asks in this session.
**Why:** 2026-05-03 an auto-push broke a teammate's deploy.
**How to apply:** commit freely when asked; stop before any `git push`.
```
Full walkthrough with the failure-mode analysis:
[`examples/before-after.md`](examples/before-after.md).
## The two commands
### `bootstrap` — you have no memory system yet
Say: **"Bootstrap a memory system for me."**
The agent interviews you first (it does not dump templates):
1. What do you use this agent for, mostly?
2. What do you find yourself re-explaining every session?
3. What has it gotten wrong that you never want repeated?
Then it creates the **minimum** structure — an index plus the 3–8 memories
your answers actually justified, each with its why — and explains every
line it wrote and every candidate it rejected. Subtraction is the point:
a memory system that starts small gets used; one that starts as twenty
empty template files gets abandoned.
### `audit` — you already have instruction files and they've grown
Say: **"Audit my memory."** The agent reads your existing instruction
files and memory directory, then reports — with file-and-line evidence:
```
MEMORY AUDIT — 2026-08-13
Duplicates (2): "use vitest" appears in CLAUDE.md:41 and testing.md:3
Contradictions (1): CLAUDE.md:12 says Postgres 15 migration planned;
CLAUDE.md:97 says frozen on 14. Which is current?
Zombies (5): 5 entries unused since May — challenge or archive list below
Misrouted (3): 40-line deploy procedure in the always-loaded file →
demote to a skill; 2 meeting notes → journal
Missing why (4): rules that cannot be safely pruned later because no
one recorded the reason they exist
Proposed actions: 12 (apply none without your approval)
```
You approve; it applies. Nothing is deleted without you.
### Daily use — mostly invisible
You do not invoke this skill day to day. It changes what "remember this"
does, and once a week you can say **"run the memory sweep"** for the
15-minute maintenance pass (journal-to-fact sync, archive done items,
contradiction scan, zombie pass).
## Installation
```bash
git clone https://github.com/danyuchn/memory-engineering-skill ~/.claude/skills/memory-engineering
```
Works with any agent that reads instruction files and a memory directory;
examples use Claude Code conventions (`CLAUDE.md`, `~/.claude/skills/`).
## What this skill is not
- Not a vector database, and not a plug for one. Most personal and team
agent setups fail on **curation**, not retrieval — that is the part
this skill fixes, with plain files you can read and diff.
- Not a note-taking method for humans. Every rule optimizes for what the
agent should carry, which is why deletion gets equal billing with
writing.
## 中文簡介
這個 skill 把網路上流行的「智慧代理四種記憶」分類，落地成一套裝了就能用
的記憶作業規則：該記什麼（入場測試：拿掉這條會不會出錯？）、記到哪
（工作／日誌／事實檔／指令分層的路由決策樹）、怎麼忘（錯了立刻刪、完成
歸檔、兩個月沒用到就挑戰它）。裝完之後說「幫我建記憶系統」會得到訪談式
的最小建置；說「健檢我的記憶」會得到一份指出重複、矛盾、殭屍條目的具體
報告。所有規則檔以英文撰寫。
## License
MIT — see [LICENSE](LICENSE).
Companion skills by the same author:
[asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
(controlled English for agent-facing text) ·
[iso-24495-skill](https://github.com/danyuchn/iso-24495-skill)
(plain language for human-facing text, English + Traditional Chinese).