OpenClaw 内置记忆引擎默认以 SQLite 存储记忆索引，支持 BM25 关键词搜索、向量搜索和混合检索，开箱即用无需额外依赖。配置任一支持的 embedding 提供商（OpenAI、Gemini、Voyage、Mistral、DeepInfra、Ollama 或本地 GGUF）后自动启用向量搜索；若未设置则仅有关键词搜索可用。遇到记忆搜索不可用时，运行 openclaw memory status 检查提供商状态，必要时手动强制重建索引 openclaw memory index --force。

OpenClaw 内置记忆引擎配置与排查

内置引擎是 OpenClaw 的默认记忆后端，在每个智能体内创建独立的 SQLite 数据库存储记忆索引。无需额外依赖即可启动，并支持关键词、向量和三者混合搜索。

功能概览

• 关键词搜索：基于 FTS5 全文索引（BM25 评分算法）。
• 向量搜索：使用任意支持的 embedding 提供商生成向量。
• 混合搜索：结合关键词与向量搜索，获得最佳检索效果。
• CJK 支持：通过 trigram 分词支持中文、日文、韩文。
• sqlite-vec 加速：可选的在数据库内执行向量查询加速。

快速开始

如果你有 OpenAI、Gemini、Voyage、Mistral 或 DeepInfra 的 API Key，内置引擎会自动检测并启用向量搜索，无需额外配置。

若要显式指定提供商：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
      },
    },
  },
}

如果没有 embedding 提供商，仅关键词搜索可用。

要强制使用本地 embedding 提供商，先在 OpenClaw 旁边安装可选运行时包 node-llama-cpp，然后设置 local.modelPath 指向一个 GGUF 文件：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        fallback: "none",
        local: {
          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
        },
      },
    },
  },
}

支持的 Embedding 提供商

提供商	ID	自动检测	说明
OpenAI	openai	是	默认模型：text-embedding-3-small
Gemini	gemini	是	支持多模态（图片+音频）
Voyage	voyage	是
Mistral	mistral	是
DeepInfra	deepinfra	是	默认模型：BAAI/bge-m3
Ollama	ollama	否	本地运行，需显式设置
Local	local	是（优先）	需安装可选的 node-llama-cpp 运行时

自动检测按表中顺序选择第一个能解析 API Key 的提供商。可通过设置 memorySearch.provider 覆盖。

索引机制

OpenClaw 将 MEMORY.md 和 memory/*.md 分块（每块约 400 token，重叠 80 token）后存入每个智能体的 SQLite 数据库。

• 索引位置：~/.openclaw/memory/<agentId>.sqlite
• 存储维护：SQLite WAL 侧文件通过定期和关闭时的检查点限制大小。
• 文件监听：记忆文件变更触发防抖重索引（延迟 1.5 秒）。
• 自动重索引：当 embedding 提供商、模型或分块配置发生变化时，自动重建整个索引。
• 手动重建：openclaw memory index --force

提示：也可以通过 memorySearch.extraPaths 索引工作区之外的 Markdown 文件。详见配置参考。

适用场景

内置引擎适合大多数用户：

• 无额外依赖，开箱即用。
• 关键词和向量搜索效果良好。
• 支持所有列出 embedding 提供商。
• 混合搜索结合两种检索优势。

需要切换到 QMD 时： 需要重排序（reranking）、查询扩展，或索引工作区以外的目录。

需要切换到 Honcho 时： 需要跨会话记忆且自动用户建模。

常见问题

记忆搜索不可用怎么排查？

运行 openclaw memory status。如果显示没有提供商，显式设置一个或添加对应 API Key。若本地提供商未检测到，确认本地路径存在并执行：
openclaw memory status --deep --agent main
openclaw memory index --force --agent main

强制重建索引后结果还是过时怎么办？

极少数情况下文件监听可能漏掉变更。直接运行 openclaw memory index --force 强制完整重建。如果 sqlite-vec 加载失败，OpenClaw 会自动回退到进程内余弦相似度计算，运行 openclaw memory status --deep 查看向量存储状态（Vector store: unavailable 表示 sqlite-vec 加载问题，Embeddings: unavailable 表示提供商/认证或模型未就绪）。

CJK 中文搜索需要特殊配置吗？

不需要。内置引擎已通过 trigram 分词支持中文 FTS5 搜索，开箱即用。向量搜索的中文效果取决于所选的 embedding 模型。

配置参考

关于 embedding 提供商设置、混合搜索调参（权重、MMR、时间衰减）、批量索引、多模态记忆、sqlite-vec、额外路径等所有配置项，请参考 Memory 配置参考。

相关文档

• 记忆引擎概览
• 记忆搜索
• 主动记忆