02-配置 · 记忆系统：五层架构

预计时间：20 分钟（读懂 + 配置 15 分钟） 重要程度：⭐⭐⭐⭐⭐ 适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7（五层架构定型于 2026-04-16）

---

本章你会学到

1. 为什么单纯靠 context window 不够
2. 五层记忆架构的每一层真实做什么
3. 从四层演进到五层的真实故事
4. 必须知道的 4 个运维陷阱（都是作者亲身踩过的）
5. 档位 2 的完整配置模板指引

---

1. 为什么需要五层记忆？

1.1 金鱼记忆的症状

一个只靠 context window 的 agent 会有这些现象：

• 会话开头告诉它”我们的飞书 app_id 是 cli_xxx”，5 分钟后它再问你一次
• 昨天踩过的坑今天重犯，因为”昨天”不在 context 里
• 每次 /new 后用户偏好全丢
• context window 满了之后，旧消息被无声截断，它”忘掉”了关键约束

1.2 单层记忆的极限

如果只靠 context window（等价于 Layer 0）：

• 容量：几十 KB 到几百 KB
• 寿命：会话结束即失
• 结构：线性消息流，检索靠肉眼翻

如果只靠一个外置向量库（等价于 Layer 2）：

• 能跨会话了
• 但不区分「当前推进态」和「长期规则」
• 不适合存「正在进行中的任务状态」
• 没有结构化关系（谁依赖谁，哪些实体相关）

结论：一层不够。OpenClaw 把记忆拆成五层，每层解决一个特定问题。

---

2. 五层架构总览

权威定义见 ~/.openclaw/shared/AGENTS.md 第 96-104 行。

Layer 0 · 当前会话          ← lossless-claw DAG 压缩（contextThreshold=0.65）
Layer 1 · proactivity       ← 运行态推进（下一步跟踪 · 任务持续性）
Layer 2 · memory-lancedb-pro ← 语义记忆（跨会话事实 · 偏好 · 决策召回）
Layer 3 · self-improving    ← 长期经验（稳定规则 · 纠错经验 · 用户偏好）
Layer 4 · Graphify          ← 结构图谱（节点 / 边 / 社区）

真实路径一览

层	存储位置	管理方
L0	Context Window + compaction 快照	lossless-claw skill
L1	~/.openclaw/proactivity/	proactivity skill（全局共享，不 per-agent）
L2	~/.openclaw/memory/lancedb-pro/	memory-lancedb-pro MCP server
L3	~/.openclaw/workspace/memory/ + ~/self-improving/	手动 + memory-consolidation 周合并
L4	~/.openclaw/data/graphify/openclaw-memory/	Graphify skill（周重建）

五层关系图（数据流向）

flowchart TB
    subgraph L0["⏱️ Layer 0 · 当前会话（易失）"]
        ctx[Context Window]
        dag[lossless-claw DAG 快照]
        ctx -->|65% 触发| dag
    end

    subgraph L1["🔄 Layer 1 · proactivity（运行态）"]
        prc[proactivity/memory.md<br/>全局推进态]
        bra[Background Review<br/>计数器]
    end

    subgraph L2["🧠 Layer 2 · LanceDB（语义检索）"]
        lance[(memory-lancedb-pro<br/>per-scope 向量库)]
    end

    subgraph L3["📚 Layer 3 · 长期经验（稳定规则）"]
        si[~/self-improving/<br/>全局热规则]
        ws[workspace/memory/<br/>main 专属]
        exp[memory/experience/<br/>子 agent 原料池]
        exp -->|reflector 评估| si
        exp -->|reflector 评估| ws
    end

    subgraph L4["🕸️ Layer 4 · Graphify（结构图谱）"]
        graph[(graph.json<br/>节点/边/社区)]
    end

    L0 -->|memory_store<br/>重要事实写入| L2
    L2 -->|memory_recall<br/>语义召回| L0
    L3 -.bootstrap 注入.-> L0
    L1 -.推进态告警.-> L0
    L2 -->|周重建| L4
    L3 -->|周重建| L4
    L4 -.结构查询.-> L0

    classDef volatile fill:#fff4e6,stroke:#ff9800
    classDef persistent fill:#e3f2fd,stroke:#1976d2
    classDef pipeline fill:#f3e5f5,stroke:#7b1fa2
    class L0 volatile
    class L1,L2 pipeline
    class L3,L4 persistent

怎么读：

• 实线 = 高频读写；虚线 = 启动注入或低频查询
• L0 是入口和出口（agent 能直接看见）；L1-L4 都通过工具或 hook 间接接触
• L2 / L3 是「主存储」，L4 是它们的图谱视图，每周重建

从四层到五层的演进

早期 OpenClaw 只有四层（L0-L3）。2026-04-16 正式引入 Layer 4 Graphify，原因：

• 问题：L2 语义检索能查「用户偏好简洁回复」这样的事实，但查不到「谁依赖谁」「哪些 agent 归同一类」这种结构
• 补救方案：引入图数据库，把 L2 和 L3 里的实体、事件、决策抽成节点和边，Graphify 社区聚类做主题分组
• 效果：多 agent 架构稳定下来后，agent 之间的”互相知道对方在干啥”不再靠 L0 塞 AGENTS.md，而靠 L4 图谱查询

---

3. Layer 0 · 当前会话（lossless-claw）

3.1 解决的问题

context window 用完后一定要压缩，但普通压缩会丢细节。lossless-claw 用 DAG 组织消息，能压缩体积但保留可追溯性。

3.2 关键配置：两个压缩触发阈值

OpenClaw 的压缩分两档，分别由不同字段控制：

档 1 · lossless-claw DAG 压缩触发线（插件自己的配置）：

{
  "plugins": {
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "contextThreshold": 0.65
        }
      }
    }
  }
}

含义：context window 用到 65% 时触发 DAG 压缩。作者从 0.75 下调到 0.65，目的是”提前触发、留足缓冲”。

档 2 · agent 内置的 safeguard compaction（开箱即用的兜底层）：

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokens": 8000,
        "maxHistoryShare": 0.6,
        "recentTurnsPreserve": 4,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 12000
        }
      }
    }
  }
}

这一档不需要 lossless-claw 也能工作，是 OpenClaw 自带的保底逻辑。

关系：lossless-claw 启用时，档 1 优先触发（更智能、保细节）；没启用 / 失败时，档 2 兜底（粗暴但可靠）。

3.3 LCM 工具：跨会话查压缩后的历史

压缩后不是丢了，是存到本地可检索的结构。用这三个工具查：

工具	用途
lcm_grep	正则 / 全文搜索压缩后的历史
lcm_expand	展开指定 summary ID 看详细原文
lcm_expand_query	委托子 agent 做深度召回（返回带引用的答案）

---

4. Layer 1 · proactivity（运行态）

4.1 核心认知：这一层是全局共享的

目录 ~/.openclaw/proactivity/ 是所有 agent 共用的运行态存储，不是每个 agent 一份。这一点和 L3 不一样。

4.2 文件结构

~/.openclaw/proactivity/
├── memory.md                          proactivity 配置 + 全局待办 + 推进状态
├── review-counter.txt                 Background Review Agent 计数器
└── review-counter.txt.last_review     上次 review 时间戳

proactivity 插件自管 —— 不需要手动创建任何文件，插件首次启动会建起来。

4.3 典型用途

• “main 已经派发给 planner 一个任务，等 planner 回”
• “飞书 callback 进来前 5 分钟里 gateway 重启了一次，reply 可能漏”
• Background Review Agent 计数到阈值，触发一次全局回顾

---

5. Layer 2 · memory-lancedb-pro（语义记忆）

5.1 底层：LanceDB 向量数据库

LanceDB 是 OpenClaw 选的向量存储，原因：

• 本地文件（不依赖外部服务）
• 列式存储（查询快）
• 支持多版本（_versions/ 目录追踪 DDL 变更）

5.2 四个核心 MCP 工具

见 ~/.openclaw/shared/TOOLS.md 第 45-48 行：

工具	用途
memory_recall	语义搜索长期记忆
memory_store	写入重要信息到长期记忆
memory_forget	删除指定记忆
memory_update	更新已有记忆

5.3 scope 机制（⚠️ 容易误解的地方）

记忆有 scope 概念：main / planner / moltbook 等各 agent 一个 scope，外加 global。

默认行为：memory_recall(query='...') 不传 scope 时，按调用方 agent 的可访问 scope 过滤，不是”只搜 main”。

调用方	默认查询范围	跨 agent 查怎么办
main	main 自己的可访问 scope	scope: 'planner'（需授权）
planner	planner 自己的可访问 scope	scope: 'main'（需授权）
任一 agent	global 或被授权的共享 scope	直接传

常见误解：“默认只搜 main”——这只对调用方是 main 时成立，调用方是 planner 时默认查 planner scope。

5.4 ⚠️ 运维陷阱：fragments 爆涨

LanceDB 写入多了会产生大量 fragment 文件和 version 文件，不压缩会：

• 查询变慢（作者碰过 758 片时 memory_recall timeout 5000ms）
• 磁盘占用暴涨

解决方案：每周 compact 一次（见第 10 章的 run-weekly-maintenance.py）。

真实事故：2026-04-17 发现 fragments=758 / versions=1358，原因是维护脚本的 step 文件放在 /tmp/ 里，重启后没了，脚本 silently return True 骗过报警。教训：维护脚本一律持久化到 ~/.openclaw/scripts/，编排器 step 缺失必须 return False。

5.5 本地补丁要同时校验源码和插件清单

memory-lancedb-pro 如果做了本地补丁，不要只看源码里某个默认值有没有改。 当前模板会同时检查：

• 当前 openclaw 命令背后的全局 npm 安装目录
• memory-lancedb-pro 源码补丁是否已应用
• openclaw.plugin.json 里的 autoRecallTimeoutMs 是否也统一到 15000

这是因为状态报告、插件加载和实际源码可能读不同位置。只把源码从 5 秒改成 15 秒，但插件清单仍写 5 秒时，你会看到“明明补丁改了，状态却还是旧默认值”的错觉。

路径也不要写死成作者本机的安装方式。买家端可能用 nvm、系统 npm、Homebrew 或 ~/.local，补丁脚本必须先解析当前 openclaw 命令，再定位插件目录。

---

6. Layer 3 · 长期经验（self-improving + workspace/memory）

6.1 两个存储位置，分工明确

位置	作用	文件示例
~/self-improving/	全局长期经验（跨 agent 共享的稳定规则）	memory.md / corrections.md / domains/*.md
~/.openclaw/workspace/memory/	main agent 专属经验	MEMORY.md / USER.md / corrections.md / 主题文件 / 日工程日志

6.2 self-improving 的三层分档

~/self-improving/
├── memory.md       HOT   ← 全局热规则（< 100 行，常读）
├── corrections.md  HOT   ← 纠错日志
├── domains/        WARM  ← 主题知识库（民宿运营 / OpenClaw 版本知识 / 任务规划）
├── projects/       WARM  ← 项目隔离
└── archive/        COLD  ← 归档

为什么分档：HOT 小且常读（每次 agent 启动就加载），WARM 按主题查，COLD 归档不加载。这和 CPU 缓存层级同理。

6.3 workspace/memory/ 结构

main agent 的专属记忆，包含：

• MEMORY.md：稳定规则索引（类似目录，指向具体记忆文件）
• USER.md：用户偏好
• SOUL.md / IDENTITY.md / AGENTS.md：身份与协作规范（通过 shared/ bootstrap 自动继承，不用手写）
• corrections.md：避坑记录
• 主题文件：feishu-bot-operations.md / gateway-config.md / 按功能分
• 日工程日志：YYYY-MM-DD-{话题}.md（每次重要会话后写）

6.4 experience/ 管道（2026-04-16 新增）

~/.openclaw/memory/experience/ 是所有 agent 的原始经验采集管道：

experience/
├── planner/
├── moltbook/
├── minsu/
├── zhaosheng/
├── yying/
└── shangfang/

每个子 agent的重要会话片段先进这里，由 reflector agent（记忆整理专家）批量评估，挑选升级到 L2 或 L3。

⚠️ main agent 没有 experience/main/ 子目录 —— main 的经验直接走 workspace/memory/ 和 ~/self-improving/，不进这个管道。experience/ 是子 agent 专属的原料池。

---

7. Layer 4 · Graphify（知识图谱）

7.1 真实路径

根目录是 ~/.openclaw/data/graphify/openclaw-memory/（不是直接 ~/.openclaw/data/graphify/，少了一层 openclaw-memory/ 子目录）。这个层级是 Graphify skill 的项目命名空间，多个项目可并存。

7.2 核心产物（真实目录）

~/.openclaw/data/graphify/openclaw-memory/
├── graphify-out/
│   ├── graph.json           节点 + 边的导出（最终图谱数据）
│   ├── GRAPH_REPORT.md      人工可读的统计 + 社区摘要
│   ├── graph.html           交互式图谱可视化
│   ├── graph-triple-in-one.html  三合一视图
│   ├── wiki/                按社区 / 主题导出的 wiki 文档
│   └── cache/               中间态缓存
├── agents/                  每个 agent 贡献的子图源数据（main / planner / minsu 等）
├── skills/                  内部 skill 注册（含 ontology skill）
├── metadata/                skill-query-map.json 等元数据
└── config/openclaw.json     Graphify 运行配置

7.3 自动重建

如果你本地安装了 Graphify，周维护脚本会在 step C 调用 ~/.openclaw/scripts/graphify/rebuild-graph-if-needed.sh；未安装时会显式记一条 SKIP，不会再把整条周维护链判成失败。

---

8. 跨层机制：bootstrap-extra-files

8.1 作用

shared/ 下的 SOUL / AGENTS / TOOLS 三个 md，所有 agent 启动时自动加载到 Project Context，不用每个 agent 手动引用。

8.2 配置位置

~/.openclaw/openclaw.json 的 hooks.internal.entries.bootstrap-extra-files：

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["shared/SOUL.md", "shared/TOOLS.md", "shared/AGENTS.md"]
        }
      }
    }
  }
}

paths 是相对 ~/.openclaw/ 的相对路径，详见 03-多Agent/02-共享规范。

8.3 会话启动顺序

见 shared/AGENTS.md 第 116-127 行：

/new 或 /reset 时加载顺序：
① SOUL.md  ② USER.md  ③ IDENTITY.md  ④ HEARTBEAT.md
⑤ TOOLS.md  ⑥ AGENTS.md  ⑦ MEMORY.md（仅直聊）  ⑧ memory/今日+昨日

额外加载（通过 bootstrap-extra-files hook，无编号）： shared/SOUL.md · shared/TOOLS.md · shared/AGENTS.md

---

9. ⚠️ 四个运维陷阱（必看）

陷阱 1：维护脚本放 /tmp → 静默失效

/tmp/ 重启后可能清空。用 /tmp 的维护脚本会在某次系统更新后消失，而编排器 if not script.exists(): return True 会把”缺失”当”成功”上报。教训：一律放 ~/.openclaw/scripts/，编排器 step 缺失必须 return False。

陷阱 2：memory_recall 默认 scope 被误解

不传 scope 不是”只搜 main”，是”按调用方 agent 的可访问 scope 过滤”。跨 agent 查记忆必须显式传 scope，且受 scope manager 授权校验。

陷阱 3：workspace/memory/ 被误打包

2026-04-17 真实事故：一次打包脚本用黑名单过滤（删几个敏感文件剩下全打），结果把 2700+ 记忆文件 + 50+ agent session 日志全打进 228MB 包。教训：打包记忆相关目录必须用白名单，明确列”允许打包的文件”，其余一律拒绝。

陷阱 4：记忆系统升级时跨层不同步

L3 改了规则但 L2 的旧事实没更新 → agent 会基于旧事实推理。教训：升级记忆模式时用 test-after-write 三步验证（写 → 读回确认 → 实际跑验证），见 shared/AGENTS.md 第 139-147 行。

---

10. 日常维护自动化

10.1 每日（自动）

daily-digest.py（launchd 每日触发）发飞书卡片，关键指标：

• LanceDB fragments 片数（> 500 告警 / > 1000 严重）
• versions 数（同样阈值）
• gateway 状态、cron 任务、任务流活跃数

10.2 每周（自动）

run-weekly-maintenance.py 四步链路：

A. LanceDB 压缩      run-compact.mjs → optimize() + cleanupOlderThan
B. 记忆合并          consolidate-memory.py
C. 图谱重建（可选）  graphify/rebuild-graph-if-needed.sh
D. 监控统计（可选）  run-lance-monitor.py

10.3 每月（手动）

memory-hygiene 深度清理 + 让 reflector agent 审一次 experience/ 池子。

---

11. 档位 2 · 完整配置模板

docs/ 讲的是架构与原则。真正搭起来需要：

• shared/SOUL.template.md —— 去个性化的 SOUL 骨架（个人身份替换为占位符）
• shared/AGENTS.template.md —— 五层记忆架构 + 派发规则的可复制模板
• shared/MEMORY.template.md —— 记忆索引骨架（无任何具体记忆）
• agents/main/MEMORY.template.md 等 —— 每个 agent 的工作空间骨架
• scripts/run-weekly-maintenance.template.py —— 可直接配 cron 的维护脚本
• guided-install/install.sh —— 问答式安装，按你的 agent 数量 + 业务领域生成

这些在本教程的 档位 2 付费解锁区 的 templates/ 目录下。详见 付费模板包说明。

---

12. 下一步

• 03-多Agent/00-协作拓扑 —— 为什么要多 agent + 怎么分工（这一章会反复引用记忆层）
• 04-运维/00-健康检查 —— daily-digest.py 飞书卡片解读
• 05-排障/00-常见问题 —— memory_recall timeout / fragments 爆涨 / 跨 agent 记忆对不上等真实问题的排查流程

---

验证清单

检查项	命令	期望
L2 目录存在	ls ~/.openclaw/memory/lancedb-pro/	有 memories.lance/ 子目录
L1 目录存在	ls ~/.openclaw/proactivity/	有 memory.md + review-counter.txt
L3 全局经验	ls ~/self-improving/	有 memory.md / corrections.md / domains/
L3 main 专属	ls ~/.openclaw/workspace/memory/	有 MEMORY.md / USER.md
L4 图谱	ls ~/.openclaw/data/graphify/openclaw-memory/graphify-out/	有 graph.json / GRAPH_REPORT.md
experience 池子	ls ~/.openclaw/memory/experience/	有子 agent 目录（不含 main）
bootstrap 注入生效	openclaw doctor	无 ❌

七项都在就说明记忆骨架搭起来了。下一步填模板内容（档位 2）。

---

这篇教程的准确性保证 本章所有架构描述、路径、工具名都对着 ~/.openclaw/shared/AGENTS.md 第 96-127 行、~/.openclaw/workspace/memory/MEMORY-UNIFIED-DESIGN-2026-04-16.md 第 14-76 行、~/.openclaw/shared/TOOLS.md 第 45-49 行交叉验证。四个运维陷阱均来自作者真实生产踩坑（2026-04-17）。

---

导航：← 多Agent架构 · 📖 目录 · → Skills选择