persistent-memory
Capture a correction or preference into a durable per-topic file instead of re-learning it every session — the explicit workaround for the fact that Claude Code sessions and subagent dispatches don't remember each other. Use when the same kind of correction keeps recurring across sessions, when starting a task type you expect to repeat, or when delegate-to-subagents's reusable-template advice applies but you need the actual mechanism. Skip for a one-off correction that won't recur, and skip for anything project-wide enough to belong in CLAUDE.md instead. Bundles scripts/memory.py, a small CLI for reading, appending to, and listing memory files.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 16
- Forks
- 2
01 前言 Front Matter
- name
- persistent-memory
- description
- Capture a correction or preference into a durable per-topic file instead of re-learning it every session — the explicit workaround for the fact that Claude Code sessions and subagent dispatches don't remember each other. Use when the same kind of correction keeps recurring across sessions, when starting a task type you expect to repeat, or when delegate-to-subagents's reusable-template advice applies but you need the actual mechanism. Skip for a one-off correction that won't recur, and skip for anything project-wide enough to belong in CLAUDE.md instead. Bundles scripts/memory.py, a small CLI for reading, appending to, and listing memory files.
02 资源文件 1
- 脚本scripts/memory.py2.5 KB
03 SKILL.md 正文
Persistent Memory
Claude Code doesn't remember you between sessions, and a dispatched subagent doesn't remember anything at all — it starts from zero session history every time (see delegate-to-subagents). Some other agent platforms build in standing per-agent memory that quietly improves with correction; Claude Code doesn't have that layer. The honest substitute is the same one used for a recurring dispatch brief: write down what was learned, in a file, and load that file before repeating the task.
This isn't a workaround to feel bad about — an explicit file beats implicit memory for exactly the reasons record-the-why and honest-artifacts already argue: you can read it, diff it, prune it, and know exactly why a decision is still in effect, none of which is true of memory you can't inspect.
When to make one
- The same kind of correction has come up more than once ("no, always use tabs here," "don't touch the generated files")
- You're starting a task type you expect to repeat (a recurring review, a recurring report format, a recurring delegation brief)
- Don't make one for a correction you're confident won't recur — that's just noise to maintain
Worked example: a session once hit 7 failing golden-hash tests, spent real time reinstalling opencv and A/B-testing versions, and committed a confident but wrong root cause ("a recording mistake"). A different session had already found and fixed the same 7 hashes a day earlier on main — the real cause was an unpinned requirements.txt letting CI and local resolve different opencv builds. The recovered hash values matched byte-for-byte; the story didn't. A one-line memory note — "check git log origin/main -- <file> before concluding a hash mismatch is just stale data" — is exactly the kind of correction this skill exists to capture: narrow, likely to recur, and cheap to write down once so nobody re-derives it the slow way again.
Where it belongs
- Project-wide and stable (a convention every contributor should know) →
CLAUDE.md, not a memory file.CLAUDE.mdis read every session by design; a memory file isn't unless something loads it. - Narrower, more volatile, or still being refined (this user's phrasing preference, a client's quirks, a not-yet-settled workflow) → a memory file, e.g.
.claude/memory/<topic>.md. Cheap to create, cheap to throw away, doesn't compete for space in CLAUDE.md. - Genuinely one-off → neither. Not everything needs to survive the session.
What goes in it
- Distilled corrections, not transcript — the same "brief, not pasted history" principle as
delegate-to-subagents's "How to brief." A raw conversation log makes the next reader re-derive the lesson instead of just applying it. - One line per correction, dated, in your own words — not the user's exact wording captured verbatim, which drifts out of context without the conversation around it.
- The current, still-true state — not a running log of everything that was ever said. Superseded corrections get replaced, not appended forever (see "Keeping it honest" below).
Keeping it honest
- Review it periodically, don't just append. A memory file that only grows is exactly the kind of unverified, never-re-checked artifact
honest-artifactswarns about — a correction from six months ago may no longer apply. - If two entries conflict, that's a signal the situation changed — resolve it, don't leave both standing.
- A memory file that hasn't been touched in a long time and no longer matches how the task is actually done is worse than no file — it actively misleads the next read. Delete it or update it; don't let it fossilize.
The script
scripts/memory.py gives you a plain-text-in, plain-text-out CLI over one memory file per topic — no database, no format to learn:
python3 scripts/memory.py show <topic> # print the current file, or say there isn't one
python3 scripts/memory.py append <topic> "<note>" # add one dated line
python3 scripts/memory.py list # list every topic that has a memory file
Files live under .claude/memory/<topic>.md by default (override with MEMORY_DIR). show is meant to run before starting a recurring task — read it the same way you'd read a reusable dispatch template before delegating. append is meant to run right after a correction, not batched up for later, or it doesn't get captured at all.
This script only reads and appends — it never rewrites or deletes an existing line, so pruning a stale entry (see "Keeping it honest") is a manual edit, not something the script does for you silently.
External validation: xAI's Grok Build (now open-source, Apache 2.0, github.com/xai-org/grok-build) draws the same append-vs-consolidate line this script enforces, and its actual consolidation code (crates/codegen/xai-grok-memory/src/dream.rs, dream_lock.rs) is worth reading past the docs summary — the real design corrects the simpler picture the docs alone suggested:
- Consolidation ("dream") isn't purely manual. It's gated (
enabledconfig, hours-since-last-run, a minimum session count) and normally fires automatically at natural checkpoints (session end) when the gates pass; the/dreamcommand bypasses the gates for a manual run, not the underlying lock. - Concurrency is a PID+mtime lock file, explicitly documented as "best-effort coordination, not mutual exclusion" — a stale lock (dead PID, or age past a threshold) gets reclaimed, and the consolidation operation itself is required to be idempotent so a rare double-acquire race is tolerated rather than prevented. The portable lesson: a periodic-or-on-demand consolidation job behind a plain lock file should be designed idempotent, since even a well-built lock only reduces the race, it doesn't eliminate it.
04 同仓库更多 Skills
widen-the-solution-space
Deliberately widen the set of candidate approaches before committing to one. Use before irreversible decisions (architecture, DB schema, data format, public API), when the first solution feels complicated or awkward, when the user is deciding rather than instructing ("what's the best way to do this?"), or when a previous attempt at the same problem failed. Skip for routine work with one obvious answer.
weigh-tradeoffs
Compare real alternatives explicitly and record why one was chosen. Use when picking between libraries, data structures, architectures, or storage options; when a decision is hard to reverse (schema, public API, data format, dependency); or when the user asks "which is better, A or B". Also use to decide how much deliberation a decision even deserves.
verify-before-claiming
Run the verification and read its output before saying anything is done, fixed, working, or passing. Use before any completion claim, before committing or opening a PR, before moving to the next task, and after a subagent or tool reports success. Triggers on the words "should work", "fixed", "done", "passing", "looks good" — and on the urge to celebrate.
verifiability-first
Turn the task into something verifiable and declare the success criterion before seeing results. Use when the request is vague about "done" ("make it work", "improve this"), when writing tests, when fixing a bug (write the failing reproduction first), or when comparing two approaches. Critical before any measurement or benchmark, where deciding the bar after seeing the numbers guarantees a "success".
threat-and-scale-check
Check trust boundaries, scale behavior, and layered safety. Use when handling user input, external API responses, files, or auth; when designing permissions, validation, or any safety mechanism; when data volume could grow; or when writing loops that touch I/O. Also use when reviewing whether a single safeguard is the only thing standing between a mistake and a disaster.
surgical-change
Keep every changed line traceable to the request. Use when editing existing code, especially code you didn't write; when tempted to clean up something you noticed while reading; when a diff is growing beyond the ask; or when deciding whether to delete code that looks dead.