本页介绍 OpenClaw 的默认内置记忆引擎：以 SQLite 为后端，提供 BM25 关键词搜索、embedding 向量搜索和混合检索。支持 OpenAI、Gemini、Voyage、Mistral、Ollama 及本地 GGUF 模型等 embedding provider，自动检测 API Key 并启用向量检索，无需额外依赖即可开箱即用。

内置记忆引擎（Builtin Memory Engine）

内置引擎是 OpenClaw 的默认记忆后端，将记忆索引存储在每个 agent 独立的 SQLite 数据库中，无需额外依赖即可运行。

功能概览

• 关键词搜索：基于 FTS5 全文索引（BM25 评分）
• 向量搜索：通过任意支持的 provider 生成 embedding
• 混合检索：结合关键词和向量，获得最佳结果
• CJK 支持：通过 trigram 分词实现中文、日文、韩文支持
• sqlite-vec 加速：可选的数据库内向量查询加速

快速上手

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

显式指定 embedding provider：

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

没有 embedding provider 时，仅关键词搜索可用。

支持的 Embedding Provider

Provider	ID	自动检测	说明
OpenAI	openai	是	默认模型：text-embedding-3-small
Gemini	gemini	是	支持多模态（图片+音频）
Voyage	voyage	是	—
Mistral	mistral	是	—
Ollama	ollama	否	本地运行，需显式配置
Local	local	是（首选）	GGUF 模型，约 0.6 GB 下载

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

索引机制

OpenClaw 将 MEMORY.md 和 memory/*.md 分块（约 400 token，80 token 重叠）后存入 per-agent SQLite 数据库。

• 索引位置：~/.openclaw/memory/<agentId>.sqlite
• 文件监听：memory 文件变更触发防抖重索引（1.5 秒延迟）
• 自动全量重建：embedding provider、模型或分块配置变更时，自动重建整个索引
• 手动重建：openclaw memory index --force

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

适用场景

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

• 无额外依赖，开箱即用
• 关键词和向量搜索效果好
• 支持所有 embedding provider
• 混合检索结合两种方法的优势

切换到 QMD 的情形：

• 需要重排（reranking）、查询扩展
• 需要索引工作区以外的目录

切换到 Honcho 的情形：

• 需要跨会话记忆
• 需要自动用户建模

排查

记忆搜索不工作？ 运行 openclaw memory status。若无 provider 检测到，显式设置一个或添加对应 API Key。

搜索结果过时？ 运行 openclaw memory index --force 强制重建。文件监听在极少数情况下可能漏掉变更。

sqlite-vec 加载失败？ OpenClaw 会自动回退到进程内 cosine 相似度计算，检查日志确认具体报错。

配置参考

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

常见问题

Q: 不配置 embedding provider，只用关键词搜索够用吗？

A: 对于简单的精确词匹配够用，但无法做语义近义词搜索。例如搜"部署"找不到含"上线"的内容。有免费 Embedding 额度时（如 Gemini）建议开启向量搜索。

Q: 如何在本地（离线）启用向量搜索？

A: 使用 Ollama 作为 embedding provider：先安装 Ollama 并拉取 embedding 模型，然后设置 memorySearch.provider: "ollama"。或者使用 local provider（自动下载 ~0.6 GB GGUF 模型）。

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

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