它提供什么
- 通过 FTS5 全文索引（BM25 评分）进行关键词搜索。
- 通过任意受支持的提供商生成的嵌入向量进行向量搜索。
- 结合两者以获得最佳结果的混合搜索。
- 根据相关性、时效性和写入时重要性进行确定性排序。
- 多样性感知排序，默认对混合结果启用 MMR。
- 可信触发器召回，无需召回模型即可获取有界的回复前上下文。
- 通过对中文、日文和韩文进行三元组分词实现 CJK 支持。
- 使用 sqlite-vec 加速数据库内向量查询（可选）。
快速开始
默认情况下，内置引擎使用 OpenAI embeddings。如果OPENAI_API_KEY 或
models.providers.openai.apiKey 已经配置好，那么向量搜索无需额外的内存配置即可工作。
要显式设置提供商：
local.modelPath 指向一个 GGUF 文件：
支持的 embedding 提供商
将
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 分开存储，因此被召回的文本不能改写其自身的信任分类。
- 索引位置： 拥有该索引的代理数据库位于
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite - 存储维护： SQLite WAL 侧文件会通过定期检查点和关闭时检查点进行限制。
- 文件监听： 对 memory 文件的更改会触发防抖式重新索引（默认 1.5 秒）。
- 自动重新索引： 当 embedding 提供方、模型、分块配置、已配置的来源或作用域发生变化时，索引会自动重建。
- 按需重新索引：
openclaw memory index --force
你也可以通过
memory.search.extraPaths 索引工作区之外的 Markdown 文件。参见
配置参考。从 QMD 迁移
QMD 已被移除；builtin 是唯一的记忆引擎。升级后，运行：memory.backend、memory.qmd 和
memory.search.qmd 设置，包括针对 agent 的 memory.search.qmd
形式。它会将 QMD 路径和额外集合保留为对应的
memory.search.extraPaths 条目，包括 { path, pattern } glob。当
Memory Core 在 ~/.openclaw/agents/<agentId>/qmd/ 下找到已废弃的按 agent 划分的 QMD 工作区时，Doctor 还会提供删除其派生索引、模型下载、集合元数据和会话导出的选项。
规范记忆仍保存在 MEMORY.md、USER.md、memory/*.md 以及已迁移的
额外路径中。Builtin 会在下一次同步时为这些相同的 Markdown 源建立索引。此次切换从设计上保证无损：不会复制或删除任何规范记忆内容；只会重建派生状态。
Builtin 现在通过以下功能覆盖了大多数 QMD 使用场景：
- 默认使用混合 BM25 和向量检索，随后依次应用时间衰减、重要性和项目亲和度，最后进行 MMR 多样性处理；
- 针对对话式搜索的有界词法查询扩展；
memory.search.extraPaths中的字符串或{ path, pattern }条目；以及- 仅在
extraPaths下可选的图像和音频索引。
memory.search.provider: "local"；如果没有嵌入提供程序，builtin 只会使用 BM25 关键词搜索。
何时使用
对于大多数用户来说，内置引擎是最佳选择：- 开箱即用，无需额外依赖。
- 对关键词和向量搜索都有良好支持。
- 支持所有嵌入提供商。
- 混合搜索结合了两种检索方式的优点。
memory.search.extraPaths 为工作区之外的目录建立索引。它使用有界的词法查询扩展来改善对话记忆召回，但不提供基于学习或模型的相关性重排序阶段。其 MMR 处理过程是确定性的，并且在本地执行。
如果你希望获得带有自动用户建模的跨会话记忆，请考虑 Honcho。
故障排查
内存搜索已禁用？ 检查openclaw memory status。如果没有检测到提供商，请显式设置一个，或添加 API 密钥。
本地提供商未检测到？ 确认本地路径存在，然后运行：
local 提供商 ID。当你希望使用本地嵌入时，请设置
memory.search.provider: "local"。
结果过时？ 运行 openclaw memory index --force 进行重建。监视器在极少数边缘情况下可能会漏掉更改。
sqlite-vec 未加载？ OpenClaw 会自动回退到进程内余弦相似度。openclaw memory status --deep 会分别报告本地向量存储和嵌入提供商，因此 Vector store: unavailable 指向 sqlite-vec 加载问题，而 Embeddings: unavailable
指向提供商/认证或模型就绪问题。请检查日志以获取具体的加载
错误。