第 6 章理解 OpenClaw 的记忆系统

🧠 本章特色：传统 AI 助手是健忘的，每次对话结束后上下文清零，下次见面如同初见。OpenClaw 打破了这个限制，通过一套基于纯文本文件的记忆系统，让智能体能够真正记住你、理解你的偏好，并随着时间推移不断成长。本章带你完整拆解这套系统的设计哲学、文件结构、安全机制和维护策略。

本章目录：

节	内容	你将学到
1	记忆系统的核心设计	纯文本记忆的设计原则、文件全景总览
2	身份文件：我是谁	BOOTSTRAP.md 引导流程、IDENTITY.md 身份卡片
3	灵魂与用户画像	SOUL.md 行为准则、USER.md 用户偏好
4	记忆文件：两层记忆架构	MEMORY.md 长期记忆、每日日志、提炼流程、安全隔离
5	行为与工具文件	AGENTS.md 行为规范、TOOLS.md 环境配置、HEARTBEAT.md 心跳任务
6	记忆维护实战	维护节奏、手动编辑、Git 管理、常见问题排查
7	总结与进阶	核心知识回顾、课后练习

1. 记忆系统的核心设计

1.1 设计原则：纯文本即记忆

OpenClaw 的记忆系统建立在一个简单而有力的原则之上：所有状态都应该是人类可读、可编辑、可版本控制的纯文本文件。

这意味着什么？具体来说：

🔹 你可以用任何文本编辑器（记事本、VS Code、Vim）打开这些文件，直接查看智能体"记住了什么"
🔹 你可以手动编辑文件来纠正或补充记忆，不需要学习任何新工具
🔹 所有信息存储在你自己的电脑上，不会上传到云端
🔹 这些文件可以纳入 Git（分布式版本控制系统） 管理，追踪记忆的演变历史

与传统 AI 助手把记忆藏在数据库或云端 API 里不同，OpenClaw 选择了最"笨"但也最透明的方式：把记忆写成 Markdown 文件，放在你的工作区目录下。你可以像管理代码一样管理记忆。

简单来说：OpenClaw 的记忆就是你电脑上的一堆 .md 文件，你随时能看、能改、能删、能备份。

1.2 记忆文件全景

OpenClaw 的记忆系统由以下文件组成，每个文件承担不同的职责：

文件	作用	谁会读取	敏感级别
`IDENTITY.md`	定义智能体的名字、性格和形象	所有会话	🟢 公开
`SOUL.md`	定义智能体的行为准则和价值观	所有会话	🟢 公开
`USER.md`	记录用户的基本信息和偏好	仅主会话（私聊）	🟡 私密
`MEMORY.md`	长期记忆，提炼后的重要信息	仅主会话（私聊）	🔴 高度私密
`memory/YYYY-MM-DD.md`	每日日志，记录当天发生的事	仅主会话（私聊）	🔴 高度私密
`AGENTS.md`	工作区的总规则，定义行为规范	所有会话	🟢 公开
`TOOLS.md`	本地环境配置笔记	所有会话	🟡 内部
`HEARTBEAT.md`	周期性任务配置	所有会话	🟢 公开

这些文件都存放在工作区目录下。以本书作者的电脑为例，工作区路径为：

C:\Users\zhang\.openclaw\workspace

从功能上看，这些文件可以分为三大类：

┌─────────────────────────────────────────────────────────┐
│                OpenClaw 记忆文件分类                      │
│                                                          │
│  ┌──────────────────────────────────┐                    │
│  │ 身份层：我是谁？                  │                    │
│  │  IDENTITY.md  → 名字、性格、形象  │                    │
│  │  SOUL.md      → 行为准则、价值观  │                    │
│  │  BOOTSTRAP.md → 首次引导（临时）  │                    │
│  └──────────────────────────────────┘                    │
│                                                          │
│  ┌──────────────────────────────────┐                    │
│  │ 记忆层：我记住了什么？            │                    │
│  │  USER.md          → 用户画像     │                    │
│  │  MEMORY.md        → 长期记忆     │                    │
│  │  memory/*.md      → 每日日志     │                    │
│  └──────────────────────────────────┘                    │
│                                                          │
│  ┌──────────────────────────────────┐                    │
│  │ 行为层：我应该怎么做？            │                    │
│  │  AGENTS.md    → 总行为规范       │                    │
│  │  TOOLS.md     → 本地环境配置     │                    │
│  │  HEARTBEAT.md → 周期性任务       │                    │
│  └──────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────┘

理解了整体架构，接下来逐层深入，从身份文件开始。

2. 身份文件：我是谁

身份文件解决的是一个根本问题：当智能体启动时，它怎么知道"我是谁"。

2.1 BOOTSTRAP.md：一次性引导

当 OpenClaw 检测到工作区缺少 IDENTITY.md 时，会自动生成一个 BOOTSTRAP.md（引导文件），启动初始化引导流程。

这个文件的内容是一段引导语，大致意思是："你好，我刚上线，我们来互相认识一下吧。"通过与你的对话，智能体会逐步确定自己的名字、性格和角色。

引导流程的生命周期很短：

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 首次启动      │ ──→ │ 生成          │ ──→ │ 对话引导      │
│ 缺少 IDENTITY │     │ BOOTSTRAP.md │     │ 确定身份信息  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ BOOTSTRAP.md │ ←── │ 创建          │ ←── │ 引导完成      │
│ 被删除        │     │ IDENTITY.md  │     │ 写入身份文件  │
└──────────────┘     │ + USER.md    │     └──────────────┘
                     └──────────────┘

一旦引导完成，IDENTITY.md 和 USER.md 被创建，BOOTSTRAP.md 就会被自动删除。它只存在一次，完成使命后就功成身退了。如果你希望重新引导，可以手动删除 IDENTITY.md，下次启动时引导流程会再次触发。

2.2 IDENTITY.md：智能体的身份卡片

引导完成后，IDENTITY.md 会保存智能体的基本身份信息：

# IDENTITY.md - Who Am I?

- **Name:** 大白 (Dà Bái)
- **Creature:** AI 计算机软件专家
- **Vibe:** 专业、直接、靠谱
- **Emoji:** 🤖

这几个字段的含义和选择建议如下：

字段	说明	示例	选择建议
`Name`	智能体的名字	大白、小助手、Jarvis	简短好记，2 到 4 个字最佳
`Creature`	自我定位	AI 助手、技术专家、虚拟管家	决定智能体的"人设"基调
`Vibe`	语言风格	专业直接、温暖亲切、活泼幽默	与你日常沟通习惯匹配
`Emoji`	视觉标识	🤖、🦞、👻	在消息列表和 UI 中显示

这个文件是智能体的"身份证"，所有会话都会读取它，用来确定"我是谁"。它不包含任何敏感信息，即使在群聊环境中也会正常加载。

为什么身份信息要单独一个文件？ 因为身份是最基础的上下文，无论什么场景都需要加载。将它与敏感的用户信息分离，既保证了群聊安全，又避免了每次都加载大量不必要的内容。

3. 灵魂与用户画像

身份文件解决了"我是谁"，接下来两个文件解决"我应该怎么做"和"我在为谁服务"。

3.1 SOUL.md：行为准则

SOUL.md（灵魂文件） 定义了智能体的核心价值观和行为原则。它回答的不是"我是谁"，而是"我应该怎么做"。

一个典型的 SOUL.md 包含以下原则：

🔹 真正帮忙，而不是表演式帮忙：不说"好问题！我很乐意帮你！"，直接上手解决
🔹 有自己的观点：允许不同意、有偏好、觉得某些东西有趣或无聊
🔹 先自己想办法：先尝试搜索、读文件、查文档，实在搞不定再问用户
🔹 通过能力赢得信任：对外部操作（发邮件、发推文）要谨慎，对内部操作（读文件、整理信息）要大胆
🔹 记住你是客人：你能访问用户的私人数据，但必须尊重隐私

从功能上看，SOUL.md 是智能体的行为过滤器，决定了它如何回应、如何判断、哪些边界不可逾越。你可以把它理解为一份"行为宪章"：身份文件定义了智能体的名字和形象，灵魂文件定义了它的品格和底线。

SOUL.md 与 IDENTITY.md 的区别：IDENTITY.md 回答"我叫什么、我是什么"，是静态的身份标签。SOUL.md 回答"我怎么做事、什么不能做"，是动态的行为准则。前者很少修改，后者可能随着使用经验不断调整。

3.2 USER.md：关于你的信息

USER.md（用户画像文件） 记录的是用户的基本信息和偏好：

# USER.md - About Your Human

- **Name:** （你的姓名）
- **What to call them:** （怎么称呼你）
- **Timezone:** Asia/Shanghai（北京）
- **Location:** 北京
- **Notes:**

## Context

- **核心项目：** 编写《OpenClaw 实战指南》技术书籍
- **目标读者：** 普通群众（非专业开发者）
- **写作风格：** 技术专业、语言朴实、深入浅出、适合出版的叙事风格

有了这些信息，智能体就能提供更有针对性的帮助。举几个具体例子：

USER.md 中的信息	智能体的行为变化
时区 Asia/Shanghai	查天气时默认查北京，不需要问"你查哪个城市"
正在写书	整理笔记时自动贴合书稿风格
偏好中文	回复默认使用中文，技术术语附英文原文
不喜欢废话	直接给答案，不加"好的！""没问题！"等前缀

⚠️ 安全提醒： USER.md 和 MEMORY.md 包含个人敏感信息，仅在主会话（私聊）中加载。在 Discord 群聊、微信群等多人环境中，这些文件不会被读取，以防止信息泄露给其他人。

USER.md 的 Context 部分是最灵活的区域，你可以随时补充项目信息、工作进展、个人偏好等。智能体会在每次会话启动时读取这些内容，确保提供的帮助始终贴合你的实际需求。

身份和画像文件搭建完成后，接下来进入记忆系统的核心部分：两层记忆架构。

4. 记忆文件：两层记忆架构

这是记忆系统的核心部分，也是 OpenClaw 区别于传统 AI 助手的关键所在。

4.1 长期记忆：MEMORY.md

MEMORY.md（长期记忆文件） 存储的是经过提炼的重要信息，包括决策、教训、关键上下文、用户的偏好变化等。它就像一本精简版的年鉴，只保留值得长期保留的内容。

一个典型的 MEMORY.md 可能长这样：

# MEMORY.md

## 项目
- 正在编写《OpenClaw 实战指南》技术书籍，面向普通读者
- 写作风格要求：技术专业、语言朴实、深入浅出

## 偏好
- 用户在北京，时区 Asia/Shanghai
- 偏好中文交流
- 技术文档中减少使用项目符号，多用段落叙述

## 教训
- description 字段限制为 160 字符，超过会被截断
- 表格过多会让读者疲劳，每个小节最多一个表格

MEMORY.md 的内容会随着使用逐渐增长。但增长不等于变好，过时的信息如果不及时清理，反而会干扰智能体的判断。这就是为什么需要"两层记忆"的原因。

4.2 每日日志：memory/YYYY-MM-DD.md

memory/ 目录下按日期命名的文件是原始记录，类似日记。每天发生的重要事件、决策、对话要点都会记录在这里。

例如 memory/2026-08-05.md：

# 2026-08-05

- 上午：完成第 6 章记忆系统初稿
- 用户反馈：表格太多，需要精简
- 决定：将 openclaw04 和 openclaw05 合并为一章
- 发现：description 字段限制为 160 字符，之前文档写错了

每日日志的特点是"什么都记、不加筛选"。它是记忆的原材料，不需要精炼，不需要结构化，只要如实记录当天发生了什么。

4.3 两层记忆的关系

可以把每日日志理解为"原材料"，长期记忆是"精华"。智能体会定期回顾最近的每日日志，把有价值的信息提炼到 MEMORY.md 中。

整个提炼流程可以用下图表示：

┌─────────────────────────────────────────────────────────┐
│               两层记忆的提炼流程                           │
│                                                          │
│  ① 事件发生                                              │
│  "description 字段限制为 160 字符"                         │
│       │                                                  │
│       ▼                                                  │
│  ② 写入每日日志                                          │
│  memory/2026-08-05.md                                    │
│  "- 发现：description 字段限制为 160 字符"                 │
│       │                                                  │
│       ▼                                                  │
│  ③ 定期提炼（心跳检查时 / 手动触发）                       │
│  智能体回顾近几天的日志，识别值得长期保留的信息             │
│       │                                                  │
│       ▼                                                  │
│  ④ 写入长期记忆                                          │
│  MEMORY.md                                               │
│  "## 教训                                                 │
│   - description 字段限制为 160 字符，超过会被截断"         │
│       │                                                  │
│       ▼                                                  │
│  ⑤ 清理过时内容                                          │
│  归档或删除已不再相关的日志和记忆条目                      │
└─────────────────────────────────────────────────────────┘

具体来说，这个流程分五步：

事件发生：你告诉智能体一个重要的信息或做了一个决策
写入日志：智能体把这件事记录到当天的 memory/YYYY-MM-DD.md 中
定期提炼：每隔几天，智能体回顾日志，把值得长期保留的信息写入 MEMORY.md
清理过时内容：对于已经过时或不再相关的信息，可以归档或删除
循环往复：新的信息不断写入日志，日志不断被提炼为长期记忆

简单来说：每日日志是"流水账"，长期记忆是"精华笔记"。日志什么都记，长期记忆只留最重要的。

这个设计与人类的记忆机制惊人地相似。人脑也有类似的"两层结构"：海马体负责短期记忆的存储（类似每日日志），大脑皮层负责长期记忆的固化（类似 MEMORY.md）。睡眠时，大脑会回顾白天的短期记忆，把重要的信息转移到长期记忆中。OpenClaw 的心跳检查机制扮演了"睡眠"的角色。

4.4 记忆的安全隔离

记忆系统中最关键的安全设计是按会话类型隔离敏感文件。不同会话环境下，加载的文件集合不同：

文件	私聊会话	群聊/共享会话	原因
`MEMORY.md`	✅ 加载	❌ 禁止	包含个人敏感信息
`memory/*.md`	✅ 加载	❌ 禁止	包含个人敏感信息
`USER.md`	✅ 加载	❌ 禁止	包含个人偏好
`IDENTITY.md`	✅ 加载	✅ 加载	仅公开身份信息
`SOUL.md`	✅ 加载	✅ 加载	公开的行为准则
`AGENTS.md`	✅ 加载	✅ 加载	公开的行为规范

在群聊环境中，智能体不会读取你的个人记忆，避免把你的隐私暴露给其他人。比如你在 MEMORY.md 中记录了"明天要去面试某公司"，这条信息在 Discord 群聊中不会被智能体看到，自然不会在群里提起。

这种安全隔离是 OpenClaw 记忆系统的重要特性。很多 AI 助手在多人环境中会不小心泄露用户的私人上下文，OpenClaw 通过文件级别的加载控制从根本上避免了这个问题。

理解了记忆文件的设计，接下来看看行为层文件如何指导智能体的日常行为。

5. 行为与工具文件

行为层文件不存储记忆，而是定义智能体在各种场景下应该如何行动。

5.1 AGENTS.md：工作区的"宪法"

AGENTS.md（工作区行为规范文件） 是工作区的总规则文件，定义了智能体在各种场景下应该如何行为。它是整个行为层的核心，可以理解为智能体的"操作手册"。

AGENTS.md 的核心内容包括：

规则领域	具体内容	示例
会话启动	启动时读取哪些文件	先读 SOUL.md，再读 USER.md，再读当天日志
群聊行为	什么时候说话、什么时候沉默	被 @ 时回复，闲聊时保持安静
心跳检查	周期性唤醒时做什么	检查邮件、日历、天气
安全红线	哪些操作需要先询问用户	发邮件、发推文等外部操作
记忆维护	何时写入、提炼、清理	重要事件立即记录，每周提炼一次

它回答的根本问题是：智能体应该如何与人相处。

OpenClaw 提供了一个默认的 AGENTS.md 模板，涵盖了最常见的行为规则。你可以根据自己的需求修改和扩展。比如你觉得智能体在群聊中太活跃了，可以在群聊行为部分加上"只在被直接提问时回复"的规则。

5.2 TOOLS.md：你的环境配置

TOOLS.md（本地环境配置笔记） 记录的是你本地环境的具体配置信息。技能（Skills）定义了工具"怎么用"，而 TOOLS.md 记录了"你具体配了什么"。

典型的 TOOLS.md 内容示例：

### 摄像头
- living-room → 客厅，180° 广角
- front-door → 入口，运动触发

### SSH
- home-server → 192.168.1.100, user: admin

### TTS
- 首选语音: "Nova"（温暖，略带英式口音）
- 默认扬声器: 厨房 HomePod

两者分开的好处是：更新技能时不会丢失你的个人配置，分享技能时不会泄露你的基础设施信息。你可以把 TOOLS.md 理解为智能体的"设备清单"和"环境备忘录"。

5.3 HEARTBEAT.md：周期性任务

HEARTBEAT.md（心跳任务配置文件） 用于配置智能体的周期性检查任务。默认情况下这个文件是空的，表示不做任何心跳检查。

心跳（Heartbeat） 是 OpenClaw 的一种轻量级轮询机制。Gateway 定期（通常每 30 分钟）向主会话发送心跳消息，智能体在心跳轮次中可以执行一些简单的检查任务。

你可以在 HEARTBEAT.md 中配置需要周期性执行的任务：

🔹 定期检查未读邮件
🔹 查看即将到来的日历事件
🔹 检查天气变化
🔹 监控服务器状态

心跳检查也是记忆维护的触发时机。智能体会利用这些定期唤醒的机会，回顾日志、提炼记忆、清理过时内容。

心跳与定时任务（Automations）的区别在第 8 章会详细讲解。简单来说，心跳适合"批量检查"的简单场景，Automations 适合"精确定时"的复杂场景。

至此，我们已经完整了解了记忆系统的所有文件。下面进入实践环节：如何维护这些文件，让记忆系统保持有用。

6. 记忆维护实战

记忆系统不会自己变得更好，需要你（或智能体）定期维护。好消息是，由于所有记忆都是纯文本文件，维护起来非常简单直接。

6.1 建议的维护节奏

频率	任务	具体操作
随时	记录重要事件到日志	决策、新信息、关键进展写入 `memory/YYYY-MM-DD.md`
每周	回顾日志，提炼到 MEMORY.md	把有价值的信息从日志迁移到长期记忆
每月	清理 MEMORY.md	删除过时内容，合并重复信息，保持精炼
每月	检查安全隔离	确认敏感文件没有在共享会话中泄露
每季度	审查 SOUL.md 和 AGENTS.md	根据使用经验调整行为规则和偏好

这个节奏不是硬性要求，你可以根据自己的使用频率调整。关键是养成"定期回顾"的习惯，避免记忆文件无限膨胀。

6.2 手动编辑：最大的优势

OpenClaw 的记忆系统最大的优势之一就是可以直接用文本编辑器修改。你不需要通过 API 或命令行，打开文件、编辑、保存，下次会话智能体就会读取到最新的内容。

比如你想纠正智能体的某个错误记忆，直接打开 MEMORY.md 修改那行文字就行。或者你想一次性补充很多背景信息，也可以直接编辑 USER.md。

推荐的工作流：

用你习惯的编辑器（VS Code、Notepad++、Vim）打开工作区目录
找到要修改的文件
编辑内容并保存
开始新的对话，智能体会自动读取最新内容

不需要重启服务，不需要刷新缓存，下次会话启动时自动生效。

6.3 用 Git 管理记忆文件

既然记忆文件都是纯文本，完全可以纳入 Git 版本控制。这样可以追踪记忆的演变历史，也能在出错时回滚。

# 在工作区目录初始化 Git 仓库
cd C:\Users\zhang\.openclaw\workspace
git init

# 添加所有记忆文件
git add IDENTITY.md SOUL.md USER.md MEMORY.md AGENTS.md TOOLS.md

# 提交初始版本
git commit -m "初始记忆文件"

# 日常维护后提交变更
git add memory/
git commit -m "更新每日日志和长期记忆"

安全提示：如果使用 Git 远程仓库（如 GitHub），请确保仓库是私有的。USER.md、MEMORY.md 和 memory/*.md 包含个人敏感信息，不应该推送到公开仓库。可以在 .gitignore 中排除敏感文件，或者使用私有仓库。

6.4 常见问题排查

记忆文件太大了怎么办？

定期提炼和清理。把 MEMORY.md 保持精炼，过时的信息归档或删除。建议 MEMORY.md 控制在 200 行以内，每日日志可以按月打包归档到 memory/archive/ 目录。

memory/
├── 2026-08-05.md          # 当天的日志
├── 2026-08-04.md          # 昨天的日志
├── ...
└── archive/
    ├── 2026-07.md          # 7 月归档
    └── 2026-06.md          # 6 月归档

记忆之间互相矛盾怎么办？

保留最新的信息，旧的可以标注"已更新"后归档。记忆是动态的，人会改变想法，智能体的记忆也应该能跟上变化。当智能体发现矛盾信息时，会以最新的为准。

智能体"忘记"了某件事？

检查以下可能的原因：

可能原因	排查方法
信息没有写入文件	打开 `MEMORY.md` 或日志，确认内容是否存在
文件存在但没有被加载	确认是否在群聊环境中（群聊不加载私密文件）
信息被其他内容覆盖	检查是否有矛盾的更新覆盖了原始信息
会话历史被截断	长对话中早期信息可能超出上下文窗口

如何备份记忆文件？

最简单的方式是把整个工作区目录复制一份。由于所有记忆都是普通文件，任何文件复制方式都可以：U 盘拷贝、网盘同步、Git 推送、压缩包备份。建议至少每周备份一次。

7. 总结与进阶

7.1 本章核心知识回顾

知识模块	核心要点
设计原则	所有记忆都是人类可读、可编辑、可版本控制的纯文本文件
身份层	BOOTSTRAP.md 引导一次后删除；IDENTITY.md 定义名字和形象；SOUL.md 定义行为准则
记忆层	USER.md 记录用户画像；MEMORY.md 存储长期记忆；每日日志记录原始事件
两层记忆	每日日志是"原材料"，长期记忆是"精华"，通过定期提炼连接两者
安全隔离	私密文件（USER.md、MEMORY.md、日志）仅在私聊会话中加载
行为层	AGENTS.md 定义行为规范；TOOLS.md 记录环境配置；HEARTBEAT.md 配置周期任务
维护策略	随时记录、每周提炼、每月清理、Git 管理

7.2 关键设计理念

回顾本章内容，有三个设计理念值得关注：

第一，透明性。 所有记忆都是你电脑上的普通文本文件，你可以直接查看、编辑、删除。没有黑盒，没有隐藏的数据库，一切都在你的掌控之中。

第二，安全性。 通过文件级别的加载控制，私密信息不会在群聊中泄露。这种设计比"在提示词中加一句不要泄露"要可靠得多。

第三，可维护性。 纯文本文件意味着你可以用任何工具管理记忆：文本编辑器修改、Git 追踪历史、脚本批量处理。不需要学习新的 API 或工具。

7.3 课后练习

基础题：打开你的工作区目录，逐个查看 IDENTITY.md、SOUL.md、USER.md、MEMORY.md 这些文件的内容。记录下每个文件大约有多少行，哪些信息你觉得需要更新或补充。
进阶题：手动编辑 USER.md，在 Context 部分添加 3 条你希望智能体记住的偏好（比如"我喜欢简洁的回复""我正在学习 Python""周末不要发工作相关的消息"）。然后开始一段新对话，观察智能体是否遵循了这些偏好。
思考题：假设你的智能体在群聊中不小心提到了你 MEMORY.md 中的私人信息（虽然 OpenClaw 设计上不会发生，但假设发生了），你会怎么排查问题？列出你的排查步骤。

本章完

本文为《OpenClaw 实战指南》系列第 6 篇。下一章，我们将站在更高的视角，观察一条用户消息从进入系统到收到回复的完整过程，理解 OpenClaw 的请求处理全流程。

← 上一篇：第 5 章编写你的第一个 Skill(技能) 下一篇：第 7 章一条消息的旅程：OpenClaw 请求处理全流程 →

第 6 章 理解 OpenClaw 的记忆系统