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

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

1. Legacy `.claude-workspace` — kept for backward compatibility (storage: external + project_id: <id> → ~/.claude/workspaces/<id>/.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.

Agents — subagents (sonnet)

Composition (dev-role agents). When /mb work dispatches a dev-role agent (developer / backend / frontend / ios / android / architect / devops / qa / analyst), it inlines mb-engineering-core.md first, then the role file, then the work item — prompt = core + "\n---\n" + role + body. The role files carry only their domain delta and reference the core; the prepend is what delivers the shared discipline. A role file dispatched alone (outside /mb work) is discipline-thin by design — read the core first if you invoke one standalone.

Do NOT delegate plan creation, architectural decisions, or ML-result evaluation to a subagent — that is main-agent work.

Plan hierarchy: Phase → Sprint → Stage. See references/templates.md § Plan decomposition for size thresholds, terminology, and when to use which level. Cyrillic «Этап / Спринт / Фаза» — legacy alias, allowed only in plans/done/*.md.

Invocation format

Agent(
  subagent_type="general-purpose",
  model="sonnet",
  description="<description>",
  prompt="<contents of agents/<agent>.md>\n\naction: <action>\n\n<context>"
)

Hooks

Lifecycle hooks shipped in hooks/. Installed automatically by install.sh (Claude Code, Cursor, Codex, OpenCode); see references/hooks.md for per-host wiring details.

Host-specific notes

Claude Code and native memory

Claude Code has built-in auto memory (user-level cross-project memory in ~/.claude/projects/.../memory/). This skill does not replace it — the two complement each other:

Rule of thumb: if it helps a teammate pick up the project tomorrow, store it in .memory-bank/. If it helps you in another project, store it in native memory. They can coexist without conflict.

Codex

For Codex, this skill is positioned as a global skill bundle plus a guidance layer:

• discovery goes through ~/.codex/skills/memory-bank/
• global entrypoint/guidance goes through ~/.codex/AGENTS.md
• hook/config integration remains primarily project-level through .codex/

Codex therefore uses the same Memory Bank workflow, but it does not need to expose the same native command surface as Claude Code/OpenCode.

Cursor

Cursor is a first-class global target. install.sh writes five artifacts to ~/.cursor/:

Cursor User Rules paste flow:

# macOS
pbcopy < ~/.cursor/memory-bank-user-rules.md
# Linux
xclip -selection clipboard < ~/.cursor/memory-bank-user-rules.md

The project-level adapter (.cursor/rules/memory-bank.mdc + .cursor/hooks.json) remains available and is installed only when the user passes --clients cursor. Global and project-level installs coexist — Cursor merges hooks from both.

Private content — <private>...</private> (since v2.1)

Markdown syntax for excluding sensitive information (client data, API keys, partner names) from indexing and search:

---
type: note
tags: [auth, partner-x]
importance: high
---

Discussed with client <private>Jane Doe, +1-555-***</private>.
Integration with <private>api_key=sk-abc123...</private> is scheduled for Tuesday.

Protection model:

• Content inside <private>...</private> does not go into index.json (neither summary nor tags)
• mb-search output redacts it as [REDACTED] (inline) or [REDACTED match in private block] (multi-line)
• The entry gets a has_private: true flag for downstream filtering
• An unclosed <private> without </private> makes the rest of the file private (fail-safe)
• hooks/file-change-log.sh warns when committing a file containing <private> blocks (reminder to review git exposure)

Double confirmation for reveal:

# Rejected without env:
mb-search --show-private <query>
# [error] --show-private requires MB_SHOW_PRIVATE=1

# Only with explicit opt-in:
MB_SHOW_PRIVATE=1 mb-search --show-private <query>

Important: <private> protects against leakage through index.json / mb-search, but it does not filter git diff. For full protection, consider .gitattributes filters or git hooks.

Auto-capture (since v2.1)

The SessionEnd hook automatically appends a placeholder entry to progress.md when a session ends without an explicit /mb done. Work is not lost even if manual actualization was skipped.

Modes (`MB_AUTO_CAPTURE` env):

• auto (default) — hook writes an entry on session end
• strict — hook skips but prints a warning to stderr (for flows where manual actualization is required)
• off — full noop

How it works:

• After successful /mb done, the command writes .memory-bank/.session-lock → the hook sees the fresh lock (<1h) and skips auto-capture (manual actualization already happened)
• Without a lock, the hook adds a short note to progress.md. Full details can be reconstructed by /mb start in the next session (MB Manager can read the JSONL transcript)
• Concurrency-safe through a short .auto-lock (30 seconds) — prevents duplicates on parallel invocations
• Idempotent by session_id — same session + same day = one entry

Opt-out: export MB_AUTO_CAPTURE=off in ~/.zshrc or disable the hook via /mb upgrade once that flag is available.

Session memory — native session logging (session-memory subsystem)

A richer, native alternative to the placeholder auto-capture above. Logs every session to .memory-bank/session/*.md (markdown, git-tracked) and auto-curates notes. Scripts live in ~/.claude/hooks/ (and the repo's .memory-bank/bin/ when present); registered in settings.json.

• Stop → `mb-session-turn.sh` — appends one ## Live log bullet per turn (last user request,

tools, touched files) without an LLM; persists the transcript path to frontmatter; deduped by turn uuid so duplicate (project + global) registration is safe. Guards: stop_hook_active, MB_CAPTURE_SUBPROCESS, MB_SESSION_CAPTURE=off, missing jq → exit 0.

• SessionEnd → `mb-session-end.sh` — a Haiku claude -p writes ## Summary + updates

_recent.md; then a gated Sonnet judge (only if the session had Write/Edit or ≥4 turns) writes 0–2 durable notes/. Idempotent by session_id (summarized frontmatter flag). Anti-recursion: env -u CLAUDECODE MB_CAPTURE_SUBPROCESS=1 claude -p --strict-mcp-config --no-session-persistence --no-chrome.

• SessionStart → `mb-session-start.sh` — injects # Recent Sessions from _recent.md;

drains stdin (exec < /dev/null) to avoid hanging on claude --resume (macOS). Read-only (runs even while capture is off).

• Recall: /mb recall <query> → hybrid semantic + lexical search over session/ + notes/,

fused by RRF (Reciprocal Rank Fusion) when the semantic backend is available; fails open to lexical-only otherwise.

Off-switch: export MB_SESSION_CAPTURE=off. Suppress the legacy stub (above) with MB_AUTO_CAPTURE=off so progress.md is not double-written once this subsystem owns capture. Cost: a significant session spends 2 claude -p calls on SessionEnd (Haiku summary + Sonnet judge); trivial sessions spend only the summary. Portable lock: mkdir-based (no flock on macOS). Active only where an active Memory Bank resolves.

PreCompact handoff capsule (handoff-v2)

The PreCompact hook hooks/mb-pre-compact.sh runs just before context compaction. It invokes scripts/mb-handoff.sh --actualize <bank> pre_compact, which writes a fresh handoff capsule to .memory-bank/handoff/latest.md. The NEXT session's SessionStart hook (hooks/mb-session-start-context.sh) prepends that capsule when it is newer than the most recent progress.md entry, so the agent resumes from an up-to-date snapshot instead of stale state.

Never blocks compaction (design §9):

• bounded to ~2s via a portable background-poll-and-kill loop (no timeout/flock, macOS-safe)
• on timeout, actualize failure, or missing handoff script → one-line stderr WARN and exit 0
• on no resolvable bank → silent exit 0
• on success → one-line stderr marker [mb] handoff capsule actualized (pre_compact)

Opt-out: export MB_PRECOMPACT_HANDOFF=off.

Cross-session coordination — .memory-bank/COORDINATION.md

When two or more sessions work in the same working tree in parallel (two agent CLIs, or agent + human), they coordinate through a single append-only board file at the bank root — COORDINATION.md. Opt-in by nature: the first session that learns about a parallel session creates it; no board file → no protocol overhead.

• Entries ## [FROM → TO] YYYY-MM-DD HH:MM — topic, never edited after append (same invariant as progress.md); typed prefixes: STATUS / QUESTION / ANSWER / FREEZE / HANDOVER / ACK / COMMIT / ESCALATION.
• Checkpoints — every session reads the board: at session start (/mb start / /mb context surface it when present), before starting a stage/plan item, before ANY commit, before editing a shared-watchlist file; and appends a COMMIT entry (hash + scoped file list) after committing.
• Shared-tree hard rules: never git add -A; commit only your own work with ordering for interleaved files agreed on the board; full suite green before commit; surprise foreign diffs escalate on the board instead of being reverted; affected plans carry a ⚠️ pointer to the board (compaction-proof).
• Full protocol (entry conventions, race handling, trust rules, hookup prompt for a new session): references/coordination.md.

Running list of agreements — .memory-bank/agreements.md

The canonical registry of confirmed decisions currently in force, distinct from progress.md (narrative history) and ADRs (rationale for the hard-to-reverse subset). Every mutation goes through scripts/mb-agree.sh (add | supersede | defer | reject | question | resolve | list | sync) — never a direct model edit — and auto-syncs a managed block (<!-- mb-agreements:start/end -->) into project-root CLAUDE.md/AGENTS.md so a fresh session sees every active agreement without being reminded.

• Lazy activation, opt-in by nature: the rules trigger ships with the skill for every project,

but zero files/blocks exist until the first /mb agree add — no added tokens in banks that never use the feature. Kill-switch: MB_AGREEMENTS=off (env or .mb-config).

• Model conduct: only an explicitly confirmed user decision is written, announced visibly as

→ AGR-NNN записано: <statement>; unconfirmed hypotheses go to Open Questions instead.

• `/mb verify` integration: when agreements.md exists, the Plan Verifier classifies every

active agreement as satisfied / violated / not-applicable; a violation fails the verdict.

• Full protocol (what is/isn't an agreement, anti-examples, statuses, ADR routing): references/agreements.md. Command reference: commands/agree.md.

References

• Rule profiles schema (dimensions, immutable baseline, precedence, validation): references/rules-profile.schema.md
• Design principles (inviolable memory promise + configurable layers): references/design-principles.md
• Metadata protocol + index.json + 8 key rules: references/metadata.md
• Plan decomposition (Phase / Sprint / Stage), templates, drift checks: references/templates.md
• Planning + Plan Verifier workflow: references/planning-and-verification.md
• /mb work reference material (workflow modes, JSON schema, examples, scripts, parallel runs): references/work-reference.md
• /mb work sprint contracts, progress trend, strategic pivoting: references/work-loop-v2.md
• Structure of .memory-bank/: references/structure.md
• Code graph cookbook (jq library, graph.json schema, intelligence layer, semantic-search routing): references/code-graph.md
• Workflow (session lifecycle): references/workflow.md
• Session memory (cross-chat capture, /mb recall, session-doctor): references/session-memory.md
• Cross-session coordination board (COORDINATION.md protocol): references/coordination.md
• Running list of agreements (agreements.md protocol, statuses, anti-examples): references/agreements.md
• Command file template: references/command-template.md
• Hooks (per-host wiring + lifecycle): references/hooks.md
• Adapter manifest schema: references/adapter-manifest-schema.md
• Tags vocabulary: references/tags-vocabulary.md
• CLAUDE.md auto-generation template: references/claude-md-template.md
• CHANGELOG: CHANGELOG.md
• Migration v1→v2: docs/MIGRATION-v1-v2.md
• Primary entrypoint:
• /mb — if the host supports native commands
• commands/mb.md / memory-bank CLI — if native command surface is unavailable