memory-bank

Use when CLAUDE.md or CLAUDE-*.md memory-bank files need creating, auditing, updating, or syncing with the codebase — after significant code changes, when documented patterns contradict the implementa

SKILL.md

GitHub

Memory Bank Maintenance

Overview

One skill for the whole memory-bank lifecycle (CLAUDE.md plus the CLAUDE-activeContext / patterns / decisions / troubleshooting / config-variables files). Replaces the claude-md-management and codebase-documenter plugins and the update-memory-bank, analyze-codebase, and cleanup-context commands — if any of those are still visible, use this skill instead.

Ground rules

  • Every line in these files is prompt cost in every future session: one line per concept, no verbose explanations, no information git already records (history, past fixes, code structure that is obvious from reading it).
  • Verify claims against the actual code before writing them down — a wrong memory is worse than no memory.
  • Preserve planning, historical, and strategic notes when syncing; drift fixes update facts, they don't erase intent.
  • Never delete CLAUDE.md or CLAUDE-*.md files; never commit them unless the user asks (repo rule: exclude from commits).
  • Convert relative dates ("last week") to absolute dates when capturing.

Modes

capture (end of session / "remember this"): reflect on what context was missing this session — commands discovered, style patterns, config quirks, gotchas. Add the few that will recur to the right file: shared → CLAUDE.md, session state → CLAUDE-activeContext.md, conventions → CLAUDE-patterns.md, rationale → CLAUDE-decisions.md, proven fixes → CLAUDE-troubleshooting.md. Create a memory-bank file only if a learning belongs there and the file doesn't exist yet.

sync ("docs don't match the code"): for each memory-bank file, check its claims against the implementation; fix what drifted, flag what you're unsure about. For a large sweep, spawn one general-purpose subagent per file on sonnet (fact-checking docs against code is execution-heavy — see the model-routing rule in CLAUDE.md) and have each return a list of stale claims with file:line evidence.

audit ("check/improve our CLAUDE.md files"): find all CLAUDE.md files (fd CLAUDE.md), then per file: commands that no longer exist, wrong paths, duplicated guidance, bloat (cut it via optimize mode), missing load-bearing context. Report before editing.

optimize ("context files too big"): dedupe across files, collapse narratives into single-line facts, move project-specific detail out of the global file. Show the diff of what gets cut.

Common mistakes

  • Writing session narrative ("today we fixed…") instead of reusable facts.
  • Recording one-off fixes that will never recur.
  • Trimming so aggressively the why behind a decision is lost — keep the one-line rationale.