# 6.3 记忆机制：写入、检索与失效

本节以官方记忆系统为准讲清”记忆存在哪里、如何被检索、如何避免污染”。OpenClaw 的长期记忆以工作区文件为中心，并配套向量索引与内置记忆工具（例如 `memory_search`、`memory_get`）。掌握这些机制后，才能把记忆从”越积越乱”变成”可维护资产”。

## 6.3.1 双层记忆结构：MEMORY.md 与每日日志

根据官方设计，OpenClaw 的记忆基于“文件即真相（files are the source of truth）”的思想存储于工作区，主要由两层组成：

* **长期记忆（`MEMORY.md`）**：存放精选持久化偏好、配置决定与沉淀经验，放在工作区根目录。
  * **安全与隐私边界**：据官方文档约束，`MEMORY.md` 仅在 **私聊主会话（direct chat）** 中被加载约束，**绝不会在群组会话（group chat）中注入**，从而保护用户的私密信息。
* **每日日志（`memory/YYYY-MM-DD.md`）**：存放阶段性项目进展、当天的探讨细节。会话启动时，系统默认只会读取“今天加昨天”的文件数据来维系短期事件的连贯性。

这种设计的工程意义是：把“可复用事实”与“过程噪声”分开，让事后的检索与上下文注入保持清爽的信噪比。

## 6.3.2 写入规则与时机：仅记录有价值的事实

官方关于”何时写入记忆”的 **最佳实践** 建议如下：

* **写入 `MEMORY.md`**：记录高价值的用户偏好、重要决策或稳定状态配置。
* **写入 `memory/YYYY-MM-DD.md`**：记录频繁但阶段性的开发操作、项目调试进度的日常流水。
* **立即写入**：无论何时，当用户明确表达”记住这个（remember this）”时，第一时间将该条目持久化。

此外，记忆写入最常见的失败是 **将推测当作事实**。我们建议把写入规则收敛为以下硬约束：

* **稳定**：跨会话复用，短期不易过期。
* **可追溯**：必须来自工具明确回执或有显式确诊依据，而不是基于大模型的一句猜测推理。
* **可纠错**：允许随时撤销更新替换，拒绝将错误信息永久固化。

**实战防坑：坏记忆与好记忆**

* ❌ **坏记忆（模型的主观推测或短时情绪记录）**：“用户今天好像心情不好，且遇到了一个难以排查的 Node.js OOM BUG。”这种文字明天就失效了，且浪费 Token。
* ✅ **好记忆（客观、可追溯的事实与参数配置）**：“用户偏好默认在工作流脚本中使用 Python。当前生产 Kubernetes 集群为 `prod-cluster-us`，且需使用指定服务账号运维（来源：2月20日会话）。”

操作示例：在 `MEMORY.md` 用结构化小节记录事实，并附带来源与更新时间；在 `memory/YYYY-MM-DD.md` 记录过程性日志。

```md
## 部署区域

- 结论：生产环境部署在 us-east-1
- 来源：变更单 CHG-12345
- 更新时间：YYYY-MM-DD
```

## 6.3.3 检索机制：混合向量搜索与精确读取

针对存储的内容（`MEMORY.md` 加上 `memory/**/*.md`）中的各类碎片，官方记忆工具提供了两种主流检索方式：

* **记忆搜索：`memory_search`**— 默认采用 **混合搜索算法（BM25 加上向量相似度）**，将数据切成小块（400 token/分块并设置小额重叠带）。返回带详细文件路径和行号的查询片段。
* **精确读取：`memory_get`** — 基于已有依据读取内容，精确命中特定行，防止信息污染。

**常见配置陷阱：embedding API 密钥依赖**

`memory_search` 的向量检索后端需要独立的 embedding API 密钥（OpenAI、Gemini 或 Voyage），**即使主对话模型使用的是 Claude，也必须额外配置**。若仅设置了 Anthropic 密钥而未配置 embedding 供应商，`memory_search` 会 **无声失效**——不报错、不返回结果，表现形如记忆功能不存在。请在 `openclaw.json` 中确认 embedding 相关的 API 密钥已正确填写，并通过日志确认向量索引是否正常构建。

**最佳配置项：调优记忆搜索权重** 还可以通过 `agents.defaults.memorySearch` 配置 JSON 针对搜索权重进行调优。实测结果表明给向量赋予略高权重有助于贴合业务需求：

```jsonc
{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,
            textWeight: 0.3
          }
        }
      }
    }
  }
}
```

操作要点：检索结果永远要遵循少而精的逻辑。把大量候选项一股脑子全灌入上下文，只会起到让模型”盲目重视全体噪音”的副作用。

## 6.3.4 索引构建管线：从文件保存到可检索

混合检索的前提是索引已就绪。OpenClaw 的索引管线在文件落盘后自动运行，无需手动触发。从使用者角度只需知道两件事：

* **延迟约 2 秒**：文件保存后系统自动重建索引，期间有防抖机制避免高频写入导致重复构建。
* **验收方法**：修改任意记忆文件后，等待约 2 秒，用 `memory_search` 检索刚写入的关键词。如果能命中则索引管线正常工作；如果持续无法命中，优先检查 embedding API 密钥配置（见 6.3.3）。

> \[!NOTE] **可选深潜：索引管线内部实现**
>
> 对于需要排查”改了文件却检索不到”问题的开发者，以下是管线的内部流程：
>
> 1. **监听与防抖**：系统使用 Chokidar 对 `MEMORY.md` 和 `memory/*.md` 实时监听，设置 1.5 秒防抖延迟——文件连续变化时，只有最后一次保存后 1.5 秒静默期过后才启动索引。
> 2. **分块策略**：文件内容按约 400 token 为单位分块，相邻块保留 80 token 重叠区域，防止关键语义被切断。
> 3. **向量生成与存储**：每个文本块送入 embedding 模型（默认 `text-embedding-3-small`，1536 维），结果存入本地 SQLite 数据库。核心表包括：`chunks`（原始文本与位置）、`embeddings`（向量）、`fts`（BM25 倒排索引）、`vector_cache`（哈希去重，跳过未变化内容的重复 embedding 调用）。

## 6.3.5 失效与清理：让记忆有生命周期

长期系统一定会遇到“事实过期”。建议为每条记忆补齐“来源/更新时间/有效期”，并定期做一次复核：过期则标注失效或迁移到每日日志；新事实覆盖旧事实时保留变更链；遇到冲突事实显式标注冲突点，避免模型自行选择。

* 过期条目标注失效或迁移到每日日志。
* 新事实覆盖旧事实时保留变更链。
* 对冲突事实显式标注冲突点，避免模型自行选择。

> \[!TIP] 踩坑实录：记忆搜索”无声失效”之谜
>
> 配好了 Anthropic API Key 就认为配置完毕，却发现 `memory_search` 从来不返回结果。调试半天才发现：记忆搜索的向量检索需要**独立的 embedding API 密钥**（OpenAI、Gemini 或 Voyage），与主对话模型的密钥相独立。最令人困扰的是它不报错，仅静默返回空结果。建议配置后用 `openclaw doctor` 验证 embedding provider 状态。