一文速通OpenClaw记忆系统设计

OpenClaw 的记忆系统不靠"隐藏状态"，全靠写入磁盘的 Markdown 文件。模型能记住的，就是写到文件里的东西。整个系统从快到慢、从短到长，分了多个层次。OpenClaw 的记忆不是单一的一个"记忆库"，而是一套分层协作的系统：会话内的短期上下文、按天的日志文件、长期记忆文件、语义搜索、主动记忆、梦境整理、结构化知识库——各有分工，互相配合。

第一层：Session 会话上下文（最短，毫秒级）

最基础的记忆就是你当前正在聊天的这段对话。

OpenClaw 把每次对话存在 *.jsonl 文件里，叫 Transcript。这是完整的对话记录——用户消息、AI 回复、工具调用，全部保存。

但有个限制： 模型的上下文窗口是有限的。对话太长时，系统会自动做 Compaction（压缩）——把旧的对话总结成一条摘要，只保留最近的消息。

防止记忆丢失的机制——Memory Flush：压缩前，系统会静默触发一轮"记忆刷写"，提醒 AI 把重要的上下文写到磁盘文件里。这一步是默认开启的，用户无感。

关键点： 会话上下文是最快的记忆（就在对话里），但也是最脆弱的——不写入文件，压缩后就没了。

第二层：memory/YYYY-MM-DD.md（日志文件，短期记忆）

每天一个日志文件，存在 memory/2026-04-16.md 这样的路径下。

记的是当天的原始观察和上下文
每次会话自动加载今天 + 昨天两个文件
超过两天就靠语义搜索来召回

这层是原始笔记——不需要精炼，想到什么写什么。

第三层：MEMORY.md（长期记忆）

这是最核心的文件，存在工作区根目录 MEMORY.md。

记的是经过整理的事实、偏好、决策——类似人类经过深思熟虑后存入大脑的知识
每次私聊会话启动时完整加载，直接进入模型上下文
文件不大，只存真正重要的东西

memory/YYYY-MM-DD.md

原始笔记
每天自动创建
量大、不精炼
只加载近 2 天

MEMORY.md

提炼后的精华
手动维护
量小、高度精炼
每次会话完整加载

第四层：Memory Search（语义搜索，按需召回）

文件多了记不住怎么办？语义搜索登场。

OpenClaw 给所有记忆文件建了索引，支持混合搜索（Hybrid Search）：

向量相似度 — 理解语义，即使措辞不同也能匹配
BM25 关键词 — 精确匹配 ID、代码符号等
时间衰减 — 旧的自动降权（半衰期默认 30 天）
MMR 去重 — 保证结果多样性

配置了任意图床 API Key（OpenAI/Gemini/Voyage/Mistral），搜索就自动开启。

底层有两个引擎可选：

Builtin（默认）：SQLite，开箱即用
QMD：本地优先的侧车服务，支持 reranking 和跨目录索引

第五层：Active Memory（主动记忆，对话前介入）

大多数记忆系统是被动的——等用户说"你记得吗"或者 AI 主动去搜，已经晚了。

Active Memory 解决的是时机问题。

它是一个插件级别的阻塞子 Agent，在主回复生成之前运行：

收到用户消息
Active Memory 先跑一遍，搜索相关记忆
把结果注入上下文
主 Agent 才开始生成回复

效果： AI 不用等你提醒它，就已经"想起来"了。

配置要点：

只针对私聊场景（避免在群里过度曝光个人记忆）
有超时控制（默认 15 秒）
可以用轻量模型跑搜索，省 token

第六层：Dreaming（梦境整理，后台 consolidation）

这是一个可选功能，默认关闭。

Dreaming 的本质是后台记忆整理，类似人类睡觉时大脑在"整理白天的记忆"。

工作流程：

按设定的 cron 频率触发（默认每天凌晨 3 点）
扫描短期信号（日志文件、会话记录）
打分筛选——不是所有东西都该进长期记忆
通过阈值的条目晋升到 MEMORY.md
整理结果写入 DREAMS.md，供人类审查

设计原则： 保持长期记忆的高信噪比。不是什么都能进 MEMORY.md，必须经过打分、召回频率、查询多样性等多重门槛。

整理后的日记存在 DREAMS.md 里，类似"梦境日记"。

第七层：Memory Wiki（知识库，最终形态）

这是记忆系统的最后一层——把长期记忆编译成结构化的知识库（Vault）。

Memory Wiki 不替代 Active Memory，它是在旁边加了一层更丰富的知识层：

做什么：

将 MEMORY.md 和 memory/ 中的持久记忆编译为可导航的 Markdown 知识库
自动生成页面结构（人物、项目、记忆、声明等）
支持在 Obsidian 中打开和浏览

Claim/Evidence 模型：

每条知识不再是一段文字，而是一个结构化的 Claim：

唯一 ID + 分类 + 内容
新鲜度标记（high/medium/low）
矛盾检测——如果新旧信息冲突，自动标记
来源追溯——每条声明都能回溯到原始会话

和普通记忆的关系：

Active Memory

运行时快速检索
毫秒级
负责召回

Dreaming

离线记忆整理
定时触发
负责晋升

Memory Wiki

离线编译展示
批处理
负责结构化

完整的数据流

用户发消息
  → Active Memory 先跑（搜索相关记忆）
  → 注入上下文
  → 主 Agent 生成回复
  → 对话中写入 memory/YYYY-MM-DD.md
  → 重要事实写入 MEMORY.md
  → 压缩前 Memory Flush 保活
  → 夜间 Dreaming 整理晋升
  → 定期 Memory Wiki 编译为结构化知识库

这套设计的好处

没有"黑盒记忆"。 所有记忆都是磁盘上的 Markdown 文件，你能看到、能编辑、能备份。不像某些 AI 平台把记忆存在数据库里，你根本不知道它记住了什么。

分层解决了不同问题：

会话上下文 → 聊天的连贯性
日志文件 → 当天的原始记录
MEMORY.md → 经得起时间考验的事实
语义搜索 → 在大量记忆中精准召回
Active Memory → 不用用户提醒就能想起来
Dreaming → 自动整理，保持长期记忆干净
Memory Wiki → 结构化的知识管理

用得越久，每层积累的价值就越大。