OpenClaw 快速上手（七）：把记忆系统讲清楚，不靠玄学

前六篇让你跑起来了一个能用的 OpenClaw，挂上了渠道，写了一个 Skill。这一篇要讲第一次安装时大家普遍踩坑的部分：记忆。

workspace 的样子

打开 ~/.openclaw/workspace/，你会看到：

~/.openclaw/workspace/
├── MEMORY.md              # 索引，控制在 40 行以内
├── HEARTBEAT.md           # 巡逻规则，按节奏被重读
└── memory/
    ├── projects.md        # 当前项目状态
    ├── lessons.md         # 踩过的坑，不想再踩
    ├── 2026-04-14.md      # 当日原始日志
    └── archive/           # 30 天以前的全部归档到这里

最重要的两个文件：MEMORY.md 是索引——Agent 每一轮都会读，所以必须短；lessons.md 沉淀那些"我们试过、它因为 Y 崩了"的长尾。日志写得勤、读得稀，平时只通过搜索去触达。

我自己花了两个月才弄明白的事：什么都往 MEMORY.md 里塞。等它涨到 200 行，每一轮先吃掉三千 token 才开始干活，Agent 还是找不到要的东西。索引不是档案。

四层记忆的心智模型

判断一条信息该放哪儿，我脑子里挂着这张表：

层	寿命	该去哪里
身份	永久	`MEMORY.md`（姓名、语气、角色）
决策	数月	`projects.md`
教训	数年	`lessons.md`
痕迹	数日	`memory/YYYY-MM-DD.md`

塞不进任何一格的，多半就是噪音。直接丢。

memoryFlush——必装的一行配置

长对话上下文吃紧时会自动压缩。默认行为是：没写下来的全部蒸发。memoryFlush 会在压缩之前专门跑一遍"把重要信息抢出来"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

softThresholdTokens 是抢救阶段允许用掉的 token 上限。4000 够写一段有用的总结；8000 浪费——除非你在跑超长会话。

memorySearch——bge-m3 完全够用

可以对所有记忆文件做语义搜索，前提是接一个 Embedding API。最便宜的路是 SiliconFlow 的 BAAI/bge-m3，免费而且足够用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "tools": {
    "memorySearch": {
      "enabled": true,
      "embedding": {
        "provider": "openai-compatible",
        "baseUrl": "https://api.siliconflow.cn/v1",
        "apiKey": "...",
        "model": "BAAI/bge-m3"
      }
    }
  }
}

效果要等大约一周才看得到。在那之前根本没东西可搜。

ContextEngine——v2026.3.7 之后的转向

到 v2026.3.6 为止，记忆是个显式工具：Agent 必须主动调 memory_search、memory_get 才能拿到历史信息。一忘就等于没记忆。

从 v2026.3.7 起，记忆改成了 hooks 生命周期，由 harness 围绕 Agent 自动跑：

bootstrap   → 第一轮之前先加载先验
ingest      → 出现新事实时实时吸收
assemble    → 拼出最终 Prompt 切片
compact     → 按预算裁剪
afterTurn   → 每一轮结束后写回变化

Agent 不再决定什么时候去记，harness 决定。听起来是小变化，其实不是。它把"Agent 记得去记忆"变成了"系统替你记，没条件可讲"。

默认的 ContextEngine 适用于绝大多数人。要换成 RAG 检索器或者知识图谱后端也行——Agent 配置不动，换一个引擎插件即可。

它仍然会漏的地方

我目前还会被咬到的三件事：

群聊和子 Agent 默认不读 MEMORY.md。 这是有意为之——群上下文是共享的，子 Agent 应该是沙箱——但忘了这点，你会花一下午想"为什么团队群里的 bot 不知道我叫什么"。
Embedding 漂移。 换 embedding 模型，旧向量全废。要么重建索引，要么忍受召回下降。没有自动迁移。
40 行的纪律没人替你守。 加一条每周 cron，wc -l MEMORY.md 超过 40 就大声报错。比"我会注意的"靠谱得多。

每个周日我跑这三行体检：

1
2
3
wc -l ~/.openclaw/workspace/MEMORY.md      # < 40
ls -lt ~/.openclaw/workspace/memory/*.md | head
ls ~/.openclaw/agents/main/sessions/*.jsonl | wc -l

MEMORY.md 一旦超 40 行，就有东西该挪到 projects.md 或 lessons.md。session 文件堆到几百以上，就该归档——不然启动会越来越慢。

一句话总结

MEMORY.md 是索引，不是数据库。
第一天就把 memoryFlush 打开。
memorySearch 等到有东西可搜的时候再加。
v2026.3.7 之后，别再让 Agent 记着去记忆，让 engine 替你记。
记忆决定 Agent 用起来像工具还是像同事。这点纪律值得守。