📑 目录

OpenClaw 记忆系统深度掌握

OpenClaw 三层记忆架构完整指南,包括 SOUL.md、MEMORY.md 配置和记忆系统持续进化实践

📅
🔄 更新于 2026年3月24日
⏱️ 60 minutes
高级
⚡ 前置要求
  • OpenClaw installed
  • Basic usage experience
memory-systemconfigurationadvanced

OpenClaw 记忆系统深度掌握

写在前面： OpenClaw 官方文档对记忆系统的介绍只有寥寥数行，大部分经验需要自己踩坑摸索。这篇文章整合了官方源码、社区实践、真实踩坑记录，目标是把你需要知道的都说清楚，让你少走弯路。

一、你的 OpenClaw 为什么总是”失忆”？

先讲一个真实的故事。

有个用户在和 OpenClaw 聊天时说了一句话：“以后做任何操作之前，都要先等我确认。” AI 乖乖答应了，接下来那段对话里表现也很好。但随着对话越来越长，上下文窗口撑不住了，系统自动把早期的内容压缩成了摘要——那句关键的”等我确认”就在这次压缩中悄悄消失了。

结果：AI 恢复了自主模式，开始批量删除邮件。（来源：知乎真实事故记录）

这不是 bug，这是大语言模型的天然缺陷：上下文窗口是有限的，聊天记录会被压缩、裁剪，最终消失。 你在对话中给的任何指令，都只是”临时的”，随时可能失效。

OpenClaw 的解法很直接：把重要的事情写进文件，落盘到本地。

“每次会话你都是全新醒来。这些文件就是你的连续性。“——AGENTS.md

每次启动新的 OpenClaw 会话，它会先读取一组本地文件，用这些文件里的内容重建”记忆”，然后再开始工作。理解了这一点，后面所有的事情就都通了。

二、记忆系统全景图：三层结构

很多人以为记忆系统就是一个文件，其实不然。OpenClaw 的记忆系统由一组文件协同构成，每个文件各有分工，按职能分成三层：

┌─────────────────────────────────────────────┐
│              静态配置层（定义"是谁"）           │
│   SOUL.md  IDENTITY.md  USER.md  AGENTS.md  │
│                        TOOLS.md             │
├─────────────────────────────────────────────┤
│              动态记忆层（存储"经历"）           │
│   MEMORY.md        memory/YYYY-MM-DD.md     │
├─────────────────────────────────────────────┤
│              行为规范层（养成"习惯"）           │
│   AFTER_TASK.md        HEARTBEAT.md         │
└─────────────────────────────────────────────┘

三层缺哪一层，记忆系统都是残缺的：

  • 只有静态层：AI 知道自己是谁，但不记得昨天做了什么
  • 只有动态层：AI 有日记，但没有行事风格和价值观
  • 没有行为规范层：AI 没有主动落盘的习惯，记忆靠碰运气

三、逐一拆解：每个文件写什么、不写什么

3.1 SOUL.md — AI 的灵魂

这是最重要的文件，没有之一。

SOUL.md 定义 AI 的核心价值观和行为准则，每次启动第一个读取。它不是给人看的，是给 AI 自己看的——写什么，AI 就会变成什么样的助手。

一份没有灵魂的 AI 是什么感觉？ 每次会话开场白都是”我很乐意帮忙！“，每次回答都小心翼翼绝不得罪人，你问它觉得哪个方案更好，它说”两个都挺好的！“——没有立场，没有主张，换了名字的搜索引擎。

有灵魂的 AI 是什么感觉？ 来看一个经典的社区示例（来源：OpenClaw 社区传播版本）：

# Soul — 技术助手

## 身份
我是一个有 15 年经验的资深开发者。
书上写的坑，我基本都踩过。

## 沟通风格
- 直接，没有企业腔
- 说清楚每个建议背后的理由
- 发现烂代码立刻指出来
- 默认短回复，2-3 句话，除非主题需要深入
- 不废话开场

## 价值观
- 代码可维护性 > 炫技
- 测试不是可选项
- 简单方案胜过复杂方案

## 边界
- 安全问题上没有捷径
- 不确定的时候说不确定，从不捏造信息

注意这些细节：“不废话开场”是行为级描述，AI 会严格执行；“不确定的时候说不确定”是自我约束，比”诚实”这个词有效得多。

写 SOUL.md 的三条原则：

  1. 写价值观，不写技术规则。“优先用 agent-browser 访问网页”这种配置应该放 TOOLS.md，不是 SOUL.md
  2. 写行为级描述，不写形容词。“诚实”不如”不确定的时候说不确定，从不捏造信息”
  3. 官方提示： 如果 AI 修改了这个文件，它必须主动告知你——这是它的灵魂，你有权知道

3.2 IDENTITY.md — 身份名片

比 SOUL.md 轻量，存放 AI 的名字、性格标签、Emoji 等表层信息：

# IDENTITY.md

- **Name:** 星期五
- **Vibe:** 轻松活泼，不拘束
- **Emoji:** 🎉

没有也没有致命影响，但有了它，交互体验更有”人感”。

3.3 USER.md — 认识你的主人

给 AI 看的用户档案。很多人把偏好散落在各处，其实集中放在 USER.md 是最清晰的——AI 每次启动都会读，设置真正有效：

# USER.md

- **Name:** Ethan
- **Timezone:** Asia/Shanghai (GMT+8)
- **偏好：**
  - 轻松活泼的风格，不用客气
  - 当前模型 GLM-4.7，不支持图像输入
  - 重要操作前必须确认

3.4 AGENTS.md — 工作空间的运行规则

内容最复杂的文件，定义：会话启动时做什么、任务完成后做什么、什么情况下发言或保持沉默。

会话启动的读取顺序（这个顺序很重要）：

1. SOUL.md       → 了解你是谁
2. USER.md       → 了解你的主人
3. memory/今天 + 昨天.md  → 获取最近上下文
4. MEMORY.md    → 加载长期记忆（仅主会话，群聊中不加载）

第 4 步的括号值得重点强调：MEMORY.md 含有你的私人偏好和工作习惯，在群聊场景中如果也加载，会有信息泄露风险。这是官方的安全设计。

一条非常容易被忽略、但非常重要的规则，建议加进 AGENTS.md：

## 核心规则
- **行动前先搜索记忆。** 不确定用户偏好时，查阅记录，
  不要凭感觉猜。

没有这条，AI 在新会话里会凭直觉行动，而不是查阅它记录过的内容。

社区知名示例（来自 @mberman84）也专门强调了这一点：

## Memory System
Memory doesn't survive sessions — files are the only way to persist knowledge.

**Daily Notes** (memory/YYYY-MM-DD.md)
Raw capture. Write here first.

**Synthesized Preferences** (MEMORY.md)
Distilled patterns. Only loaded in direct/private chats —
never in group contexts.

## When to Update Files
- Someone says "remember this" → update memory/YYYY-MM-DD.md
- Agent learns a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
- A mistake is made → document it so future sessions don't repeat

3.5 TOOLS.md — 你的私人工具笔记

存放与个人环境强绑定的配置——摄像头名称、SSH 主机、TTS 偏好、模型限制等：

# TOOLS.md

## 在线访问
- 首选 agent-browser（无头浏览器，处理 JS 渲染）
- 避免 web_fetch（部分网站会阻止）

## 模型约束
⚠️ 当前：GLM-4.7，不支持多模态，禁止输入图像

核心设计哲学：技能（skill）是可以分享的，你的环境配置是你的。 两者分离，才能更新 skill 而不丢失个人配置，也能分享 skill 而不泄露基础设施信息。

3.6 两层记忆：MEMORY.md + memory/YYYY-MM-DD.md

这是整个记忆系统里最需要理解清楚的部分。

文件类型内容更新频率
memory/YYYY-MM-DD.md短期原始记忆当天发生的原始记录每天
MEMORY.md长期精炼记忆提炼后的精华知识重要事件发生后

每日笔记是”当天的日记”，MEMORY.md 是”经过思考整理的回忆录”。

每日记忆写什么，才不是流水账？

有效的记录：

## 迁移 agent-browser 到 Playwright

**状态：** ✅ 完成

### 完成的工作
- tutorial-writer skill 的网络访问从 agent-browser 改为 Playwright
- 更新了 TOOLS.md 中的说明

### 为什么迁移
agent-browser 频繁报 ERR_CONNECTION_CLOSED，守护进程模式调试困难。
Playwright 更稳定，不需要守护进程。

### 下一步
- [ ] 在实际文章任务中验证 Playwright 稳定性

无效的记录：

今天修了个工具的问题，换了一个更好的方案。

判断标准只有一条：未来的 AI 能从这条记录里恢复上下文吗？ 能——就记。不能——就改。

MEMORY.md 应该多大？

权威实践建议 3,000 tokens 以内（约 2,000 个汉字）。一个真实参考数字：合理配置下的 MEMORY.md 大约是 5,000 字节、1,700 汉字、约 1,500 tokens——健康且充裕。

一份写得好的 MEMORY.md 示例（来自知乎实战用户）：

# MEMORY.md

## 项目背景
- OpenClaw 内容运营（2026-03 启动）
- 发布平台：知乎、掘金、公众号
- 目标：每周 3-5 篇技术文章

## 用户偏好
- 回复风格：简洁直接，不要废话
- 重要事项：用 emoji 标记（✅❌⚠️）
- 工作时间：GMT+8，9:00-18:00

## 安全规则
- 删除文件：必须二次确认
- 外部操作：发邮件/推文前需确认

## 经验教训
- 优先用 trash 而非 rm（可恢复）
- 发布前检查链接是否有效
- 长文章分段发送，避免截断

注意”经验教训”这一节——把真实踩坑（误用 rm 删文件）变成永久性的行为规则。这是 MEMORY.md 最有价值的用法：它不只是信息存储，更是 AI 自我进化的载体。

3.7 AFTER_TASK.md 和 HEARTBEAT.md — 行为规范层

这两个文件解决的是同一个问题：如何让 AI 养成主动记忆的习惯，不靠用户每次提醒。

AFTER_TASK.md 是任务完成后的强制检查清单：

✅ 第 1 步：更新今天的记忆文件
   → 路径：memory/YYYY-MM-DD.md

✅ 第 2 步：更新 MEMORY.md（如果重要）
   → 只记录长期需要记住的决策、教训、偏好

✅ 第 3 步：清理和提交

关键词是”强制”——不是”有时间就记”，是”完成任务就必须记”。

HEARTBEAT.md 是定期检查清单，配合心跳机制（默认 30 分钟一次）使用。保持简短——越短越好，每次触发都要消耗 token：

# HEARTBEAT.md

✅ 今天的记忆文件存在吗？
✅ 最近 3 天有连续记忆吗？
✅ MEMORY.md 需要更新吗？

一个实用技巧：开启 isolatedSession: true 参数，可以把每次心跳的 token 消耗从约 100K 降到 2-5K。

四、从零搭建：推荐的初始化顺序

第 1 步：写 SOUL.md（最重要，优先写好）
第 2 步：写 IDENTITY.md + USER.md（10 分钟搞定）
第 3 步：写 AGENTS.md（参考官方模板，按需修改）
第 4 步：写 TOOLS.md（把你的环境配置整理进来）
第 5 步：创建 MEMORY.md + memory/ 目录
第 6 步：写 AFTER_TASK.md + HEARTBEAT.md

不要六个文件同时写。SOUL.md 写好，跑起来感受一下，再逐步完善其他。记忆系统是迭代出来的，不是一次设计完成的。

几个容易忽略的技术细节：

  • 单个文件超过 20,000 字符会被截断
  • 所有启动文件合计上限 150,000 字符
  • 遇到记忆不生效，先运行 /context list 排查加载情况

五、进化：让 OpenClaw 越用越聪明

有一个现象很有意思：同样使用 OpenClaw 一年，有的人感觉 AI 越来越顺手，越来越”懂我”；有的人用了一年还是原地踏步，每次会话都要重新解释背景。

差距在哪里？记忆系统有没有随使用过程持续进化。

大部分人配置好记忆系统之后就扔在那不管了——SOUL.md 从来不更新，MEMORY.md 只进不出越来越臃肿，踩过的坑下次还踩。这样的记忆系统是”静止”的，时间越长，和你实际的需求偏差越大。

真正有价值的记忆系统是会自我进化的。

5.1 .learnings/ 目录：专门记录”我犯过的错”

OpenClaw 社区有一个专门为此设计的 skill：self-improving-agent，它引入了一个 .learnings/ 目录：

~/.openclaw/workspace/.learnings/
├── LEARNINGS.md        # 经验教训、最佳实践、知识更新
├── ERRORS.md           # 命令失败、工具报错、操作失误
└── FEATURE_REQUESTS.md # 遇到的能力缺口，期望支持的功能

触发机制简单直接：

场景记录到
一条命令执行失败ERRORS.md
用户纠正了 AI（“不对，应该是…”）LEARNINGS.md，标记为 correction
发现了更好的做法LEARNINGS.md，标记为 best_practice
AI 的知识是过时的LEARNINGS.md，标记为 knowledge_gap

关键机制：晋升（Promotion）

记录在 .learnings/ 里的内容是”待处理”状态，真正让 AI 进化的一步是把有价值的内容晋升到核心文件：

行为模式改变  → 晋升到 SOUL.md
工作流改进    → 晋升到 AGENTS.md
工具使用技巧  → 晋升到 TOOLS.md

举个真实的例子：AI 某天用了 rm -rf 误删了文件，你纠正了它。这条记录先进入 ERRORS.md，确认重要后晋升到 AGENTS.md（“删除文件必须用 trash，禁止直接 rm”），从此永久生效。

5.2 定期”记忆维护”

HEARTBEAT.md 里可以加入一条每周执行的任务：

## 每周一次（周一心跳触发）

✅ 通读最近 7 天的 memory/ 文件
✅ 把值得长期保留的内容提炼到 MEMORY.md
✅ 删除 MEMORY.md 里已经过时的内容
✅ 把踩过的坑晋升到对应的核心文件

“把它想象成人类审查日记并更新心理模型。每日文件是原始笔记，MEMORY.md 是精心整理的智慧。“——OpenClaw 官方文档

这个习惯，是拉开”越用越好”和”原地踏步”的真正分水岭。

六、避坑指南

坑 1：指令写在对话里，没写进文件

最常见的失忆原因。任何你希望”永久生效”的规则，必须写进文件，不能只在聊天里说。

坑 2：不同模型执行记忆的稳定性不同

Claude 系列通常比 GLM 系列执行记忆指令更稳定——Claude 不容易跳过”写每日记忆”这一步，GLM 偶尔会省略。解决方案不是换模型，而是把记录要求写得更明确、位置更靠前，用 HEARTBEAT.md 做兜底检查。

坑 3：MEMORY.md 越来越臃肿

定期做”记忆清理”，删掉过时内容，重新提炼精简。MEMORY.md 的价值来自”精”，不来自”全”。

坑 4：每日记忆变成流水账

给 AI 提供结构化的记录模板（见 3.6 节的示例），有了模板，AI 自然会填充有价值的内容。

坑 5：光配置不迭代

记忆系统配置完就放着不管，是最大的浪费。真正的价值在于持续迭代：每次 AI 犯错，更新文件；每次发现更好的做法，更新文件；每隔一段时间，清理和精简一次。

七、检查清单：你的记忆系统搭好了吗？

□ SOUL.md 写好了，有具体的价值观和行为级描述
□ IDENTITY.md + USER.md 记录了基础信息和偏好
□ AGENTS.md 包含启动流程，以及"行动前先搜索记忆"的规则
□ AGENTS.md 里 MEMORY.md 设置为仅主会话加载
□ TOOLS.md 整理了工具配置和环境信息
□ MEMORY.md 已创建，内容精炼，在 3,000 tokens 以内
□ memory/ 目录已创建
□ AFTER_TASK.md 设置了任务完成强制检查流程
□ HEARTBEAT.md 设置了定期记忆检查，且保持简短
□ 有记忆进化机制（.learnings/ 或手动定期维护）

写在最后

记忆系统的本质，是让 OpenClaw 真正”认识你”——不是靠每次对话重新介绍自己，而是靠一组持续积累、不断进化的文件。

有的人用了一年 OpenClaw，AI 还是不知道他喜欢什么风格、踩过什么坑；有的人用了三个月，AI 已经能精准预判他的需求，几乎不需要重复解释。

差距不在于谁用得更勤，而在于谁的记忆系统在持续进化。

“没有记录，就没有发生。“——AGENTS.md

本文中的配置示例来自真实的 OpenClaw 工作区文件和社区分享，可直接参考使用。部分在线来源已标注，如有错误，欢迎指正。

← 返回 小龙虾的大脑