内置记忆引擎

内置引擎是默认的记忆后端。它将你的记忆索引存储在按代理划分的 SQLite 数据库中，并且无需额外依赖即可开始使用。

它提供什么¶

• 通过 FTS5 全文索引实现关键词搜索（BM25 评分）。
• 通过任意受支持提供商的嵌入实现向量搜索。
• 混合搜索将两者结合以获得最佳结果。
• 根据相关性、时效性和写入时重要性进行确定性排序。
• 多样性感知排序，混合结果默认启用 MMR。
• 用于有界的回复前上下文的可信触发召回，无需召回模型。
• 通过三元组分词为中文、日文和韩文提供CJK 支持。
• 用于数据库内向量查询的 sqlite-vec 加速（可选）。

原生 sqlite-vec 查询在独立的只读进程中运行，因此慢查询不会阻塞 Gateway 事件循环。取消搜索会终止其查询进程；OpenClaw 不会在 Gateway 线程上重试该原生查询。查询会为每个数据库复用一个进程，最多保持两个进程存活。空闲进程会在 30 分钟后退出，或在另一个数据库需要容量时退出。每个查询都会重新打开数据库，因此已提交的更新和替换后的索引仍然可见。

关键词检索、召回元数据、精选触发器和项目候选项以及源时间戳使用记忆搜索工作进程。Gateway 等待投影行并应用相同的排序。仅限会话的搜索将其最终元数据和时间戳读取保留在调用方上，因为额外的工作进程请求会增加实测延迟；其他检索读取在 Gateway 事件循环之外运行。搜索会保留其索引代，直到工作进程关闭其读取器；召回元数据在候选项检索之后读取，因此已遗忘的块会被排除。这不会更改存储的数据、配置或升级行为。

在 Gateway 就绪后，空闲预热会在首次搜索之前加载处于活动状态的 Memory Core 检索工作进程。它不会打开索引、启动嵌入提供商或延迟就绪。在预热完成前到达的请求仍会正常初始化检索；工作进程保留其现有的空闲退出策略。

如果语义检索在来自记忆文件的关键词匹配已就绪后达到 30 秒工具截止时间，memory_search 会返回这些匹配项并附带部分结果警告。会话转录命中需要新的可见性检查，并且被排除在超时恢复之外。部分响应不会将整个记忆语料库放入超时冷却。当代理未提供最终回复时，回退警告会说明超时时长以及是否有部分结果可用。

何时使用¶

对于大多数用户而言，内置引擎是合适的选择：

• 开箱即用，无需额外依赖。
• 能很好地处理关键词搜索和向量搜索。
• 支持所有嵌入提供商。
• 混合搜索结合了两种检索方式的优点。

内置引擎可以使用 memory.search.extraPaths 索引工作区之外的目录。它使用有界的词汇查询扩展来改善对话召回，但不提供基于学习或模型的相关性重排序阶段。其 MMR 处理是确定性的且本地的。

如果你希望拥有跨会话记忆和自动用户建模，请考虑 Honcho。

快速开始¶

默认情况下，内置引擎使用 OpenAI 嵌入。如果已配置 OPENAI_API_KEY 或 models.providers.openai.apiKey，则无需额外记忆配置即可使用向量搜索。

要显式设置提供商：

{
  memory: {
    search: {
      provider: "openai",
    },
  },
}

如果没有嵌入提供商，则只能使用关键词搜索。

要强制使用本地 GGUF 嵌入，请安装并配置官方 llama.cpp 提供商，然后将 local.modelPath 指向一个 GGUF 文件：

openclaw plugins install @openclaw/llama-cpp-provider

{
  memory: {
    search: {
      provider: "local",
      fallback: "none",
      local: {
        modelPath: "~/.openclaw/models/llama.cpp/hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
      },
    },
  },
}

支持的嵌入提供商¶

设置 memory.search.provider 可从 OpenAI 切换到其他提供商。

索引工作原理¶

OpenClaw 将 MEMORY.md、已存在的根目录 USER.md 以及 memory/*.md 索引为 块（默认 400 个 token，重叠 80 个 token），并将它们存储在按代理划分的 SQLite 数据库中。OpenClaw 不会自动创建 USER.md。

每个块都可以携带可空的重要性和触发器元数据。空值是中性的，因此旧索引仍然可用。搜索在应用 MMR 多样性之前，会结合混合相关性、时效性衰减和重要性；触发器召回仅注入精选或已提升为可信的条目。

每个已索引块还具有由 SQLite 拥有的来源信息：来源类别（owner、 agent、untrusted 或 system）、会话类型、观察时间以及可选的取代键。此元数据与 Markdown 分开存储，因此召回的文本无法重写其自身的信任分类。自动会话摄取还会为其暂存条目记录源会话来源，从而支持提升后的选择性删除。有关覆盖范围和限制，请参阅 记忆来源与删除。

• 索引位置： 所属 agent 数据库位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• 存储维护： SQLite WAL 附属文件通过定期检查和关闭时检查点保持有界。
• 文件监视： 内存文件变更会触发防抖重建索引（默认 1.5 秒）。
• 索引兼容性： 更改嵌入 provider、模型、设置、已配置来源或范围可能会暂停搜索，直到你显式重建。 参见 provider 选择。
• 按需重建索引： openclaw memory index --force --agent <id>

当索引身份报告 OpenClaw 分块实现变更时，普通搜索或 CLI 搜索会在返回结果前重建它。重建使用 agent 当前的嵌入设置；状态检查保持只读。

搜索触发的维护会增量应用待处理的内存和会话变更，同时搜索保持可用。失败的全量重建会保留其全量重试状态；普通脏内容本身不会强制重建。如果内存文件在索引期间变更或消失，只会增量重试该文件未完成的工作。其他文件完成索引，且变更文件的过期分块不会被发布。

如果主机原生文件监视容量耗尽，Memory Core 会记录一条警告并禁用其监视器。后续搜索会触发增量同步以发现文件变更。在后台工作完成期间，搜索可以返回上一个索引；后续搜索会看到更新后的内容。恢复监视容量后，重启 Gateway 以再次启用原生监视。

增量索引、过期来源清理和缓存修剪会在另一个 SQLite 写入器处于活动状态时异步等待。缓存修剪以有界批次删除最旧的条目，在批次之间让出，同时保留现有缓存上限。

全量重建索引会在临时数据库中构建替换版本，并原子地发布内存表。并发搜索和状态读取继续使用已发布的索引；失败的重建会保持该索引完整。嵌入缓存会在发布前进行限制，而不是在将多余条目复制到共享数据库之后。

其他 agent 状态（包括同一数据库中的会话和转录）会被保留。使用 memory index 命令 进行仅内存修复。

openclaw memory status 报告每个来源的已存储分块文本和二进制嵌入字节（JSON 中的 sourceCounts[].chunkBytes）。这些是负载大小，不是总磁盘使用量：嵌入缓存、FTS/向量表、SQLite 开销以及 WAL/空闲页均被排除。

分块和嵌入缓存向量使用小端 64 位浮点数 BLOB。即使可选的 sqlite-vec 加速器不可用，软件搜索回退也会读取这些全精度向量；sqlite-vec 保留其独立的 32 位向量索引。关键词索引使用每个分块的稳定整数标识，因此编辑和删除会直接更新对应的 FTS 行。

Agent schema 23 在本地转换现有 JSON 向量，而不联系嵌入 provider。它保留分块 ID、来源信息、召回元数据和缓存标识。格式错误的旧向量会保留其可搜索文本，并将其来源标记为需要重建索引。无法保留的未知 schema 扩展会导致迁移停止，而不重写这些表。升级或回退到旧版本时，请遵循 数据库版本控制和回滚契约。

升级后，自动项目召回和触发器召回可能需要修复旧来源信息。该修复在后台运行。在受影响的来源被重新分类之前，自动召回保持为空，但回复会继续。

从 QMD 迁移¶

QMD 已被移除；builtin 是唯一的内存引擎。升级后，运行：

openclaw doctor --fix

Doctor 会移除已弃用的 memory.backend、memory.qmd 和 memory.search.qmd 设置，包括 agent 范围的 memory.search.qmd 形式。它会保留 QMD 路径和额外集合作为对应的 memory.search.extraPaths 条目，包括 { path, pattern } glob。当 QMD 会话索引已启用时，Doctor 还会启用 builtin 会话索引 并将 sessions 添加到 memory.search.sources，而不会启用更广泛的 跨会话召回。保留的会话重置转录仍位于 agent 的会话目录中，并从这些原始工件中索引。

Doctor 仅移除 ~/.openclaw/agents/<agentId>/qmd/ 下每个 agent 的空 QMD 目录。非空目录保持不动： OpenClaw 已弃用的 QMD 后端与独立 QMD 使用相同的布局，且没有 所有权标记。保留的目录不会阻止迁移或 Gateway 启动。备份后，如果你确认没有独立 QMD 安装使用它们， 可以手动删除旧索引、模型下载、集合元数据和会话导出。

规范内存仍位于 MEMORY.md、USER.md、memory/*.md 以及 迁移后的额外路径中。Builtin 会在下次同步时索引这些相同的 Markdown 来源。切换在设计上是无损的：不会复制或删除任何规范内存内容；只会重建派生状态。

Builtin 现在通过以下方式覆盖大多数 QMD 用例：

• 默认使用混合 BM25 和向量检索，随后在 MMR 多样性之前应用时间衰减、 重要性和项目亲和度，
• 为对话式搜索提供有界词汇查询扩展，
• memory.search.extraPaths 中的字符串或 { path, pattern } 条目，以及
• 仅在 extraPaths 下可选的图像和音频索引。

QMD 查询模式的已学习交叉编码器重排序和 HyDE 生成不属于 builtin 内存。MMR 会减少重复结果，但不是已学习的相关性重排序器。要替换 QMD 的进程内、零密钥 GGUF 嵌入，请安装 llama.cpp provider 并设置 memory.search.provider: "local"；如果没有嵌入 provider，builtin 仅使用 BM25 关键词搜索。

故障排查¶

记忆搜索已禁用？ 检查 openclaw memory status。如果未检测到任何提供商，请显式设置一个或添加 API 密钥。

未检测到本地提供商？ 使用 openclaw onboard 运行一次交互式 llama.cpp 设置，确认本地路径存在，然后运行：

openclaw memory status --deep --agent main
openclaw memory index --force --agent main

独立 CLI 命令和 Gateway 都使用相同的 local 提供商 ID。 当你想要本地嵌入时，设置 memory.search.provider: "local"。

结果过期？ 运行 openclaw memory index --force 以重建。监视器 在极少数边缘情况下可能会遗漏更改。

sqlite-vec 未加载？ OpenClaw 会自动回退到进程内余弦 相似度。openclaw memory status --deep 会将本地向量存储与嵌入提供商分开报告，因此 Vector store: unavailable 指向 sqlite-vec 加载问题，而 Embeddings: unavailable 指向提供商/身份验证或模型就绪问题。请检查日志以获取具体的加载 错误。

安全索引恢复¶

在结果过期或嵌入提供商变更后重建时，请显式选择 受影响的代理：

openclaw memory status --agent <agent-id> --deep
openclaw memory index --agent <agent-id> --force --verbose
openclaw memory status --agent <agent-id> --deep

在重建之前丢弃派生索引和嵌入缓存，请使用 memory reset：

openclaw memory reset --agent <agent-id>
openclaw memory index --agent <agent-id>

重置会要求确认；对于非交互式使用，请添加 --yes。它仅清除 记忆拥有的派生表，保留非记忆数据库表，包括 会话和转录，以及记忆源文件。它会与现有 记忆维护协调，而无需重启 Gateway；之后 Gateway 可以重新索引 保留的源。如果索引正在忙碌，请等待其完成并重试重置。 重置不会缩小数据库文件或恢复已删除的数据。

如果索引失败或数据库意外增长，请保留数据库 及其附属文件，保留详细错误，并在手动恢复之前创建并验证备份。 仅凭大型数据库无法显示哪些表是原因。重新索引不是会话历史恢复：如果在移动或删除数据库后历史缺失，请使用 恢复工作流从已验证的备份中恢复。

回收磁盘空间¶

从 openclaw memory status --agent <agent-id> --json 开始。比较 数据库和 WAL 大小、可重用字节、保留的嵌入缓存负载以及 每个源的块负载。可重用字节是 SQLite 内部已经空闲的页面； 它们不是额外数据。缓存和块负载不包括索引和 SQLite 开销，因此它们无法解释共享文件中的每个字节。

如果需要丢弃派生索引，请创建并验证 备份，然后通过其部署所有者停止 Gateway，并 停止其他写入者。在重置和压缩期间保持它们停止，以便后台 索引无法在命令之间重新填充缓存：

openclaw memory reset --agent <agent-id> --yes
openclaw doctor --session-sqlite compact --session-sqlite-agent <agent-id>
openclaw memory index --agent <agent-id>
openclaw memory status --agent <agent-id>

如果只需要回收未使用的页面，请跳过重置并保留现有索引。 Doctor 会压缩整个代理数据库，验证完整性，并报告 压缩前后的数据库和 WAL 大小。压缩需要临时磁盘空间；在 卷已满时，请先释放空间或将已验证的备份移动到具有足够 容量的卷，然后再尝试。重建可能会调用嵌入提供商并 产生费用。验证后，通过其部署所有者重启 Gateway。 重置和压缩都不会删除规范会话或更改保留策略。

配置¶

有关嵌入提供商设置、搜索结果限制和阈值、批量 索引、多模态记忆、sqlite-vec、额外路径以及所有其他配置 项，请参阅 记忆配置参考。

相关¶

• 记忆概览
• 记忆搜索
• 活动记忆