Installation¶

Three paths. Pick the one that fits.

Path A — pipx (recommended)¶

Requires: Python 3.11+, pipx (install guide).

pipx install memory-bank-skill                      # installs the CLI only
memory-bank install                                 # global install (Claude, Codex, Pi, Cursor, OpenCode)
memory-bank install --clients claude-code,cursor    # wires agents, rules, commands, Pi prompts
memory-bank install --clients cursor --project-root .  # optional project-level .cursor/ adapter
memory-bank install --language ru                   # install Russian rule wording

Upgrades:

pipx upgrade memory-bank-skill

Verify:

memory-bank doctor
memory-bank version

Path B — Homebrew (macOS / Linuxbrew)¶

Requires: Homebrew.

brew tap fockus/tap
brew install memory-bank
memory-bank install
memory-bank install --clients cursor --project-root .  # optional project-level .cursor/ adapter
memory-bank install --language en

Upgrades: brew upgrade memory-bank.

Path C — git clone (developers / contributors)¶

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

Upgrade via scripts/mb-upgrade.sh (reads git fetch origin).

CLI reference (pipx / Homebrew)¶

Command	Purpose
`memory-bank install [--clients <list>] [--language <en\|ru>] [--project-root <path>]`	Run global install + optional cross-agent adapters
`memory-bank uninstall [-y\|--non-interactive]`	Remove global install
`memory-bank init`	Print `/mb init` hint for your AI coding client
`memory-bank version`	Print version
`memory-bank self-update`	Show upgrade command
`memory-bank doctor`	Resolve bundle path + platform info
`memory-bank --help`	Full usage

--clients accepts: claude-code, cursor, windsurf, cline, kilo, opencode, pi, codex.

--language accepts: en, ru.

TTY install without --language → interactive language prompt
non-interactive install without --language → default en
env override also works: MB_LANGUAGE=ru memory-bank install
uninstall can also be non-interactive: memory-bank uninstall -y

memory-bank install now performs these global registrations:

Canonical skill path: ~/.claude/skills/skill-memory-bank
Claude runtime alias: ~/.claude/skills/memory-bank
Codex runtime alias: ~/.codex/skills/memory-bank
Codex global hints: ~/.codex/AGENTS.md
Pi runtime alias: ~/.pi/agent/skills/memory-bank
Pi global prompts: ~/.pi/agent/prompts/*.md
Pi global hints/rules: ~/.pi/agent/AGENTS.md

It also performs a native OpenCode global install:

~/.config/opencode/AGENTS.md
~/.config/opencode/commands/*.md

For Codex this is intentionally conservative:

the skill, bundled commands, bundled agents, and bundled hooks are discoverable globally;
project-level Codex config/hooks still live under <project>/.codex/;
there is no native Codex /mb install command surface.

If you also pass --clients opencode, project-level OpenCode files are added under:

<project>/AGENTS.md
<project>/opencode.json
<project>/.opencode/plugins/memory-bank.js
<project>/.opencode/commands/*.md

See cross-agent-setup.md for per-client details.

Storage modes¶

memory-bank install installs the global skill and rules. Creating a Memory Bank for a specific project is a separate step via /mb init. You have three options:

Local mode (default)¶

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

The bank lives in the repo at .memory-bank/. Commit it to share with your team. Recommended for most projects.

Global mode (opt-in personal storage)¶

/mb init --storage=global --agent=claude-code
/mb init --storage=global --agent=cursor
/mb init --storage=global --agent=codex
/mb init --storage=global --agent=opencode
/mb init --storage=global --agent=pi

The bank lives outside the repo under ~/.<agent>/memory-bank/projects/<id>/.memory-bank. This is personal storage — do not commit it to the project repo. The project dir stays clean. Use this when you want persistent memory without touching the repository.

Agent	Global bank location
`claude-code`	`~/.claude/memory-bank/projects/<id>/.memory-bank`
`cursor`	`~/.cursor/memory-bank/projects/<id>/.memory-bank`
`codex`	`~/.codex/memory-bank/projects/<id>/.memory-bank`
`opencode`	`~/.config/opencode/memory-bank/projects/<id>/.memory-bank`
`pi`	`~/.pi/agent/memory-bank/projects/<id>/.memory-bank`

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 until you run /mb init.
All engineering rules still apply: TDD, SOLID, Clean Architecture, DRY/KISS/YAGNI, Testing Trophy, protected files, no placeholders. The installed global rules are always-on regardless of Memory Bank state.
This is a valid steady state for projects where you want rules enforcement without bank overhead.

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

Cursor User Rules¶

memory-bank install writes ~/.cursor/memory-bank-user-rules.md with version markers:

<!-- memory-bank:start vX.Y.Z -->
<rules content>
<!-- memory-bank:end -->

Cursor does not expose a file API for User Rules. Paste the file manually into Settings → Rules → User Rules. TTY installs offer a clipboard helper (pbcopy, xclip, or wl-copy); non-interactive installs only print the path and never wait for stdin.

Security-sensitive toggles¶

Project-local .memory-bank/metrics.sh overrides are disabled by default. To run one intentionally, use MB_ALLOW_METRICS_OVERRIDE=1.
Pi project adapter modes: default MB_PI_MODE=agents-md writes project AGENTS.md; MB_PI_MODE=skill writes ~/.pi/agent/skills/memory-bank only when the global Pi skill alias is not already present. Existing Pi skill backups are kept under ~/.pi/agent/.memory-bank-backups/, outside the Pi skill discovery directory.

Platform support¶

Platform	Status
macOS	✅ Full
Linux	✅ Full
Windows	⚠️ WSL only (bash required)

Running memory-bank install on native Windows exits with a WSL hint.

Troubleshooting¶

**memory-bank: command not found** — Ensure ~/.local/bin (pipx) or /opt/homebrew/bin (Homebrew) is on your $PATH.

**memory-bank doctor reports "Bundle: NOT FOUND"** — Something corrupted the venv shared-data. Reinstall: pipx reinstall memory-bank-skill.

**jq required errors** — Install jq: brew install jq or sudo apt install jq.

Upgrade didn't pick up new version — pipx reinstall memory-bank-skill (more aggressive than pipx upgrade).

memory-bank uninstall hangs in CI — pass -y / --non-interactive.