PMB 实战教程：给 AI 编码 Agent 装上本地持久记忆
每次重启 Claude Code、Codex 或 Cursor 后，Agent 都会忘记上周的决策、项目的结构、你教给它的经验——这已经成为 AI 编码工作流中最令人沮丧的体验之一。PMB 正是为了解决这个问题而生：一个本地优先、零 API 密钥、零订阅的 MCP 内存服务器。
一句话概括
PMB = 一个 SQLite 文件 + 29 个 MCP 工具 + 零云端依赖。安装后，Agent 的每次对话都能访问此前所有会话中积累的知识——上周修复的 bug、项目的架构约定、你个人的编码偏好。
安装与配置
安装极其简洁：
pip install pmb-ai pmb warmup # 预热嵌入模型（~90 MB，首次调用加速） pmb setup # 检测并自动配置已安装的 Agent
pmb setup 会识别当前环境中的 Agent 并自动将 MCP 配置写入 CLAUDE.md 或 AGENTS.md。你也可以手动指定：
pmb connect claude # 配置 Claude Code pmb connect codex # 配置 Codex CLI pmb connect cursor # 配置 Cursor
多个 Agent 可以共享同一个工作区——pmb connect claude --workspace personal 和 pmb connect cursor --workspace personal 指向同一份 SQLite 文件。
为什么需要本地持久记忆？
当前的 AI 编码 Agent 有一个根本性缺陷：每次新建会话都是全新的白板。Claude Code 不知道你上周重构了哪个模块，Codex 不记得你要求它在测试中使用 pytest 而非 unittest，Cursor 不熟悉你项目的依赖注入模式。
这种”会话失忆”导致了三个具体问题：
- 重复指令：每次都要重新告诉 Agent 你的偏好和项目约定
- 上下文碎片：Agent 在不同会话中做出互相矛盾的修改
- 知识流失：上周排查出的 bug 根因，这周可能被 Agent 重新引入
传统的解决方案——在 CLAUDE.md 或 AGENTS.md 中写规则文件——只能覆盖静态约定，无法承载动态变化的项目状态（”这个模块昨天刚重构完”、”那条配置上周五被改过”）。PMB 用本地持久化的方式填补了这个空白。
核心能力：三类记忆操作
1. 读取——你不必教第二遍
PMB 的核心交互是 prepare(message)——一个 MCP 调用，返回 Agent 当前任务所需的全部上下文，耗时 4-16 毫秒：
You: 修复上周二遇到的 LoadGuard 定价 bug
Agent: 在内存中找到 12 条相关事件、4 条经验规则、
3 条决策记录、2 个未完成目标
→ 直接定位到 src/engine/verdict-policy.ts 第 142 行
对于更灵活的查询，recall(query) 提供混合搜索（BM25 + 向量 + 实体图 + 可选交叉编码器重排），35 毫秒温查询。
2. 写入——由 Agent 自动完成
Agent 在编码过程中自动调用 record_batch_async 记录决策、经验和已完成的任务。PMB 的写入路径是异步的——MCP 工具在 1 毫秒内返回，嵌入和向量存储在后端线程中完成。
3. 钩子系统——记忆不依赖 Agent 自觉性
记忆工具最难的部分不是存储，而是让 Agent 记得使用它。PMB 的四个协议级钩子解决了这个问题：
- auto-recall（自动召回）：每次用户消息都自动检索相关记忆并注入上下文。Agent 永远不需要主动决定调用
recall——PMB 在消息层面拦截、分类、检索，然后将结果注入 Agent 的上下文窗口。不需要任何模型协作。 - ambient observe（环境观察）：记录 Agent 执行的每个工具操作——编辑、测试、提交——过滤掉纯读取操作（
ls、cat），只保留有副作用的操作。这是 Stop 钩子生成记忆项的原始素材。 - session-restore（会话恢复）：上下文窗口压缩后，Agent 会忘记刚才在做什么。此钩子从会话记录中重建”你在哪里”的状态——最近的决策、已完成的工作、正在进行的目标——让 Agent 无需重新询问就能接续之前的工作。
- follow-through（执行跟踪）：在每次交互结束时，PMB 检查之前展示的经验规则是否被 Agent 实际遵循了（通过 Token 重叠检测），并标注为”已遵循”或”未验证”。这完全确定性执行，不依赖模型的自我报告。
这些钩子的效果可以通过以下命令预览：
pmb auto-context "修复 LoadGuard 定价 bug" # 预览自动召回 pmb session-restore -m 180 # 预览会话恢复 pmb lesson-followcheck --dry-run # 预览执行跟踪 pmb autowrite --dry-run # 预览环境写入
4. 可调配置（105 个参数，25 个常用）
PMB 提供 105 个可调参数，其中 25 个影响日常使用质量的参数列在默认层级：
pmb config list # 查看 25 个常用参数 pmb config list --pro # 查看全部 105 个参数（含实验性参数）
常用参数示例：recall.top_k（返回结果数量）、recall.bm25_weight（BM25 与向量混合权重）、recall.rerank（交叉编码器重排）、dedup.enable（去重层数）、agent.apply_lessons（Agent 使用经验规则）。
可视化仪表盘
pmb dashboard 启动本地 Web UI（端口 8765），包含 9 个标签页：实体图（Map）、时间线（Timeline）、概览、实体、叙事线索（Arcs）、经验规则（Lessons）、重复项合并、性能数据、召回调试。
pmb dashboard # 打开 http://127.0.0.1:8765 pmb tui # 终端交互界面 pmb stats # 快速统计数据 pmb doctor # 健康检查
高级用法
导入外部数据：PMB 可以索引 PDF、代码目录、Markdown 笔记甚至 ChatGPT 导出文件：
pmb index pdf paper.pdf # 索引 PDF pmb index project . # 扫描代码库 pmb import chatgpt ~/Downloads/export.json # 导入 ChatGPT 历史
团队协作：虽然默认使用 stdio 模式（无网络，最安全），PMB 也支持可选的 HTTP 模式（Bearer Token 认证），让多台机器上的 Agent 共享同一份记忆。
多语言支持：默认嵌入模型是 bge-m3，原生支持中文、英文、俄文等 50+ 语言。中文查询自动匹配中英文混合记忆。
实战场景：代码库重构中的记忆接力
假设你在重构一个支付模块。第一天，你让 Claude Code 重构了 PaymentService 类，并记录了关键决策：”保持 processRefund 接口签名不变，因为三方支付 SDK 依赖它”。第二天你重启 Agent 开始新会话。
没有 PMB 时：Agent 不认识这个决策，可能擅自修改了 processRefund 的签名，导致三方 SDK 调用失败。
有 PMB 时：Agent 启动后，prepare("重构支付模块") 在 6 毫秒内召回前一天的决策记录。Agent 自动遵循”保持接口不变”的规则继续重构，不需要你重复提醒。重启、模型升级、甚至切换 Agent 工具——这些事件都不会影响记忆的连续性。
性能数据
| 指标 | 数值 |
|---|---|
| 温查询 p50/p95 | 35ms / 110ms |
prepare() | 4-16ms |
| 异步写入 | < 1ms |
| MCP 冷启动 | 3.7s |
| LoCoMo recall@10 | 94.5% |
| 多语言召回 top-10 | 99.2% |
隐私与许可
PMB 默认 100% 离线运行——引擎不发起任何网络请求。零遥测，零外部服务。所有数据存储在 ~/.pmb/ 目录下，可以用 cp 随意复制或备份。Apache 2.0 许可证，可自由 fork 和修改。
如果你的 Agent 面临”每次重启都是全新对话”的困扰，PMB 用一个 SQLite 文件解决了这个问题。
GitHub: github.com/oleksiijko/pmb 安装:
pip install pmb-ai && pmb setup