Memory 系统

这一课你将能做到

1. 用 openclaw memory 管理记忆索引、搜索、重置
2. 理解 MEMORY.md 在记忆体系中的角色
3. 设计「团队约定进 MEMORY.md，个人偏好进自动记忆」的分层策略

为什么要学

没有记忆的 bot 是金鱼——每次对话都从零开始，「我们团队用 pnpm 不用 npm」说了一百遍还是会被问。Memory 系统让 bot 把重要信息沉淀下来，下次自动想起。但记忆不是越多越好：错误的记忆会误导，敏感的记忆会泄露，混乱的记忆会稀释关键信息。

人话：Memory 是 bot 的「工作笔记」，记什么、怎么记、怎么查，决定了它是越用越聪明还是越用越糊涂。

先建立图像

记忆来源
  ├── 自动提取：对话中模型判断「这值得记」→ 写入记忆存储
  ├── 手动写入：MEMORY.md（workspace 文件，团队硬性约定）
  └── 会话历史：原始对话记录（ compaction 后保留摘要）

记忆存储
  └── SQLite 数据库（~/.openclaw/ 下），带向量索引

记忆检索
  ├── 语义搜索：openclaw memory search "部署流程"
  └── 自动注入：每轮对话时相关记忆自动进入上下文

维护操作
  ├── openclaw memory index    ← 重建索引
  ├── openclaw memory search   ← 语义搜索
  ├── openclaw memory status   ← 健康检查
  ├── openclaw memory forget   ← 按来源删除
  └── openclaw memory reset    ← 清空重建

跟着做

步骤 1：检查记忆系统状态

openclaw memory status
openclaw memory status --deep --agent main

--deep 做完整健康检查，--agent 指定查看某个 agent 的记忆。

步骤 2：手动写入团队约定到 MEMORY.md

编辑 ~/.openclaw/workspace/MEMORY.md：

# 团队约定

- 包管理器：pnpm，禁止 npm/yarn
- 分支策略：main 保护，feature 分支前缀 `feat/`
- 代码评审：至少一人 approve 才能合并
- 部署时间：每周二、四下午 3 点，其他时间禁发

这些内容是「团队宪法」，应该永远被 bot 记住。

步骤 3：让 bot 自动积累记忆

正常对话即可。当模型判断某信息值得长期保存时（用户偏好、项目决策、常用命令），会自动写入记忆存储。你可以在 Control UI 的 Memory 面板查看已积累的记忆条目。

步骤 4：搜索验证

openclaw memory search "包管理器"
openclaw memory search "deploy" --max-results 5 --json

步骤 5：维护与清理

# 重建索引（记忆检索异常时）
openclaw memory index --force

# 按会话来源删除记忆
openclaw memory forget --agent main --session <session-id> --dry-run

# 完全重置（谨慎）
openclaw memory reset --agent main --yes
openclaw memory index --agent main

讲清楚要点

1. MEMORY.md 是「手动记忆」，自动记忆是「模型自选」：MEMORY.md 由人编写，内容确定、优先级最高；自动记忆由模型判断，覆盖日常细节。两者并存，不冲突。
2. 记忆检索是语义搜索，不是关键词匹配：搜「怎么发版」也能命中「部署流程」的记忆，因为底层是向量索引。这要求记忆描述本身清晰。
3. memory forget 是精确删除，memory reset 是核弹：forget 按 session、按参与者、按 hook 来源删除；reset 清空全部重建。生产环境优先 forget。
4. 记忆有 provenance（来源追踪）：每条记忆记录来自哪个会话、哪个用户，支持追溯和定向删除，合规场景必备。
5. 索引会随版本升级失效：OpenClaw 大版本更新后旧索引可能不兼容，memory status --index 检测并提示重建，memory index --force 执行。

你可能会懵的地方

• MEMORY.md 和自动记忆会重复吗？ 会，但无害。MEMORY.md 是权威来源，自动记忆是补充。如果自动记忆与 MEMORY.md 冲突，以 MEMORY.md 为准（它在 workspace 注入，优先级更高）。

• 记忆会泄露吗？ 记忆存储在本地 SQLite，不主动外发。但模型会把相关记忆注入上下文发给模型 API，所以敏感信息（密码、密钥、身份证）不应写入记忆。用 memory forget 定向清除。

• 为什么 bot 「记得」了错误信息？ 自动记忆可能记错（模型误判）。用 memory search 找到错误条目，然后用 memory forget --session <id> 删除来源会话的记忆，或 memory reset 重建。

• 多 agent 的记忆隔离吗？ 默认每个 agent 独立记忆存储。--agent <id> 参数指定操作目标。团队场景下建议每个 bot 独立记忆，避免「评审 bot 知道值班 bot 的私事」。

• compact 和 memory 什么关系？ compaction 是会话层面的上下文压缩（把旧对话摘要成要点）；memory 是跨会话的长期存储。compaction 时模型可以把「值得长期记住的要点」转存到 memory，实现从短期会话到长期记忆的沉淀。

错法对照

错法	问题	正解
把用户密码写进 MEMORY.md	密钥注入上下文，发给模型 API	只写流程性约定，密钥用环境变量
从不清理错误记忆	错误信息反复误导 bot	定期 memory search 审查，memory forget 清理
用 reset 解决一切问题	全部记忆丢失，包括有价值的	优先 forget 定向删除，reset 是最后手段
多 agent 共享记忆目录	bot 间信息串扰	每个 agent 独立记忆，独立 --agent 管理
忽略版本升级后的索引重建	记忆检索失效或报错	升级后跑 memory status --index，必要时 index --force

卡点急救

1. bot 突然「失忆」：memory status 看索引是否异常；memory index --force 重建；检查最近是否升级过 OpenClaw。
2. 搜索结果不相关：记忆描述太模糊；用更精确的查询词；或直接在对话中纠正 bot，让它更新记忆。
3. memory 命令报 agent 不存在：确认 --agent 参数值与 agents.entries 中的 id 一致；未配置多 agent 时省略 --agent 用默认。

面试常问

• OpenClaw 的记忆体系如何分层？ 三层：MEMORY.md（人工维护的权威约定，workspace 注入，优先级最高）；自动记忆（模型在对话中判断值得保存的信息，SQLite + 向量索引，语义检索）；会话历史（原始对话，经 compaction 保留摘要）。三层互补，兼顾确定性与灵活性。

• 如何保证记忆安全合规？ 写入控制：敏感信息不进 MEMORY.md，对话中避免透露密钥；存储控制：本地 SQLite，provenance 追踪来源；删除控制：memory forget 按会话/参与者/来源定向删除；审计：定期 memory search 抽查内容，合规场景配合 openclaw audit 导出记录。

• 记忆系统与 RAG 的区别？ RAG 是「检索外部文档增强生成」，面向静态知识库；OpenClaw Memory 是「对话中动态沉淀 + 人工约定 + 语义检索」，面向交互过程中产生的偏好、决策、上下文。Memory 更轻量、更贴近个人/团队工作流，RAG 更适合大规模文档问答。

自测三问

1. MEMORY.md 与自动记忆的分工与优先级关系？
2. memory forget 与 memory reset 的适用场景？
3. 为什么敏感信息不应该写入记忆系统？

小结一句话

Memory 是 bot 的工作笔记：MEMORY.md 记团队宪法，自动记忆记日常细节，语义检索让 bot 越用越聪明，provenance 让一切可追溯。

延伸

• Memory 概念
• Memory CLI 参考
• 下一课：Agents 与路由——多 agent 分工、路由规则与并行专家通道。