{"id":49114267,"url":"https://github.com/fockus/skill-memory-bank","last_synced_at":"2026-06-11T01:01:44.888Z","repository":{"id":352531517,"uuid":"1215504684","full_name":"fockus/skill-memory-bank","owner":"fockus","description":"Universal long-term project memory + dev toolkit for Claude Code, Cursor, Windsurf, Cline, Kilo, OpenCode, Pi Code, Codex","archived":false,"fork":false,"pushed_at":"2026-06-09T18:22:32.000Z","size":2306,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T20:11:57.599Z","etag":null,"topics":["agent-skill","ai-agents","ai-coding-assistant","anthropic","claude","claude-code","claude-skill","clean-architecture","cline","codex","cursor","developer-tools","memory-bank","opencode","project-memory","skill","tdd","windsurf"],"latest_commit_sha":null,"homepage":"https://fockus.github.io/skill-memory-bank/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fockus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T01:33:59.000Z","updated_at":"2026-06-09T18:22:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fockus/skill-memory-bank","commit_stats":null,"previous_names":["fockus/skill-memory-bank"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/fockus/skill-memory-bank","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fockus%2Fskill-memory-bank","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fockus%2Fskill-memory-bank/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fockus%2Fskill-memory-bank/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fockus%2Fskill-memory-bank/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fockus","download_url":"https://codeload.github.com/fockus/skill-memory-bank/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fockus%2Fskill-memory-bank/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34177444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agents","ai-coding-assistant","anthropic","claude","claude-code","claude-skill","clean-architecture","cline","codex","cursor","developer-tools","memory-bank","opencode","project-memory","skill","tdd","windsurf"],"created_at":"2026-04-21T06:10:10.211Z","updated_at":"2026-06-11T01:01:44.867Z","avatar_url":"https://github.com/fockus.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# memory-bank-skill\n\n**Persistent project memory + dev toolkit for AI coding agents.**\n\nYour AI remembers the project between sessions, follows the same engineering rules,\nand picks up exactly where you left off.\n\nClaude Code · Cursor · Windsurf · Cline · Kilo · OpenCode · Codex · Pi Code\n\n[![CI](https://img.shields.io/github/actions/workflow/status/fockus/skill-memory-bank/test.yml?branch=main\u0026label=tests\u0026style=flat-square\u0026color=brightgreen\u0026v=300)](https://github.com/fockus/skill-memory-bank/actions/workflows/test.yml)\n[![PyPI version](https://img.shields.io/pypi/v/memory-bank-skill?style=flat-square\u0026color=brightgreen\u0026label=pypi\u0026v=300)](https://pypi.org/project/memory-bank-skill/)\n[![GitHub release](https://img.shields.io/github/v/release/fockus/skill-memory-bank?style=flat-square\u0026color=brightgreen\u0026label=release\u0026v=300)](https://github.com/fockus/skill-memory-bank/releases/latest)\n[![Python versions](https://img.shields.io/pypi/pyversions/memory-bank-skill?style=flat-square\u0026color=brightgreen\u0026v=300)](https://pypi.org/project/memory-bank-skill/)\n[![Homebrew tap](https://img.shields.io/badge/homebrew-fockus%2Ftap-brightgreen?style=flat-square\u0026v=300)](https://github.com/fockus/homebrew-tap)\n[![Downloads](https://img.shields.io/pypi/dm/memory-bank-skill?style=flat-square\u0026color=brightgreen\u0026v=300)](https://pypi.org/project/memory-bank-skill/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square\u0026v=300)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/fockus/skill-memory-bank?style=social)](https://github.com/fockus/skill-memory-bank/stargazers)\n\n[Install](#install) · [Quick start](#5-minute-quick-start) · [What you get](#what-you-get) · [Code graph](#the-code-graph) · [Commands](#3-dev-workflow-commands) · [Cross-agent](#4-cross-agent-portability) · [FAQ](#faq) · [Docs](#documentation) · [Website](https://fockus.github.io/skill-memory-bank/)\n\n\u003ca href=\"https://fockus.github.io/skill-memory-bank/\"\u003e\u003cimg 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\"\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n\n\u003e **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](CHANGELOG.md) · [v4 → v5 migration](docs/MIGRATION-v4-v5.md)\n\n```bash\npipx install memory-bank-skill \u0026\u0026 memory-bank install\n```\n\n```text\n# then, inside your agent:\n/mb init     # once per project\n/mb start    # every session — full context restored\n```\n\n| Slash commands | `/mb` sub-commands | Subagents | AI clients | Automated tests |\n|:--------------:|:------------------:|:---------:|:----------:|:---------------:|\n| 25             | 25+                | 29        | 8          | 1,900+          |\n\n---\n\n## The problem it solves\n\nEvery 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.\n\n```\n.memory-bank/\n├── status.md          ← where we are, what's next\n├── checklist.md       ← current tasks (✅ / ⬜)\n├── roadmap.md         ← priorities, direction\n├── research.md        ← hypotheses log (H-NNN) + current experiment\n├── backlog.md         ← parking lot for ideas + ADRs\n├── progress.md        ← work log (append-only)\n├── lessons.md         ← mistakes not to repeat\n├── notes/             ← knowledge (5-15 line snippets)\n├── plans/             ← detailed plans per feature/fix\n├── reports/           ← analysis, post-mortems\n├── experiments/       ← EXP-NNN experiment artifacts\n└── codebase/          ← stack / architecture / conventions map (`/mb map`)\n```\n\nThis directory lives alongside your code (commit it, share it with your team, or `.gitignore` it — your call).\n\n---\n\n## Install\n\nPick one:\n\n### Option 0: skills.sh CLI (fastest one-shot install)\n\n```bash\nnpx skills add fockus/skill-memory-bank\n```\n\nCopies 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.\n\n### Option 1: pipx (recommended, cross-platform)\n\n```bash\npipx install memory-bank-skill           # stable\n# or, for the latest release candidate:\npipx install --pip-args='--pre' memory-bank-skill\n\n# pipx only installs the CLI. Run this once to wire agents, rules, commands, and Pi prompts:\nmemory-bank install                      # global install for Claude Code + Cursor + Codex + OpenCode + Pi\n# optional: pick installed rule language explicitly\nmemory-bank install --language ru\n```\n\n**Requires:** Python 3.11+, `pipx`, `jq`.\n\n### Option 2: Homebrew (macOS / Linuxbrew)\n\n```bash\nbrew tap fockus/tap\nbrew install memory-bank\nmemory-bank install\n```\n\n### Option 3: git clone (developers)\n\n```bash\ngit clone https://github.com/fockus/skill-memory-bank.git ~/.claude/skills/skill-memory-bank\ncd ~/.claude/skills/skill-memory-bank\n./install.sh\n```\n\n### Add cross-agent support (Cursor, Windsurf, OpenCode, etc.)\n\nThree ways — pick whichever matches your workflow:\n\n**A. Interactive menu** (from any terminal — recommended if you're unsure which clients you want):\n\n```bash\ncd your-project/\nmemory-bank install                     # multi-select prompt for all 8 clients\n# in TTY mode it will also ask which language to use for installed rules\n```\n\n**B. CLI flags** (scripts / CI / one-liner):\n\n```bash\ncd your-project/\nmemory-bank install --clients claude-code,cursor,windsurf\nmemory-bank install --clients claude-code,cursor --language en\n```\n\n**C. From inside an agent with command surface** (Claude Code / OpenCode):\n\n```\n/mb install                                 # interactive picker\n/mb install cursor,windsurf                 # direct\n/mb install all                             # every client\n```\n\nClaude Code/OpenCode can front this through `/mb install`, then run `memory-bank install --clients \u003cselected\u003e` 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.\n\nSupported client names: `claude-code`, `cursor`, `windsurf`, `cline`, `kilo`, `opencode`, `pi`, `codex`.\nSupported rule languages: `en` (default), `ru` (full translation), `es`/`zh` (scaffolds — community PRs welcome, see [docs/i18n.md](docs/i18n.md)). You can also set `MB_LANGUAGE=en|ru|es|zh`.\n\nFull per-client details: [docs/cross-agent-setup.md](docs/cross-agent-setup.md).\n\n---\n\n## 5-minute quick start\n\n1. **Install** (see above).\n\n2. **Open your project** in your AI agent (Claude Code, Cursor, etc.) and run:\n\n   ```\n   /mb init\n   ```\n\n   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.\n\n3. **Every session starts with:**\n\n   ```\n   /mb start\n   ```\n\n   The agent loads `status.md`, `checklist.md`, `roadmap.md`, `research.md` — it knows exactly what you were working on and what comes next.\n\n4. **As you work:** the agent updates `checklist.md` (⬜ → ✅) whenever tasks finish.\n\n5. **Every session ends with:**\n\n   ```\n   /mb done\n   ```\n\n   This appends a session entry to `progress.md`, updates `status.md` if needed, writes a knowledge note if something interesting was learned.\n\nThat's it. Rinse and repeat.\n\n### Storage modes\n\nMemory Bank supports three ways to store your bank — pick the one that fits your workflow:\n\n**Local mode (default)**\n```bash\n/mb init                       # same as /mb init --storage=local\n```\nThe 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.\n\n**Global mode (opt-in personal storage)**\n```bash\n/mb init --storage=global --agent=claude-code   # for Claude Code\n/mb init --storage=global --agent=cursor         # for Cursor\n/mb init --storage=global --agent=codex          # for Codex\n```\nThe bank lives outside the repo under `~/.\u003cagent\u003e/memory-bank/projects/\u003cid\u003e/.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.\n\n**Rules-only mode (no init required)**\n\nYou can intentionally skip `/mb init` entirely. In this state:\n- The agent prints `[MEMORY BANK: ABSENT]` — Memory Bank lifecycle commands (`/mb start`, `/mb done`, etc.) stay inactive.\n- **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.\n- Run `/mb init` at any point to activate Memory Bank without losing any code.\n\nExisting local bank users can stay on local mode — there is no forced migration.\n\n### Rule profiles \u0026 stack presets\n\nPersonalize 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).\n\n```bash\n# User-global profile (works even without a project Memory Bank):\nmb-profile.sh init --scope=user --role=backend --stack=go --architecture=microservices --delivery=contract-first\n\n# Project profile (stored in .memory-bank/ or global bank):\nmb-profile.sh init --scope=project --role=frontend --stack=typescript --architecture=fsd --delivery=sdd\n```\n\nSupported role presets: **backend**, **frontend**, **mobile**.\nSupported stack presets: **go**, **python**, **javascript**, **typescript**, **java**, **generic**.\nSupported architecture presets: clean, hexagonal, modular-monolith, microservices, ddd, fsd, mobile-udf, event-driven.\nSupported delivery presets: tdd, contract-first, api-first, sdd, legacy-safe, exploratory.\n\nRules-only mode personalization: a user-global profile (`~/\u003cagent-config\u003e/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 ...`.\n\nCanonical machine format is **JSON**. YAML examples appear in documentation only and must be converted before storage. For full guidance see [docs/rule-profiles.md](docs/rule-profiles.md).\n\n---\n\n## What you get\n\n### 1. Persistent project memory\n\nAcross 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/`.\n\n### 2. Engineering rules applied automatically\n\nInstalls `~/.claude/RULES.md`, `~/.claude/CLAUDE.md`, canonical skill registration in\n`~/.claude/skills/skill-memory-bank`, compatibility aliases in `~/.claude/skills/memory-bank`,\n`~/.codex/skills/memory-bank`, and `~/.cursor/skills/memory-bank`, plus full Cursor global\nsurface (`~/.cursor/hooks.json` + `~/.cursor/hooks/*.sh` + `~/.cursor/commands/*.md`\n+ `~/.cursor/AGENTS.md` managed section + `~/.cursor/memory-bank-user-rules.md`\npaste-file for Settings → Rules → User Rules), plus native OpenCode global files\n(`~/.config/opencode/AGENTS.md` + `~/.config/opencode/commands/`) with:\n\n- **TDD** — tests before implementation\n- **Clean Architecture** (backend) — Infrastructure → Application → Domain, never the reverse\n- **Feature-Sliced Design** (frontend) — `app → pages → widgets → features → entities → shared`\n- **Mobile** (iOS/Android) — UDF + Clean layers, SwiftUI+Observation / Compose+StateFlow\n- **SOLID** — SRP (≤300 LOC / class), ISP (≤5 methods / interface), DIP (constructor injection)\n- **Testing Trophy** — integration \u003e unit \u003e e2e; mock only external services\n- **Coverage** targets — 85% overall, 95% core, 70% infrastructure\n\nThe agent reads these rules at session start and follows them without you having to remind it.\n\n### 3. Dev-workflow commands\n\n**25 top-level slash-commands** (live in `commands/`):\n\n| Command | Purpose |\n|---------|---------|\n| `/mb \u003csub\u003e` | Memory Bank hub (20+ sub-commands — see table below) |\n| `/start` | Lightweight session start (loads STATUS/checklist only) |\n| `/done` | Lightweight session close (no full actualize) |\n| `/plan` | Implementation plan generator with DoD/TDD scaffolding (Phase / Sprint / Stage) |\n| `/discuss` | 5-phase requirements-elicitation interview → `context/\u003ctopic\u003e.md` (EARS-validated) |\n| `/sdd` | Kiro-style spec triple → `specs/\u003ctopic\u003e/{requirements,design,tasks}.md` |\n| `/work` | Execute plan/spec stages with role-agents; composable pipeline (`--review`/`--judge`/`--stages`, review **off by default**) |\n| `/config` | Manage `pipeline.yaml` engine config (init / show / validate / path) |\n| `/profile` | Manage rule profiles and stack presets (init / show / validate / set / path) |\n| `/commit` | Conventional-commit message with MB context |\n| `/pr` | Create pull request with structured description |\n| `/review` | Full code review (correctness + security + perf + style) |\n| `/test` | Run tests + coverage analysis + gap report |\n| `/refactor` | Guided refactoring (Strangler Fig, staged diffs) |\n| `/doc` | Generate / refresh documentation from code |\n| `/changelog` | Update CHANGELOG.md from recent commits |\n| `/catchup` | Summarize recent changes since last session |\n| `/adr` | Architecture Decision Record template writer |\n| `/contract` | Contract-first workflow (Protocol/ABC → tests → impl) |\n| `/security-review` | OWASP-focused security audit pass |\n| `/api-contract` | API contract validation + breaking-change detection |\n| `/db-migration` | Safe DB migration planning (rollback, backfill) |\n| `/observability` | Logging / metrics / tracing audit for a module |\n| `/roadmap-sync` | Regenerate `roadmap.md` autosync block from plan frontmatter |\n| `/traceability-gen` | Regenerate REQ → Plan → Test traceability matrix |\n\n**Key `/mb` sub-commands** (full list lives in `commands/mb.md`):\n\n| Sub-command | Purpose |\n|-------------|---------|\n| `/mb` / `/mb context` | Collect project context (status, checklist, active plan) |\n| `/mb start` | Extended session start — full context + active plan body |\n| `/mb done` | Close session — actualize + note + progress |\n| `/mb update` | Refresh core files with live metrics (no note) |\n| `/mb verify` | Verify implementation matches the active plan (CRITICAL before `/mb done`) |\n| `/mb doctor` | Find \u0026 fix inconsistencies inside the memory bank |\n| `/mb plan \u003ctype\u003e \u003ctopic\u003e` | Create detailed plan (feature / fix / refactor / experiment) |\n| `/mb search \u003cquery\u003e` | Keyword search across the memory bank |\n| `/mb note \u003ctopic\u003e` | Quick knowledge note (5-15 lines) |\n| `/mb tasks` | Show pending tasks from checklist |\n| `/mb index` | Registry of all entries (core + notes/plans/experiments/reports) |\n| `/mb map [focus]` | Scan codebase, write MD docs to `.memory-bank/codebase/` (stack/arch/quality/concerns/all) |\n| `/mb graph [--apply]` | Multi-language code graph (Python `ast` + Go/JS/TS/Rust/Java tree-sitter); opt-in `--questions` / `--cochange` / `--docs`. See [code-graph docs](docs/concepts/code-graph.md) |\n| `/mb wiki [--dry-run]` | LLM per-community codebase wiki + surprising-connection edges (Haiku/Sonnet subagents, no API key) |\n| `/mb recall \u003cquery\u003e` | Cross-session recall over past chats (`session/` + `notes/`). See [session-memory docs](docs/concepts/session-memory.md) |\n| `/mb reindex [--full]` | Build/refresh the local semantic index for `/mb recall` (fastembed, $0; degrades to lexical) |\n| `/mb compact [--apply]` | Status-based decay — archive old done plans + low-importance notes |\n| `/mb import --project \u003cpath\u003e` | Bootstrap MB from Claude Code JSONL transcripts |\n| `/mb tags [--apply]` | Normalize frontmatter tags (Levenshtein-based synonym merge) |\n| `/mb upgrade` | Update skill from GitHub (git pull + re-install) |\n| `/mb init [--minimal\\|--full]` | Initialize `.memory-bank/` in a new project |\n| `/mb install [\u003cclients\u003e]` | Install Memory Bank + cross-agent adapters interactively or via client list |\n| `/mb deps [--install-hints]` | Dependency check (python3, jq, git + optional tree-sitter) |\n| `/mb help [subcommand]` | Show sub-command reference inline |\n\n**Run `/mb help` inside any agent** to see this table live; `/mb help \u003csub\u003e` for full detail of one sub-command.\n\n### 4. Cross-agent portability\n\nOne `.memory-bank/` directory, 8 AI clients:\n\n| Client | Native hooks | Adapter output |\n|--------|--------------|----------------|\n| **Claude Code** | Full lifecycle | `~/.claude/settings.json` + `hooks/` |\n| **Cursor 1.7+** | ✅ (Claude-Code-compatible format) | **Global (auto):** `~/.cursor/{skills,hooks,commands,AGENTS.md,hooks.json,memory-bank-user-rules.md}` · **Project (optional `--clients cursor`):** `.cursor/rules/*.mdc` + `.cursor/hooks.json` |\n| **Windsurf** | ✅ Cascade Hooks | `.windsurf/rules/*.md` + `.windsurf/hooks.json` |\n| **Cline** | ✅ `.clinerules/hooks/*.sh` | `.clinerules/memory-bank.md` + `hooks/` |\n| **Kilo** | ❌ (fallback to git hooks) | `.kilocode/rules/` + `.git/hooks/` |\n| **OpenCode** | ✅ TypeScript plugins + native commands | `~/.config/opencode/{AGENTS.md,commands/}` + project `AGENTS.md` + `opencode.json` + TS plugin |\n| **Codex** (OpenAI) | ✅ Conservative global support + experimental project hooks | `~/.codex/skills/memory-bank` + `~/.codex/AGENTS.md` + project `AGENTS.md` + `.codex/config.toml` + `.codex/hooks.json` |\n| **Pi Code** | Global skill + global prompts + `AGENTS.md` | `~/.pi/agent/skills/memory-bank`, `~/.pi/agent/prompts/*.md`, `~/.pi/agent/AGENTS.md` + optional project `AGENTS.md` |\n\n`AGENTS.md` is shared across OpenCode, Codex, Pi — ownership is refcount-tracked, so uninstalling one client doesn't break the others.\n\n---\n\n## The code graph\n\n`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.\n\n```bash\n/mb graph --apply    # → .memory-bank/codebase/graph.json + god-nodes.md\n```\n\n- **Languages:** Python via stdlib `ast` (zero extra deps) + Go, JavaScript, TypeScript, Rust, Java via tree-sitter (`pip install 'memory-bank-skill[codegraph]'`).\n- **`graph.json`** — JSON Lines: one node (module / function / class) or edge (import / call / inherit) per line. Greppable, `jq`-queryable, diffable, committable.\n- **`god-nodes.md`** — refactoring hotspots: top symbols and modules by degree, **bridge files** by betweenness centrality, Louvain module communities.\n- **Incremental:** SHA256 per-file cache — the first build takes minutes on a 1000-file repo, rebuilds take seconds.\n\n### Three ways to use it\n\n| Mode | Tool | Question it answers | Cost |\n|------|------|---------------------|------|\n| **1. Structural queries** | `mb-graph-query.py` (`neighbors` / `impact` / `tests`) or raw `jq` | \"Who calls X?\" · \"What breaks if I change X?\" · \"Which tests cover X?\" | $0, \u003c1 s |\n| **2. Semantic search** | `mb-semantic-search.py` — BM25 by default, local embeddings opt-in | \"Where is the rate-limiting logic?\" — concept queries, tolerant to naming | $0, fully local |\n| **3. LLM wiki** | `/mb wiki` — Haiku writes one article per module community, Sonnet hunts cross-community \"surprising connections\" | \"Give me the map\" · \"What non-obvious links exist?\" | your agent's own subagents — **no extra API key** |\n\n```bash\n# 1 — impact analysis before a refactor: deterministic, zero tokens\npython3 scripts/mb-graph-query.py impact --graph .memory-bank/codebase/graph.json --symbol WriteFile\njq -r 'select(.type==\"edge\" and .kind==\"call\" and .dst==\"WriteFile\") | .src' \\\n   .memory-bank/codebase/graph.json\n\n# 2 — find code by meaning, not by name\npython3 scripts/mb-semantic-search.py \"how does auth token refresh work\" --source-only\n\n# 3 — a written wiki of your architecture + semantic edges with confidence + rationale\n/mb wiki\n```\n\n**Opt-in layers** (without them the base output stays byte-identical):\n\n- `--cochange` — git-history co-change edges: files that change together *without importing each other* (test ↔ subject, config ↔ reader). Coupling no AST can see.\n- `--questions` — deterministic suggested questions appended to `god-nodes.md` (\"what should I look at first?\").\n- `--docs` — signatures + docstrings on nodes, so semantic search matches intent, not just identifiers.\n\nThe 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.\n\n### How it compares\n\n| | memory-bank-skill | Aider repo-map | Serena MCP | Cursor indexing | Cline |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Persistent queryable graph on disk | ✅ JSONL | ❌ ranked text per request | ❌ live LSP | ❌ server-side vectors | ❌ no index |\n| Structural queries (\"who calls X?\") | ✅ jq / CLI | ❌ | ✅ LSP-precise | ❌ similarity only | ❌ |\n| Works offline, $0, no server process | ✅ | ✅ | ⚠️ local server | ❌ cloud embeddings | ✅ |\n| Git co-change edges | ✅ opt-in | ❌ | ❌ | ❌ | ❌ |\n| LLM codebase wiki + semantic edges | ✅ no extra API key | ❌ | ❌ | ❌ | ❌ |\n| Lives next to project memory (plans / ADRs / sessions) | ✅ | ❌ | ❌ | ❌ | ❌ |\n\nHonest 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.\n\nFull reference: [code-graph concepts](docs/concepts/code-graph.md) · [jq cookbook](references/code-graph.md).\n\n---\n\n## Usage examples\n\n### Starting a new feature\n\n```\nYou: /mb plan feature user-auth\n\nAgent: [creates .memory-bank/plans/2026-04-20_feature_user-auth.md with DoD,\n        test plan, stage breakdown, dependencies]\n\nYou: Now implement stage 1.\n\nAgent: [reads plan, writes failing tests first (TDD), then implementation,\n        runs tests, updates checklist ⬜ → ✅]\n\nYou: /mb verify\n\nAgent: [plan-verifier agent checks that implementation matches plan DoD]\n\nYou: /mb done\n\nAgent: [appends session summary to progress.md, updates status.md if needed]\n```\n\n### Jumping into an existing project\n\n```bash\ncd some-legacy-project/\nmemory-bank install                     # global install for all supported clients\n#                                       # (Claude + Cursor + Codex + OpenCode, auto)\nmemory-bank install --clients cursor    # OPTIONAL: also wire .cursor/ project adapter\n#                                       # — global parity already active without this flag\n\n# In Cursor:\n/mb init --full                         # auto-detect stack, generate CLAUDE.md\n/mb start                               # load everything\n```\n\n### Cursor-only quick start\n\n```bash\n# Step 1. Install (no --clients flag needed for Cursor global parity)\nmemory-bank install\n\n# Step 2 (one-time, per machine). Cursor User Rules panel is UI-only —\n# paste the generated bundle into Settings → Rules → User Rules:\npbcopy \u003c ~/.cursor/memory-bank-user-rules.md           # macOS\nxclip -selection clipboard \u003c ~/.cursor/memory-bank-user-rules.md   # Linux\n# The file is wrapped in \u003c!-- memory-bank:start vX.Y.Z --\u003e / \u003c!-- memory-bank:end --\u003e markers.\n\n# Step 3. Open any project in Cursor and run:\n/mb init                                # one-time per project\n/mb start                               # every session\n```\n\n### Sharing state with your team\n\n`.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.\n\n---\n\n## CLI reference\n\nAfter `pipx install memory-bank-skill`:\n\n```bash\nmemory-bank install [--clients \u003clist\u003e] [--language \u003cen|ru|es|zh\u003e] [--project-root \u003cpath\u003e] [--non-interactive]\nmemory-bank uninstall [-y|--non-interactive]\nmemory-bank init                    # prints /mb init hint\nmemory-bank version\nmemory-bank self-update             # prints `pipx upgrade ...`\nmemory-bank doctor                  # resolves bundle, platform info, checks bash\nmemory-bank --help\n```\n\nFlags:\n- `--clients \u003clist\u003e` — 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.\n- `--project-root \u003cpath\u003e` — where to place client-specific adapters. Default: current directory.\n- `--non-interactive` — never prompt; use defaults when `--clients` not specified. Use in CI / scripted installs.\n- `-y` / `--non-interactive` on `uninstall` — skip the confirmation prompt. Use in CI / scripted cleanup.\n\n---\n\n## Environment variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `MB_AUTO_CAPTURE` | SessionEnd auto-capture mode: `auto` / `strict` / `off` | `auto` |\n| `MB_REDACT_SECRETS` | Redact API keys/tokens (sk-…, ghp\\_…, AKIA…, JWT, `*_API_KEY=` values…) from session capture and the semantic index before they reach disk | `on` |\n| `MB_COMPACT_REMIND` | Weekly `/mb compact` reminder: `auto` / `off` | `auto` |\n| `MB_ALLOW_METRICS_OVERRIDE` | Allow executing project-local `.memory-bank/metrics.sh` overrides | `0` |\n| `MB_PI_MODE` | Pi project adapter mode. Supported: `agents-md` (project `AGENTS.md`) or `skill` (`~/.pi/agent/skills/memory-bank`; leaves existing global symlink unchanged) | `agents-md` |\n| `MB_SKILL_BUNDLE` | Override bundle path (dev / testing) | auto-detected |\n| `MB_SKIP_DEPS_CHECK` | Skip preflight dep check in `install.sh` | `0` |\n\n---\n\n## Platform support\n\n| OS | Status |\n|----|--------|\n| macOS | ✅ Native |\n| Linux | ✅ Native |\n| Windows (Git Bash) | ✅ Via Git for Windows — install works, CLI auto-detects `bash.exe` |\n| Windows (WSL) | ✅ Full native POSIX path |\n| Windows (native PowerShell, no bash) | ⚠️ Fails with install hint |\n\n**Windows quick start:**\n\n```powershell\n# Either:\nwinget install Git.Git            # → supplies bash.exe at C:\\Program Files\\Git\\bin\\bash.exe\n# or:\nwsl --install                     # → full Linux env\npip install memory-bank-skill     # inside WSL or with Git Bash on PATH\nmemory-bank doctor                # verifies bash discovery\nmemory-bank install               # works once bash is resolvable\n```\n\n`memory-bank doctor` on Windows reports the detected bash path (or an install hint if none found).\n\n---\n\n## FAQ\n\n**Q: Do I need to commit `.memory-bank/` to git?**\nA: Recommended if working in a team — that's how state is shared. Solo project: optional. Either way works.\n\n**Q: Does this replace Claude Code's built-in memory?**\nA: No — complementary. Native memory is per-user, cross-project (preferences, style). `.memory-bank/` is per-project, team-shared (status, plans, decisions). Both load simultaneously.\n\n**Q: Will it work on private repositories?**\nA: Yes. Everything is local. No data sent anywhere unless your AI agent itself calls external APIs (that's unchanged).\n\n**Q: What if my team uses different AI agents?**\nA: That's the whole point. Install per-client: `memory-bank install --clients cursor,windsurf,claude-code`. One memory bank, everyone reads it.\n\n**Q: Cursor hooks are experimental / Codex hooks are experimental — is that a problem?**\nA: 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](docs/cross-agent-setup.md) for specifics.\n\n**Q: My existing `AGENTS.md` / `.cursor/hooks.json` — will this overwrite them?**\nA: No. Adapters use a marker pattern (`\u003c!-- memory-bank:start/end --\u003e` for MD files, `_mb_owned: true` for JSON hooks) and merge idempotently. User content is preserved; uninstall only removes MB-owned sections.\n\n**Q: How do I upgrade?**\nA: `pipx upgrade memory-bank-skill` or `brew upgrade memory-bank`. Git-clone install: `cd ~/.claude/skills/skill-memory-bank \u0026\u0026 git pull \u0026\u0026 ./install.sh`.\n\n**Q: Does reinstalling create `.pre-mb-backup.*` files every time?**\nA: 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.\n\n**Q: I want to remove everything.**\nA: `memory-bank uninstall -y` removes global install without a prompt. Per-project adapters: `adapters/\u003cclient\u003e.sh uninstall \u003cproject-dir\u003e`.\n\n**Q: Can a project-local `.memory-bank/metrics.sh` run arbitrary commands during install or doctor flows?**\nA: 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.\n\n**Q: Does Pi need a separate setup step?**\nA: `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 \u003crepo\u003e`. Existing local Pi skill directories are backed up outside `~/.pi/agent/skills/` so Pi does not discover backup copies as duplicate skills.\n\n**Q: Is this production-ready?**\nA: 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.\n\n---\n\n## Documentation\n\n**Get started** *(learning)*\n\n- **[5-minute quick start](#5-minute-quick-start)** — install → `/mb init` → `/mb start` → work → `/mb done`\n- **[Your first feature, end to end](docs/first-feature.md)** — a worked example: plan → TDD → verify → done\n- **[Install guide](docs/install.md)** — pipx / Homebrew / git-clone with troubleshooting\n- **[Overview](docs/concepts/overview.md)** — the mental model in one page\n\n**Concepts** *(understanding)*\n\n- **[Composable `/mb work` pipeline](commands/work.md)** — review off by default; `--review`/`--judge`/`--stages` + the `full` preset\n- **[Code graph \u0026 semantic search](docs/concepts/code-graph.md)** — `/mb map`, `/mb graph` (+`--questions`/`--cochange`/`--docs`), `mb-semantic-search.py`, `/mb wiki`\n- **[Cross-session memory](docs/concepts/session-memory.md)** — `/mb recall`, session hooks, the local semantic index\n- **[Rule profiles \u0026 presets](docs/rule-profiles.md)** — tune the rules to your role/stack without weakening the safety baseline\n\n**How-to** *(tasks)*\n\n- **[Cross-agent setup](docs/cross-agent-setup.md)** — per-client cheatsheet + hook capability matrix\n- **[Troubleshooting](docs/troubleshooting.md)** — common issues and fixes\n- **[v4 → v5 migration](docs/MIGRATION-v4-v5.md)** — review now off by default; composable `/mb work` pipeline\n- **[v3.0 → v3.1 migration](docs/MIGRATION-v3-v3.1.md)** · **[v1 → v2 migration](docs/MIGRATION-v1-v2.md)** — older structural upgrades\n- **[Repository migration](docs/repo-migration.md)** — for users upgrading from `claude-skill-memory-bank`\n\n**Reference**\n\n- **[Agents reference](docs/agents-reference.md)** — all 29 subagents and when each one is invoked\n- **[Release process](docs/release-process.md)** — PyPI OIDC setup + tag workflow\n- **[CHANGELOG](CHANGELOG.md)** — version history\n- **[Security policy](SECURITY.md)** — reporting, scope, design decisions\n\n---\n\n## Contributing\n\n1. Fork \u0026 clone.\n2. `./install.sh \u0026\u0026 /mb init` in the repo itself (this skill uses itself — meta but works).\n3. Write tests first (TDD). `bats tests/bats/ tests/e2e/` + `python3 -m pytest tests/pytest/`.\n4. Follow the rules in `rules/RULES.md` (the same ones the skill enforces on users).\n5. Open a PR. CI runs on Python 3.11 + 3.12 × ubuntu + macos.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Links\n\n- **Website:** https://fockus.github.io/skill-memory-bank/\n- **Repo:** https://github.com/fockus/skill-memory-bank\n- **PyPI:** https://pypi.org/project/memory-bank-skill/\n- **Homebrew tap:** https://github.com/fockus/homebrew-tap\n- **Issues:** https://github.com/fockus/skill-memory-bank/issues\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://www.star-history.com/#fockus/skill-memory-bank\u0026Date\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=fockus/skill-memory-bank\u0026type=Date\u0026theme=dark\" /\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=fockus/skill-memory-bank\u0026type=Date\" /\u003e\n    \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=fockus/skill-memory-bank\u0026type=Date\" width=\"600\" /\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n**Your agent is already smart. memory-bank-skill makes it remember.**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffockus%2Fskill-memory-bank","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffockus%2Fskill-memory-bank","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffockus%2Fskill-memory-bank/lists"}