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：

1. 显式写入：用户要求「记住 XXX」 2. 自动 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)      │
              └─────────────────────────┘

核心设计原则

1. 透明性优先：所有记忆都是明文 Markdown 文件，用户随时可读、可写、可删 2. 分层记忆：Bootstrap 注入（长期）× Active Memory 实时召回 × Dreaming 后台晋升 × Compaction 会话压缩 3. 可插拔架构：Memory Engine、Context Engine 均可替换，支持插件扩展 4. 零隐藏状态：模型只「记得」写入磁盘的内容，没有黑箱状态 5. 主动优于被动：Active Memory 在主回复前主动搜索，而非等待模型自己想起来

---

报告生成时间：2026-05-08 数据来源：https://docs.openclaw.ai