跳转到内容
OpenClaw Docs

内置内存引擎

内置引擎是默认的内存后端。它将你的内存索引存储在每个代理专用的 SQLite 数据库中，无需额外的依赖即可开始使用。

功能特性

Section titled “功能特性”
  • 通过 FTS5 全文索引（BM25 评分）实现的关键词搜索。
  • 通过任何支持的提供商的嵌入向量实现的向量搜索。
  • 结合两者以获得最佳结果的混合搜索。
  • 通过针对中文、日文和韩文的三元组分词实现的中日韩 (CJK) 支持。
  • 用于数据库内向量查询的 sqlite-vec 加速（可选）。

入门指南

Section titled “入门指南”

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

要显式设置提供商：

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

如果没有嵌入提供商，则仅提供关键词搜索。

要强制使用内置本地嵌入提供商，请在 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",
        },
      },
    },
  },
}

Supported embedding providers

Section titled “Supported embedding providers”
ProviderID注意事项
Bedrockbedrock使用 AWS 凭证链
DeepInfradeepinfra默认值：BAAI/bge-m3
GeminigeminiSupports multimodal (image + audio)
GitHub Copilotgithub-copilot使用 Copilot 订阅
本地local可选 node-llama-cpp 运行时
Mistralmistral
Ollamaollama本地/自托管
OpenAIopenai默认值：text-embedding-3-small
OpenAI 兼容openai-compatible通用 /v1/embeddings 端点
Voyagevoyage

设置 memorySearch.provider 以切换离开 OpenAI。

索引如何工作

Section titled “索引如何工作”

OpenClaw 将 MEMORY.md 和 memory/*.md 索引为分块（约 400 个 token，具有 80 个 token 的重叠），并将它们存储在每个代理的 SQLite 数据库中。

  • 索引位置： ~/.openclaw/memory/<agentId>.sqlite
  • 存储维护： SQLite WAL 附属文件通过定期和关闭检查点进行限制。
  • 文件监视： 对内存文件的更改会触发防抖重新索引（1.5秒）。
  • 自动重新索引： 当嵌入提供商、模型或分块配置更改时，整个索引将自动重建。
  • 按需重新索引： openclaw memory index --force

何时使用

Section titled “何时使用”

对于大多数用户来说，内置引擎是正确的选择：

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

如果您需要重排序（reranking）、查询扩展（query expansion），或者想要索引工作区之外的目录，请考虑切换到 QMD。

如果您需要带有自动用户建模的跨会话记忆，请考虑使用 Honcho。

故障排除

Section titled “故障排除”

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

未检测到本地提供商？ 请确认本地路径存在并运行：

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

独立的 CLI 命令和 Gateway 使用相同的 CLIGateway(网关)local 提供商 ID。当您需要本地嵌入时，请设置 memorySearch.provider: "local"。

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

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

配置

Section titled “配置”

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

相关

Section titled “相关”