memory-bank

Memory Bank 技能

面向编码 Agent 的三合一技能：

1. Memory Bank — 通过 .memory-bank/ 实现项目长期记忆（status.md、checklist.md、roadmap.md、research.md、backlog.md、adr.md、progress.md、lessons.md、notes/、plans/、experiments/、reports/、codebase/）。
2. RULES — 全局工程规则：TDD、Clean Architecture（后端）、FSD（前端）、Mobile（iOS/Android UDF）、SOLID、Testing Trophy。
3. 开发工具包 — 36 个命令：/mb、/start、/done、/plan、/brief、/discuss、/groom、/sdd、/work、/drive、/team、/qa、/config、/pipeline、/profile、/rules、/commit、/pr、/review、/test、/refactor、/doc、/changelog、/catchup、/adr、/contract、/security-review、/api-contract、/db-migration、/observability、/roadmap-sync、/traceability-gen、/analyze-task、/flow、/goal、/agree。

设计约定。 Memory Bank 建立在一项不可违背的承诺之上——Agent 会记住——以及其上的一套完全可配置、节省 token 的分层机制。默认行为不会在未经明确选择的情况下改变；用户自定义设置在升级后仍会保留；高开销路径默认关闭。完整约定请参阅 references/design-principles.md。

详细信息存放在按需读取的单层参考文件中——请参阅文末的参考资料。

---

开发流程 — 编码 Agent 应遵循的阶段

Memory Bank 项目按以下顺序推进。流程深度随任务复杂度而定——除开发阶段外，简单任务可以跳过任何阶段；评审和判定为可选。

#	阶段	命令	说明
1	访谈	/mb discuss <topic>（别名 /mb askme）	深入访谈 → 形成决策，以及经过 EARS 验证的需求草案，保存到 context/<topic>.md
2	规格说明或计划	/mb sdd <topic> · /mb plan <type> <topic>	按复杂度选择：功能／多任务 → 规格三件套（specs/<topic>/requirements+design+tasks.md、可执行 ）；范围较小且明确的变更 → 计划（`plans/*.md`、）；简单修复 → 不产出文档（仍须遵守规则）
3	开发	/mb work <target>	通过实施 → 验证循环，逐项执行规格任务／计划阶段，并使用角色子 Agent（TDD、契约优先）
4	验证	/mb verify	plan-verifier 根据计划／规格说明的 DoD 审核差异；若工作遵循了计划／规格说明，则在 /mb done 之前必须执行
5	评审 （可选）	/mb work <target> --review	评审者给出结论（子 Agent 组合或外部 codex）并进行严重性门槛检查；默认关闭
6	判定 （可选）	/mb work <target> --judge	mb-judge 判定 GO / GO_WITH_BACKLOG / NO_GO，并终止评审循环
6a	QA （可选）	/mb qa run	在真实浏览器中（Playwright MCP）运行的实际环境上，逐一检查 <bank>/qa/test_cases/ 中的 md 验收场景；环境更新后、关闭前执行
7	收尾	/mb done	更新 Memory Bank：追加进展，更新清单／状态

梳理（任意阶段）。 /mb groom <topic>（也可使用 grooming）可在固定流程之外开展批判性梳理会——适用于初步想法、已有规格说明的任务，或值得重新审视的决策。与 /mb discuss 不同，其目标不是产出规格说明：Agent 会质疑必要性和方案，提出自己的解决方案，并补全遗漏；摘要保存到 context/<topic>-groom.md，确认后的决策写入 agreements.md／backlog（ADR／Ideas），会议最后提出后续步骤建议（例如 /mb sdd）。 流水线。 整个链路可以在 <bank>/pipeline.yaml 中配置为命名工作流（步骤、各角色的 model/thinking、严重性门槛、受保护路径、预算）。配置文件存在时，/mb work 会自动解析它（mb-workflow.sh）并按配置步骤执行——例如受治理的 implement → verify → review → judge → fix → done——无需逐次运行时传入标志。使用 /mb pipeline / /mb config 管理；使用 /mb config validate 验证。默认行为不会在未经选择的情况下改变：未配置流水线且未传入标志时，执行简单的 implement → verify。

命令索引 — 所有 /mb 子命令（请了解这些命令；在相关情况下向用户推荐；各子命令的详情见 commands/mb.md 或 /mb help <sub>）：

• 会话与上下文： context（默认，空参数） · start · done · update · tasks · note <topic> · index
• 需求与决策： discuss <topic>（别名 askme） · groom <topic>（别名 grooming） · sdd <topic> · openspec <import|list|status|sync> · plan <type> <topic> · idea <title> · idea-promote <I-NNN> · adr <title> · agree <sub> · goal
• 执行： work [target] · verify · config <sub> · pipeline <sub> · flow <route> · analyze-task
• 代码库智能与记忆： map [focus] · graph · wiki · research <query> · search <query> · recall <query> · recap <sid> · conflicts · consolidate · tags
• 设置与维护： init · install · profile <sub> · rules <sub> · doctor · compact · migrate-structure · import · upgrade · deps · statusline · help [sub]

除了 /mb，工具包还提供独立命令（见上文介绍中的列表）：/commit、/pr、/review、/test、/refactor、/doc、/changelog、/catchup、/contract、/security-review、/api-contract、/db-migration、/observability、/roadmap-sync、/traceability-gen。

计划层级： 阶段 → 冲刺 → 子阶段。有关规模阈值、术语以及各层级的适用场景，请参阅 references/templates.md § 计划分解。西里尔文 «Этап / Спринт / Фаза» 是旧版别名，仅允许用于 plans/done/*.md。

---

任务路由

开始前，评估任务规模——琐碎 / 小型 / 标准 / 大型 / 超大型——并据此匹配计划、测试、文档和检查： references/effort-tiers.md。用户的明确要求优先于评估结果。独立任务交由并行子 Agent 处理。计划保持粗略；仅在遇到阻碍时才拆解（ADaPT）。

工作区解析 — 与 Agent 无关的存储

Memory Bank 通过 scripts/_lib.sh::mb_resolve_path 解析当前活动知识库。优先级固定且明确：

1. 显式参数 — mb-*.sh <mb_path> 始终优先。
2. MB_PATH 环境变量覆盖 — 用于在 Shell 会话中临时重定向。
3. 本地模式 — <project>/.memory-bank/（/mb init 的默认值，团队共享，可提交到版本库）。
4. 全局模式 — 在 <agent_config>/memory-bank/registry.json 中注册。初始化时需要传入 --storage=global --agent=<name>（或设置 $MB_AGENT 环境变量）。各 Agent 的路径见 references/structure.md § 全局存储路径。
5. 旧版 .claude-workspace — 旧指针模式，见 references/structure.md § 旧版模式。
6. 回退模式 — 相对路径 .memory-bank（与现有脚本兼容）。

活动状态语义

• [MEMORY BANK: ACTIVE] — 解析器返回的是已存在的知识库（本地或已注册的全局知识库）。
• [MEMORY BANK: ABSENT] — 当前项目不存在知识库。应明确提示这一状态，并停止 Memory Bank 生命周期——不要静默初始化。
• [MEMORY BANK: INITIALIZED] — 仅在显式执行 /mb init 并成功后使用。

仅规则模式

项目可以有意不使用 Memory Bank（[MEMORY BANK: ABSENT]）。在这种情况下：

• 在用户明确运行 /mb init 之前，/mb 生命周期命令保持停用状态。
• 工程规则基线仍然适用：TDD、SOLID、Clean Architecture / FSD、DRY/KISS/YAGNI、Testing Trophy、受保护文件、禁止占位符、完成前验证。全局技能安装绝不会自动启用 Memory Bank 状态。

调用 MB Manager 或脚本时，始终传入解析后的 mb_path。

---

工具 — shell 脚本

所有脚本都位于与此 SKILL.md 同级的 scripts/ 目录中。在全局安装中，通常可通过宿主别名访问该工具包：

• Claude Code：~/.claude/skills/memory-bank/
• Codex：~/.codex/skills/memory-bank/
• Cursor：~/.cursor/skills/memory-bank/

脚本可在当前目录的 .memory-bank/ 中运行，也可通过 mb_path 参数指定路径。 在执行每条命令的同一次 shell 调用中，将 SKILL_DIR 设为所加载 SKILL.md 所在目录的绝对路径（或设为 MB_SKILLS_ROOT）；在 Codex 中，通常使用上面的技能别名路径。 绑定该路径后，使用 SKILL_DIR="${MB_SKILLS_ROOT:-${SKILL_DIR:?Set SKILL_DIR from the loaded skill path}}"。

GraphRAG-lite 检索路由

对于含糊的代码理解问题，例如“X 的逻辑在哪里？”或“查找类似实现”，默认使用 code_context。精确的结构性问题直接路由到图工具：“谁调用/导入/定义了 X？” → graph_neighbors，“反向依赖”或变更影响 → graph_impact，“哪些测试覆盖了这个文件/符号？” → graph_tests。用户明确要求“语义搜索”时，使用 search_code，因为明确的工具意图优先。

失败时放行：图缺失、图过时、语义提供程序缺失或原生扩展不可用，都不得阻塞 Agent。不要假定已安装可选依赖（tree-sitter、networkx、fastembed）：bash "$SKILL_DIR"/scripts/mb-deps-check.sh --install-hints 会打印确切的安装命令。使用 bash "$SKILL_DIR"/scripts/mb-graph.sh who-calls|impact|tests <Symbol> / search "<query>" / status 和 scripts/mb-code-context.py 作为通用 CLI 回退方案；Pi 和 OpenCode 可能提供原生工具封装，而 Claude Code、Codex 和通用 AGENTS.md Agent 可以直接调用脚本。

Agent 调用的入口（包含内部库的完整分组表见 references/scripts.md）：

• mb-context.sh [--deep] — 加载知识库上下文（状态、检查清单、活动计划、代码库摘要）
• mb-graph.sh who-calls|impact|tests <Symbol> / search "<query>" / status — 图与语义代码搜索入口
• mb-search.sh <q> [--tag t] — 在知识库中进行关键词搜索
• /mb recall <query>（hooks/mb-recall.sh）— 对会话、笔记、协议和进度进行混合语义 + 词法回溯（RRF）
• mb-plan.sh <type> <topic> / mb-plan-sync.sh <plan> — 创建包含 `` 标记的计划，并将其同步到检查清单/路线图
• mb-spec-validate.sh <topic> — 验证规格三件套（EARS、可执行的 `` 任务、REQ 覆盖情况）
• mb-workflow.sh / mb-work-resolve.sh / mb-work-plan.sh — 解析 /mb work 工作流、目标和逐项 JSON 计划
• mb-agree.sh add|question|list … — agreements.md 的唯一写入入口
• mb-coord.sh active / append — 读取/写入跨会话看板，无需加载该看板
• mb-idea.sh / mb-adr.sh — 在 backlog.md 中记录想法（I-NNN），或在 adr.md 中记录 ADR（ADR-NNN）
• mb-profile.sh — 规则配置（init、show、validate、set）
• mb-drift.sh / mb-done-gates.sh — 确定性漂移检查器；/mb done 的强制门禁

---

快速开始

# Storage modes — pick one per project:
/mb init                                      # local mode (default) — bank in repo (.memory-bank/)
/mb init --storage=local                      # explicit local mode — same as above
/mb init --storage=global --agent=claude-code # global mode — bank in ~/.claude/memory-bank/...
                                              # (personal, NOT committed to the repo)
# Rules-only mode: no /mb init at all — [MEMORY BANK: ABSENT] state;
# /mb lifecycle stays inactive; all TDD/SOLID/Clean Architecture/DRY/KISS/YAGNI rules still apply.

# Initialization flags
/mb init --full          # same as /mb init (stack auto-detect + CLAUDE.md generation)
/mb init --minimal       # only the .memory-bank/ structure

# Session flow (basic)
/mb start                # load context
# ... work, checklist.md updates as tasks complete ...
/mb verify               # verify plan alignment (if there was a plan)
/mb done                 # actualize + note + progress

# Unified SDD flow (spec-driven features)
/mb discuss <topic>      # EARS-validated requirements → context/<topic>.md
/mb sdd <topic>          # spec triple: requirements / design / tasks.md (executable)
# specs/<topic>/tasks.md is a first-class executable artifact with  markers,
# NOT a scaffold — each block is resolved by /mb work <topic> as a work item.
/mb work <topic>         # execute spec tasks one by one (reads  blocks)
/mb verify               # verify against spec + plan
/mb done                 # actualize + progress

# Personalize rules for your stack (optional):
/mb profile init --scope=project --role=backend --stack=go --architecture=microservices --delivery=contract-first
# or user-global (works even without a project Memory Bank):
/mb profile init --scope=user --role=frontend --stack=typescript

如果宿主不支持原生斜杠命令，请使用：

• commands/mb.md 作为工作流入口；
• memory-bank ... CLI 执行 install/init/doctor 流程；
• 使用此技能工具包附带的脚本和 Agent 提示词。

Agent — 子 Agent

完整名单（何时调用各个 Agent、提示词文件、compose: 局部内容）→ references/agents.md。

计划编写和 ML 结果评估由主 Agent 负责：它掌握用户上下文和决策。mb-architect 负责执行已批准计划中的架构事项。Bug、失败或不稳定的测试，以及无法解释的行为交给 mb-debugger（先找出根因，再修复）。

调用

按名称分派 Agent — Agent(subagent_type="mb-manager", description="…", prompt="action: <action>\n\n<context>")。 已安装的 Agent 定义会提供默认值；pipeline.yaml 可以请求不同的模型／effort 值。只有当宿主允许为该角色设置这些值时，才使用单次调用覆盖；否则应先渲染并重新加载匹配的角色，再进行分派，或报告不匹配情况，不要悄悄替换值。 这些命令会写入 Claude Code 格式；其他宿主使用各自的工具分派相同的已安装角色：

宿主	按名称分派	角色的安装位置
Claude Code	Agent(subagent_type=<name>, prompt=…)（较旧版本：Task）	~/.claude/agents/<name>.md
OpenCode	subagent({agent: "mb-developer", description: "Implement assigned task", prompt: "Implement the assigned task and verify its definition of done."})	.opencode/agent/<name>.md；全局选择加入：设置
Codex	spawn_agent(agent_type=<name>, message=…)；已安装的角色包含 model/effort；运行时覆盖取决于宿主支持情况	~/.codex/agents/<name>.toml
Pi	mb_dispatch_subagent(role=<name>, task=…) 或 pi-subagents subagent(agent=<name>, task=…)；thinking 会透传	~/.pi/agent/agents/<name>.md

OpenCode 的 model 参数可选。没有按名称分派功能的宿主会读取角色文件及其 compose: 局部内容，并在当前会话中直接完成工作。

---

Hooks、宿主、隐私与捕获

• Codex 原生 Hooks 包含不依赖模型的根会话记忆，以及用户信任后获取的子会话上下文；设置 MB_SESSION_CAPTURE=off 可选择退出。详情：references/codex-native-hooks.md。
• OpenCode 2 使用原生命令／Hooks，并提供可选择加入的不依赖模型的根会话捕获；运行时的模型／变体继承不会更改永久固定值。设置、捕获开关和限制：OpenCode 2。
• 生命周期 Hooks（清单及各宿主的配置）：references/hooks.md § Hooks 清单。
• 宿主专属说明（Claude Code 原生记忆、Codex、Cursor）：references/hosts.md。
• <private> 内容、自动捕获（MB_AUTO_CAPTURE）、会话日志、PreCompact 交接：references/privacy-and-capture.md。/mb done 可以自动提交知识库（MB_AUTO_COMMIT=1、scripts/mb-auto-commit.sh）。

---

跨会话协作 — .memory-bank/COORDINATION.md

当两个或更多会话在同一个工作树中并行工作时（例如两个 Agent CLI，或 Agent 与人工协作），它们通过知识库根目录中的一个仅追加写入的看板文件 COORDINATION.md 进行协作。该机制默认选择加入：第一个得知有并行会话的会话会创建该文件；没有看板文件，就没有协议开销。

• 使用 scripts/mb-coord.sh active 读取，切勿使用 cat — 看板仅追加写入，可能达到数百 KB；该命令会输出处于活动状态的 FREEZE、尚未收到 ACK 的 HANDOVER、最近 3 条记录以及汇总行。使用 mb-coord.sh append --type <T> --title <t> 写入记录。
• 完整协议（记录约定、竞态处理、信任规则、新会话的接入提示词）：references/coordination.md。

---

正在执行的协议列表 — .memory-bank/agreements.md

当前生效的已确认决策的权威登记表，与 progress.md（叙述性历史记录）和 ADR（针对难以撤销的部分所记录的理由）不同。每次变更都必须通过 scripts/mb-agree.sh（add | supersede | defer | reject | question | resolve | list | sync）进行，绝不可直接修改模型，并且会自动将受管理的内容块 (``) 同步到项目根目录的 CLAUDE.md/AGENTS.md，确保新会话无需提醒就能看到所有有效协议。

• 完整协议（什么算协议、反例、状态、ADR 路由）：references/agreements.md。命令参考：commands/agree.md。

---

参考资料

• 规则配置文件架构（维度、不可变基线、优先级、验证）：references/rules-profile.schema.md
• 设计原则（不可违背的记忆承诺 + 可配置层）：references/design-principles.md
• 元数据协议 + index.json + 8 条关键规则：references/metadata.md
• 计划分解（Phase / Sprint / Stage）、模板、偏移检查：references/templates.md
• 规划 + Plan Verifier 工作流：references/planning-and-verification.md
• 编排器控制台（运行中的轨道、待解决问题、压缩后的检查）：references/orchestrator-console.md
• 工作量等级（任务规模从琐碎……额外，并匹配计划/测试/文档/检查）：references/effort-tiers.md
• ADaPT-lite — 仅分解卡住的条目，complexity_escalation：references/adapt.md
• /mb work 参考资料（工作流模式、JSON 架构、示例、脚本、并行运行）：references/work-reference.md
• /mb work Sprint 合约、进度趋势、战略转向：references/work-loop-v2.md
• .memory-bank/ 的结构：references/structure.md
• 代码图谱指南（jq 库、graph.json 架构、智能层、语义搜索路由）：references/code-graph.md
• 工作流（会话生命周期）：references/workflow.md
• 会话记忆（跨聊天捕获、/mb recall、session-doctor）：references/session-memory.md
• 跨会话协调板（COORDINATION.md 协议）：references/coordination.md
• 协议记录列表（agreements.md 协议、状态、反例）：references/agreements.md
• 命令文件模板：references/command-template.md
• Hooks（按宿主配置 + 生命周期）：references/hooks.md
• 脚本 — 完整分类表（bank 核心、计划与规格、/mb work、图谱、会话记忆、内部库）：references/scripts.md
• Agents — 完整子 Agent 列表：references/agents.md
• mb-debugger 调试技巧（改编自 superpowers，MIT）：references/debugging/root-cause-tracing.md · references/debugging/defense-in-depth.md · references/debugging/condition-based-waiting.md
• 特定宿主说明（Claude Code、Codex、Cursor）：references/hosts.md
• 隐私与捕获（<private>、自动捕获、会话记录、PreCompact 交接）：references/privacy-and-capture.md
• Codex 原生 hooks 适配器：references/codex-native-hooks.md
• Pi 原生集成：references/pi-native-integration.md
• 适配器清单架构：references/adapter-manifest-schema.md
• 标签词汇表：references/tags-vocabulary.md
• CLAUDE.md 自动生成模板：references/claude-md-template.md
• 全局规则（安装为 ~/.claude/RULES.md）：rules/RULES.md；始终启用的核心区块：rules/CLAUDE-GLOBAL.md
• 关键规则目录（一行式代码/流程规则、默认值、锁定原则；通过 /mb rules / mb-rules.sh 选择）：rules/key-rules.json
• 各技术栈的审查者校准示例：references/rubric-examples/common.md · references/rubric-examples/backend.md · references/rubric-examples/frontend.md · references/rubric-examples/go.md · references/rubric-examples/mobile.md · references/rubric-examples/python.md · references/rubric-examples/typescript.md
• 流程路由：flow-templates/arch.md · flow-templates/bugfix.md · flow-templates/code-change.md · flow-templates/migration.md · flow-templates/research.md
• 流程模式：flow-templates/patterns/adversarial-verify.md · flow-templates/patterns/classify-and-act.md · flow-templates/patterns/fanout-synthesize.md · flow-templates/patterns/generate-filter.md · flow-templates/patterns/loop-until-done.md · flow-templates/patterns/tournament.md
• CHANGELOG：CHANGELOG.md
• 迁移 v1→v2：docs/MIGRATION-v1-v2.md
• 主要入口：
  • /mb — 如果宿主支持原生命令
  • commands/mb.md / memory-bank CLI — 如果原生命令界面不可用