Memory Bank

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 — 29 commands: /mb, /start, /done, /plan, /discuss, /sdd, /work, /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.

> 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](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.

---

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       # EARS-validated requirements → context/.md
/mb sdd           # spec triple: requirements / design / tasks.md (executable)
# specs//tasks.md is a first-class executable artifact with  markers,
# NOT a scaffold — each block is resolved by /mb work  as a work item.
# requirements.md may add an optional `## Scenarios` layer:  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          # execute spec tasks one by one (reads  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 always wins.
2. MB_PATH env override — for ad-hoc redirection in shell sessions.
3. Local mode — /.memory-bank/ (default of /mb init, team-shared, committable).
4. Global mode — registered in /memory-bank/registry.json. Requires --storage=global --agent= on init (or $MB_AGENT env). Per supported agent:

• claude-code → $HOME/.claude/memory-bank/projects//.memory-bank
• cursor → $HOME/.cursor/memory-bank/projects//.memory-bank
• codex → $HOME/.codex/memory-bank/projects//.memory-bank
• opencode → $HOME/.config/opencode/memory-bank/projects//.memory-bank
• pi → $HOME/.pi/agent/memory-bank/projects//.memory-bank
• windsurf/cline/kilo → analogous under the respective config dir

1. Legacy .claude-workspace — kept for backward compatibility (storage: external + project_id: → ~/.claude/workspaces//.memory-bank). New projects should use --storage=global instead.
2. 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 [--tag t] | Keyword search across the memory bank. --tag filters via index.json | | mb-note.sh | Create notes/YYYY-MM-DD_HH-MM_.md. Collision-safe (_2 / _3) | | mb-plan.sh | Create plans/YYYY-MM-DD__.md with ` markers | | mb-plan-sync.sh | Synchronize a plan ↔ checklist + roadmap + status (idempotent) | | mb-plan-done.sh | Close a plan: ⬜→✅ + move to plans/done/ | | mb-idea.sh [HIGH\|MED\|LOW] | Capture a new idea in backlog.md with monotonic I-NNN | | mb-idea-promote.sh | Promote an idea (I-NNN) into an active plan | | mb-adr.sh | 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 teststatus=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:progresschain); CRITICAL drift on tamper (handoff-v2) | | mb-rules-check.sh | Deterministic rules enforcement (SRP / Clean Architecture / TDD delta) | | mbruleschecklib.sh | Shared helper library for mb-rules-check.sh | | mbrulescheckprofile.sh | Profile resolution and output emitters for mb-rules-check.sh | | mbrulescheckbaseline.sh | Baseline SRP / Clean Architecture / TDD checks for mb-rules-check.sh | | mbrulescheckstack.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) | | 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 | Validate REQ bullets against the 5 EARS patterns | | mb-req-next-id.sh | Emit the next monotonic REQ-NNN identifier | | mb-sdd.sh | Create a Kiro-style spec triple under specs// (requirements / design / tasks). Scaffolds an optional ## Scenarios (GIVEN/WHEN/THEN) section | | mb-scenario-extract.py | Extract GIVEN/WHEN/THEN blocks → normalized test-plan (JSON Lines: covers + steps + stable testid). --validate checks present scenarios are well-formed. Opt-in layer; absent scenarios → empty/no-op | | mbworkitems.py | Shared parser for plan stages () and spec tasks (); CLI emits JSON Lines | | mbreqid.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 (reqrs008) onto canonical ids | | mb-spec-validate.sh | 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 /tests, /tests, or MBTESTROOTS). --json mode for structured output | | mb-spec-tasks-migrate.sh [--apply\|--dry-run] | Migrate legacy ## N. ... tasks to 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 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:protectedpaths | | mb-work-review-parse.sh | Validate reviewer output for /mb work review-loop | | mb-work-severity-gate.sh | Apply pipeline.yaml:severitygate to review counts | | mb-workflow.sh | Resolve the active workflow + per-step model/thinking config from pipeline.yaml for /mb work | | 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-session-spend.sh | Session token-spend tracker (sprint context guard) | | mb-session-recent-rebuild.sh | Regenerate session/recent.md from session/.md (keeps newest MBRECENTKEEP; deterministic, idempotent) | | mb-recap.sh | /mb recap: reconstruct a full progress.md entry from session/*.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 -> ] 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 (MBAUTOCOMMIT=1) — 4 safety gates | | 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-codegraph.py | Code graph orchestrator. Extractors in memorybankskill/: codegraphpython (stdlib ast), codegraphtreesitter (multi-language, opt-in), codegraphanalytics (communities/cohesion/betweenness, optional networkx), codegraphcochange (git co-change edges via opt-in --cochange) | | mb-graph-query.py | Query codebase/graph.json: neighbors, impact, tests, explain, summary with JSON/markdown output | | mbgraphquery_core.py` | Cor

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fockus
• Source: fockus/skill-memory-bank
• License: MIT
• Homepage: https://fockus.github.io/skill-memory-bank/

Install and usage instructions live in the source repository linked above.