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 — 25 commands: /mb, /start, /done, /plan, /discuss, /sdd, /work, /config, /profile, /commit, /pr, /review, /test, /refactor, /doc, /changelog, /catchup, /adr, /contract, /security-review, /api-contract, /db-migration, /observability, /roadmap-sync, /traceability-gen.

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.

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.
/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.