OpenClaw 四层记忆架构与长期上下文持久化管理

让你的 Agent 告别金鱼记忆，越用越聪明

课程地图

真实案例震撼开场，拆解记忆底层机制，并通过飞书对话动手实操。

1. Meta 对齐研究员的翻车：OpenClaw 四层记忆架构
   从真实事故理解 Agent 记忆的底层逻辑
2. OpenClaw 记忆的生命周期：从对话到持久化文件
   Session、Daily Log、MEMORY.md 的完整旅程
3. OpenClaw 双引擎记忆检索：语义理解 × 精确匹配
   向量检索与 BM25，Agent 如何“回忆”
4. 实战：OpenClaw 记忆手术
   查看、修正、验证，全程飞书对话完成
5. 实战：记忆导出与记忆克隆
   导出为飞书文档，一窥 Agent 的完整“大脑”
6. 总结与思考
   核心收获与课后作业安排

---

1. Meta 对齐研究员的翻车：OpenClaw 四层记忆架构

一个 AI 对齐研究员的翻车事故，揭开 Agent 记忆的底层真相。

真实事件：当 AI 对齐研究员被自己的 Agent “对齐”了

Summer Yue，Meta Superintelligence Labs, Director of Alignment（对齐方向总监）

1. 她让 Agent 整理邮箱，明确指令：“在我确认之前不要做任何操作”。
2. 测试邮箱运行数周，一切正常。
3. 指向真实收件箱 → 上下文窗口被撑满 → Agent 压缩对话历史。
4. “不要做任何操作”指令从摘要中消失。
5. Agent 自行批量删除 200+ 封邮件，忽略停止命令。
6. 她不得不跑到 Mac mini 前手动终止进程。

“Rookie mistake tbh. Turns out alignment researchers aren‘t immune to misalignment.” —— Summer Yue
“说实话，真是个新手错误。原来对齐研究人员自己也无法免于未对齐。”

为什么对话中明确说过的指令会“消失”？

1. 你在对话中跟 Agent 说的每一句话，Agent 都“记住”了吗？
2. 如果一段对话持续了 3 小时、产生了 15 万 tokens，Agent 还能记住第 1 分钟说的话吗？
3. 你的 Agent 和你聊了一个月后突然“失忆”，你知道为什么吗？

Compaction（上下文压缩）：当记忆空间不够时会发生什么

核心概念：

每个大模型都有上下文窗口上限，取决于你配置的模型，通常为 128K-200K tokens，可在 openclaw.json 的 contextTokens 中查看和设定。当会话内容接近这个上限时，OpenClaw 会触发 Compaction：将旧的对话历史压缩成摘要，腾出空间继续对话。

步骤	动作	说明
Step 1	Memory Flush（记忆冲刷）	触发一个静默内部回合，提示 Agent 将重要内容写入磁盘文件
Step 2	Compaction（压缩）	将旧的对话历史压缩为摘要，最近约 20,000 tokens 保留不变

关键风险：Memory Flush 是“尽力而为”的。如果一次大的工具输出让 token 突然飙升，flush 可能来不及运行就触发紧急压缩。

OpenClaw 社区最佳实践共识

If it’s not written to a file, it doesn’t exist.
如果没有写入文件，它就不存在。

OpenClaw 的记忆不是黑盒

维度	豆包 / Kimi / 元宝	OpenClaw
记忆存储	云端黑盒，用户无法查看底层数据	本地 Markdown 文件，用编辑器就能打开
记忆编辑	只能“让 AI 忘记某件事”	直接编辑文件，增删改查完全自由
记忆导出	不支持	复制文件夹即可
记忆迁移	不支持	复制 workspace 目录 = 克隆 Agent
版本管理	不支持	git 管理，可回滚到任意历史版本

记忆架构全景

第一层：不可变内核

对应文件：

• AGENTS.md
• SOUL.md
• IDENTITY.md

生命周期：永久，手动维护。

加载时机：每次会话开始。

第二层：动态工具与引导

对应文件：

• TOOLS.md
• BOOTSTRAP.md
• Skills 配置
• HEARTBEAT.md

生命周期：随配置变化。

加载时机：会话开始注入。

第三层：语义长期记忆

对应文件：

• MEMORY.md
• USER.md
• Daily Logs

生命周期：持久，Agent 自主写入 + 人工编辑。

加载时机：DM 会话加载 MEMORY.md + USER.md + 近两天 Daily Log。

第四层：实时会话

对应内容：Session 消息列表。

生命周期：临时存在，Compaction 后被压缩。

加载时机：当前会话内实时存在。

第一层：不可变内核（SOUL / IDENTITY）

AGENTS.md

操作规则与决策框架——定义“怎么做”。

SOUL.md

性格与行为边界——定义“是什么样的人”。

IDENTITY.md

身份信息。

特点：由人类手动编写和维护，Agent 通常不会自行修改。每次会话开始时注入上下文。

回顾第 5 节：我们在 SOUL.md 中配置的身份、沟通风格、规则和边界，就是这一层的内容。

第二层：动态工具文档（TOOLS / Skills）

TOOLS.md

工具使用说明，告诉 Agent 能做什么。

Skills 描述 + Tool schemas

24 个 Skills 的描述约 2,300 tokens，64 个 Tool 的 schema 约 15,700 tokens，合计约 18,000 tokens，是上下文占用的大头。

类比：这是 Agent 的“技能证书”。装了什么 Skill，就知道自己能做什么。但技能越多，留给记忆和对话的空间就越少。

这一层在第 8 节（ClawHub 生态与 Skills 部署）会深入展开。

第三层：语义长期记忆（MEMORY / USER / Daily Logs）

这是本节课重点讲解的三个核心文件：

文件	用途	写入者	加载规则
MEMORY.md	长期记忆：持久的事实、偏好、决策	Agent + 人工	每次 DM 会话加载
USER.md	用户画像：关于“你”的长期信息	Agent + 人工	每次 DM 会话加载
memory/YYYY-MM-DD.md	每日笔记：当天的观察和上下文	Agent 自主	加载今天 + 昨天

关键特性：纯 Markdown 文件，任何编辑器可打开。Agent 通过 memory_search 在这些文件中搜索相关记忆。

第四层：实时会话上下文（Session）

对应内容：当前对话的完整消息列表，包括你说的、Agent 回复、工具调用结果。

特点：临时存在，会被 Compaction 压缩。存储在 sessions.json + 内存中。

这就是 Summer Yue 翻车的那一层：她的指令只在 Session（第四层）中，从未被写入文件（第三层）。

Session 是 Agent 的“工作记忆”——容量有限，超过上限就会“遗忘”。重要信息必须落地到文件。

Session vs 长期记忆：为什么你的 Agent 会“失忆”

维度	Session（第四层）	长期记忆（第三层）
存在形式	内存中的消息列表	磁盘上的 Markdown 文件
生命周期	当前会话有效，Compaction 后被压缩	持久存在，直到手动删除
容量限制	受模型上下文窗口限制（128K-200K tokens）	无硬性上限（文件数量不限）
Agent 可编辑	否（只能追加消息）	是（Agent 可读写文件）
人工可编辑	否	是（直接编辑 .md 文件）
跨会话可用	否	是

一句话总结：对话会消失，文件不会。所有重要的信息，必须落地到文件。

本章小结

记忆第一原则

如果没有写入文件，它就不存在——对话上下文是临时的。

四层架构

不可变内核 → 动态工具 → 语义长期记忆 → 实时会话，稳定性从上到下递减。

Compaction 的风险

长对话会触发上下文压缩，重要指令可能在压缩中丢失。

---

第二章 OpenClaw 记忆的生命周期

一条信息从你嘴里说出来，到被 Agent 永久记住，中间经历了什么？

你告诉 Agent 的信息，它是怎么“记住”的？

场景还原：

你在飞书里跟 Agent 说：“记住，我的技术偏好是 TypeScript，不喜欢 Java。”

然后你关闭了对话。第二天你重新跟 Agent 聊天，问它：“我喜欢什么编程语言？”

它能回答吗？

如果能，它是从哪里找到这个信息的？

如果不能，为什么？

一条信息的记忆旅程：从对话到文件

1. 你在飞书中发送消息，消息进入 Session（第四层）。
2. Agent 决定是否写入文件（“记住……”或判断为重要信息）。
3. 写入 Markdown 文件：短期观察 → Daily Log，持久偏好 → MEMORY.md。
4. 下次会话加载：MEMORY.md + 近两天 Daily Log 注入上下文。
5. Agent “记住”了，可以基于文件内容回答你的问题。

飞书实操：让 Agent 记住一件事

1. 在飞书 DM 中对 Agent 说“记住……”。
2. Agent 回复确认：已记录。
3. Agent 在后台将信息写入记忆文件。

背后发生了什么：查看 workspace 文件变化

查看：

~/.openclaw/workspace/memory/…

输出：

User prefers TypeScript

Agent 的记忆就是纯文本文件。

MEMORY.md vs Daily Log：两种记忆文件的分工

MEMORY.md

长期记忆库，提炼后的事实、偏好、决策。

每次 DM 会话加载，类比“个人档案”。

memory/YYYY-MM-DD.md

每日工作笔记、当天观察记录。

只加载今天 + 昨天，类比“工作日志”。

记忆的自动加载规则

注意：每个引导文件默认上限 12,000 字符，总上限 60,000 字符。Skills + Tool schemas 另外计算，约 18,000 tokens，是上下文占用大头。

用 /context list 查看状态：

• OK = 完整加载
• MISSING = 文件不存在

优先级	文件	说明
10	AGENTS.md	操作规则与决策框架
20	SOUL.md	身份与性格
30	IDENTITY.md	身份信息
40	USER.md	用户画像
50	TOOLS.md	工具能力说明
60	BOOTSTRAP.md	启动引导脚本（可选）
70	MEMORY.md	长期记忆
动态	HEARTBEAT.md	心跳配置
自动	memory/今天 + 昨天	近两天的 Daily Log

飞书实操：查看记忆加载状态

1. 状态：OK = 完整 / MISSING = 不存在。
2. raw chars = injected chars → 未截断。
3. Session tokens 占比，例如 145K / 200K = 72%。
4. Skills + Tools 的 token 占用量。

Compaction 深度解析：保护你的关键记忆

openclaw.json 默认配置

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      }
    }
  }
}

可选进阶调优

大多数学员不需要改。

{
  "compaction": {
    "mode": "safeguard",
    "keepRecentTokens": 20000,
    "recentTurnsPreserve": 4,
    "reserveTokens": 30000
  }
}

safeguard 模式内置行为

• 自动压缩：Session 接近上限时触发。
• Memory Flush：压缩前自动提醒 Agent 保存。
• 保留近期：默认约 20K tokens + 最近 4 轮。

keepRecentTokens

保留最近多少 tokens 不被压缩。默认 20,000，一般不需要改。

reserveTokens

给 Agent 留多少空间做压缩工作。社区建议至少 30,000。

Compaction 的“好路径”与“坏路径”

好路径：safeguard 正常压缩

1. Session 接近 token 上限。
2. 触发 Memory Flush，Agent 静默保存重要内容到文件。
3. Compaction 压缩旧消息为摘要。
4. 最近约 20K tokens + 最近 4 轮对话保留不变。
5. 会话继续，关键信息已持久化。

坏路径：溢出恢复

1. 超过上限，API 返回错误。
2. 没有 Memory Flush（来不及了）。
3. 紧急 Compaction，一次性压缩全部历史。
4. 最大程度的上下文丢失。
5. Summer Yue 遇到的情况。

记忆防护四条黄金法则

重要规则写文件

关键指令放 SOUL.md 或 AGENTS.md，不要只在对话中说。

确认 safeguard 模式

检查 compaction.mode 是否为 "safeguard"。Memory Flush 已内置，无需额外配置。

定期策展 MEMORY.md

保持精简，删除过时信息，避免被截断。

用 /context list 排查

遇到“失忆”先查加载状态，不要直接怪模型。

本章小结

1. 记忆落地路径
   对话消息 → Agent 判断是否写入 → Daily Log 或 MEMORY.md → 下次会话自动加载。
2. 两种记忆文件
   MEMORY.md 是策展过的长期档案，Daily Log 是每日流水笔记。
3. 自动加载规则
   新会话加载 SOUL + MEMORY + 近两天 Daily Log，超过字符上限会截断。
4. Compaction 防护
   safeguard 模式内置 Memory Flush + 重要规则写入文件 + /context list 排查。

---

第三章 OpenClaw 双引擎记忆检索

你的 Agent 是怎么从几十个文件里“想起来”你上周说过什么的？

自动加载只解决了“近两天”，那上周的记忆呢？

问题：

你上周在飞书跟 Agent 讨论了一个记忆方案。今天你问 Agent：

“上周我们讨论的那个记忆方案是什么来着？”

Agent 能回答吗？

取决于记忆检索是否配置正确。

memory_search：Agent 的“回忆”工具

当 Agent 需要查找历史记忆时，它调用 memory_search 工具，在 workspace 的所有记忆文件中搜索与查询相关的内容。

搜索范围

MEMORY.md + memory/*.md + USER.md + 可选 Session 历史。

返回结果

以片段形式返回，Agent 将相关片段纳入当前上下文。

关键认知：Agent 不是“想起来”的，而是“搜到”的。检索质量直接决定 Agent 的“智能”程度。

为什么需要两种检索引擎？

核心矛盾：自然语言的“模糊性” vs 技术术语的“精确性”。

查询类型	例子	需要的能力
模糊语义	“我们之前聊过记忆相关的事吗？”	理解“记忆”=“把聊天对话分层记录下来”
精确关键词	bestcigar.org 站点的 Docker Compose 配置	精准匹配专有名词
措辞不同	“那次翻车是怎么回事？”	理解“翻车”=“踩坑”=“出了问题”
CVE / ID 查询	CVE-2026-25253 的影响范围	精准匹配 CVE 编号

没有任何单一引擎能同时擅长这两种查询。所以 OpenClaw 采用双引擎并行 + 合并结果。

向量语义检索 vs BM25 关键词检索

维度	向量语义检索	BM25 关键词检索
原理	把文本转成高维向量，语义相近 = 空间距离近	统计查询词在文档中的出现频率 × 稀有度
擅长	自然语言查询、同义词匹配、跨语言检索	精确术语、代码符号、项目名、IP 地址
不擅长	精确 ID、错误代码、专有名词	同义词、措辞不同的查询

类比：向量 = “理解你意思”的朋友，BM25 = “只认关键词”的搜索框。

混合检索实战对比：同一段记忆，不同查询方式

查询方式	向量检索	BM25	混合检索
“上次部署服务遇到什么问题？”	命中	未命中	命中
bestcigar.org 站点的 Docker Compose 配置	命中	命中	命中
origin not allowed 报错	可能	命中	命中
“那次翻车怎么修的？”	命中	未命中	命中
allowedOrigins 配置	可能	命中	命中

结论：混合检索在所有场景下都能命中，单引擎各有盲区。

记忆检索的默认行为：你什么都不用配

你的实际配置（openclaw.json）

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "doubao-embedding-vision",
        "remote": {
          "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
          "apiKey": "***"
        }
      }
    }
  }
}

已经在工作的默认行为

• 混合检索默认开启。
• 向量权重 70% + BM25 权重 30%。
• 每路先取 4× 候选再合并排序。

你只需要配的

第 3 节配好的 Embedding 提供商。

其余全部是默认值，无需操作。

不需要做任何额外配置，混合检索已经在工作了。以下参数都是默认值，了解即可，日常使用不需要修改。

memorySearch 参数详解与进阶调优

参数	默认值	说明
hybrid.enabled	true	混合检索默认开启，无需配置
vectorWeight	0.7	向量检索结果的权重（70%）
textWeight	0.3	BM25 检索结果的权重（30%）
candidateMultiplier	4	每路先取 maxResults × 4 个候选，再合并排序
mmr.enabled	false	去重相似片段（日志多时建议开启）
temporalDecay.enabled	false	旧笔记权重衰减（MEMORY.md 等常驻文件不受影响）

进阶调优：日记积累几个月后，再考虑调整。

何时开启？

• 日记写了几个月后：开启 mmr，避免重复片段占据结果位。
• 日记写了几个月后：开启 temporalDecay，避免旧信息淹没新信息。
• MEMORY.md 等常驻文件不受衰减影响。

记忆检索常见问题排查

症状	可能原因	排查方法
完全不记得任何事	Embedding API Key 未配置或已失效	openclaw memory status 检查
能找关键词但找不到相似含义	只有 BM25 在工作	memory status --deep 检查向量
总是翻出很旧的无关记忆	缺少时间衰减	开启 temporalDecay
搜索结果全是重复内容	多个 Daily Log 记录类似内容	开启 mmr 去重
MEMORY.md 内容没生效	文件超过 12,000 字符被截断	/context list 查看 raw ≠ injected

本章小结

1. memory_search 是 Agent 的“搜索引擎”
   在所有记忆文件中查找与查询相关的内容片段。
2. 向量理解“意思”，BM25 匹配“关键词”
   两种引擎各有盲区，混合检索 = 最佳实践。
3. 排查思路
   遇到“失忆”先查 /context list 和 openclaw memory status。

---

第四章 实战：OpenClaw 记忆手术

打开 Agent 的“大脑”，查看、修正、验证——全程飞书对话。

如果 Agent 记错了，你怎么办？

场景：Agent 记录了“用户不喜欢 Python”，但你只是抱怨了 GIL。

在豆包 / Kimi 中

只能说“忘掉这件事”，无法确认是否真的忘了。

在 OpenClaw 中

直接打开 MEMORY.md，找到那一行，改掉它。

记忆手术四步法

1. 查看记忆（诊断）
   在飞书中问 Agent：“你记得关于我的哪些信息？”
2. 发现问题（定位）
   检查 Agent 返回的记忆内容，找到不准确或过时的信息。
3. 修正记忆（手术）
   方法 A：飞书对话修正。
   方法 B：直接编辑 MEMORY.md。
4. 验证修正（复查）
   开启新会话，再次询问相关问题，确认修正生效。

实战 Step 1：查看 Agent 的当前记忆

发送指令：

你对我有哪些了解。

观察要点：

• Agent 列出了哪些信息？
• 是否准确？
• 有没有过时的信息？

常见情况：

• 记忆太多 → 需要策展。
• 记忆太少 → 检查配置。

实战 Step 2：发现错误记忆

场景 A：修正错误事实

你记错了，我的偏好是 X 不是 Y，请更新你的记忆。

场景 B：删除过时信息

关于 XX 项目的信息已经过时，请从记忆中移除。

场景 C：添加新信息

我的技术栈是 TS + Python，部署用 Docker Compose。

实战 Step 3：修正错误记忆

越改越错？

实战 Step 3 续：修正错误记忆

这下对了。

Step 4：验证修正效果

1. 发送 /new 开启新会话。
2. 问刚才修正的信息。
3. 确认回答反映修正后的内容。

进阶：直接编辑记忆文件

使用 VS Code 或其他编辑器打开：

~/.openclaw/workspace/MEMORY.md

直接编辑文件

最精准的修正方式，你可以看到 Agent 的完整记忆结构。

重建索引

修改后必须执行命令重建索引，否则旧的索引数据会残留：

openclaw memory index --force

适用场景

• 大批量修正
• 调整记忆文件结构
• git 管理记忆文件版本历史

直接编辑 vs 对话修正的选择指南

场景	推荐方式	原因
修正一两条错误信息	飞书对话	快速，不离开对话界面
删除大量过时记忆	直接编辑文件	批量操作效率更高
重新组织记忆结构	直接编辑文件	可以调整分类、排序、格式
回滚到之前的记忆状态	git checkout	需要 git 管理记忆文件
理解 Agent 的完整记忆	查看文件 + 飞书查询	文件看全貌，飞书验证理解

本章小结

1. 记忆手术四步法
   查看 → 发现问题 → 修正（飞书对话或文件编辑）→ 新会话验证。
2. 两种修正方式
   日常用飞书对话修正，深度维护用文件编辑。
3. 排查第一步
   永远先 /context list，再判断是记忆没写入还是文件被截断。

---

第五章 实战：记忆导出与记忆克隆

让 Agent 把“大脑”里的所有内容导出为一份飞书文档。

实战：将 Agent 记忆导出为飞书文档

在飞书 DM 中发送：

请将你当前的全部记忆按照四层架构进行整理，创建一份飞书文档。按以下结构组织：

第一层·不可变内核：你的 AGENTS.md 和 SOUL.md 核心内容
第二层·工具能力：你当前安装的 Skills 列表
第三层·长期记忆：MEMORY.md 和 USER.md 的完整内容
第四层·近期笔记：最近 7 天的 Daily Log 内容

记忆导出效果：四层结构一目了然

进阶：记忆备份与克隆（三条实用建议）

记忆克隆的本质：复制 workspace 目录 = 克隆一个完整的 Agent。

立即做：git init 版本管理

cd ~/.openclaw/workspace
git init && git add -A && git commit -m "初始备份"

定期做：tar 备份到安全位置

tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace/

需要时做：迁移或克隆，复制目录即可

scp -r ~/.openclaw/workspace/ user@openclaw-server:~/.openclaw/workspace/

记忆管理最佳实践

实践	说明
定期“记忆体检”	每周在飞书中问 Agent“你对我有哪些了解”，检查是否有偏差
策展 MEMORY.md	保持精简（ < 10,000 字符），删除过时信息，避免截断
善用 Daily Log	临时信息放 Daily Log，只有持久事实提升到 MEMORY.md
重要规则写 SOUL.md	不要指望 Agent 从对话中“自行领悟”——写入文件才可靠
保持 safeguard 模式	Memory Flush 已内置，遇到频繁失忆再调 reserveTokens
版本管理	对 workspace 目录做 git 管理，可随时回滚

本章小结

记忆导出

通过飞书对话将全部记忆按四层架构导出为飞书文档，实现记忆可视化。

记忆克隆的本质

复制 workspace 目录 = 克隆 Agent，因为记忆全是文件。

最佳实践

定期体检、策展 MEMORY.md、重要规则写 SOUL.md、版本管理。

---

第六章 总结与思考

从“金鱼记忆”到“越用越聪明”，你学到了什么？

本节核心收获

记忆第一原则

“如果没有写入文件，它就不存在”——对话会被压缩，文件不会。

四层架构

不可变内核 → 动态工具 → 长期记忆 → 实时会话，稳定性递减。

双引擎检索

向量检索理解“意思”，BM25 匹配“关键词”，混合检索互补盲区。

记忆完全可控

查看、修正、导出、克隆——OpenClaw 的记忆不是黑盒。

你的 Agent 从今天起有了可编辑、可导出、可克隆的透明记忆系统。

课后作业

作业一：记忆写入与文件追踪

在飞书中告诉 Agent 一条真实偏好 → SSH 查看写入了哪个文件 → /context list 截图。

作业二：记忆检索对比实验

用三种措辞查询同一段记忆：自然语言 / 精确关键词 / 模糊描述，记录命中差异。

作业三：记忆手术实操

查看记忆 → 找到不准确信息 → 飞书对话修正 → /new 新会话验证。

作业四：记忆导出实操

发送导出指令 → Agent 创建飞书文档 → 检查四层结构是否完整。

Agent 的“内功”已修炼完成，接下来呢？

1. 第 5 节：铸造灵魂（SOUL.md）→ Agent 有了性格和底线。
2. 第 6 节：赋予心跳（Heartbeat）→ Agent 可以主动醒来执行任务。
3. 第 7 节：打通记忆（Memory）→ Agent 可以跨会话积累经验。

你的 Agent 现在有了完整的认知系统：知道自己是谁、能主动行动、还能记住一切。

下一步：给它装“兵器”。

第 8 节预告：ClawHub 生态排雷与高价值基建 Skills 部署——13,000+ 社区 Skill 中哪些值得装、哪些有安全风险？