memory-bank
Repo-committed project memory — decisions, context, solved mysteries as distilled one-fact files; recall before related work. Trigger when starting work in a previously-touched area, after solving som
SKILL.md.claude/skills/memory-bank/SKILL.md
GitHubMemory Bank — Durable Project Knowledge
The missing memory layer: knowledge that must outlive sessions AND machines AND assistants. Lives in the repo (memory-bank/ at project root), committed to git, readable by humans. Distilled facts, never transcripts — recall should cost tens of tokens, not thousands.
Division of labor (don't duplicate the other layers):
handover.md= current state (what's in flight, next steps) — volatile, overwritten.- Skill
learnings.md= technique knowledge (how to do X well) — per-skill, project-agnostic. - Auto-memory (assistant-level) = user preferences and cross-project facts.
- memory-bank = this project's durable truths: decisions + why, domain context, constraints, solved-mystery writeups. If it belongs in git history or code comments, it doesn't belong here.
Self-improvement (do this first and last)
- At start: read
learnings.mdin this skill's folder if it exists. Apply relevant lessons. - At end of every use: append one dated bullet — a recall that saved rework, a capture format that proved useful/useless. Merge instead of duplicating; delete disproven bullets.
Structure
memory-bank/
INDEX.md ← one line per entry: - [Title](file.md) — recall hook
decisions/ ← choices with lasting consequences: what, why, alternatives rejected
context/ ← domain/product truths not derivable from code (why this feature exists, external constraints)
solutions/ ← solved-mystery writeups: symptom → root cause → fix → how to spot it again
One fact per file, kebab-case names, each file ≤ ~20 lines with a one-line summary at top. INDEX.md is the only file read routinely — keep every line's recall hook specific enough to judge relevance without opening the file.
Recall protocol (the half most setups skip)
- Before starting work in any area, scan
INDEX.md(create the folder + index on first use). Open only the entries whose hooks match the task — never bulk-read the bank. - Treat entries as point-in-time claims: verify against current code before acting on anything load-bearing, and update the entry if it drifted.
- When the user asks "why is X like this" — check
decisions/before deriving an answer from code.
Capture protocol
Capture at these moments (not on a timer):
- A decision with lasting consequences is made →
decisions/: what was chosen, why, what was rejected and why. Convert relative dates to absolute. - A non-obvious problem is solved (took >30 min or >2 failed hypotheses) →
solutions/: symptom → cause → fix, written so the next occurrence is recognized in one read. - External/domain context surfaces that code can't express (client requirement, API quirk, design intent) →
context/. - User says "remember this" → capture; if it's actually a preference or cross-project fact, route it to the appropriate layer instead and say so.
- A handover note is over its ceiling → it is demoting to you. Decisions and solved mysteries become entries here; session narrative is not accepted (git already holds it) and must be dropped, not parked. See the
handoverskill's routing table. In parallel mode the demoting session holds the@memory-bank-indexclaim inhandover/locks.d/while writing — the bank is shared and owned by no role.
Rules: distill — never paste transcripts, diffs, or code blocks longer than 5 lines (link file:line instead). Check the index for an existing entry to update before creating; delete entries proven wrong; add the index line in the same step as the file (an unindexed memory is invisible). Link related entries by filename.
Maintenance
- Entries whose subject was removed from the codebase → delete file + index line.
- The
memory-gardenerskill's pruning rules apply tomemory-bank/too — invoke it when INDEX.md exceeds ~40 lines. - Commit memory-bank changes with the work that produced them — the memory and the code change share a commit and stay in sync.