unyieldingclaw-dev/personal-memory-bank

# Personal Memory Bank   为 AI 编码助手（Claude Code、Cursor）提供持久化的项目记忆。包含五个结构化文件，供您的 AI 在会话开始时读取。包括 `mb` CLI（9 个命令）、`/test-audit` 覆盖率套件、5 个代理（agent）的 `/code-review`、`/security-review` 以及受控的自动化钩子（hooks）。 ## 解决的问题 每个 AI 编码会话开始时都是空白的。您需要重新解释您的技术栈、重新描述您的模式、重新确立约束条件。这种开销会在几周和几个月内不断累积。 Memory Bank 通过在您的项目中保留一小组结构化文件来解决这个问题，您的 AI 会在每次会话开始时自动读取这些文件。 ## 功能概览 | 领域 | 您将获得什么 | |------|-------------| | 记忆系统 | 5 文件结构化上下文，权限层级，新鲜度追踪，溯源 frontmatter | | `mb` CLI | init, status, doctor, query, clean, commit, upgrade, verify-integrity, help（9 个主要命令；`mb update` 是 `mb upgrade` 的别名） | | 斜杠命令 | `/test-audit`, `/code-review`, `/security-review`, `/feature-dev`, `/health-check` | | 治理 | Pre/PostToolUse hooks, CI pipeline, task contracts, subagents | ## 安装 (Windows) **1. 克隆此仓库** ``` git clone https://github.com/unyieldingclaw-dev/personal-memory-bank cd personal-memory-bank ``` **2. 运行安装程序** ``` install.bat ``` 在资源管理器中双击它，或在终端中运行它。完成后会自动打开一个新终端。 **3. 在任何项目中，运行：** ``` mb init ``` 就是这样。启动 Claude Code 或 Cursor 会话——您的 AI 将立即获得上下文。 **Mac / Linux:** ``` chmod +x install.sh && ./install.sh ``` 然后在任何项目中运行：`mb init` ## 首次会话 在 `mb init` 之后，打开最重要的两个文件： ``` memory-bank/projectbrief.md ← what does this project do? (2-3 paragraphs) memory-bank/techContext.md ← what is your stack? ``` 填写这些内容。其他所有内容（systemPatterns、activeContext、progress）都会在您工作时自然填充。 然后运行： ``` mb status ``` 以确认 memory bank 在您开始之前是健康的。 ## 日常命令 ``` mb status Quick state check — initialized, memory, context, standards, tasks mb doctor Full 20-point diagnostic — git, templates, hooks, file sizes, version, drift detection, checksums, context ceiling mb query TAG Find all memory tagged with TAG (e.g. mb query auth) mb clean Memory bank maintenance — slim check + guided cleanup prompt mb commit Commit memory bank changes separately from feature code mb upgrade Propagate latest governance templates to this project; checks remote for newer PMB version mb help Full command list ``` ## 斜杠命令 五个命令通过 `mb init` 分发给每个新项目。另一个命令（`/health-check`）安装在 PMB 仓库本身，用于自检。 ### 测试套件 两个互补的工具共同覆盖了完整的测试质量图景： **`/test-audit`** —— *覆盖率差距诊断。* 扫描更改的文件（或使用 `--all` 扫描整个项目），自动检测您的框架（Jest, Vitest, pytest, Go, RSpec, Rust），将每个源文件映射到其预期的测试文件，并标记出： - 缺失的测试文件 `[HIGH]` - 没有断言的测试文件 `[MEDIUM]` - 缺少测试步骤的 CI 配置 `[MEDIUM]` - 缺失的框架配置 `[LOW]` **`/code-review`** —— *6–8 个 subagent 协调审查。* 始终生成五个独立的领域 subagent（安全、正确性、可维护性、测试、架构漂移），每个 subagent 只能看到 diff 及其自己的领域视角，因此发现不会相互偏见。两个条件领域在适用时会加入：性能（如果 diff 涉及紧密循环、数据库查询或 I/O）和无障碍（如果涉及 HTML/JSX/TSX/Vue/Svelte）。最终的 **Opposition subagent** 接收所有领域的发现，并必须明确回答四个结构化问题——夸大其词、覆盖漏洞、误报和跨领域风险；明确指出“不适用”被视为失败。该命令不会编辑文件、生成测试或应用修复。 综合来看：`/test-audit` 告诉您*缺失了什么*。`/code-review` 告诉您*已有的内容是否良好*。 ### 所有命令 | 命令 | 功能描述 | |---------|-------------| | `/pmb-status` | 快速状态检查 —— PMB 的 `git status`；在会话开始或开始工作前运行 | | `/test-audit` | 覆盖率差距诊断 —— 框架检测，源文件到测试文件的映射，CI 检查 | | `/code-review` | 6–8 个 subagent 审查 —— 5 个始终开启的领域（安全、正确性、可维护性、测试、架构漂移）+ 最多 2 个条件领域（性能、无障碍）+ Opposition 审计 | | `/security-review` | 扫描当前 diff 中的 9 种安全模式（密钥、注入、身份验证、加密等） | | `/feature-dev` | 运行完整的 7 阶段功能开发工作流（头脑风暴 → 规格 → 计划 → 实施 → 审查 → 提交） | | `/health-check` | 仅限 PMB：运行 `mb doctor`（20 项检查）并打印带标签的摘要 | ## 工作原理 memory bank 是位于 `memory-bank/` 中的五个 markdown 文件： | 文件 | 包含内容 | 更改频率 | |------|--------------|------------------| | `projectbrief.md` | 项目必须做什么以及绝对不能做什么 | 极少 | | `systemPatterns.md` | 架构决策和代码模式 | 当模式发生变化时 | | `techContext.md` | 技术栈、依赖项、环境 | 当技术栈发生变化时 | | `activeContext.md` | 您现在正在进行的工作 | 每次会话 | | `progress.md` | 已完成、正在进行和计划中的工作 | 完成工作后 | 您的 AI 会在每次会话开始时读取所有这五个文件。您在情况发生变化时更新它们。`mb` 实用程序可帮助您管理它们。

治理模型

Memory Bank 建立在**受控辅助**的理念之上——即 AI 在明确的、分层的约束内运行时最为有用，而不是作为自主代理。该系统在四个层面上强制执行此操作： | 层级 | 类型 | 职责 | |-------|------|----------------| | `CLAUDE.md` | 咨询性 | 行为规范、工作流模式、代码风格 | | Hooks | 确定性结构 | 针对每个命令的强制执行——对危险操作进行阻止/确认/警告 | | Reviewer / Opponent | 语义性 | 范围漂移、规范合规性、代码质量检查 | | CI | 确定性门控 | 代码库范围的恒定性（文件大小、禁止模式、密钥） | 有关完整的强制执行层架构，请参阅 [`docs/HOOKS-GUIDE.md`](docs/HOOKS-GUIDE.md)。

## 高级功能 当您需要它们时，它们就在那里——您不需要为了入门而理解它们。

权限层级和冲突解决

文件具有明确的权限级别。当指令发生冲突时，权限较高的文件优先： `projectbrief.md` (不可变) → `systemPatterns / techContext` (稳定) → `activeContext` (易变) → `progress` (累积) 您的 AI 被指示要显露冲突，而不是默默地调和它们。

新鲜度追踪和驱逐

每个 memory bank 文件都包含带有 `staleness-threshold` 和 `review-cycle` 的 frontmatter。每当您编辑文件时，PostToolUse hook 会自动更新 `last-reviewed`。 运行 `mb doctor` 以查看哪些文件已过期（检查 9 涵盖了陈旧度）。运行 `mb clean` 以获取 AI 提示词，该提示词将删除重复项并汇总所有文件中的记忆。 `mb doctor` 包含陈旧度摘要、启动上下文大小上限（WARN >15 KB, ERROR >25 KB）、语义漂移检测（检查 17）和 SHA-256 完整性校验和（检查 20）。

溯源 frontmatter

每个 memory bank 文件的 frontmatter 中都包含 `compaction_generation`、`source_type`、`confidence` 和 `lineage` 字段。当压缩深度达到 gen ≥ 2 时，`mb doctor` 检查 #8 会发出警告；如果不存在规范的源文件，则会报错。这使您能够区分由人类编写的文件和由 AI 多次汇总的文件。

启动上下文可见性

`mb doctor` 在每次运行结束时都会打印一个 Startup Context 部分： ``` Startup Context Files loaded: 6 Estimated tokens: ~4500 Largest contributors: CLAUDE.md ~2500 tokens memory-bank/systemPatterns.md ~780 tokens memory-bank/techContext.md ~420 tokens 30-day growth: +8% [OK] Stale but loaded: none [OK] ``` 这准确地向您展示了您的 AI 在会话开始时携带的 token 开销、是哪些文件导致了这些开销，以及上下文是否随时间推移而膨胀。在大小成为问题之前，使用它来决定何时需要修剪文件。

基于标签的检索

文件在其 frontmatter 中使用分层标签（`auth/session`, `infra/postgres`）。运行 `mb query auth` 以查找所有与身份验证相关的 memory bank 内容——通过标签或部分标题。

Worktree 支持

memory bank 仅存在于主 worktree 中。`mb commit` 会检测并拒绝来自 git 子 worktree 的更改，从而防止脑裂（split-brain）记忆。

CI / 治理流水线

`pmb-health` CI 工作流在每次推送和 PR 时运行，包含六个作业： | 作业 | 检查内容 | |-----|---------------| | `file-size` | memory-bank/ 的单文件行数限制；所有其他 .md 文件（警告：500，失败：800） | | `forbidden-patterns` | 凭据 grep；规范占位符标记；对 .sh 脚本执行 shellcheck | | `secret-scan` | 对完整提交历史执行 gitleaks | | `template-integrity` | `templates/.claude/settings.json` 中引用的每个 hook 脚本都存在于 `templates/scripts/` 中 | | `rules-file-integrity` | `CLAUDE.md` 和 `standards/` 中不可见的 Unicode 字符、隐藏的 HTML 注释、LLM 绕过短语 | | `sast` | 对 `scripts/` 和 `templates/scripts/` 执行 Semgrep `p/bash` 扫描 | `mb doctor` 在本地运行的相同检查也会在 CI 中强制执行，因此在合并之前就能发现偏差。

上下文交接协议

当 Claude Code 接近其上下文限制时，输入 `Handoff`。AI 会创建 `handoff.md`，其中包含正在进行的所有工作的完整摘要。启动一个新会话——AI 会读取 `handoff.md`，将其合并到 memory bank 中，并从您上次中断的地方继续。

标准分发和版本追踪

`mb init` 将 12 个治理标准文件（`standards/`）复制到每个新项目中，以便斜杠命令可以在运行时引用它们。`mb upgrade` 会检查缺失的标准文件并创建它们；如果文件已被自定义，它会显示建议的 diff 而不是直接覆盖。 每个项目都会获得一个 `.pmb-version` 文件，记录是哪个 PMB 版本初始化或最后升级了它。`mb upgrade` 会检查远程是否有更新的版本，如果有则会发出警告（非阻塞性——可离线工作）。 `mb doctor` 检查 11 和 12 会对缺失的必需标准文件和版本偏差发出警告。

Git hooks (pre-push 和 pre-commit)

PMB 会自动安装两个 git hooks——无需手动复制。 **`mb init`** 会在项目中创建 `.githooks/pre-push` 和 `.githooks/pre-commit`，并设置 `core.hooksPath = .githooks`（这是本地的 git 配置，不会被提交），因此 git 会从受版本控制的 `.githooks/` 目录解析 hooks。**`mb upgrade`** 使它们保持最新（两个 hooks 都是 `TEMPLATE_OWNED`——如果过期则会被覆盖）。 **`.githooks/pre-push`** —— 在每次 `git push` 之前运行，出错则阻止推送： - 暂存文件中未解决的合并冲突或冲突标记 - 工作树中未提交的更改 - 缺少 `.gitattributes` - push diff 中可能存在的密钥（AWS keys, API tokens, GitHub PATs）——当不存在上游跟踪引用时，通过 `git log --not --remotes` 扫描首次推送 - 超过 500 KB 的文件 - `mb validate` 结果（如果 `mb` 在 PATH 中） 失败即放行——如果脚本意外出错，则允许继续推送。 **`.githooks/pre-commit`** —— 在每次 `git commit` 之前运行： - **阻止** 暂存 `handoff.md`（`handoff.md` 是临时文件，绝对不能提交） - **警告** `.claude/settings.json` 中缺失 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 在 PM 1.1.0 之前初始化的项目在 `.git/hooks/pre-push` 处拥有旧的 shim。`mb upgrade` 会自动迁移它们：安装 `.githooks/` hooks，设置 `core.hooksPath`，并移除旧的 shim。 有关完整的参考，请参阅 `docs/HOOKS-GUIDE.md`。

## 故障排除 **`mb init` 提示找不到模板** 从 memory-bank 仓库目录再次运行 `install.bat`。 **AI 没有读取 memory bank** 检查您的项目根目录下是否有 `CLAUDE.md`。对于 Cursor，验证 `.cursor/rules/memory-bank.mdc` 是否存在。重启 IDE。 **memory bank 变得越来越大** 运行 `mb doctor` 查看哪个文件超出了其目标大小。运行 `mb clean` 获取 AI 提示词以重写并去重记忆。 **某些内容看起来已损坏** 运行 `mb doctor` 获取完整的诊断信息。 ## 许可证 MIT

标签：AI编程助手, Claude Code, Cutter, Libemu, MITM代理, 上下文管理, 代码审查, 开发辅助工具, 记忆框架, 防御加固