# OpenClaw 架构到工程实践 Memory 记忆系统深度解析> **摘要**：智能体之所以智能，核心不在于 LLM，而在于记忆系统。> 我一直认为记忆才是智能体的核心，所以有必要深入了解 Openclaw 的记忆机制和原理，才能让 Openclaw 发挥强大的作用。> 本文将深入解析 OpenClaw 如何实现短 - 中 - 长期分层记忆系统、压缩/Flush 机制以及独特的"梦境系统"，让 AI 真正实现持续进化。 ---## 引言：为什么记忆系统是 AI 智能化的关键？如果 Agent 每次执行任务都像第一次一样从零开始，那它的智能将大打折扣。**记忆 (Memory)** 是连接个性化与持续进化的关键桥梁。在 OpenClaw 的设计哲学中，AI 智能的三大支柱是：**LLM + 记忆系统 + 工具**。而各智能体最大的区别，恰恰在于记忆系统的设计，而非 LLM 或工具的实现。如何设计智能体的记忆系统，直接决定了 agent 的执行质量和进化能力。---## 记忆系统的成本与收益权衡记忆系统是 Agent 智能化的核心，但也是 Token 消耗的大户：- **每一次长期记忆读取**（检索 + 注入）都伴随着 LLM 调用- **每一次写入**（总结 + 存储）同样需要推理算力因此，在工程实践中必须做好权衡：| 问题 | 解决策略 ||------|---------|| **什么值得记？** | 优先记录高价值信息：用户偏好、成功方案、失败教训 || **何时去记？** | 会话结束后异步执行，避免阻塞用户交互 || **如何控制成本？** | 配置经济模型、严格限制检索数量与注入长度 |---## 一、短 - 中 - 长期三层记忆体系OpenClaw 设计了灵活的分层记忆系统，实现不同时间跨度的知识沉淀：### 1. 短期执行态记忆**作用**：为当前正在执行的任务提供上下文- 包含本次会话的**完整对话历史**- 每一步 ReAct 循环的**思考/行动/观察**- 工具调用的**中间产物****特点**：易变、高速、任务导向存储在内存和 `~\.openclaw\agents\{agent}\sessions\*.jsonl` 文件中，随会话结束或被压缩而消失。### 2. 中期保存记忆**作用**：保存当天执行的记录或任务当会话达到一定阈值（默认 20000 tokens），将当前会话中需要长期保存的笔记写入 `memory/YYYY-MM-DD.md`；若无内容可存，回复 `NO_REPLY`。**特点**：持久、可检索的对话内容可能包含用户偏好和经验信息，需要通过"梦境系统"进一步转化为 MEMORY.md 长期保存。存储位置：`~\.openclaw\workspace\memory\YYYY-MM-DD.md`### 3. 长期持久化记忆**作用**：存储跨会话的、可供未来检索的知识和经验Agent 可以将关键的对话结论、用户偏好、成功的解决方案、失败的教训存入长期记忆。这部分记录在 MEMORY.md，还有一部分完整的历史会话记录在 RAG 中进行向量检索。**特点**：持久、可检索、知识导向当新任务开始时，Agent 会：- 加载 MEMORY.md 完整内容- 用任务关键词进行**RAG 语义搜索**- 找到相关的历史经验并注入当前上下文例如：当用户再次要求"写周报"时，Agent 能从长期记忆中记起该用户偏好的模板和数据源。存储位置：`~\.openclaw\workspace\MEMORY.md`、`~\.openclaw\memory\{agent}.sqlite`---## 二、记忆层级对比表| 记忆层级 | 文件位置 | 写入时机 | 适合内容 ||---------|---------|---------|---------|| **长期核心记忆** | `MEMORY.md` | 需持久化的内容 | 用户偏好、固定流程、禁止行为、工具路径 || **每日日志** | `memory/YYYY-MM-DD.md` | 日常记录 | 任务进展、临时结论、运行上下文 || **短期记忆** | 会话内存/sessions\*.jsonl | 自动（临时） | 当前对话草稿，关闭即清空 |---## 三、workspace 长期记忆存储的本质本质上 OpenClaw 的记忆主要来源于 **MEMORY.md**，其他临时、短期记忆都会提取高质量的记忆保存在其中。记忆流动路径：```sessions/*.jsonl → (记忆压缩 + Memory Flush) → memory/YYYY-MM-DD.md → (梦境系统：浅睡/眼动/深睡) → MEMORY.md```### 三种记忆形式的区别| 维度 | `MEMORY.md` | `memory/2026-02-14.md` | `sessions/*.jsonl` ||-----|------------|----------------------|------------------|| **类型** | 长期记忆文件 (Markdown) | 每天日志 (Markdown) | 会话记录 (JSONL) || **用途** | 人类可读的持久化知识沉淀 | 会话日记、每日日记 | 完整的会话记录 || **内容形式** | Markdown 文本笔记 | Markdown 文本笔记 | JSON 格式保存对话 || **访问方式** | 直接读取编辑 | 直接读取编辑 | 直接读写编辑 || **何时写入** | 决策、偏好和持久事实存入 | 日常笔记和运行上下文存入 | 运行上下文存入 || **设计目标** | **人类可读 - 知识管理** | 日志和会话 - 总结 | **审计追踪 - 会话完整性** |---## 四、为什么需要 MEMORY.md？这是**人类可读的长期记忆库**，核心价值包括：- ✅ 投资哲学、交易原则- ✅ 个人偏好设置- ✅ 重大决策记录- ✅ 复盘教训总结**为什么需要它？**1. Agent 重启后依然保留关键背景2. 用户可随时审查修改3. 避免过度依赖 AI 的"幻觉"---## 五、每日日志的标准格式`~/memory/YYYY-MM-DD.md` 这是**每日会话日志摘要**，标准格式应包含：```markdown# YYYY-MM-DD## 今天发生的事情- 完成的任务- 遇到的挑战## 学到的东西- 新的认知/洞见## 待办事项- 后续跟进```**核心设计理念：**- **透明度**：记忆是普通 Markdown 文件，用户可以随时查看/编辑- **可控性**：agent 必须显式写入文件才能"记住"- **低耦合**：无需额外依赖，纯文件系统操作- **版本友好**：可纳入 Git 跟踪---## 六、Session 记忆压缩与 Memory Flush 机制随着对话进行，短期记忆会迅速膨胀，很快就会触及上下文窗口的极限。为此，OpenClaw 引入了 **会话修剪 (Session Pruning)** 和 **压缩 (Compaction)** 机制。### 工作原理1. **摘要生成**：当对话历史过长时，Agent 在后台调用专门的 LLM 任务，将早期对话内容生成简洁摘要2. **滚动替换**：用摘要替换原始多轮对话记录，大幅缩减上下文长度3. **触发时机**：会话 Token 使用量接近上下文窗口上限时### 静默写入机制当会话上下文接近 20,000 tokens 软阈值时，自动触发一次静默写入：```json{ "agents": { "defaults": { "compaction": { "reserveTokensFloor": 20000, "memoryFlush": { "enabled": true, "softThresholdTokens": 4000, "systemPrompt": "会话即将压缩，请将重要信息写入持久记忆。", "prompt": "将需要长期保存的笔记写入 memory/YYYY-MM-DD.md；若无内容可存，回复 NO_REPLY。" } } } }}```**关键点：**- 通过 `NO_REPLY` 指令，完全不产生任何用户可见输出- 实现**异步执行、不阻塞交互**- 用户无感知，完全在后台运行- 关键信息已被持久化到磁盘，压缩操作正常执行---## 七、梦境系统：从日记到智慧的跃迁memory/YYYY-MM-DD.md 中的记忆也是中期的，记录每天的对话内容和总结。随着时间的推移，日记文件会越来越多，我们无法将所有日记都注入到 Prompt 中（会导致 Token 消耗过大）。OpenClaw 引入**梦境系统**（功能仍在 Beta 阶段，很少人知道），类似人的睡眠周期：| 阶段 | 频率 | 动作 ||-----|-----|-----|| **Light Sleep (浅睡)** | 每日 | 扫描每日日记 + 会话 transcript，建立/更新短期记忆追踪 || **REM Sleep (快速眼动)** | 每周五点 | 模式识别，跨天聚合分析 || **Deep Sleep (深度睡眠)** | 每天凌晨 3 点 | 六维评分晋升到 MEMORY.md |### Deep Sleep 阶段的六维评分在深度睡眠阶段，系统采用**六维晋升评分权重**，筛选出高质量记忆，长期保存在 MEMORY.md 中，实现从"数据"到"智慧"的质变。---## 八、RAG 模糊记忆系统虽然将高质量的记忆（用户习惯、经验、决策等）保存在 MEMORY.md 中，但总还有一些记忆值得记录下来，比如：曾经聊过的话题、多次聊过的主题等。这些信息也方便后续检索。OpenClaw 引入**RAG 向量存储和检索机制**，将完整的 session、每天日记保存在向量数据库中，每次 agent 启动时都会检索历史会话记录。相比 MEMORY.md 的记忆，这些比较零散，但也属于 agent 的**模糊记忆**，就像人类的记忆——有些记忆需要一些触点才会回忆起来。### 同步机制| 场景 | 动作 ||-----|-----|| **启动时** | 全量 reindex 所有记忆源 || **运行时** | chokidar 文件系统 watcher 监听变更 || **增量同步** | session 文件变化时触发增量更新 || **工具调用后** | sessions_send/sessions_yield 等执行后同步 |### 向量数据库结构```sql-- 数据库文件：~/.openclaw/memory/{agent}.sqliteVECTOR_TABLE = "chunks_vec" -- 向量表 (SQLite vec0 扩展)FTS_TABLE = "chunks_fts" -- BM25 全文索引CACHE_TABLE = "embedding_cache" -- 嵌入缓存表```支持向量相似度权重和 BM25 关键词权重混合检索。### 数据来源| 数据源 | 路径 | 说明 ||-------|-----|-----|| 每日日记 | `workspaces/{agent}/memory/*.md` | 切片后向量化 || 会话历史 | `agents/{agent}/sessions/*.jsonl` | 片段级向量化 |---## 九、记忆加载顺序与优先级那么，OpenClaw 的记忆是如何被加载的呢？我们来看看 **Prompt 的构建过程**：```Core Identify Files → Core Memory → Tool Definitions → RAG Retrieval → Session Context```### 完整的 System Prompt 构建流程```┌─────────────────────────────────────────────────────────────┐│ System Prompt 构建 │├─────────────────────────────────────────────────────────────┤│ ││ 【Bootstrap Files - 按优先级排序】 (单文件≤20K, 总计≤150K) ││ 优先级越小越优先：agents(10) → soul(20) → identity(30)... ││ ││ Step 1: Core Identity Files ││ ├─ AGENTS.md [P0-10] (操作规则和指令) ││ ├─ SOUL.md [P1-20] (人格特质和语气) ││ ├─ IDENTITY.md [P2-30] (Agent 名称和定位) ││ ├─ USER.md [P3-40] (用户信息和偏好) ││ ├─ TOOLS.md [P4-50] (工具使用笔记) ││ └─ BOOTSTRAP.md[P5-60] (标记 bootstrap 完成状态) ││ ││ Step 2: Core Memory ││ ├─ MEMORY.md [P6-70] (长期记忆精华，每次自动加载) ││ └─ HEARTBEAT.md(仅默认 agent+ 启用 heartbeat 时加载) ││ ││ Step 3: Tool Definitions ││ ├─ skills metadata ││ └─ tools schema (read/write/exec/...) ││ ││ Step 4: RAG Retrieval (lazy load) ││ ├─ memory_search query (按需触发) ││ ├─ SQLite index.db: vector_similarity + BM25 ││ └─ top-k snippets 注入 context ││ ││ Step 5: Session Context ││ ├─ current session transcript ││ └─ tool call results ││ ││ ↓ LLM Generation ││ │└─────────────────────────────────────────────────────────────┘```### 优先级说明当然，Prompt 长度是有限制的，所以按优先级依次加载：1. **Core Identify** 是最重要的，记录的信息要尽量简单，不宜过复杂、冗余。（必选）2. **Core Memory** 记录的是长期的高质量经验教训、决策、高频的话题等。该文件需要定期人工检视，甚至清理。（必选）3. **RAG 检索** 是动态获取的，并不一定需要执行。---## 十、相关配置详解### 1. memory-core 插件配置用于梦境系统和向量化检索：```json"entries": { "memory-core": { "enabled": true, "config": { "dreaming": { "enabled": true, "frequency": "0 3 * * *", "phases": { "light": { "enabled": true }, "rem": { "enabled": true }, "deep": { "enabled": true, "limit": 10, "minScore": 0.8, "recencyHalfLifeDays": 14 } } } } }}```### 2. RAG 检索、session flush 和压缩配置```json"agents": { "defaults": { "compaction": { "mode": "safeguard", "reserveTokensFloor": 20000, "memoryFlush": { "enabled": true, "softThresholdTokens": 4000, "prompt": "将需要长期保存的笔记写入 memory/YYYY-MM-DD.md；若无内容可存，回复 NO_REPLY。", "systemPrompt": "会话即将压缩，请将重要信息写入持久记忆。" } }, "memorySearch": { "enabled": true, "sources": ["memory", "sessions"], "chunking": { "tokens": 400, "overlap": 80 }, "query": { "maxResults": 6, "minScore": 0.6, "hybrid": { "enabled": true } } } }}```---## 总结：记忆系统是 AI 进化的基石OpenClaw 的记忆系统设计体现了以下核心理念：### 1. 分层设计- 短期：快速响应，任务连续- 中期：日常积累，可追溯- 长期：智慧沉淀，持续进化### 2. 自动压缩- 会话修剪：控制上下文长度- 静默写入：不阻塞用户交互- 梦境系统：从数据到智慧的质变### 3. RAG 增强- 向量检索：模糊记忆激活- 混合查询：语义 + 关键词- 增量同步：实时更新### 4. 人机协同- 人类可读：Markdown 格式- 可审查修改：透明可控- 版本友好：Git 可跟踪**记忆不是存储，而是进化**。OpenClaw 通过这套优雅的记忆系统，实现了从"一次性聊天机器人"到"持续进化的数字员工"的跃迁。---**喜欢本文？欢迎转发分享！** 关注获取更多 OpenClaw 技术深度内容，一起探索 AI Agent 的工程实践前沿。
夜雨聆风
