Software 2.0

OpenClaw 的记忆机制

admin -

OpenClaw 是一个在您自己的硬件上运行的开源 AI 助手。它在 WhatsApp、Telegram、Slack、Discord 等多个平台上工作。该项目于 2025 年 11 月作为 Clawdbot 开始，在收到 Anthropic 的商标投诉后更名为 Moltbot，最终确定为 OpenClaw。超过 190,000 个 GitHub 星标。MIT 许可证。

大多数 AI 记忆系统将上下文存储在您无法检查的专有数据库中。OpenClaw 采用了不同的方法。它将所有内容写入磁盘上的普通 Markdown 文件，使用混合搜索对它们进行索引，并在需要时检索相关上下文。您可以使用 Git 打开、编辑和版本控制这些文件。这些文件就是记忆。

1、OpenClaw 记忆的两种类型

OpenClaw 记忆分为两层，每一层都作为工作区目录中的 Markdown 文件存储（默认：~/.openclaw/workspace）。

长期记忆： MEMORY.md

这个文件保存持久的事实。决策、偏好、重复模式。它在私有会话开始时被加载到系统提示词中（从不进行群组聊天，出于隐私考虑）。

这里的内容示例：

  • "用户更喜欢 Python 而不是 JavaScript"
  • "项目使用 PostgreSQL 15"
  • "提交前总是运行测试"

每日日志： memory/YYYY-MM-DD.md

这些是用于运行上下文的仅追加文件。今天发生了什么。哪些任务正在进行中。对话中的笔记。与 MEMORY.md 不同，每日日志不会自动注入到提示词中。AI 在需要最近的上下文时，使用其内置的 memory_search 和 memory_get 工具按需检索它们。

划分很简单：如果信息下个月还重要，它就进入 MEMORY.md。如果它今天重要，它就进入每日日志。

OpenClaw 如何从 Markdown 文件存储、索引和检索记忆。

2、OpenClaw 记忆搜索如何工作

将记忆存储在文件中很简单。当 AI 需要时找到正确的记忆是困难的部分。

OpenClaw 使用混合搜索，结合两种不同的方法来查找相关记忆。

2.1 向量搜索（语义）

当保存记忆文件时，OpenClaw 将其分解为大约 400 个令牌的块，块之间有 80 个令牌的重叠。每个块都使用嵌入模型（OpenAI、Gemini、Voyage 或本地模型）转换为数字表示（称为嵌入）。

当 AI 需要回忆某事时，查询也会被嵌入。然后系统使用余弦距离找到嵌入与查询嵌入最接近的块。这捕获语义匹配。搜索"数据库偏好"会找到一个块说"总是使用 PostgreSQL"，即使单词完全不同。

这些嵌入存储在 ~/.openclaw/memory/{agentId}.sqlite 中的 SQLite 数据库中，使用 sqlite-vec 扩展进行快速最近邻查找。

2.2 关键词搜索（BM25）

向量搜索擅长意义。它并不总是擅长精确术语。如果您搜索"PostgreSQL 15.4"而记忆正是这样说的，关键词匹配比语义匹配更可靠。

OpenClaw 使用 SQLite 的 FTS5（全文搜索）模块进行 BM25 关键词排名。这处理精确短语、特定名称和技术术语。

2.3 结合两种结果

两次搜索并行运行。每次返回一个候选池（默认：4x 最终结果计数）。系统使用加权评分合并它们：

最终分数 = (向量分数 x 0.7) + (关键词分数 x 0.3)

向量搜索获得 70% 的权重，因为在大多数情况下语义理解更重要。关键词搜索获得 30% 以捕获精确匹配。低于最小相关性分数的结果被过滤掉。前 6 个结果（默认）作为 Markdown 片段返回给 AI，每个片段大约 700 个字符，带有文件路径和行号。

AI 通过两个内置工具访问它：memory_search 用于跨所有索引文件的混合查询，memory_get 用于通过路径读取特定文件。如果用户问"我们使用什么数据库？"，AI 调用 memory_search，从 MEMORY.md 获取相关块，并回答。

3、上下文窗口问题

每个 AI 模型都有一个上下文窗口。它是一次可以处理的文本总量。对于 200K 令牌模型，这大约是 150,000 个单词。听起来很多，但长对话会将其填满。

当上下文窗口填满时，AI 无法处理更多输入。大多数系统只是失败或切断较旧的消息。OpenClaw 通过自动压缩来处理这个问题。

OpenClaw 记忆如何处理自动压缩

当会话接近上下文限制时，OpenClaw 压缩对话历史。这是序列：

  1. 检测。 OpenClaw 监控令牌使用情况。当它达到阈值（上下文窗口减去保留令牌减去软缓冲区）时，它会触发压缩。
  2. 压缩前记忆刷新。 在压缩之前，OpenClaw 触发一个静默回合。它告诉 AI："您即将失去上下文。现在将任何重要内容写入记忆文件。" AI 将持久信息保存到 MEMORY.md 或每日日志。这是一个安全网。通过在会话状态中跟踪计数器来防止双重刷新。
  3. 压缩。 SDK 压缩对话历史。它在压缩冗余交换的同时保留事实信息和决策。时间顺序被保留。工具使用结果被保留。
  4. 重试。 触发溢出的原始请求使用压缩后的历史记录重试。

如果压缩本身失败（压缩请求超过其自己的上下文限制），OpenClaw 回退到会话重置。它生成一个新的会话 ID 并重新开始。这是最后手段。对话上下文丢失，但在刷新期间保存的记忆在 Markdown 文件中幸存。

OpenClaw 还有额外的回退机制（例如降低模型的思考级别）以从持久溢出情况中恢复。

当对话接近上下文窗口限制时会发生什么。

4、嵌入提供商和可选功能

OpenClaw 按此顺序自动选择嵌入提供商：首先是本地模型（完全离线，无 API 调用），然后是 OpenAI、Gemini 或 Voyage（如果有 API 密钥可用）。如果您希望没有任何东西离开您的机器，本地选项很重要。云选项更快，需要的设置更少。嵌入缓存防止在重新索引期间重新处理未更改的块。

两个实验性功能扩展了基础系统。QMD 后端完全在您的机器上作为辅助进程运行 BM25 + 向量 + 重新排序。会话记忆（启用时）在工作区文件旁边索引对话记录，以便 AI 可以搜索过去的对话，而不仅仅是显式保存的内容。

5、权衡

OpenClaw 记忆背后的核心原则是文件是事实的来源。SQLite 索引派生自它们。如果删除索引，它会重建。如果编辑文件，索引会在下次同步时更新。

您获得的：对 AI 记住的内容有完全透明度，能够通过编辑文本文件来纠正它，以及可移植性（复制文件夹，记忆随附）。

您失去的：关系映射。OpenClaw 的原生记忆不构建知识图或跟踪概念如何相互连接。它找到相关块，但它不推理它们之间的连接。第三方集成如 Cognee 和 Mem0 为需要它们的团队添加基于图的功能。

作为构建自动化工具的人，文件优先方法是我发现最实用的部分。能够打开 MEMORY.md 并看到 AI 恰好保留了什么（并修复它弄错的内容）消除了大多数 AI 记忆系统仍然有的猜测层。

6、常见问题

OpenClaw 记忆在会话之间持久化吗？

是的。OpenClaw 将记忆写入磁盘上的 Markdown 文件。这些文件跨会话、重启和频道切换幸存。在会话开始时，MEMORY.md 自动注入到系统提示词中。每日日志不会自动加载，但 AI 可以通过其搜索工具按需检索它们。

OpenClaw 在哪里存储记忆文件？

默认情况下，在 ~/.openclaw/workspace 中。长期事实进入 MEMORY.md。每日上下文进入 memory/YYYY-MM-DD.md。SQLite 索引位于 ~/.openclaw/memory/{agentId}.sqlite。

我可以手动编辑 OpenClaw 记忆吗？

是的。记忆文件是普通 Markdown。在任何文本编辑器中打开它们，进行更改，索引会在下次同步时更新。这是相对于使用专有存储的系统的主要优势之一。

OpenClaw 记忆离线工作吗？

存储和基于文件的检索在本地工作。嵌入生成需要本地模型或 API 调用（OpenAI、Gemini 或 Voyage）。如果没有任何嵌入提供商，搜索回退到仅 BM25 关键词匹配。

7、结束语

下面是OpenClaw记忆实现的快速总结：

  • 存储： 普通 Markdown 文件（MEMORY.md + 每日日志）
  • 索引： 400 令牌块，80 令牌重叠
  • 搜索： 混合：向量（70%）+ BM25 关键词（30%）
  • 数据库： 带有 sqlite-vec 和 FTS5 的 SQLite
  • 压缩： 接近上下文窗口限制时自动压缩
  • 记忆刷新： 压缩前静默保存以防止数据丢失
  • 回退： 如果压缩失败则重置会话
  • 提供商： 本地、OpenAI、Gemini 或 Voyage 嵌入

官方 OpenClaw 记忆文档 详细介绍了配置选项。

原文链接: How OpenClaw Memory Works

汇智网翻译整理，转载请标明出处