内置记忆引擎

内置引擎是默认的记忆后端。它会把你的记忆索引存储在每个智能体的 SQLite 数据库中，并且入门不需要额外依赖。

# 它提供什么

• 关键词搜索：通过 FTS5 全文索引实现（BM25 评分）。
• 向量搜索：通过任意受支持提供商的 embeddings 实现。
• 混合搜索：结合两者以获得最佳结果。
• 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 sidecar 会通过定期 checkpoint 和关闭时 checkpoint 进行限制。
• 文件监听： 记忆文件变更会触发防抖的重新索引（1.5 秒）。
• 自动重新索引： 当 embedding 提供商、模型或分块配置发生变化时，会自动重建整个索引。
• 按需重新索引： openclaw memory index --force

# 何时使用

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

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

如果你需要 reranking、查询扩展，或想索引工作区外的目录，请考虑切换到 QMD。

如果你想要带自动用户建模的跨会话记忆，请考虑 Honcho。

# 故障排除

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

未检测到本地提供商？ 确认本地路径存在，然后运行：

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

独立 CLI 命令和 Gateway 网关使用相同的 local 提供商 ID。 如果提供商设置为 auto，只有当 memorySearch.local.modelPath 指向现有本地文件时，才会优先考虑本地 embeddings。

结果过旧？ 运行 openclaw memory index --force 重建索引。监听器 在极少数边缘情况下可能会漏掉变更。

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

# 配置

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

# 相关

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