Skip to content

Memory Bank — Documentation

Long-term project memory for AI coding agents. Plus engineering rules baseline (TDD / Clean Architecture / SOLID / FSD / Mobile) and a 25-command dev toolkit.

One inviolable promise, fully configurable above. See references/design-principles.md for the contract.

Start here

Concepts

Background reading on how the skill is structured.

  • Overview — high-level picture of the layers.
  • Design principles — inviolable core + configurability invariants + token economy.
  • Composable /mb work pipeline — review off by default; per-stage flags, the full preset, three-layer precedence.
  • Code graph & semantic search — /mb map, /mb graph (+ opt-in layers), mb-semantic-search.py, /mb wiki.
  • Cross-session memory — /mb recall, session hooks, the local semantic index.
  • Memory model (coming) — status.md / checklist.md / plans/ / progress.md / lessons.md / notes/ and how they fit together.
  • Pipeline config (coming) — pipeline.yaml schema with examples.
  • Overlay system (coming) — agent-prompt and rule-profile overlays.
  • Glossary (coming) — Phase / Sprint / Stage / Goal / Wave / Worktree.

Workflows

Step-by-step guides for common ways of working.

  • Plan-driven: your first feature — /mb plan → /mb work → /mb verify → /mb done, with a worked example.
  • Basic session (coming) — /mb start → work → /mb done.
  • Spec-driven (coming) — /mb discuss → /mb sdd → /mb work.
  • Goal-driven (coming) — /goal init → /goal "..." → /mb work --autopilot → /goal done.
  • Autopilot (coming) — long-running Ralph-loop with hard stops.
  • Debugging (coming) — /mb debug and auto-recovery on verify FAIL.

Features

Reference pages, one per capability.

Stable

  • Rule profiles — role × stack × architecture × delivery preset matrix; 22 presets; immutable baseline; user/project scope precedence.

Coming as part of the goal-driven-autopilot spec

  • Worktree isolation — git worktree-based execution sandbox.
  • Parallel waves — DAG-based stage parallelism via depends_on.
  • Atomic stage commit — one commit per /mb work stage with safety gates.
  • Token economy — concrete techniques: slim mode, signal reuse, artefact frugality, parallel-fallback.

Existing features pending dedicated docs

The following are documented inside SKILL.md / references/ today; they will get their own pages in a follow-up backfill sprint.

  • Memory Bank core (.memory-bank/ structure, append-only progress).
  • Codebase mapping (/mb map → codebase/STACK.md / ARCHITECTURE.md / CONVENTIONS.md / CONCERNS.md).
  • Code graph (/mb graph --apply, graph.json, god-nodes.md).
  • GraphRAG-lite retrieval (mb-code-context.py, semantic + graph + text fallback).
  • Private content (<private>...</private> blocks, redaction in index.json and search).
  • Auto-capture (SessionEnd hook, MB_AUTO_CAPTURE=auto|strict|off).
  • Weekly compact reminder.

Commands

Per-command reference pages. Until a page exists, see commands/<name>.md in the skill bundle, or run the command with no args for inline help.

Full list (25): 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.

Coming as part of goal-driven-autopilot: goal, debug.

Reference

Schemas and exhaustive listings — material agents may need.

  • Hooks — per-host wiring and lifecycle.
  • Tags vocabulary — canonical tags for index.json.
  • Templates — plan decomposition (Phase / Sprint / Stage), drift checks.
  • Planning + verification — plan-verifier workflow.
  • Memory Bank structure — every file in .memory-bank/ and what it stores.
  • Workflow — session lifecycle (start, during, finish, before compaction).
  • Rules-profile schema — dimensions, immutable baseline, validation.
  • Adapter manifest schema — for adding new AI-client integrations.
  • Metadata protocol — index.json fields, 8 key rules.
  • CLAUDE.md template — auto-generated by /mb init --full.
  • Command file template — for authoring new /commands/*.md.
  • Agents reference — all 29 subagents grouped by role, and which command invokes each.
  • CLI scripts reference (coming) — every scripts/mb-*.{sh,py} with arguments and exit codes.
  • pipeline.yaml schema (coming) — full configuration reference.
  • Artefact schemas (coming) — project.md, goal.md, plan frontmatter, spec frontmatter, note frontmatter.

Integration

How the skill fits with each AI coding agent.

  • Cross-agent setup — supported clients matrix, install paths, host-specific notes.
  • Claude Code (coming) — native command surface, hooks, native auto memory coexistence.
  • Cursor (coming) — global vs project install, User Rules paste flow, hooks integration.
  • Codex (coming) — global skill bundle + project-level adapter.
  • OpenCode (coming) — TS plugin, experimental.session.compacting.
  • Pi (coming) — dual-mode discovery.
  • CI/CD (coming) — using mb-test-run.sh / mb-drift.sh from pipelines.

Recipes

Practical "how do I…" guides. Grow as we accumulate notes worth generalising.

  • TDD workflow (coming)
  • Multi-stage feature delivery (coming)
  • Refactoring with the Strangler Fig pattern (coming)
  • Debugging flaky tests (coming)

Operations

Run, upgrade, ship the skill itself.

  • Install guide — install methods and troubleshooting.
  • Release process — PyPI OIDC + tag workflow.
  • Repo migration — for users upgrading from claude-skill-memory-bank.
  • i18n — adding a new locale (en / ru ship; es / zh scaffolds).
  • Upgrading (coming) — /mb upgrade, what changes, what survives.

Migrations

Version-specific upgrade guides.

Security

  • Security policy — reporting, scope, response timeline, design decisions.
  • Archived audit (2026-04-21) — third-party audit snapshot; key findings addressed in 3.x/4.x (path validation on uninstall, MB_ALLOW_METRICS_OVERRIDE opt-in gate).

Contributing to docs

  • Each docs/*.md ≤ 300 lines. If a page grows, split.
  • Cross-link liberally, do not duplicate content.
  • concepts/ explains why. features/ explains what. workflows/ explains how. reference/ is exhaustive lookup.
  • New skill capability ⇒ at least one docs/features/<name>.md page before the feature is released.
  • Existing files are not moved while their paths are referenced from README.md, CONTRIBUTING.md, or tests. Restructuring is a deliberate refactor with link updates.