# 随便聊聊OpenClaw记忆系统

> OpenClaw记忆系统解析：不用向量数据库，用纯Markdown文件做AI Agent的长期记忆——MEMORY.md、按天日志、会话归档三层文件各有加载策略和安全边界；写入由Prompt原则引导智能体自主决策而非固定规则，配合预压缩记忆刷新和向量+BM25混合检索的memory_search工具。

Canonical: https://doraemeng.dev/notes/openclaw-memory-system/


OpenClaw 的记忆系统里没有向量数据库。长期记忆、每日日志、会话归档全部是工作区里的 Markdown 文件，开发者可以直接打开看，也可以直接改。这个选择很反常：检索、去重、过期清理都得自己处理；但它把「Agent 到底记住了什么」变成了一件可以 git diff 的事，对一个需要长期运行的个人 Agent，这个可解释性往往比检索召回率更值钱。

这篇笔记的事实来自 Eternity（阿里巴巴）2026-02-13 的知乎文章（https://zhuanlan.zhihu.com/p/2005632275774195031）。下面的机制描述来自原文，判断和取舍由我补充；原文没有给出的数据，我用占位符标出。

## 三层文件，三种加载边界

这套系统把记忆分成三层，每层的加载策略和安全边界不同。MEMORY.md 放在工作区根目录，存的是经过整理的高层决策、用户偏好和持久事实；它只在主会话（和人类所有者的直接对话）里加载，Discord 或群聊等共享场景会把它排除在外。Daily Logs 放在 memory/YYYY-MM-DD.md，记录当天的笔记和持续更新的上下文；每次会话自动加载今天和前一天的文件，相当于给 Agent 一段短期工作记忆。Session Archives 放在 memory/YYYY-MM-DD-{slug}.md，是过往会话的静态归档，文件名的 slug 由大语言模型生成；它们不会被自动加载，只有 Agent 显式调用检索工具时才会被读到。

三层文件覆盖了三种时间尺度，真正的设计点在加载边界：主会话的私密记忆不能进群聊，最近的上下文要便宜地随取随用，旧会话则按需检索，避免把整个历史塞进 prompt。MEMORY.md 只在主会话加载这一条，把「记忆」和「隐私边界」绑在了一起；Daily Logs 的今天加昨天，则是在新鲜度和 token 成本之间取了一个固定窗口；Session Archives 不自动加载，意味着历史信息默认是冷的，只有检索命中才会被拉进上下文。

## 写入：规则留给 Prompt，格式留给文件

更新机制没有一张「什么该写、什么不该写」的硬编码规则表。Agent 拥有完整的文件读写权限，是否写入、写到 MEMORY.md 还是当天的日志，取决于当前上下文、System Prompt 里的行为约定和用户的显式指令。用户说「记住这个」时，Agent 调用文件写入工具更新 MEMORY.md 或 memory/YYYY-MM-DD.md。这个设计把判断交给了模型，好处是能处理规则覆盖不到的情况；代价是写入行为不确定，同一个信息可能今天被写进长期记忆，明天只留在日志里。要让这套机制稳定，Prompt 里的边界必须写得足够具体，否则「重要」这个词会由模型每次重新解释。

当上下文接近压缩上限时，系统会插入一次「预压缩记忆刷新」。它先检查权限确认，跳过沙箱、命令行模式和心跳模式；然后暂停会话，插入整理步骤，整个过程对用户无感知。和常见的上下文压缩不同，它在删除旧消息之前给模型一次持久化机会：比如保存具体的手机号码，而不是把它压缩成「用户提到一个手机号码」。这个顺序很关键——压缩是不可逆的信息损失，刷新把「哪些细节值得留」的判断提前到信息还完整的时候。代价是压缩发生的时点本来就很紧张，额外一轮整理会拉长这次会话的停顿；原文没有给出刷新耗时，[待补：预压缩刷新在主会话中的实际延迟与失败回退策略]。预压缩刷新用的系统提示词很短：

```
"Pre-compaction memory flush turn.",
"The session is near auto-compaction; capture durable memories to disk.",
You may reply, but usually ${SILENT_REPLY_TOKEN} is correct.
```

它只说了「把持久记忆落到磁盘」，没有规定写哪些字段；具体写什么仍然由模型判断。这也解释了为什么同一套系统在不同用户手里会形成完全不同的记忆结构：Prompt 只给了方向，结构是模型和用户在日常对话里共同长出来的。

用户执行 `/new` 时，会触发 session-memory hook：把上一段对话（默认最近 15 条原始消息）保存成 Markdown 文件，调用 LLM 生成一个 1-2 个词的 slug，文件名是 YYYY-MM-DD-{slug}.md；没有生成 slug 时退回时间戳 YYYY-MM-DD-{HHMM}.md。slug 的提示词要求小写、连字符分隔、不要文件扩展名，只回复 slug 本身，并给了 vendor-pitch、api-design、bug-fix 三个例子：

```
Based on this conversation, generate a short 1-2 word filename slug (lowercase, hyphen-separated, no file extension.
Reply with ONLY the slug, nothing else. Examples: "vendor-pitch", "api-design", "bug-fix"
```

这个细节看起来琐碎，实际决定了归档能不能被检索到。文件名本身就是一层索引：slug 起得准，人和 Agent 都能靠路径先缩小范围；起不准，就只能回到全文搜索。

## 检索：向量负责语义，BM25 负责精确串

检索侧有两个工具。memory_search 在 MEMORY.md 和 memory/*.md 上做混合搜索：向量搜索负责语义相近，BM25 负责精确匹配，两者通过权重控制；返回的是最相关的片段、文件路径和行号。memory_get 在 memory_search 的基础上读取指定行范围，让 Agent 可以只展开命中的那一段，而不是把整个文件读进上下文。这个分工解决的是两件不同的事：向量搜索能处理「上次说的那个部署方案」这种换了说法的查询，BM25 能处理手机号、错误码、函数名这种必须逐字命中的串；只留一种，总有一类查询会失手。

BM25 按词频和逆文档频率打分，查询词必须真的出现在文本里，所以它对精确串很可靠，但对同义改写无能为力；向量搜索把文本映射到嵌入空间，能跨过措辞差异，却可能把「相似但不对」的片段排到前面。混合搜索的价值在于让两类召回互相补位，权重则决定了默认偏向哪一边。memory_get 返回行范围这件事看起来小，实际是在控制上下文成本：检索命中后只读那几行，比把整个归档文件塞进 prompt 便宜得多。

## 这套设计的账本

这套设计的账本在 token 和写入确定性上。自动加载的 MEMORY.md 和最近两天日志会直接占用上下文窗口，文件越大，留给对话的空间越少；原文没有给单文件大小上限或截断策略，[待补：自动加载的截断规则与典型 token 占用]。写入交给模型判断，意味着记忆质量取决于 Prompt 和模型当天的判断，不能像数据库事务那样保证「写一次就一定在」。在单用户、记忆量不大的个人 Agent 场景，这些代价还能接受；到了多用户或大记忆量场景，检索和隔离的要求会反过来逼你上更重的存储。

原帖评论区有人问触发 compaction 时为什么像卡住一样、等很久没反应；另一位读者说「这么干太消耗 token」。原文没有给出压缩和刷新的耗时数据，第一个问题只能按机制定位：刷新要在压缩前插入一轮模型调用，如果模型响应慢或工具调用重试，用户看到的就是停顿。第二个问题在上面已经算过账，它和停顿指向同一个边界——纯文件方案在记忆量小的时候很舒服，记忆一多，token 成本和停顿会先于检索精度成为瓶颈。

如果让我给一个判断：单人使用的 Agent，先把 Markdown 记忆做扎实，别急着上向量库；等 MEMORY.md 大到每次加载都心疼，再谈分块索引和归档策略。下一步该补的是加载上限、写入校验和压缩耗时的可观测性；换存储引擎可以往后放。这三样缺一个，长会话出问题时你就只能靠猜。

