Memory search

memory_search 从您的记忆文件中查找相关笔记，即使措辞与原文不同。它的工作原理是将记忆索引为小块，并使用嵌入、关键词或两者结合进行搜索。

快速开始

如果您配置了 GitHub Copilot 订阅、OpenAI、Gemini、Voyage 或 Mistral API 密钥，memory search 将自动工作。要显式设置提供商：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai", // or "gemini", "local", "ollama", etc.
      },
    },
  },
}

对于多端点设置，provider 也可以是自定义 models.providers.<id> 条目，例如 ollama-5080，当该提供商设置了 api: "ollama" 或其他嵌入适配器所有者时。

对于没有 API 密钥的本地嵌入，请设置 provider: "local"。源码检出可能仍需要原生构建批准：pnpm approve-builds 然后 pnpm rebuild node-llama-cpp。

某些 OpenAI 兼容的嵌入端点需要非对称标签，例如搜索时使用 input_type: "query"，索引块使用 input_type: "document" 或 "passage"。使用 memorySearch.queryInputType 和 memorySearch.documentInputType 进行配置；请参阅 Memory configuration reference。

支持的提供商

提供商	ID	需要 API 密钥	备注
Bedrock	`bedrock`	否	当 AWS 凭证链解析时自动检测
Gemini	`gemini`	是	支持图像/音频索引
GitHub Copilot	`github-copilot`	否	自动检测，使用 Copilot 订阅
本地	`local`	否	GGUF 模型，约 0.6 GB 下载量
Mistral	`mistral`	是	自动检测
Ollama	`ollama`	否	本地，必须显式设置
OpenAI	`openai`	是	自动检测，快速
Voyage	`voyage`	是	自动检测

搜索如何工作

OpenClaw 并行运行两条检索路径并合并结果：

flowchart LR
    Q["Query"] --> E["Embedding"]
    Q --> T["Tokenize"]
    E --> VS["Vector Search"]
    T --> BM["BM25 Search"]
    VS --> M["Weighted Merge"]
    BM --> M
    M --> R["Top Results"]

向量搜索 查找具有相似含义的笔记（“gateway host”匹配“运行 OpenClaw 的机器”）。
BM25 关键词搜索 查找精确匹配（ID、错误字符串、配置键）。

如果仅有一条路径可用（没有嵌入或没有 FTS），则另一条路径单独运行。

当嵌入（embeddings）不可用时，OpenClaw 仍会在 FTS（全文搜索）结果上使用词法排序，而不是仅回退到原始的精确匹配排序。这种降级模式会提升具有更强查询词覆盖率和相关文件路径的区块，即使没有 OpenClawsqlite-vec 或嵌入提供商，也能保持召回的有效性。

提高搜索质量

当您拥有大量笔记历史记录时，以下两个可选功能会有所帮助：

时间衰减

旧笔记会逐渐降低排序权重，以便最近的信息优先显示。默认半衰期为 30 天，上个月的笔记得分为其原始权重的 50%。像 MEMORY.md 这样的常青文件永远不会衰减。

MMR（多样性）

减少冗余结果。如果五条笔记都提到了相同的路由器配置，MMR 会确保顶部结果涵盖不同的主题，而不是重复出现。

同时启用

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            mmr: { enabled: true },
            temporalDecay: { enabled: true },
          },
        },
      },
    },
  },
}

多模态记忆

使用 Gemini Embedding 2，您可以与 Markdown 一起索引图像和音频文件。搜索查询仍然是文本，但它们会匹配视觉和音频内容。有关设置，请参阅 Memory configuration reference。

会话记忆搜索

您可以选择索引会话记录，以便 memory_search 能够回忆起之前的对话。这可以通过 memorySearch.experimental.sessionMemory 选择启用。有关详细信息，请参阅 configuration reference。

故障排除

没有结果？ 运行 openclaw memory status 检查索引。如果为空，请运行 openclaw memory index --force。

仅有关键词匹配？ 您的嵌入提供商可能未配置。请检查 openclaw memory status --deep。

本地嵌入超时？ 默认情况下，ollama、lmstudio 和 local 使用更长的内联批处理超时时间。如果主机只是太慢，请设置 agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds 并重新运行 openclaw memory index --force。

找不到中日韩文本？ 使用 openclaw memory index --force 重建 FTS 索引。