OpenClaw 记忆管理：从入门到高阶完整实战指南（拆解总结）

本文是对 Ray Wang 分享的 OpenClaw 记忆管理实战指南的深度拆解与总结。该方案基于 5 个 Agent 协作团队 30 天的实际生产运行经验，旨在解决 LLM Agent 的“健忘”与“记忆幻觉”问题。

核心哲学：文件 = 事实来源

Context Window $\neq$ Memory*。上下文窗口是临时的“工作台”，而文件才是永久的“仓库”。任何没有写入文件的信息在 session 结束后都会消失。因此，核心原则是：*所有重要信息必须实时写入文件。

—

一、 三层记忆架构

为了平衡检索效率与存储精度，方案采用了三层架构：

1. 短期层：`NOW.md` (工作台)

用途：记录当前状态、优先级、阻塞项。

特点：每次 heartbeat 覆写，不追加。它是 Agent 在上下文被压缩（Compaction）后的首选恢复点。

核心逻辑：唯一允许覆写的记忆文件。

2. 中期层：每日日志 (`memory/YYYY-MM-DD.md`)

用途：事件流水，记录当天发生的一切原始数据。

特点：追加式（Append-only），永不覆写。

写入规范：采用 `### HH:MM — Title` 格式，便于快速扫描。

3. 长期层：结构化知识库 (`INDEX.md` $\rightarrow$ 子目录)

用途：存储提炼后的可复用知识（如 `lessons/` 教训, `decisions/` 决策, `people/` 画像）。

特点：由 `INDEX.md` 作为导航枢纽，包含健康度标记（优先级 $\text{🔴/🟡/⚪}$、状态 $\text{active/stale/conflict}$）。

—

二、 信息生命周期与流动

记忆通过一个完整的 pipeline 进行提炼和演进：

$$\text{对话/事件} \xrightarrow{\text{实时写入}} \text{每日日志} \xrightarrow{\text{夜间反思}} \text{知识库} \xrightarrow{\text{每周 GC}} \text{冷存储 (.archive/)}$$

日间：通过 $\text{heartbeat}$ 和对话实时写入日志。

夜间 (23:45)*：执行 *夜间反思 (Nightly Reflection)。将日志中的原始事件提炼为结构化知识，并执行 CRUD 验证。

每周 (周日 00:00)*：执行 *垃圾回收 (GC)。将超过 30 天且无引用的冷数据移至 `.archive/` 目录，以降低检索噪音。

—

三、 可靠性保障：防止记忆幻觉 (HaluMem)

为了防止 Agent 编造或覆盖正确记忆，引入了 CRUD 验证机制：

1. 先读再写：在写入知识文件前，必须先读取当前内容。
2. 四分类处理：
– 一致 $\rightarrow$ $\text{NOOP}$ (跳过)。
– 更新 $\rightarrow$ $\text{UPDATE}$ (标记旧版为 Superseded，追加新版)。
– 矛盾 $\rightarrow$ $\text{CONFLICT}$ (两版均保留，标记冲突，等待人工裁决)。
– 无关 $\rightarrow$ $\text{ADD}$ (追加新段落)。
3. 过时检测：通过 `last_verified` 字段，超过 30 天未验证的信息标记为 `⚠️ stale`。

—

四、 检索策略

采用三级检索，优先低成本方案：

L1 (Index)：通过 `INDEX.md` 定位类别 $\rightarrow$ 找到目标文件。

L2 (Direct)：已知路径直接读取。

L3 (Semantic)：使用 QMD 向量数据库进行语义搜索（作为兜底）。

五、 总结与建议

对于想要搭建记忆系统的开发者，建议采取渐进式搭建：

阶段 0 $\rightarrow$ `NOW.md` + 每日日志 (实现基础跨 session 记忆)。

阶段 1 $\rightarrow$ 引入 `INDEX.md` 与主题目录 (实现结构化知识积累)。

阶段 2 $\rightarrow$ 引入 Heartbeat 与夜间反思 (保障知识质量)。

阶段 3 $\rightarrow$ 引入语义搜索与 GC (提升检索效率与主动遗忘)。

—
原作者链接：[Ray Wang on X – OpenClaw 记忆管理指南](https://x.com/wangray/status/2027034737311907870?s=20)