AI Agent 总是忘事？omp 记忆系统让它记住所有踩过的坑

TL;DR：想让 omp 记住你的踩坑记录和技术决策？只需 3 行 YAML 开启 Mnemopi 记忆系统，它会自动从历史会话中提取经验，在新会话中召回相关记忆。本文讲清楚两种记忆后端、核心机制、实战配置和常见陷阱。

第 5 次跟 agent 说「上次部署前要检查 SSL 证书」的时候，你就会想：这玩意儿就不能自己记住吗？

omp 的 session 机制已经很强大：session tree 让长任务可回溯，compaction 压缩当前分支，branch summary 跨分支带记忆。但这些都是会话内的记忆——会话结束，记忆就封存了。

记忆系统对单 agent 和多 agent 同样重要——即使你只用一个 agent，跨会话记忆也能省去大量重复沟通。

为什么需要记忆系统

omp 的 session 机制已经很强大：session tree 让长任务可回溯，compaction 压缩当前分支，branch summary 跨分支带记忆。但这些都是会话内的记忆——会话结束，记忆就封存了。

下次开新会话，agent 又得从零开始：

• 你告诉它”上次重构 auth 模块时发现 JWT 有兼容性问题”
• 它得重新读代码才能理解
• 你告诉它”部署前要检查 SSL 证书”
• 它得重新读 .env 才知道证书路径

人类有长期记忆，agent 也应该有。

两种记忆后端

omp 提供两种记忆后端，适合不同场景：

1. Local 摘要管道（默认）

这是轻量级方案。工作原理：

1. Phase 1 — 提取：对每个历史会话，用模型提取持久信号：技术决策、约束、解决的失败、重复的工作流
2. Phase 2 — 合并：把所有会话的提取合并成三个输出：
   • MEMORY.md — 长期记忆文档
   • memory_summary.md — 启动时注入的紧凑摘要
   • skills/ — 可复用的过程手册

新会话启动时，memory_summary.md 会被注入到系统提示中。agent 能看到之前学过什么，但只是参考，不是指令。

优点：简单、轻量、不需要额外依赖
缺点：基于文本摘要，检索靠关键词匹配，大规模记忆时效率低

2. Mnemopi 向量检索后端

这是重量级方案。Mnemopi 是一个基于 SQLite 的本地知识库，核心特性包括：

• 语义检索：用 embedding 模型把记忆向量化，找到真正相关的记忆
• 多策略融合：向量、图、事实、时间四种检索策略，通过 reciprocal rank fusion 提升准确率
• 自动保留：每 N 轮对话自动提取并存储当前会话的记忆
• 项目隔离：per-project scoping，不同项目的记忆互不干扰

优点：语义检索准确、支持大规模记忆、可扩展
缺点：需要配置 embedding 模型、占用更多磁盘

怎么选？

简单说：Local 够用就用 Local，不够再上 Mnemopi。

Mnemopi 核心机制

工作流程

会话开始（agent_start 事件）
    ↓
如果 autoRecall 为 true，自动召回：从 Mnemopi 检索相关记忆（前 8 条）
    ↓
注入到 <memories> 块，作为背景上下文
    ↓
agent 正常工作，记忆是背景，不是指令
    ↓
每 4 轮对话，自动保留当前会话记忆
    ↓
会话结束

记忆召回

会话开始时（agent_start 事件），如果 autoRecall 为 true，Mnemopi 会自动触发召回：

1. 取前 3 轮用户消息组成查询
2. 从配置的 bank 中检索最相关的 8 条记忆
3. 注入到系统提示的 <memories> 块

召回的记忆是背景上下文，不是指令。当前用户消息和工具输出优先级更高。

记忆保留

会话结束后，Mnemopi 会自动保留：

• 技术决策：“决定用 JWT 替代 session，因为…”
• 工作流：“部署前先检查 SSL，然后…”
• 踩坑记录：“注意：fontProviders.google() 在国内会失败”
• 约束规则：“禁止修改 dist/ 目录”

保留频率由 mnemopi.retainEveryNTurns 控制，默认每 4 轮用户对话保留一次。

项目隔离

Mnemopi 支持三种 scoping 模式：

per-project-tagged 是推荐模式：项目特定的记忆写在项目 bank，但召回时会同时搜索项目 bank 和全局 bank，去重后合并。

实战配置

最小配置（3 行搞定）

想快速体验？只需 3 行 YAML，其余用默认值：

memory:
  backend: mnemopi
mnemopi:
  scoping: per-project-tagged

这样就能开启基于向量检索的记忆系统，项目隔离，自动召回和保留。

启用 Mnemopi

在 ~/.omp/config.yml 或项目 .omp/config.yml 中：

memory:
  backend: mnemopi
mnemopi:
  scoping: per-project-tagged
  autoRecall: true
  autoRetain: true
  recallLimit: 8
  retainEveryNTurns: 4

基础配置就这些。接下来是可选的进阶配置——根据你的需求选择。

配置 Embedding 模型

Mnemopi 默认使用本地 embedding 模型：

• en：BAAI/bge-base-en-v1.5（768 维，英文优化）
• multilingual：intfloat/multilingual-e5-large（1024 维，多语言支持）

如果需要更好的多语言支持：

mnemopi:
  embeddingVariant: multilingual

如果想用远程 embedding API（比如 OpenAI）：

mnemopi:
  embeddingModel: text-embedding-3-small
  embeddingApiUrl: https://api.openai.com/v1
  embeddingApiKey: ${OPENAI_API_KEY}

安全提示：建议通过环境变量管理 API key，不要直接写在配置文件中。${OPENAI_API_KEY} 会被自动替换为环境变量的值。

Embedding 模型决定了记忆检索的语义准确性。接下来配置 LLM，它负责记忆的提取和总结。

配置 LLM

Mnemopi 用 LLM 来提取和总结记忆。三种模式：

1. smol（默认）：用 omp 配置的 smol 模型
2. remote：用 OpenAI 兼容的远程 API
3. none：禁用 LLM，只用 FTS 检索

推荐用 smol，省 token：

mnemopi:
  llmMode: smol

如果需要更高质量的总结：

mnemopi:
  llmMode: remote
  llmBaseUrl: https://api.openai.com/v1
  llmApiKey: ${OPENAI_API_KEY}
  llmModel: gpt-4.1-mini

高级配置（可选）

如果需要更精准的召回，可以开启多策略融合和增强召回：

mnemopi:
  polyphonicRecall: true  # 开启 4-voice polyphonic recall（默认关闭）
  enhancedRecall: true    # 开启分层查询缓存（默认关闭）
  noEmbeddings: false     # 是否禁用 embedding（默认 false）

注意：polyphonicRecall 和 enhancedRecall 默认关闭，需要手动开启。开启后会增加计算开销，但召回准确率会显著提升。

记忆与 Rules/Skills 的协作

记忆系统不是替代 Rules 和 Skills，而是补充它们：

实际协作中三者叠加使用：

• Rules 说”禁止 fontProviders.google()”——agent 知道底线
• Skills 说”字体配置用 fontProviders.fontsource()”——agent 知道怎么做
• Memory 说”上次配置字体时，发现 Satori 需要 ttf 格式”——agent 知道历史经验

Rules 管红线（做了就坏），Skills 管能力（没它不会），Memory 管经验（没它会重复踩坑）。三者共同构成 agent 的知识体系。

实战案例

案例一：部署经验积累

第一次部署：

你：部署博客到服务器。
agent：（从零开始）需要检查 SSL 证书、配置 rsync、验证部署...
结果：花了 20 分钟，踩了几个坑。

记忆保留后：

你：部署博客到服务器。
agent：（从记忆召回）我记得上次部署时：
1. 需要先检查 SSL 证书剩余天数
2. 用 `bash scripts/blog.sh status` 检查状态
3. 用 `bash scripts/deploy.sh` 部署
4. 部署后用 curl 验证
结果：5 分钟完成，零踩坑。

案例二：技术决策复用

第一次决策：

你：这个项目用什么数据库？
agent：（分析需求后）推荐 SQLite，因为...
你：好，用 SQLite。

记忆保留后：

你：新功能需要存储用户偏好。
agent：（从记忆召回）我记得这个项目用 SQLite 存储，决策原因是...
建议：在现有 SQLite 数据库中加 user_preferences 表。

案例三：踩坑记录

第一次踩坑：

你：为什么构建失败了？
agent：（调查后）发现 fontProviders.google() 在国内无法访问。
修复：改用 fontProviders.fontsource()。

记忆保留后：

你：配置新字体。
agent：（从记忆召回）注意：这个项目禁止使用 fontProviders.google()，
因为国内构建会失败。必须用 fontProviders.fontsource()。
（直接给出正确配置，没有踩坑）

案例四：记忆出错

记忆冲突：

你：用什么认证方案？
agent：（从记忆召回）我记得这个项目用 JWT。
你：不对，上次改用 session 了。
agent：（检查代码后）抱歉，记忆过时了。当前代码确实用 session。

解决方案： 用 /memory diagnose 检查记忆健康状态，发现冲突后用 /memory clear 清理过时记忆。记忆是启发式上下文，不是权威——当记忆与当前 repo 状态冲突时，以 repo 为准。

性能与陷阱

1. 记忆膨胀

随着时间推移，记忆会越来越多。Mnemopi 的 recallLimit 默认 8 条，但记忆库可能有几千条。

解决方案：

• 定期用 /memory clear 清理过时记忆
• 调整 mnemopi.recallLimit 控制召回数量
• 使用 per-project scoping 隔离不同项目

2. 记忆冲突

记忆可能过时或错误。比如：

• 记忆说”用 JWT”，但项目已经改用 session
• 记忆说”SSL 证书 2026-08-27 到期”，但已经续期

解决方案：

• agent 被指示：记忆是启发式上下文，不是权威
• 当记忆与当前 repo 状态冲突时，以 repo 为准
• 用 /memory diagnose 检查记忆健康状态

3. 隐私与安全

记忆可能包含敏感信息：API key、密码、内部决策。

解决方案：

• Mnemopi 在写入前会 redact 常见的 secret/token 模式
• 记忆存储在本地 SQLite，不上传
• 用 /memory clear 可以彻底删除

记忆系统的未来

当前的记忆系统已经很强大，但还有改进空间：

1. 跨项目记忆共享：让通用经验（比如”TypeScript 最佳实践”）在所有项目间共享。当前 workaround：用 global scoping 模式，但会牺牲项目隔离性。
2. 记忆衰减：旧记忆权重降低，新记忆权重升高。当前 workaround：定期用 /memory clear 清理过时记忆，手动维护记忆质量。
3. 主动学习：agent 主动识别值得记忆的模式，而不是被动保留。当前 workaround：在会话中明确告诉 agent「这个决策值得记住」，触发主动保留。
4. 记忆可视化：查看记忆库的内容、统计、演化。当前 workaround：用 /memory stats 和 /memory diagnose 查看基本统计。

记忆系统让 agent 从被动执行者变为有经验积累的协作者。Rules 管红线（做了就坏），Skills 管能力（没它不会），Memory 管经验（没它会重复踩坑）。三者共同构成 agent 的知识体系。

下一步

记忆系统解决了”记不记得”的问题，但还有一个更直接的问题：agent 怎么安全地修改代码？

下一篇讲 omp 的 approval modes——auto-edit / full-auto / ask 三种模式，以及怎么按任务选择最合适的模式。

本文是「omp 编程工具使用探讨」专栏第 7 篇。文中的配置示例来自 omp 官方文档，实战经验来自这个博客项目的实际使用。