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

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.

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:

   hljs language-bash

   Copy

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

   hljs language-bash

   Copy

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

   hljs language-bash

   Copy

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

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, python, javascript, typescript, java, generic. Supported architecture presets: clean, hexagonal, modular-monolith, microservices, ddd, fsd, mobile-udf, event-driven. Supported delivery presets: tdd, contract-first, api-first, sdd, legacy-safe, exploratory.

Rules-only mode personalization: a user-global profile (~/<agent-config>/memory-bank/rules-profile.json) applies Go/backend/microservices presets even when no project Memory Bank exists. No project files are written. Use /mb profile init --scope=user ... or mb-profile.sh init --scope=user ....

Canonical machine format is JSON. YAML examples appear in documentation only and must be converted before storage. For full guidance see docs/rule-profiles.md.

What you get

1. Persistent project memory

Across sessions, compaction events, and even across AI agents — the project state survives. Switch from Claude Code to Cursor mid-project and the new agent catches up by reading .memory-bank/.

2. Engineering rules applied automatically

Installs ~/.claude/RULES.md, ~/.claude/CLAUDE.md, canonical skill registration in ~/.claude/skills/skill-memory-bank, compatibility aliases in ~/.claude/skills/memory-bank, ~/.codex/skills/memory-bank, and ~/.cursor/skills/memory-bank, plus full Cursor global surface (~/.cursor/hooks.json + ~/.cursor/hooks/*.sh + ~/.cursor/commands/*.md

• ~/.cursor/AGENTS.md managed section + ~/.cursor/memory-bank-user-rules.md paste-file for Settings → Rules → User Rules), plus native OpenCode global files (~/.config/opencode/AGENTS.md + ~/.config/opencode/commands/) with:

• TDD — tests before implementation
• Clean Architecture (backend) — Infrastructure → Application → Domain, never the reverse
• Feature-Sliced Design (frontend) — app → pages → widgets → features → entities → shared
• Mobile (iOS/Android) — UDF + Clean layers, SwiftUI+Observation / Compose+StateFlow
• SOLID — SRP (≤300 LOC / class), ISP (≤5 methods / interface), DIP (constructor injection)
• Testing Trophy — integration > unit > e2e; mock only external services
• Coverage targets — 85% overall, 95% core, 70% infrastructure

The agent reads these rules at session start and follows them without you having to remind it.

3. Dev-workflow commands

25 top-level slash-commands (live in commands/):

Key /mb sub-commands (full list lives in commands/mb.md):

Run /mb help inside any agent to see this table live; /mb help <sub> for full detail of one sub-command.

4. Cross-agent portability

One .memory-bank/ directory, 8 AI clients:

AGENTS.md is shared across OpenCode, Codex, Pi — ownership is refcount-tracked, so uninstalling one client doesn't break the others.

The code graph

grep -rn burns tokens and lies — it matches strings, comments, and shadowed names. /mb graph builds a deterministic, queryable map of your codebase instead, with three different ways to ask it questions.

/mb graph --apply    # → .memory-bank/codebase/graph.json + god-nodes.md

• Languages: Python via stdlib ast (zero extra deps) + Go, JavaScript, TypeScript, Rust, Java via tree-sitter (pip install 'memory-bank-skill[codegraph]').
• graph.json — JSON Lines: one node (module / function / class) or edge (import / call / inherit) per line. Greppable, jq-queryable, diffable, committable.
• god-nodes.md — refactoring hotspots: top symbols and modules by degree, bridge files by betweenness centrality, Louvain module communities.
• Incremental: SHA256 per-file cache — the first build takes minutes on a 1000-file repo, rebuilds take seconds.

Three ways to use it

# 1 — impact analysis before a refactor: deterministic, zero tokens
python3 scripts/mb-graph-query.py impact --graph .memory-bank/codebase/graph.json --symbol WriteFile
jq -r 'select(.type=="edge" and .kind=="call" and .dst=="WriteFile") | .src' \
   .memory-bank/codebase/graph.json

# 2 — find code by meaning, not by name
python3 scripts/mb-semantic-search.py "how does auth token refresh work" --source-only

# 3 — a written wiki of your architecture + semantic edges with confidence + rationale
/mb wiki

Opt-in layers (without them the base output stays byte-identical):

• --cochange — git-history co-change edges: files that change together without importing each other (test ↔ subject, config ↔ reader). Coupling no AST can see.
• --questions — deterministic suggested questions appended to god-nodes.md ("what should I look at first?").
• --docs — signatures + docstrings on nodes, so semantic search matches intent, not just identifiers.

The dev-role subagents are wired to the graph automatically (graph_neighbors / graph_impact / graph_tests routing): before editing they check the blast radius instead of guessing, and fall back to plain grep when the graph is missing or stale — the graph never blocks work.

How it compares

Honest trade-offs: language coverage is 6 vs Aider's 130+; call resolution is name-based (no LSP / type-checker precision — Serena wins there); and there is no PageRank-ranked automatic context packing like Aider's repo-map. We trade those for a persistent, $0, locally queryable artifact that lives next to the rest of your project memory.

Full reference: code-graph concepts · jq cookbook.

Usage examples

Starting a new feature

You: /mb plan feature user-auth

Agent: [creates .memory-bank/plans/2026-04-20_feature_user-auth.md with DoD,
        test plan, stage breakdown, dependencies]

You: Now implement stage 1.

Agent: [reads plan, writes failing tests first (TDD), then implementation,
        runs tests, updates checklist ⬜ → ✅]

You: /mb verify

Agent: [plan-verifier agent checks that implementation matches plan DoD]

You: /mb done

Agent: [appends session summary to progress.md, updates status.md if needed]

Jumping into an existing project

cd some-legacy-project/
memory-bank install                     # global install for all supported clients
#                                       # (Claude + Cursor + Codex + OpenCode, auto)
memory-bank install --clients cursor    # OPTIONAL: also wire .cursor/ project adapter
#                                       # — global parity already active without this flag

# In Cursor:
/mb init --full                         # auto-detect stack, generate CLAUDE.md
/mb start                               # load everything

Cursor-only quick start

# Step 1. Install (no --clients flag needed for Cursor global parity)
memory-bank install

# Step 2 (one-time, per machine). Cursor User Rules panel is UI-only —
# paste the generated bundle into Settings → Rules → User Rules:
pbcopy < ~/.cursor/memory-bank-user-rules.md           # macOS
xclip -selection clipboard < ~/.cursor/memory-bank-user-rules.md   # Linux
# The file is wrapped in <!-- memory-bank:start vX.Y.Z --> / <!-- memory-bank:end --> markers.

# Step 3. Open any project in Cursor and run:
/mb init                                # one-time per project
/mb start                               # every session

Sharing state with your team

.memory-bank/ is just markdown. Commit it. Your colleague clones the repo, runs /mb start, and has the full project context without asking you a single question.

CLI reference

After pipx install memory-bank-skill:

memory-bank install [--clients <list>] [--language <en|ru|es|zh>] [--project-root <path>] [--non-interactive]
memory-bank uninstall [-y|--non-interactive]
memory-bank init                    # prints /mb init hint
memory-bank version
memory-bank self-update             # prints `pipx upgrade ...`
memory-bank doctor                  # resolves bundle, platform info, checks bash
memory-bank --help

Flags:

• --clients <list> — comma-separated. Valid: claude-code, cursor, windsurf, cline, kilo, opencode, pi, codex. If omitted and running in a TTY → interactive menu. Non-TTY default: claude-code only.
• --project-root <path> — where to place client-specific adapters. Default: current directory.
• --non-interactive — never prompt; use defaults when --clients not specified. Use in CI / scripted installs.
• -y / --non-interactive on uninstall — skip the confirmation prompt. Use in CI / scripted cleanup.

Environment variables

Platform support

Windows quick start:

# Either:
winget install Git.Git            # → supplies bash.exe at C:\Program Files\Git\bin\bash.exe
# or:
wsl --install                     # → full Linux env
pip install memory-bank-skill     # inside WSL or with Git Bash on PATH
memory-bank doctor                # verifies bash discovery
memory-bank install               # works once bash is resolvable

memory-bank doctor on Windows reports the detected bash path (or an install hint if none found).

FAQ

Q: Do I need to commit .memory-bank/ to git? A: Recommended if working in a team — that's how state is shared. Solo project: optional. Either way works.

Q: Does this replace Claude Code's built-in memory? A: No — complementary. Native memory is per-user, cross-project (preferences, style). .memory-bank/ is per-project, team-shared (status, plans, decisions). Both load simultaneously.

Q: Will it work on private repositories? A: Yes. Everything is local. No data sent anywhere unless your AI agent itself calls external APIs (that's unchanged).

Q: What if my team uses different AI agents? A: That's the whole point. Install per-client: memory-bank install --clients cursor,windsurf,claude-code. One memory bank, everyone reads it.

Q: Cursor hooks are experimental / Codex hooks are experimental — is that a problem? A: Partial — where native hooks don't exist or aren't stable, we ship graceful fallbacks or conservative integration. Cursor global install wires 10 hooks including sessionStart, matcher-aware preToolUse, and matcher-aware postToolUse. For Codex, global support means skill discovery + ~/.codex/AGENTS.md hints; hook/config integration is still primarily project-level via .codex/. See docs/cross-agent-setup.md for specifics.

Q: My existing AGENTS.md / .cursor/hooks.json — will this overwrite them? A: No. Adapters use a marker pattern (<!-- memory-bank:start/end --> for MD files, _mb_owned: true for JSON hooks) and merge idempotently. User content is preserved; uninstall only removes MB-owned sections.

Q: How do I upgrade? A: pipx upgrade memory-bank-skill or brew upgrade memory-bank. Git-clone install: cd ~/.claude/skills/skill-memory-bank && git pull && ./install.sh.

Q: Does reinstalling create .pre-mb-backup.* files every time? A: No. Since 3.0.0, install.sh is byte-level idempotent: each target is compared via cmp -s to the expected post-install content (including localization) and backup is created only if content actually differs. Repeat installs on an up-to-date tree produce zero backups. Language swap (--language en → --language ru) backs up exactly the localize-target files (RULES.md, memory-bank-user-rules.md) and nothing else.

Q: I want to remove everything. A: memory-bank uninstall -y removes global install without a prompt. Per-project adapters: adapters/<client>.sh uninstall <project-dir>.

Q: Can a project-local .memory-bank/metrics.sh run arbitrary commands during install or doctor flows? A: Not by default. Project-local metrics overrides are disabled unless you explicitly opt in with MB_ALLOW_METRICS_OVERRIDE=1. Without that env var, the shipped stack detection stays on the safe built-in path.

Q: Does Pi need a separate setup step? A: memory-bank install now writes Pi global artifacts automatically: ~/.pi/agent/AGENTS.md, ~/.pi/agent/skills/memory-bank, and slash prompt templates in ~/.pi/agent/prompts/. In an existing Pi session, run /reload after install. For a project-level shared AGENTS.md, additionally run memory-bank install --clients pi --project-root <repo>. Existing local Pi skill directories are backed up outside ~/.pi/agent/skills/ so Pi does not discover backup copies as duplicate skills.

Q: Is this production-ready? A: Yes. Current stable line is v5.0.0 (released 2026-06-10). Daily used on real projects — including on this repository itself (the skill maintains its own .memory-bank/). Full test envelope green: 1,900+ automated tests (pytest + bats) on Python 3.11/3.12 × Ubuntu and macOS. Stable API.

Documentation

Get started (learning)

• 5-minute quick start — install → /mb init → /mb start → work → /mb done
• Your first feature, end to end — a worked example: plan → TDD → verify → done
• Install guide — pipx / Homebrew / git-clone with troubleshooting
• Overview — the mental model in one page

Concepts (understanding)

• Composable /mb work pipeline — review off by default; --review/--judge/--stages + the full preset
• Code graph & semantic search — /mb map, /mb graph (+--questions/--cochange/--docs), mb-semantic-search.py, /mb wiki
• Cross-session memory — /mb recall, session hooks, the local semantic index
• Rule profiles & presets — tune the rules to your role/stack without weakening the safety baseline

How-to (tasks)

• Cross-agent setup — per-client cheatsheet + hook capability matrix
• Troubleshooting — common issues and fixes
• v4 → v5 migration — review now off by default; composable /mb work pipeline
• v3.0 → v3.1 migration · v1 → v2 migration — older structural upgrades
• Repository migration — for users upgrading from claude-skill-memory-bank

Reference

• Agents reference — all 29 subagents and when each one is invoked
• Release process — PyPI OIDC setup + tag workflow
• CHANGELOG — version history
• Security policy — reporting, scope, design decisions

Contributing

1. Fork & clone.
2. ./install.sh && /mb init in the repo itself (this skill uses itself — meta but works).
3. Write tests first (TDD). bats tests/bats/ tests/e2e/ + python3 -m pytest tests/pytest/.
4. Follow the rules in rules/RULES.md (the same ones the skill enforces on users).
5. Open a PR. CI runs on Python 3.11 + 3.12 × ubuntu + macos.

License

MIT. See LICENSE.

Links

• Website: https://fockus.github.io/skill-memory-bank/
• Repo: https://github.com/fockus/skill-memory-bank
• PyPI: https://pypi.org/project/memory-bank-skill/
• Homebrew tap: https://github.com/fockus/homebrew-tap
• Issues: https://github.com/fockus/skill-memory-bank/issues

Your agent is already smart. memory-bank-skill makes it remember.