Memory Bank Skill

Three-in-one skill for code agents:

1. Memory Bank — long-term project memory through .memory-bank/ (STATUS, plan, checklist, RESEARCH, BACKLOG, progress, lessons, notes/, plans/, experiments/, reports/, codebase/).
2. RULES — global engineering rules: TDD, Clean Architecture (backend), FSD (frontend), Mobile (iOS/Android UDF), SOLID, Testing Trophy.
3. Dev toolkit — 33 commands: /mb, /start, /done, /plan, /brief, /discuss, /groom, /sdd, /work, /drive, /config, /pipeline, /profile, /commit, /pr, /review, /test, /refactor, /doc, /changelog, /catchup, /adr, /contract, /security-review, /api-contract, /db-migration, /observability, /roadmap-sync, /traceability-gen, /analyze-task, /flow, /goal, /agree.

Design contract. Memory Bank rests on one inviolable promise — agents remember — and a stack of fully configurable, token-economical layers above it. Default behaviour never changes without explicit opt-in; user customisations survive upgrades; expensive paths are off by default. See references/design-principles.md for the full contract.

Supported host model:

• Claude Code / OpenCode — native command surface + global install.
• Cursor — native full support: global skill alias (~/.cursor/skills/memory-bank/), global hooks (~/.cursor/hooks.json), global slash commands (~/.cursor/commands/), ~/.cursor/AGENTS.md with managed section, plus a paste-ready file for Settings → Rules → User Rules. Project-level .cursor/ adapter remains available as an add-on via --clients cursor.
• Codex — global skill discovery + AGENTS.md hints + project-level .codex/ adapter; no separate native slash-command surface.
• Other code agents — via adapters, AGENTS.md, local hooks/configs, or direct CLI/script usage.

---

Development flow — stages a code agent should expect

Work in a Memory Bank project follows this order. Depth scales with task complexity — every stage except development itself can be skipped for trivial work; review and judge are opt-in.

#	Stage	Command	Notes
1	Interview	/mb discuss <topic> (alias /mb ask_me)	Grilling interview → decisions + EARS-validated requirements draft in context/<topic>.md
2	Spec or plan	/mb sdd <topic> · /mb plan <type> <topic>	Pick by complexity: feature/multi-task → spec triple (specs/<topic>/requirements+design+tasks.md, executable <!-- mb-task:N -->); smaller bounded change → plan (plans/*.md, <!-- mb-stage:N -->); trivial fix → no artifact (rules still apply)
3	Development	/mb work <target>	Executes spec tasks / plan stages one by one through an implement → verify loop with role subagents (TDD, contract-first)
4	Verification	/mb verify	plan-verifier audits diff vs plan/spec DoD; mandatory before /mb done when work followed a plan/spec
5	Review (optional)	/mb work <target> --review	Reviewer verdict (subagent ensemble or external codex) + severity gate; off by default
6	Judge (optional)	/mb work <target> --judge	mb-judge decides GO / GO_WITH_BACKLOG / NO_GO and terminates the review loop
7	Close	/mb done	Actualize bank: progress append, checklist/status update

Grooming (any stage). /mb groom <topic> (also grooming) runs a critical grooming session outside the fixed order — for a raw idea, a task that already has a spec, or a decision worth revisiting. Unlike /mb discuss, the goal is not a spec: the agent challenges necessity and approach, proposes its own solutions, covers white spots; the summary lands in context/<topic>-groom.md, confirmed decisions go to agreements.md / backlog (ADR/Ideas), and the session ends with proposed next steps (e.g. /mb sdd).

Pipeline. The whole chain can be encoded in <bank>/pipeline.yaml as a named workflow (steps, per-role model/thinking, severity gates, protected paths, budget). When present, /mb work resolves it automatically (mb-workflow.sh) and follows the configured steps — e.g. governed implement → verify → review → judge → fix → done — without per-run flags. Manage with /mb pipeline / /mb config; validate with /mb config validate. Defaults never change without opt-in: no pipeline and no flags = simple implement → verify.

Command index — all /mb subcommands (know these exist; suggest them to the user when relevant; details per subcommand → commands/mb.md or /mb help <sub>):

• Session & context: context (default, empty arg) · start · done · update · tasks · note <topic> · index
• Requirements & decisions: discuss <topic> (alias ask_me) · groom <topic> (alias grooming) · sdd <topic> · openspec <import|list|status|sync> · plan <type> <topic> · idea <title> · idea-promote <I-NNN> · adr <title> · agree <sub> · goal
• Execution: work [target] · verify · config <sub> · pipeline <sub> · flow <route> · analyze-task
• Codebase intelligence & memory: map [focus] · graph · wiki · research <query> · search <query> · recall <query> · recap <sid> · conflicts · consolidate · tags
• Setup & maintenance: init · install · profile <sub> · doctor · compact · migrate-structure · import · upgrade · deps · statusline · help [sub]

Beyond /mb, the toolkit ships standalone commands (see the list in the intro above): /commit, /pr, /review, /test, /refactor, /doc, /changelog, /catchup, /contract, /security-review, /api-contract, /db-migration, /observability, /roadmap-sync, /traceability-gen.

---

Quick start

# Storage modes — pick one per project:
/mb init                                      # local mode (default) — bank in repo (.memory-bank/)
/mb init --storage=local                      # explicit local mode — same as above
/mb init --storage=global --agent=claude-code # global mode — bank in ~/.claude/memory-bank/...
                                              # (personal, NOT committed to the repo)
# Rules-only mode: no /mb init at all — [MEMORY BANK: ABSENT] state;
# /mb lifecycle stays inactive; all TDD/SOLID/Clean Architecture/DRY/KISS/YAGNI rules still apply.

# Initialization flags
/mb init --full          # same as /mb init (stack auto-detect + CLAUDE.md generation)
/mb init --minimal       # only the .memory-bank/ structure

# Session flow (basic)
/mb start                # load context
# ... work, checklist.md updates as tasks complete ...
/mb verify               # verify plan alignment (if there was a plan)
/mb done                 # actualize + note + progress

# Unified SDD flow (spec-driven features)
/mb discuss <topic>      # EARS-validated requirements → context/<topic>.md
/mb sdd <topic>          # spec triple: requirements / design / tasks.md (executable)
# specs/<topic>/tasks.md is a first-class executable artifact with <!-- mb-task:N --> markers,
# NOT a scaffold — each block is resolved by /mb work <topic> as a work item.
# requirements.md may add an optional `## Scenarios` layer: <!-- mb-scenario:N --> blocks
# (### Scenario: + **Covers:** REQ-x + GIVEN/WHEN/THEN). They become a test-plan
# (mb-scenario-extract.py) that /mb plan links and /mb work turns into one real test
# per scenario in the project's stack. Enforce coverage with
# `mb-spec-validate.sh --require-scenarios`; off by default (EARS-only specs stay valid).
/mb work <topic>         # execute spec tasks one by one (reads <!-- mb-task:N --> blocks)
/mb verify               # verify against spec + plan
/mb done                 # actualize + progress

Personalize rules for your stack (optional):

/mb profile init --scope=project --role=backend --stack=go --architecture=microservices --delivery=contract-first

or user-global (works even without a project Memory Bank):

/mb profile init --scope=user --role=frontend --stack=typescript

If the host does not support native slash commands, use:

• commands/mb.md as the workflow entrypoint;
• the memory-bank ... CLI for install/init/doctor flows;
• bundled scripts and agent prompts from this skill bundle.

---

Workspace resolution — agent-agnostic storage

Memory Bank resolves its active bank through scripts/_lib.sh::mb_resolve_path. The precedence is fixed and explicit:

1. Explicit argument — mb-*.sh <mb_path> always wins.
2. MB_PATH env override — for ad-hoc redirection in shell sessions.
3. Local mode — <project>/.memory-bank/ (default of /mb init, team-shared, committable).
4. Global mode — registered in <agent_config>/memory-bank/registry.json. Requires --storage=global --agent=<name> on init (or $MB_AGENT env). Per supported agent:
   • claude-code → $HOME/.claude/memory-bank/projects/<id>/.memory-bank
   • cursor → $HOME/.cursor/memory-bank/projects/<id>/.memory-bank
   • codex → $HOME/.codex/memory-bank/projects/<id>/.memory-bank
   • opencode → $HOME/.config/opencode/memory-bank/projects/<id>/.memory-bank
   • pi → $HOME/.pi/agent/memory-bank/projects/<id>/.memory-bank
   • windsurf/cline/kilo → analogous under the respective config dir
5. Legacy .claude-workspace — kept for backward compatibility (storage: external + project_id: <id> → ~/.claude/workspaces/<id>/.memory-bank). New projects should use --storage=global instead.
6. Fallback — relative .memory-bank (compat with existing scripts).

Active-state semantics

• [MEMORY BANK: ACTIVE] — when the resolver returns an existing bank (local or registered global).
• [MEMORY BANK: ABSENT] — when no bank exists for the current project. Surface this and stop the Memory Bank lifecycle — do not silently initialize.
• [MEMORY BANK: INITIALIZED] — only after a successful explicit /mb init.

Rules-only mode

A project may intentionally have no Memory Bank ([MEMORY BANK: ABSENT]). In that case:

• /mb lifecycle commands stay inactive until the user explicitly runs /mb init.
• The engineering rules baseline still applies: TDD, SOLID, Clean Architecture / FSD, DRY/KISS/YAGNI, Testing Trophy, protected files, no placeholders, verification before completion. Global skill installation never auto-enables Memory Bank state.

When invoking MB Manager or scripts, always pass the resolved mb_path.

---

Tools — shell scripts

All scripts live in scripts/ next to this SKILL.md. In global installs, the bundle is typically available through host aliases:

• Claude Code: ~/.claude/skills/memory-bank/
• Codex: ~/.codex/skills/memory-bank/
• Cursor: ~/.cursor/skills/memory-bank/

Scripts work with .memory-bank/ in the current directory or through the mb_path argument.

GraphRAG-lite retrieval routing

code_context is the default for ambiguous code-understanding questions such as "where is the logic for X?" or "find similar implementation". Exact structural questions route directly to graph tools: "who calls/imports/defines X?" → graph_neighbors, "reverse deps" or change impact → graph_impact, and "what tests cover this file/symbol?" → graph_tests. User explicitly asks "semantic search" → search_code because explicit tool intent wins.

Fail open: missing graph, stale graph, missing semantic provider, or unavailable native extension must not block the agent. Use scripts/mb-graph-query.py and scripts/mb-code-context.py as the universal CLI fallback; Pi and OpenCode may expose native tool wrappers, while Claude Code, Codex, and generic AGENTS.md agents can call the scripts directly.

Script	Purpose
_lib.sh	Shared helpers sourced by other scripts
mb-context.sh [--deep]	Build context from core files (STATUS + plan + checklist + RESEARCH + codebase summary). --deep shows full codebase docs
mb-statusline.py [--install]	Claude Code statusline showing context-window fill % (used/limit, 1M-aware) + model · branch · project. Reads the status JSON on stdin; --install wires it into ~/.claude/settings.json (backup, no clobber)
mb-search.sh <q> [--tag t]	Keyword search across the memory bank. --tag filters via index.json
mb-note.sh <topic>	Create notes/YYYY-MM-DD_HH-MM_<topic>.md. Collision-safe (_2 / _3)
mb-plan.sh <type> <topic>	Create plans/YYYY-MM-DD_<type>_<topic>.md with <!-- mb-stage:N --> markers
mb-plan-sync.sh <plan>	Synchronize a plan ↔ checklist + roadmap + status (idempotent)
mb-plan-done.sh <plan>	Close a plan: ⬜→✅ + move to plans/done/
mb-idea.sh <title> [HIGH|MED|LOW]	Capture a new idea in backlog.md with monotonic I-NNN
mb-idea-promote.sh <I-NNN>	Promote an idea (I-NNN) into an active plan
mb-adr.sh <title>	Capture an Architecture Decision Record in backlog.md (ADR-NNN)
mb-init-bank.sh	Deterministic, locale-aware .memory-bank/ scaffolder
mb-config.sh	Memory Bank config resolver + locale auto-detector
mb-metrics.sh [--run]	Language-agnostic metrics (12 stacks). --run captures test_status=pass|fail
mb-index.sh	Registry of all entries (core + notes/plans/experiments/reports)
mb-index-json.py	Build index.json (frontmatter notes + lessons headings). Atomic write
mb-drift.sh	8 deterministic drift checkers (path, staleness, script coverage, dependency, cross-file, index sync, command, frontmatter)
mb-progress-chain.sh	--rebuild-tail / --verify the progress.md append-only hash chain (index.json:progress_chain); CRITICAL drift on tamper (handoff-v2)
mb-rules-check.sh	Deterministic rules enforcement (SRP / Clean Architecture / TDD delta)
mb_rules_check_lib.sh	Shared helper library for mb-rules-check.sh
mb_rules_check_profile.sh	Profile resolution and output emitters for mb-rules-check.sh
mb_rules_check_baseline.sh	Baseline SRP / Clean Architecture / TDD checks for mb-rules-check.sh
mb_rules_check_stack.sh	Stack-aware and FSD checks for mb-rules-check.sh
mb-done-gates.sh	Mandatory /mb done gate set (tests + rules + placeholder scan); --force --reason records a NOTE in progress.md (handoff-v2)
mb-test-run.sh	Structured test runner with per-stack output parsing → strict JSON
mb-deps-check.sh [--install-hints]	Preflight dependency checker (python3, jq, git + optional tree-sitter, networkx)
mb-checklist-prune.sh [--apply]	Collapse completed sections in checklist.md to one-liners (≤120-line cap). Rule: checklist.md = open TODO only; commit hashes / test counts / closeouts go to progress.md. Opt-in SessionEnd autoprune when it exceeds the cap via MB_CHECKLIST_AUTOPRUNE=on (hooks/mb-checklist-autoprune.sh)
mb-compact.sh [--apply]	Status-based compaction decay — archive old done plans + low-importance notes
mb-handoff.sh	Handoff capsule manager — --actualize / --read / --rotate a ≤1500-byte session capsule under handoff/ (handoff-v2)
mb-tags-normalize.sh [--apply]	Levenshtein-based tag synonym detection + merge across notes/
mb-roadmap-sync.sh	Regenerate roadmap.md autosync block from plans/*.md frontmatter
mb-traceability-gen.sh	Regenerate traceability.md from specs + plans + tests
mb-ears-validate.sh <file>	Validate REQ bullets against the 5 EARS patterns
mb-req-next-id.sh	Emit the next monotonic REQ-NNN identifier
mb-sdd.sh <topic>	Create a Kiro-style spec triple under specs/<topic>/ (requirements / design / tasks). Scaffolds an optional ## Scenarios (GIVEN/WHEN/THEN) section
mb-scenario-extract.py <file>	Extract <!-- mb-scenario:N --> GIVEN/WHEN/THEN blocks → normalized test-plan (JSON Lines: covers + steps + stable test_id). --validate checks present scenarios are well-formed. Opt-in layer; absent scenarios → empty/no-op
mb_work_items.py	Shared parser for plan stages (<!-- mb-stage:N -->) and spec tasks (<!-- mb-task:N -->); CLI emits JSON Lines
mb_req_id.py	Shared REQ-ID grammar (single source of truth) used by traceability / spec-validate / ears-validate. Supports prefixed schemes (REQ-RS-008), distinguishes a definition from a mid-line mention, expands REQ-RS-002/003 slash-shorthand, and maps pytest identifiers (req_rs_008) onto canonical ids
mb-spec-validate.sh <topic|spec-dir|spec-file>	Validate spec triple integrity (EARS, parseable tasks, per-task Covers/DoD/Testing, no REQ orphans). Present GIVEN/WHEN/THEN scenarios are structure-checked; --require-scenarios (opt-in) enforces ≥1 scenario per REQ; --require-tests (opt-in) enforces ≥1 covering test per REQ (scans <repo>/tests, <mb>/tests, or MB_TEST_ROOTS). --json mode for structured output
mb-spec-tasks-migrate.sh <topic|tasks-file> [--apply|--dry-run]	Migrate legacy ## N. ... tasks to <!-- mb-task:N --> format. Dry-run default, --apply writes backup before changes, idempotent
mb-pipeline.sh	Manage the project's pipeline.yaml (spec §9)
mb-pipeline-validate.sh	Structural validation for pipeline.yaml (spec §9)
mb-work-resolve.sh	Resolve <target> arg into a plan/spec path (spec §8.2)
mb-work-range.sh	Emit per-stage indices (plan mode) or per-sprint paths
mb-work-plan.sh	Emit per-stage execution plan as JSON Lines (spec §8)
mb-work-budget.sh	Token budget tracker for /mb work --budget
mb-work-protected-check.sh	Match files against pipeline.yaml:protected_paths
mb-work-review-parse.sh	Validate reviewer output for /mb work review-loop
mb-work-severity-gate.sh	Apply pipeline.yaml:severity_gate to review counts
mb-work-trend.sh	Review-cycle trend: weighted score (10×blocker + 3×major + 1×minor) vs the previous cycle → improving / stagnant / regressing / null (work-loop-v2 G2)
mb-work-pivot.sh	Decide refine / pivot_in_role / pivot_via_architect from the trend + cycle count, instead of grinding the same fix (pivot_after_cycles, pivot_escalate_to_architect_on)
mb-work-contract.sh	Per-stage "what done means" contract under <bank>/contracts/<topic>_stage-<N>.md — create / read / validate / path; the reviewer can judge against it
mb-workflow.sh	Resolve the active workflow + per-step model/thinking config from pipeline.yaml for /mb work
mb-drive.sh	Autonomous goal-driven loop: next reads goal-acceptance + the firewall + work-state + budget and emits exactly one action (implement / repair / pivot / stop_*). Stateless, fail-closed — stop_success requires a green firewall AND 100% acceptance (REQ-DR-014)
mb-drive-stop.sh	Drive-loop stop telemetry + per-run drive state: arm marks a drive live (arms the Stop-hook resume-gate), record --reason|--action writes the stop reason once into the mb-flow fence, progress.md, and the run's state slot (REQ-DR-033/034)
mb-work-state.sh	Durable /mb work loop-state + max_cycles enforcement; optional per-run isolation/claim under MB_WORK_PARALLEL
mb-work-slots.sh	Sourced helper: per-run state/budget/drive slot-path resolution + source→run claim index (gated behind MB_WORK_PARALLEL)
mb-work-checkbox.sh	Deterministic DoD-checkbox flip, gated on the run's work-state phase (single-writer for checklist.md)
mb-work-diff.sh	Baseline-scoped diff for a /mb work run — feeds verify/review with the stage's own changes only
mb-work-progress-append.sh	Locked, atomic, append-only writer for <bank>/progress.md (safe under concurrent runs)
mb-work-codex-preflight.sh	Fail-safe codex CLI availability/auth health-check before a cross-model review wave
mb-session-doctor.sh	Diagnose session-memory subsystem health (unsummarized sessions, missing index/adapters, legacy stubs)
mb-agent-caps.sh	Capability-aware dispatch: resolve CLI transport (pi/opencode/codex/claude-agent) + concrete model per role by probing CLI presence and model availability
mb-reviewer-resolve.sh	Pick the active reviewer agent name
mb-review.sh	Review orchestrator entry point: deterministic 5-section payload assembly (diff + calibration examples + test evidence + auto-findings), model-agnostic, --emit-payload/--input
mb-review-cache.sh	Touched-file test-evidence cache: compute_touched_sha + TTL HIT/MISS resolution under .memory-bank/tmp/
mb-review-examples.sh	Layered calibration-example loader: project-over-skill precedence by example_id, fence-aware parser, per-category rotation, path-traversal/symlink-safe; renders the ## Calibration examples payload section
mb-session-spend.sh	Session token-spend tracker (sprint context guard)
mb-session-recent-rebuild.sh	Regenerate session/_recent.md from session/*.md (keeps newest MB_RECENT_KEEP; deterministic, idempotent)
mb-recap.sh <sid>	/mb recap: reconstruct a full progress.md entry from session/<sid>*.md via one Haiku call, replacing that session's auto-capture stub idempotently (recapped frontmatter). Missing session → exit non-zero, no writes; real entry already present → refuse
mb-conflicts.sh [--judge] [--threshold N]	/mb conflicts: report memory entries with high lexical overlap and opposing/replacement assertions (en+ru markers) as conflict candidates — $0 pass (token-set Jaccard > N, default 0.3) over notes/ + lessons.md + recent progress.md, zero LLM calls. --judge confirms/rejects each pair via one Sonnet call + prints a suggested [SUPERSEDED: YYYY-MM-DD -> <ref>] marker. PRINT-ONLY — never writes to any bank file
mb-consolidate.sh [--apply] [--days N]	/mb consolidate: fold sessions older than N days (default 30) that cluster by shared files / lexical overlap into 5–15 line notes/ candidates, archive those session files VERBATIM → session/archive/, and move their contiguous auto-capture progress STUBS VERBATIM → progress-archive.md. Zero LLM calls. Dry-run is the DEFAULT (writes nothing — bank byte-identical); --apply performs it. Real progress entries are immutable and never move
mb-auto-commit.sh	Opt-in auto-commit of .memory-bank/ after /mb done (MB_AUTO_COMMIT=1 or --force) — 4 safety gates, MB-only staging, never pushes
mb-freshness.sh [--porcelain|--stop-nudge|--banner]	Deterministic MB-vs-code drift alarm (behind/dirty); drift-gated Stop nudge + SessionStart banner (MB_DRIFT_WARN_COMMITS/MB_DRIFT_WARN_DIRTY_LINES, opt-out MB_FRESHNESS_BANNER=off). See docs/concepts/session-memory.md for the auto-commit recipe
mb-migrate-v2.sh	One-shot v1 → v2 migrator for .memory-bank/
mb-migrate-structure.sh	One-shot v3.0 → v3.1 structure migrator for .memory-bank/
mb-import.py	Claude Code JSONL → Memory Bank bootstrap importer
mb-openspec.sh	Thin dispatcher for the OpenSpec import adapter: import|list|status|sync → mb-openspec.py
mb-openspec.py	One-way OpenSpec changes/<id>/ → MB spec triple specs/<topic>/ import + drift-aware list/status/sync (opt-in --normalize LLM slot layer)
mb_openspec_model.py	Dataclasses shared by the OpenSpec adapter's parser/converter
mb_openspec_parse.py	Read-only OpenSpec change parser (parse_change, compute_source_hash)
mb_openspec_convert.py	Deterministic OpenSpec → MB spec-triple converter (anchors, EARS classify, re-import anchor reuse)
mb_openspec_normalize.py	Opt-in --normalize LLM slot layer + source-hash cache for the OpenSpec adapter (fail-open)
mb-agree.sh	Single writer for the running list of agreements (agreements.md): add|defer|reject|question|resolve|list|sync + managed-block sync
`mb-code