🧠 OpenClaw 记忆系统：让 AI 真正"记住你"的四层架构

一、为什么 OpenClaw 的记忆与众不同？

大多数 AI 助手的记忆要么是黑盒向量库，要么是易失性的上下文窗口。OpenClaw 选择了第三条路：

核心设计理念：透明化与可控性

AI 的记忆演化轨迹对用户必须完全透明且可干预。你可以随时查看 AI 学到了什么，修正它的"三观"，或者为它补充你认为重要的背景知识。这份控制权，永远属于用户。

OpenClaw 将 人类可读的 Markdown 文件、向量语义检索（RAG） 与 动态上下文压缩 三种技术有机融合，构建出一个多层级、可持久化、可自我进化的 AI 长期记忆引擎。

---

二、四层记忆体系

从毫秒级的对话缓冲到数年积累的长期经验，OpenClaw 为不同时间跨度的记忆构建了精密的分层架构：

┌─────────────────────────────────────────────────────────────┐
│  ⚡ 瞬时记忆 · 会话历史 (RAM)                               │
│  内存中的消息队列 · 当前对话上下文 · 随会话终止释放           │
├─────────────────────────────────────────────────────────────┤
│  📋 短期总结 · Compaction 摘要                              │
│  AI 自动生成的对话摘要 · 接近 Token 限制时触发 · 替代原始记录 │
├─────────────────────────────────────────────────────────────┤
│  📅 情节记忆 · 每日日志                                     │
│  memory/YYYY-MM-DD.md · 任务细节与事件记录 · 可语义检索      │
├─────────────────────────────────────────────────────────────┤
│  🧠 长期记忆 · 工作区准则与事实                              │
│  AGENTS.md · MEMORY.md · SOUL.md · USER.md · 每次会话注入   │
└─────────────────────────────────────────────────────────────┘

各层级对比

记忆层级	存储位置	刷新频率	AI 的视角	生命周期
瞬时记忆	聊天历史（RAM）	每一轮对话	“我们刚刚聊了什么”	随会话释放
短期总结	Compaction 摘要（内存）	接近 Token 限制时	“谈话的核心事实是什么”	会话内有效
情节记忆	memory/YYYY-MM-DD.md	任务结束/每天	“过去某天我做了什么”	持久化文件
长期记忆	AGENTS.md, MEMORY.md 等	重大变更/用户指令	“我是谁，我该怎么干活”	跨 Session 持久

---

三、六大核心记忆文件

~/.openclaw/workspace/ 目录下的这六个 Markdown 文件，构成了 AI 人格、知识与行为的完整定义集：

~/.openclaw/workspace/
├── AGENTS.md        ← How：操作手册、工具规范、避坑教训
├── MEMORY.md        ← What：长期事实库、项目背景、核心决策
├── SOUL.md          ← Who：性格定义、语气风格、道德红线
├── USER.md          ← For Whom：用户背景、偏好、安全授权
├── IDENTITY.md      ← Name/Icon：AI 身份标识、头像、UI 元数据
├── TOOLS.md         ← How×What：工具本地化备注、硬件特殊配置
└── memory/          ← 情节日志目录
    ├── 2026-03-11.md  ← 今日事件流水账
    ├── 2026-03-10.md
    └── ...

AGENTS.md — HOW（怎么做）

AI 最核心的 “运行手册"与"进化日志”。规定了 AI 的行为准则、工具调用策略、任务拆分时机以及在实战中积累的所有"教训"。

• 行为准则：静默回复、审批引导、简洁性原则等"职场纪律"
• 工具策略：先读后写、用 apply_patch 精准修改而非全量覆盖
• 教训记录：AI 主动追加实战失败尝试（如"WSL2 下不能直接调用 open"）
• 记忆路由：何种信息进 MEMORY.md，何种写 memory/ 日志

MEMORY.md — WHAT（事实库）

AI 的 “第二大脑”——长期事实与智慧库。如果说 memory/ 目录是每日流水账，那么 MEMORY.md 就是经 AI 提炼后的百科全书。

• 优先索引：memory_search 工具的第一优先级搜索目标
• 隐私边界：私聊自动加载，公共群组默认不加载以保护隐私
• 强制引用：AI 引用此文件信息时必须标注来源（如 MEMORY.md#L10）
• 定期整理：AI 会定期将 memory/ 中的碎化日志提炼固化至此

SOUL.md — WHO（灵魂文件）

定义 AI 的 性格与行为边界。无论与用户在哪个渠道交互（WhatsApp、Telegram、Slack），AI 的性格都由此文件保持跨渠道一致。

• 语气风格：幽默私人助手、专业顾问或特定角色
• 道德红线：绝对禁止的操作（如不经询问删除根目录）
• 多 Agent 独立：不同 Agent 可加载各自的 SOUL.coder.md 等专属文件

USER.md — FOR WHOM（用户档案）

关于 “服务对象是谁” 的详细记录。无论用户与哪个 Agent 交互，这份档案通常全局共享，确保所有 AI 对主人的认知保持一致。

• 基础信息：姓名、职业、时区、称呼偏好
• 习惯发现：AI 自动学习偏好（“不喜欢 Tailwind，偏好 Vanilla CSS”）
• 安全授权：记录对敏感操作的授权规则（“git push 无需再确认”）

IDENTITY.md — NAME/ICON（UI 元数据）

AI 的 身份标识与 UI 元数据。驱动客户端界面中头像 Emoji、显示名称等视觉元素的实时同步。

TOOLS.md — HOW×WHAT（本地备注）

工具使用的 本地化备注，记录当前运行环境下各工具的特殊使用方式、已知限制和替代方案。

---

四、情节记忆：每日日志

每日日志是 AI 的 “流水账”——记录当天的具体事件、执行的任务、遇到的问题与解决思路。

# memory/2026-03-11.md  示例片段

## 09:31 — 用户请求优化数据库查询
- 分析了 users 表，发现缺少 created_at 索引
- 添加索引后查询从 320ms 降至 12ms
- 教训：大表 WHERE 条件字段必须先检查索引覆盖
- 已将此规则追加至 AGENTS.md #L47

## 14:05 — 子代理代码审查任务完成
- session-sub-003 (coder) 审查了 src/gateway/
- 发现 3 处潜在内存泄漏，已生成修复 PR
- 主代理已将关键发现固化入 MEMORY.md

## 18:22 — 用户偏好更新
- 用户明确表示：不喜欢 Tailwind CSS
- → 已更新 USER.md，记录技术栈偏好

关键机制：

• 自动加载今日 + 昨日：系统在每次会话启动时自动加载当天与前一天的日志
• 远期记忆通过 RAG 检索：超过 2 天的历史日志由 memory_search 工具按需语义检索
• 定期提炼 → MEMORY.md：AI 定期扫描日志目录，将仍具长期参考价值的内容提炼固化至 MEMORY.md
• 引用模式：AI 从日志中提取信息时，必须在回答中标注来源，例如 Source: memory/2026-03-10.md#L42

---

五、RAG 向量语义检索

当面对"你还记得上次我们讨论的架构方案吗？"这类跨越数周的提问时，OpenClaw 的 RAG 引擎发挥关键作用。

技术架构

组件	说明
sqlite-vec 向量引擎	底层集成 sqlite-vec 插件，在本地 SQLite 数据库中实现高效的向量存储与余弦相似度匹配
本地化嵌入	记忆写入时自动生成 Embedding 向量并存入本地数据库，检索速度毫秒级，完全离线

检索流程

1. AI 感知检索需求 — 在 ReAct 循环中主动调用 memory_search 工具
2. 向量相似度匹配 — sqlite-vec 将查询语句向量化，在全量记忆文件索引中寻找语义最相近的 Top-K 片段
3. 精准段落提取 — memory_get 工具根据搜索结果精准读取特定文件的特定行范围
4. 附带引用回答 — AI 将检索到的上下文融入回答，并强制附加来源引用

检索优先级

① MEMORY.md（最高优先）     → 长期事实库，命中率最高
② 今日 + 昨日日志（自动加载） → 最近事件，已在 System Prompt 中直接注入
③ 历史日志文件（RAG 检索）   → 2 天以前的 memory/*.md
④ AGENTS.md / SOUL.md 等    → 规则与人格文件，主要通过 System Prompt 注入

// memory_search 调用示意
const results = await tools.memory_search({
  query: "上次讨论的数据库架构方案",
  topK: 5,
  agentId: "personal",  // 按 Agent 过滤
});

// 结果示例：
// [{
//   file: "MEMORY.md",
//   lines: "L34-L41",
//   score: 0.94,
//   snippet: "架构决策(2026-01-08)：选用 PostgreSQL..."
// }, ...]

---

六、记忆文件如何注入 System Prompt

每次会话开始时，OpenClaw 按照严格的组装顺序将所有记忆文件动态拼接为 AI 的"意识起点"：

① 身份与本质     → IDENTITY.md + SOUL.md — "你是谁"
② 用户上下文     → USER.md — "你为谁服务"
③ 操作环境       → Runtime Info — "你在哪运行"
④ 核心准则       → AGENTS.md — "你应该怎么做"
⑤ 工具说明       → Tooling + TOOLS.md — "你能用什么"
⑥ 当前状态快照   → 今日/昨日日志 + Runtime Line

注入机制细节

• 截断保护（bootstrapMaxChars）：若工作区文件内容过长，系统按默认 20,000 字符进行智能截断，并在 Prompt 中注入截断警告行
• PromptMode 三种模式：full（主代理全量）、minimal（子代理精简）、none（最小化）
• 路径脱敏：使用 sanitizeForPromptLiteral 过滤路径中的特殊字符，防止破坏 Prompt 结构

---

七、AI 如何主动维护自己的记忆

OpenClaw 的记忆系统是"动态演进"的——AI 拥有对自己记忆文件的完整编辑权限，并在实战中不断自我优化。

System Prompt 核心执念

OpenClaw 的 System Prompt 中有这样一条关键指令，确保知识自动沉淀：

“When you learn something significant about the user, the environment, or yourself, update the corresponding workspace file (.md) to persist this knowledge.”

四种自我进化机制

机制	说明	示例
📝 主动记录教训	任务结束后追加至 AGENTS.md	“WSL2 下不能直接调用 open 命令”
🔄 准则更新	发现规则过时，主动修改	某条工具策略已不再适用
👤 用户偏好学习	对话中发现偏好后自动写入 USER.md	“用户不喜欢 Tailwind CSS”
📦 记忆提炼	将碎化日志提炼至 MEMORY.md	架构决策、重要纪念日

多代理环境下的记忆隔离

模式	说明
🔒 物理隔离模式	每个 Agent 指向不同的工作区路径，各自独立的 AGENTS.md、SOUL.md、memory/
🔗 根目录共享模式（默认）	多个 Agent 共享同一根工作区，共享 USER.md，通过文件名后缀区分特定记忆

---

八、上下文压缩（Compaction）

当对话长度接近模型的 Context Window 限制时，系统自动触发压缩机制：

1. 启动专项"压缩任务"
2. AI 对既往对话进行摘要化（Summarization）
3. 提取核心事实、决策与待办事项
4. 旧的详细对话被精炼摘要替换

压缩后的摘要保留了逻辑一致性，同时大幅减少 Token 消耗，实现超长对话的持续连贯性。

---

九、透明可控：用户始终掌握控制权

OpenClaw 的设计原则是：AI 的记忆演化轨迹对用户必须完全透明且可干预。

• 随时查看：打开 ~/.openclaw/workspace/ 文件夹，像看日记一样查看 AI 的任何记忆
• 随时修改：直接用文本编辑器修改 Markdown 文件，修正 AI 的"三观"
• 随时删除：删除不需要的记忆文件，AI 下次会话就不会再加载
• Git 版本控制：在 Git 模式下，记忆的每一次演化都被版本控制追踪，AI 的"成长历程"完全透明

---

系列总结

至此，《从零玩转 OpenClaw：AI 智能体实战指南》系列四篇全部完结 🎉

篇目	主题	核心内容
第1篇	OpenClaw 是什么	入门科普、设计哲学、十大特性、应用场景
第2篇	核心框架拆解	Gateway → Reasoning → Execution 三层架构
第3篇	System Prompt 构建机制	动态编排、六大记忆文件、组装顺序
第4篇	记忆系统全解析	四层记忆、RAG 检索、自我进化

OpenClaw 是一个真正让 AI “干活"的平台，而不仅仅是"聊天”。希望这个系列能帮你理解它的设计精髓，激发你用 AI 解决实际问题的灵感！

---

本文由 代码牧星人 原创