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 不熟悉你项目的依赖注入模式。

这种”会话失忆”导致了三个具体问题：

1. 重复指令：每次都要重新告诉 Agent 你的偏好和项目约定
2. 上下文碎片：Agent 在不同会话中做出互相矛盾的修改
3. 知识流失：上周排查出的 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 工具——这些事件都不会影响记忆的连续性。

性能数据

隐私与许可

PMB 默认 100% 离线运行——引擎不发起任何网络请求。零遥测，零外部服务。所有数据存储在 ~/.pmb// 目录下，可以用 cp 随意复制或备份。Apache 2.0 许可证，可自由 fork 和修改。

如果你的 Agent 面临”每次重启都是全新对话”的困扰，PMB 用一个 SQLite 文件解决了这个问题。

GitHub: github.com/oleksiijko/pmb 安装: pip install pmb-ai && pmb setup