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.
Concretely, three things change:
- "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.
- 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.
- Your always-loaded context gets smaller, not bigger, over time — because deletion is half the system, not an afterthought.
| 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 — 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:
---
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.
Say: "Bootstrap a memory system for me."
The agent interviews you first (it does not dump templates):
- What do you use this agent for, mostly?
- What do you find yourself re-explaining every session?
- 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.
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.
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).
git clone https://github.com/danyuchn/memory-engineering-skill ~/.claude/skills/memory-engineeringWorks with any agent that reads instruction files and a memory directory;
examples use Claude Code conventions (CLAUDE.md, ~/.claude/skills/).
- 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 把網路上流行的「智慧代理四種記憶」分類，落地成一套裝了就能用 的記憶作業規則：該記什麼（入場測試：拿掉這條會不會出錯？）、記到哪 （工作／日誌／事實檔／指令分層的路由決策樹）、怎麼忘（錯了立刻刪、完成 歸檔、兩個月沒用到就挑戰它）。裝完之後說「幫我建記憶系統」會得到訪談式 的最小建置；說「健檢我的記憶」會得到一份指出重複、矛盾、殭屍條目的具體 報告。所有規則檔以英文撰寫。
MIT — see LICENSE.
Companion skills by the same author: asd-ste100-skill (controlled English for agent-facing text) · iso-24495-skill (plain language for human-facing text, English + Traditional Chinese).