OpenClaw Memory 设计解析：从文件化记忆到可扩展检索架构

OpenClaw 的 Memory 设计有一个很明确的立场：记忆不是模型内部状态，而是可落盘、可检索、可审计的数据。

这让它和“纯对话上下文”型 Agent 走了不同路线。你看到的不是一个黑箱记忆体，而是一个工程系统：文件是事实源，索引是派生层，检索工具是访问入口。

设计原理：Memory 不是神经状态，而是工程状态

OpenClaw 的核心设计可以概括为 3 条。

记忆以文件为中心，模型只读取被写入的内容。
检索层与存储层分离，索引可以重建。
Memory 的生命周期受工程机制约束，而不是依赖对话偶然性。

这套设计把“记住了什么”从不可观测状态，变成了可观测、可回放、可治理的状态。对中大型团队来说，这比“模型说它记得”更可靠。

架构分层：文件层、索引层、工具层

文件层：Source of Truth

常见结构是：

MEMORY.md：长期记忆，偏事实、偏好、规则。
memory/YYYY-MM-DD.md：短期日志，按日累积事件。

这个分层本质是把知识分为“稳定信息”和“过程信息”。

索引层：可丢弃的加速层

OpenClaw 会对文件分块后建立检索索引，常见实现是向量检索与关键词检索组合。索引的角色是加速，不是事实源。

这意味着：

索引坏了可以重建。
存储迁移成本低。
运维问题与数据语义问题可以拆开处理。

工具层：受控访问记忆

一般通过 memory_search、memory_get 一类工具访问记忆：

memory_search 负责召回相关片段。
memory_get 负责按路径或范围读取原文。

这比“把整份 Memory 丢进上下文”更稳。上下文窗口由工具调用节流，而不是由开发者手工猜测。

隔离设计：多维边界而不是单一边界

Memory 系统是否可用于生产，关键在隔离。

OpenClaw 的隔离通常至少有 3 层：

Agent 级隔离：不同 Agent 绑定不同会话与索引。
Workspace 级隔离：不同工作区物理隔离文件。
Session 级隔离：按会话轨迹组织与检索。

这 3 层同时存在时，能显著降低“跨任务污染”和“跨用户泄漏”风险。

可扩展性：把 Memory 做成槽位，而不是做成特性

OpenClaw 的可扩展点主要在两个方向。

后端可替换：文件与索引实现可替换或增强。
数据源可扩展：除默认记忆文件外，可接入外部文档路径。

如果你把它理解为“面向 Agent 的轻量 RAG 平台”，很多设计选择会更容易理解。它不是要模拟人脑，而是要让记忆系统在工程上可进化。

QMD：OpenClaw 的实验性 Memory 后端

在 OpenClaw 扩展体系里，QMD 可以理解为本地优先的检索 Sidecar。启用后，Memory 仍以 Markdown 为事实源，但检索执行从默认内置实现切换到 QMD。

QMD 的定位

QMD 不替代 Memory 文件层，只替代索引与检索执行层。它通常强调 3 件事：

本地运行优先，减少外部依赖。
混合检索（BM25 + 向量）并支持重排序。
与 memory_search、memory_get 工具接口兼容。

启用方式与配置项

最小配置通常是：

{
  "memory": {
    "backend": "qmd"
  }
}

常见参数一般在 memory.qmd.*，例如：

command：QMD 可执行文件路径。
searchMode：检索命令模式。
includeDefaultMemory：是否包含默认记忆文件。
paths：额外索引路径。
update：更新周期、超时、启动同步策略。
limits：Top-K、片段长度、查询超时。

运行机制（工程视角）

QMD 模式下，系统通常按以下流程执行：

启动时初始化 QMD 集合。
将默认 Memory 与额外路径建立索引。
周期执行 update，处理文件增量变更。
执行检索并将结果回传到 Memory 工具层。

当 QMD 进程不可用或执行异常时，建议保留回退到内置后端的路径，避免 Memory 工具中断。

适用场景与代价

适用场景：

文档规模增大后，默认检索召回不稳定。
需要更强的重排序能力来提高 Top-K 有效率。
需要离线、本地化、可控的检索链路。

新增代价：

需要安装并维护 QMD 运行环境。
首次启用可能涉及模型下载与冷启动等待。
需要额外调优更新频率、超时和资源占用。

优点：透明、可控、可调试

1. 可审计

Memory 文件可直接查看，问题定位不依赖模型解释。

2. 可版本化

文件天然适配 Git 流程，变更可追踪、可回滚。

3. 可运维

索引重建、数据清理、权限治理都能落到常规工程能力。

4. 成本可管理

通过分层和检索策略，能避免把所有历史硬塞进上下文。

缺点：工程责任前移

1. 质量依赖写入策略

如果写入规则设计不当，系统会“记错”或“记不住”。

2. 记忆膨胀风险

按日追加很容易变成长尾噪声，召回质量会下降。

3. 检索并不等于理解

召回到了相关片段，不代表模型一定正确使用它。

4. 配置复杂度提升

隔离、索引、缓存、路径策略都要治理，初期门槛比纯对话高。

实践建议：从“可用”走向“可运营”

1. 做三层记忆治理

建议至少拆成：

会话工作记忆（短周期）
事件记忆（天/周）
语义记忆（长期事实）

2. 建立定期压缩机制

每天追加日志，每周做摘要归档。不要让检索长期面对原始流水账。

3. 固定检索评估指标

至少监控：

Top-K 命中率
无关召回率
关键事实遗漏率

没有指标，优化只会停留在感觉层面。

4. QMD 建议做双路径回退演练

若启用了 memory.backend = "qmd"，建议在预发环境定期演练“QMD 失败 -> 内置后端回退”。

重点验证：

工具调用链是否无感切换。
召回质量是否在可接受区间。
告警与日志是否足够定位问题。

5. 把权限当成架构的一部分

Memory 文件是明文资产，必须做目录权限、进程边界和环境隔离。不要把它当普通临时缓存。

注意点：4 个容易踩坑的地方

不要把 MEMORY.md 变成巨型百科，长期层应只保留高价值事实。
不要只做向量检索，关键词检索对 ID、术语、路径类信息很关键。
不要忽略冷启动，先定义最小写入模板再放开自动写入。
不要把“能检索”误判为“能决策”，关键动作仍需规则约束。

总结

OpenClaw Memory 的价值不在“更像人”，而在“更像工程系统”。

它把记忆问题拆成可治理的 3 个子问题：存储、检索、策略。这个拆分让你可以独立迭代每一层，并在复杂场景里保持可解释性与可控性。

如果你的目标是做可长期运行的 Agent，而不是一次性 Demo，这条路线比“把上下文不断加长”更现实。