<div align="center">

memory-bank-skill

Persistent project memory + dev toolkit for AI coding agents.

Your AI remembers the project between sessions, follows the same engineering rules, and picks up exactly where you left off.

Claude Code · Cursor · Windsurf · Cline · Kilo · OpenCode · Codex · Pi Code

Install · Quick start · What you get · Code graph · Commands · Cross-agent · FAQ · Docs · Website

<a href="https://fockus.github.io/skill-memory-bank/"><img src="https://raw.githubusercontent.com/fockus/skill-memory-bank/main/site/og-image.png" alt="memory-bank-skill — persistent memory for AI coding agents" width="720"></a>

</div>

New in v5.0 — the /mb work pipeline is now composable: the default flow is a lean implement → verify → done, with review and judge as opt-in stages (--review, --judge, --workflow full). CHANGELOG · v4 → v5 migration

pipx install memory-bank-skill && memory-bank install

# then, inside your agent:
/mb init     # once per project
/mb start    # every session — full context restored

| Slash commands | /mb sub-commands | Subagents | AI clients | Automated tests | |:--------------:|:------------------:|:---------:|:----------:|:---------------:| | 25 | 25+ | 29 | 8 | 1,900+ |

---

The problem it solves

Every new AI coding session is amnesia: you re-explain the project, re-state the plan, re-list what's done — and context compaction erases whatever the agent finally learned. memory-bank-skill makes project memory a first-class citizen: a .memory-bank/ directory next to your code that the agent reads at session start and updates as it works.

.memory-bank/
├── status.md          ← where we are, what's next
├── checklist.md       ← current tasks (✅ / ⬜)
├── roadmap.md         ← priorities, direction
├── research.md        ← hypotheses log (H-NNN) + current experiment
├── backlog.md         ← parking lot for ideas + ADRs
├── progress.md        ← work log (append-only)
├── lessons.md         ← mistakes not to repeat
├── notes/             ← knowledge (5-15 line snippets)
├── plans/             ← detailed plans per feature/fix
├── reports/           ← analysis, post-mortems
├── experiments/       ← EXP-NNN experiment artifacts
└── codebase/          ← stack / architecture / conventions map (`/mb map`)

This directory lives alongside your code (commit it, share it with your team, or .gitignore it — your call).

---

Install

Pick one:

Option 0: skills.sh CLI (fastest one-shot install)

npx skills add fockus/skill-memory-bank

Copies the skill bundle (SKILL.md + scripts + commands + agents) into your local skills directory. Use this for a quick single-host try-out (Claude Code, Cursor, or any host that reads ~/.claude/skills/ or ~/.cursor/skills/). For cross-agent setup (Codex / Windsurf / OpenCode hooks, managed blocks in AGENTS.md, memory-bank CLI, hooks, slash commands globally installed), use Option 1 or 2 below.

Option 1: pipx (recommended, cross-platform)

pipx install memory-bank-skill           # stable
# or, for the latest release candidate:
pipx install --pip-args='--pre' memory-bank-skill

# pipx only installs the CLI. Run this once to wire agents, rules, commands, and Pi prompts:
memory-bank install                      # global install for Claude Code + Cursor + Codex + OpenCode + Pi
# optional: pick installed rule language explicitly
memory-bank install --language ru

Requires: Python 3.11+, pipx, jq, git, bash (3.2+; macOS ships one, Windows needs Git Bash/WSL — see docs/install.md).

Option 2: Homebrew (macOS / Linuxbrew)

brew tap fockus/tap
brew install memory-bank
memory-bank install

Option 3: git clone (developers)

git clone https://github.com/fockus/skill-memory-bank.git ~/.claude/skills/skill-memory-bank
cd ~/.claude/skills/skill-memory-bank
./install.sh

Add cross-agent support (Cursor, Windsurf, OpenCode, etc.)

Three ways — pick whichever matches your workflow:

A. Interactive menu (from any terminal — recommended if you're unsure which clients you want):

cd your-project/
memory-bank install                     # multi-select prompt for all 8 clients
# in TTY mode it will also ask which language to use for installed rules

B. CLI flags (scripts / CI / one-liner):

cd your-project/
memory-bank install --clients claude-code,cursor,windsurf
memory-bank install --clients claude-code,cursor --language en

C. From inside an agent with command surface (Claude Code / OpenCode):

/mb install                                 # interactive picker
/mb install cursor,windsurf                 # direct
/mb install all                             # every client

Claude Code/OpenCode can front this through /mb install, then run memory-bank install --clients <selected> for the current project. In Codex use the CLI directly; Codex gets global skill discovery plus ~/.codex/AGENTS.md hints, not a native /mb command surface.

Supported client names: claude-code, cursor, windsurf, cline, kilo, opencode, pi, codex. Supported rule languages: en (default), ru (full translation), es/zh (scaffolds — community PRs welcome, see docs/i18n.md). You can also set MB_LANGUAGE=en|ru|es|zh.

Full per-client details: docs/cross-agent-setup.md.

---

5-minute quick start

1. Install (see above).

2. Open your project in your AI agent (Claude Code, Cursor, etc.) and run:

   /mb init
   

   This creates .memory-bank/ with all the files above, detects your stack, and generates a CLAUDE.md (or equivalent) pointing the agent at the memory bank.

3. Every session starts with:

   /mb start
   

   The agent loads status.md, checklist.md, roadmap.md, research.md — it knows exactly what you were working on and what comes next.

4. As you work: the agent updates checklist.md (⬜ → ✅) whenever tasks finish.

5. Every session ends with:

   /mb done
   

   This appends a session entry to progress.md, updates status.md if needed, writes a knowledge note if something interesting was learned.

That's it. Rinse and repeat.

The core workflow: build a feature

init / start / done are the session bookends. The actual feature work happens through a plan or spec → work → verify → done loop. Two entry points:

Plan-based — for a well-understood change:

/mb plan feature "user avatar upload"   # scaffolds a staged plan with SMART DoD + TDD notes
/mb work                                # executes the plan stage by stage (TDD → verify per stage)
/mb verify                              # audits the diff against every DoD item — REQUIRED before done
/mb done                                # closes the session, appends progress, writes a note

Spec-driven (SDD) — for a larger or fuzzier feature, add an interview + spec first. The full chain is brief → discuss → sdd → work:

/mb brief billing-overhaul --input PRD.md   # raw request + documents → validated one-pager in briefs/
/mb discuss billing-overhaul            # 5-phase interview → EARS-validated context/billing-overhaul.md
/mb sdd billing-overhaul                # generates specs/billing-overhaul/{requirements,design,tasks}.md
/mb work billing-overhaul               # executes the tasks.md items (<!-- mb-task:N -->) in order
/mb verify
/mb done

Use one kebab-case slug for the whole feature (billing-overhaul, not "billing overhaul") — /mb discuss uses the topic verbatim as the filename, so keeping it already-slugged makes every later command resolve to the same context/ and specs/ paths.

/mb work runs implement (TDD) → verify → done by default — review is off, so it stays fast and cheap. /mb verify is mandatory before /mb done whenever the work followed a plan: it re-reads the plan and checks every DoD item against the real code, so you never close a stage that only looks finished.

Storage modes

Memory Bank supports three ways to store your bank — pick the one that fits your workflow:

Local mode (default)

/mb init                       # same as /mb init --storage=local

The bank lives in the repo at .memory-bank/. Commit it to share with your team, or add it to .gitignore for solo use. This is the default and recommended mode for team projects.

Global mode (opt-in personal storage)

/mb init --storage=global --agent=claude-code   # for Claude Code
/mb init --storage=global --agent=cursor         # for Cursor
/mb init --storage=global --agent=codex          # for Codex

The bank lives outside the repo under ~/.<agent>/memory-bank/projects/<id>/.memory-bank. It is personal storage and must not be committed to the project repo. Use this when you want persistent memory across sessions but don't want to touch the repository.

Rules-only mode (no init required)

You can intentionally skip /mb init entirely. In this state:

• The agent prints [MEMORY BANK: ABSENT] — Memory Bank lifecycle commands (/mb start, /mb done, etc.) stay inactive.
• All engineering rules still apply: TDD, SOLID, Clean Architecture, DRY/KISS/YAGNI, Testing Trophy, protected files, no placeholders. The installed global rules (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, etc.) are always-on.
• Run /mb init at any point to activate Memory Bank without losing any code.

Existing local bank users can stay on local mode — there is no forced migration.

Rule profiles & stack presets

Personalize the configurable rules layer without weakening the immutable safety baseline (TDD, no placeholders, protected files, destructive-confirm, fail-fast, DRY/KISS/YAGNI, verification before completion — these cannot be disabled by any profile).

# User-global profile (works even without a project Memory Bank):
mb-profile.sh init --scope=user --role=backend --stack=go --architecture=microservices --delivery=contract-first

# Project profile (stored in .memory-bank/ or global bank):
mb-profile.sh init --scope=project --role=frontend --stack=typescript --architecture=fsd --delivery=sdd

Supported role presets: backend, frontend, mobile. Supported stack presets: go,