OpenClaw 记忆系统深度分析报告
> 文档版本：2026-05-08 > 依据来源：OpenClaw 官方文档 (https://docs.openclaw.ai) > 分析范围：Memory Overview、Active Memory、Dreaming、Memory Search、Builtin Memory Engine、Context Engine、Compaction、Session、Context、System Prompt
一、设计哲学：记忆即文件
OpenClaw 的核心理念是「记忆即文件」——模型只能记住写入磁盘的内容，没有隐藏状态。所有记忆都以纯 Markdown 文件的形式保存在 agent 工作空间（默认 ~/.openclaw/workspace），对用户完全透明可读。
~/.openclaw/workspace/
├── MEMORY.md # 长期记忆
├── DREAMS.md # 梦境日记（可选）
└── memory/
└── YYYY-MM-DD.md # 每日笔记
这与其他 AI 系统的黑箱记忆形成鲜明对比。OpenClaw 用户可以随时打开这些文件阅读、编辑或删除，模型也可以通过 memory_search 和 memory_get 工具访问它们。
二、核心组件总览
┌─────────────────────────────────────────────────────────────┐
│ Context Window │
│ (System Prompt + Conversation History + Tools Results) │
└─────────────────────────────────────────────────────────────┘
↑
┌─────────┴──────────┐
│ Bootstrap Files │
│ (MEMORY.md 等每次 │
│ turn 自动注入) │
└────────────────────┘
↑
┌────────────────────┼────────────────────┐
│ │ │
memory_search memory_get Dreaming
(语义+关键词搜索) (精确读取) (后台晋升)
↑ ↑ ↑
┌─────┴─────┐ ┌────┴────┐ ┌─────┴─────┐
│ Builtin │ │ Daily │ │ Light │
│ (SQLite) │ │ Notes │ │ Deep │
│ + Vector │ │ *.md │ │ REM │
└───────────┘ └─────────┘ └───────────┘
┌─────────────────────────────────────────────────────────┐
│ Active Memory (Blocking Sub-Agent) │
│ 在主回复生成前，以 blocking 方式主动搜索记忆 │
└─────────────────────────────────────────────────────────┘
三、Bootstrap 文件注入体系
3.1 工作机制
OpenClaw 在每个 turn 都会将一组固定的工作空间文件注入到系统提示的 Project Context 区域，称为 Bootstrap 文件。这些文件在上下文窗口中处于稳定区域（cache boundary 上方），不受会话内容影响。
3.2 注入文件列表
| 文件 | 作用 | 加载策略 |
|---|---|---|
AGENTS.md |
工作空间总览与行为准则 | 每次注入 |
SOUL.md |
AI 人格与性格定义 | 每次注入 |
TOOLS.md |
本地工具与授权笔记 | 每次注入 |
IDENTITY.md |
身份定义与保密准则 | 每次注入 |
USER.md |
用户信息与偏好 | 每次注入 |
HEARTBEAT.md |
心跳任务清单 | 存在时注入 |
MEMORY.md |
长期记忆 | 存在时每次注入 |
BOOTSTRAP.md |
首次运行引导 | 仅全新工作空间 |
3.3 截断机制
OpenClaw 对 Bootstrap 文件有严格的大小限制，防止上下文污染：
- 单文件上限：
agents.defaults.bootstrapMaxChars（默认 12,000 chars） - 总注入上限：
agents.defaults.bootstrapTotalMaxChars（默认 60,000 chars） - 超出时会在文件中插入截断标记
> ⚠️ 注意：memory/*.md 每日笔记不在 Bootstrap 注入范围内，模型只能通过 memory_search / memory_get 工具按需访问。不过 /new 或 /reset 启动新会话时，运行时可能会主动拼接最近几条每日笔记作为启动上下文。
3.4 Sub-agent 差异
子 agent 会话（如 sessions_spawn 启动的隔离子任务）只会注入 AGENTS.md 和 TOOLS.md，其他 Bootstrap 文件会被过滤掉，以保持子 agent 上下文精简。
四、长期记忆 — MEMORY.md
4.1 定位与内容
MEMORY.md 是 OpenClaw 的长期记忆文件，包含：
- 持久化的事实（姓名、偏好、决策）
- 重要的历史结论
- 用户偏好和工作风格
- 已完成项目记录
4.2 加载时机
MEMORY.md 通过 Bootstrap 机制在每个 DM 会话 turn 都自动注入上下文。这意味着每次对话开始，模型都能「看见」长期记忆。
4.3 写入方式
模型在两种情况下主动写入 MEMORY.md：
- 显式写入：用户要求「记住 XXX」
- 自动 flush：在 compaction（会话压缩）发生之前，OpenClaw 自动运行一个静默的 memory-flush turn，提醒模型将重要信息保存到记忆文件
4.4 管理原则
- 长期记忆应保持高信号（只保留真正重要的）
- 不应记录大量流水账式内容（这属于每日笔记）
- Dreaming 系统会帮助自动筛选和晋升符合条件的短期信号
五、每日笔记 — memory/YYYY-MM-DD.md
5.1 定位
每日笔记是短期记忆，记录当天的工作内容、观察和上下文。
5.2 加载策略
- 今天 + 昨天的每日笔记会被自动加载（通过 Bootstrap 或运行时拼接入上下文）
- 更早的每日笔记需要模型主动调用
memory_search/memory_get按需检索
5.3 存储位置
memory/ 目录下的每日笔记可以被 Dreaming 系统摄入分析，未被晋升的内容最终会自然老化。
六、Active Memory（主动记忆）
6.1 设计动机
大多数记忆系统都是被动式的——依赖模型自己决定何时搜索记忆，或依赖用户说「记住这个」或「搜索记忆」。这时记忆本应发挥作用的时机已经错过了。
Active Memory 给了系统一个有限的、 bounded 的机会，在主回复生成之前主动召回相关记忆，使回复更自然。
6.2 运行机制
Active Memory 是一个blocking sub-agent，运行在主回复之前：
用户消息 → [构建查询] → [Active Memory Blocking Sub-Agent]
↓
返回 NONE 或相关摘要
↓
[拼接隐藏的 active_memory_plugin 上下文]
↓
[主回复生成]
6.3 关键配置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
enabled |
false | 插件总开关 |
agents |
["main"] |
哪些 agent 启用 |
allowedChatTypes |
["direct"] |
仅 DM 会话（可扩展到 group/channel） |
model |
unset | 专用 recall 模型，unset 则继承会话模型 |
modelFallback |
- | 模型解析失败时的兜底 |
queryMode |
recent |
发送给 sub-agent 的上下文量 |
promptStyle |
balanced |
记忆召回的激进程度 |
timeoutMs |
15000 | sub-agent 超时 |
maxSummaryChars |
220 | 召回摘要的最大长度 |
persistTranscripts |
false | 是否保留 sub-agent transcript |
6.4 Query Modes（查询模式）
message < recent < full
速度最快 召回质量最高
- message：仅发送用户最新消息。速度最快，适合强偏好召回。
- recent：最新消息 + 最近几轮对话。平衡模式，适合跟进类问题。
- full：完整会话历史。召回质量最高，但延迟最大。
6.5 Prompt Styles（召回策略）
| 风格 | 行为 |
|---|---|
strict |
最保守，仅明显匹配才返回 |
balanced |
通用平衡（recent 模式默认值） |
contextual |
最重视上下文连续性（full 模式默认值） |
recall-heavy |
更容易召回软匹配 |
precision-heavy |
除非明显匹配，否则返回 NONE |
preference-only |
专为偏好、习惯、口味等个人事实优化 |
6.6 适用场景
✅ 适合：稳定偏好、习惯、长期用户上下文、自然出现的记忆召回 ❌ 不适合：自动化、内部 worker、单次 API 任务、隐藏个性化会让人惊讶的场景
6.7 会话开关
/active-memory status # 查看状态
/active-memory off # 当前会话关闭
/active-memory on # 当前会话开启
/active-memory off --global # 全局关闭
七、Dreaming（梦境后台晋升系统）
7.1 定位
Dreaming 是 OpenClaw 的后台记忆 consolidation 系统，帮助将短期信号晋升为长期记忆，同时保持过程可解释、可审查。
> ⚠️ Dreaming 默认关闭，需要显式启用。
7.2 三阶段架构
Light Phase ──→ Deep Phase ──→ REM Phase
(排序暂存) (评分晋升) (主题反思)
↓ ↓ ↓
.dreams/ MEMORY.md DREAMS.md
(机器状态) (持久写入) (人类可读)
Light Phase（轻睡眠）
- 摄入最近的短期记忆信号和 recall traces
- 去重并暂存候选条目
- 记录 reinforcement 信号供后续 Deep 排名使用
- 不写入
MEMORY.md
Deep Phase（深睡眠）
- 对候选条目进行加权评分排名
- 必须同时通过
minScore、minRecallCount、minUniqueQueries三个阈值门 - 将符合条件的内容追加到
MEMORY.md - 写入
DREAMS.md的## Deep Sleep摘要
REM Phase（快速眼动）
- 从短期 traces 中提取主题和反思信号
- 不写入
MEMORY.md - 记录 REM reinforcement 信号供 Deep 排名使用
7.3 Deep 排名信号（权重）
| 信号 | 权重 | 说明 |
|---|---|---|
| Relevance（相关性） | 0.30 | 平均检索质量 |
| Frequency（频率） | 0.24 | 短期积累的信号数量 |
| Query Diversity（查询多样性） | 0.15 | 触达条目的不同查询/天数上下文 |
| Recency（时效性） | 0.15 | 时间衰减新鲜度 |
| Consolidation（巩固度） | 0.10 | 多日复发强度 |
| Conceptual Richness（概念丰富度） | 0.06 | 来自片段/路径的概念标签密度 |
7.4 Dream Diary（DREAMS.md）
Dreaming 将三类输出写入 DREAMS.md（或已存在的 dreams.md）：
- ## Light Sleep 块
- ## Deep Sleep 摘要
- ## REM Sleep 块
这些内容供人类阅读和审查，不是晋升源。Dreaming 生成的 diary/report artifacts 会从短期晋升候选中排除，只有基于原始记忆片段的条目才有资格晋升到 MEMORY.md。
7.5 grounded Backfill（基于史实回填）
Dreaming 还有一条历史回填通道：
# 预览历史每日笔记的梦境输出
openclaw memory rem-harness --path ./memory --grounded
# 写入可逆的回填条目到 DREAMS.md
openclaw memory rem-backfill --path ...
# 仅回填暂存候选，不直接晋升
openclaw memory rem-backfill --path ... --stage-short-term
回填候选会进入与正常 Deep phase 相同的短期暂存区，DREAMS.md 仍作为人工审查入口。
7.6 调度
启用后，memory-core 自动管理一个 cron 任务执行完整 sweep（light → REM → deep）。
| 设置 | 默认值 |
|---|---|
dreaming.frequency |
0 3 * * *（每天凌晨 3 点） |
dreaming.model |
默认运行时模型 |
八、Memory Search（记忆搜索）
8.1 工作机制
memory_search 通过两种检索路径并行运行并合并结果：
Query → [Embedding] ──→ Vector Search ──┐
→ [Tokenize] ──→ BM25 Search ──┼→ Weighted Merge → Top Results
- 向量搜索（Vector Search）：基于语义相似性（"gateway host" 能匹配 "运行 OpenClaw 的机器"）
- BM25 关键词搜索：精确匹配（ID、错误字符串、配置 key）
如果只有一个路径可用，另一个路径单独运行。如果嵌入提供商不可用，OpenClaw 会降级为基于 FTS 的词汇排名，而非纯精确匹配。
8.2 支持的嵌入提供商
| 提供商 | ID | 自动检测 | 备注 |
|---|---|---|---|
| OpenAI | openai |
✅ | 默认 text-embedding-3-small |
| Gemini | gemini |
✅ | 支持多模态（图片+音频） |
| Voyage | voyage |
✅ | |
| Mistral | mistral |
✅ | |
| DeepInfra | deepinfra |
✅ | 默认 BAAI/bge-m3 |
| GitHub Copilot | github-copilot |
✅ | |
| Ollama | ollama |
❌ | 需显式设置 |
| Local（本地） | local |
首个本地 | 需要 node-llama-cpp |
| Bedrock | bedrock |
✅ | AWS 凭证链可解析时 |
> 💡 如果配置了 OpenAI、Gemini、Voyage 或 Mistral 的 API key，向量搜索开箱即用，无需额外配置。
8.3 高级特性
Temporal Decay（时间衰减）
旧笔记的排名权重逐渐降低（默认半衰期 30 天），确保最新信息优先。MEMORY.md 永不受衰减影响。
MMR（最大边际相关性）
减少结果冗余——如果五条笔记都提到同一个路由器配置，MMR 确保 top 结果覆盖不同主题，而非重复。
8.4 索引机制
OpenClaw 将 MEMORY.md 和 memory/*.md 切分成小块（~400 tokens，80 tokens 重叠）后存入 SQLite 数据库。
- 索引位置：
~/.openclaw/memory/<agentId>.sqlite - 文件监听：内存文件变更触发防抖重索引（1.5s）
- 自动重索引：嵌入提供商、模型或分块配置变更时自动重建
- 手动重建：
openclaw memory index --force
九、Compaction（会话压缩）
9.1 触发条件
Compaction 在两种情况下触发： 1. 自动压缩：会话接近模型的上下文窗口限制 2. 溢出恢复：模型返回上下文溢出错误，OpenClaw 压缩后重试
9.2 工作机制
older turns → 总结为紧凑摘要 → 保存到 session transcript
recent turns → 保持原样
压缩只改变模型在下一轮看到的上下文，完整会话历史仍保存在磁盘的 session transcript 中。
9.3 Memory Flush（记忆冲刷）
在压缩发生前，OpenClaw 会自动运行一个静默的 memory-flush turn，提醒模型将重要信息保存到记忆文件，防止上下文丢失。
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"model": "ollama/qwen3:8b" // 使用本地模型加速 flush
}
}
}
}
}
9.4 Compaction vs Pruning
| Compaction | Pruning | |
|---|---|---|
| 作用 | 将旧对话总结为摘要 | 裁剪旧的 tool results |
| 是否持久化 | 是（存入 session transcript） | 否（仅在内存中，不写磁盘） |
| 范围 | 整个会话 | 仅 tool results |
十、Context Engine（可插拔上下文引擎）
10.1 定位
Context Engine 控制 OpenClaw 为每次模型运行构建上下文的方式：包含哪些消息、如何总结旧历史、如何管理跨 sub-agent 边界。
10.2 生命周期钩子
每个 Context Engine 需要实现四个核心方法：
| 钩子 | 时机 | 职责 |
|---|---|---|
ingest |
新消息加入会话时 | 存储或索引消息到引擎数据存储 |
assemble |
每次模型运行前 | 返回在 token 预算内的一系列消息 + 可选的 systemPromptAddition |
compact |
上下文窗口满时 | 总结/缩减旧上下文 |
afterTurn |
运行完成后 | 持久化状态、触发后台压缩、更新索引 |
10.3 Legacy Engine（默认）
默认的 legacy 引擎保留 OpenClaw 原始行为：
- ingest：no-op（会话管理器直接处理消息持久化）
- assemble：透传（现有 sanitize → validate → limit 管线处理）
- compact：委托给内置的 summarization compaction
- afterTurn：no-op
10.4 Plugin Engines
插件可以通过 registerContextEngine() 注册自定义引擎，支持完全自定义 assembly、compaction 和 cross-session recall 行为。
systemPromptAddition 是 Context Engine 注入动态召回指导的关键机制——通过 buildMemorySystemPromptAddition() 将 active memory 提示段转换为可 prepend 的 systemPromptAddition 字符串。
十一、会话管理与记忆的交互
11.1 Session 路由规则
| 来源 | 行为 |
|---|---|
| Direct messages | 默认共享一个 session |
| Group chats | 按群隔离 |
| Cron jobs | 每次运行全新 session |
| Webhooks | 按 hook 隔离 |
11.2 Session 生命周期
- 每日重置（默认）：每天凌晨 4 点（本地）开启新 session
- 空闲重置（可选）：一段时间无交互后开启新 session
- 手动重置：
/new或/reset
11.3 Session 与记忆的关系
- Session transcript 是会话历史的载体，由 Compaction 管理
MEMORY.md是跨会话的长期记忆，通过 Bootstrap 注入- 每日笔记
memory/*.md是短期会话上下文，按需通过memory_search访问 - Active Memory 在单会话内的 turn 之间召回短期上下文
十二、Built-in Memory Engine（内置记忆引擎）
12.1 定位
内置引擎是默认的记忆后端，使用 SQLite 存储记忆索引，无需额外依赖即可使用。
12.2 提供的能力
- 关键词搜索：FTS5 全文索引 + BM25 评分
- 向量搜索：通过嵌入提供商
- 混合搜索：结合两者取最优
- CJK 支持：通过 trigram 分词支持中日韩文字
- sqlite-vec 加速：可选的数据库内向量查询
12.3 索引文件位置
~/.openclaw/memory/<agentId>.sqlite
十三、Memory Wiki 插件（知识库层）
memory-wiki 插件在 active memory 插件之上提供知识库功能：
- 确定性页面结构
- 结构化 claims 和 evidence
- 矛盾和新鲜度追踪
- 生成 dashboard
- 编译 digest 供 agent/runtime 消费
- wiki 原生工具：wiki_search、wiki_get、wiki_apply、wiki_lint
它不替换 active memory 插件——后者仍负责召回、晋升和梦境。memory-wiki 在旁边添加了一个富含溯源的知识层。
十四、工具汇总
| 工具 | 类型 | 用途 |
|---|---|---|
memory_search |
工具 | 语义+关键词混合搜索记忆 |
memory_get |
工具 | 读取指定记忆文件或行范围 |
memory_recall |
工具（AM sub-agent 可用） | Active Memory 内部召回 |
/dreaming status/on/off |
命令 | Dreaming 控制 |
/active-memory status/on/off |
命令 | Active Memory 控制 |
openclaw memory status |
CLI | 检查索引状态和提供商 |
openclaw memory index --force |
CLI | 强制重建索引 |
openclaw memory promote |
CLI | 手动预览/应用晋升 |
openclaw memory rem-harness |
CLI | 预览 REM 反思输出 |
十五、当前环境状态
15.1 峰哥的 OpenClaw 配置
{
"plugins": {
"entries": {
"memory-core": {
"enabled": true,
"config": {
"dreaming": { "enabled": true }
}
}
}
}
}
15.2 启用状态
| 组件 | 状态 | 说明 |
|---|---|---|
| MEMORY.md Bootstrap 注入 | ✅ 启用 | 每次 turn 自动注入 |
| memory/*.md 每日笔记 | ✅ 正常 | 今天+昨天自动加载 |
| Active Memory | ❌ 未启用 | 配置中未出现 |
| Dreaming | ✅ 启用 | memory-core 内置，enabled: true |
| memory_search 向量搜索 | ❓ 未知 | 需要 API key 或本地嵌入 |
| Compaction | ✅ 启用 | 默认开启，safeguard 模式 |
| Memory Wiki | ❌ 未安装 | 可选插件 |
十六、总结：OpenClaw 记忆系统架构
┌─────────────────────┐
│ Bootstrap Files │
│ (MEMORY.md 每次注入) │
└──────────┬──────────┘
│
┌───────────────────────┼───────────────────────┐
↓ ↓ ↓
┌──────────────┐ ┌────────────────┐ ┌──────────────┐
│ Daily Notes │ │ Active Memory │ │ Dreaming │
│ memory/*.md │ │ (blocking SA) │ │ (后台晋升) │
└──────┬───────┘ └───────┬────────┘ └──────┬───────┘
│ │ │
↓ ↓ ↓
┌────────────────────────────────────────────┐
│ memory_search (混合搜索) │
│ Vector + BM25 → 加权合并 → Top Results │
└──────────────────────┬─────────────────────┘
↓
┌────────────────────────┐
│ Builtin Memory Engine │
│ (SQLite + sqlite-vec) │
└────────────────────────┘
────────────────────────────────────────────
Context Window
(System Prompt + History + Tools + Bootstrap)
↑
┌────────────┴────────────┐
│ Context Engine │
│ (legacy / plugin) │
└─────────────────────────┘
核心设计原则
- 透明性优先：所有记忆都是明文 Markdown 文件，用户随时可读、可写、可删
- 分层记忆：Bootstrap 注入（长期）× Active Memory 实时召回 × Dreaming 后台晋升 × Compaction 会话压缩
- 可插拔架构：Memory Engine、Context Engine 均可替换，支持插件扩展
- 零隐藏状态：模型只「记得」写入磁盘的内容，没有黑箱状态
- 主动优于被动：Active Memory 在主回复前主动搜索，而非等待模型自己想起来
报告生成时间：2026-05-08 数据来源：https://docs.openclaw.ai