记忆搜索

memory_search 会从你的记忆文件中查找相关笔记，即使表述与原始文本不同。它会将记忆分块成小片段，并使用嵌入、关键词或两者进行搜索。

快速开始

OpenClaw 默认使用 OpenAI 嵌入。若要使用其他提供商，请显式设置：

{  agents: {    defaults: {      memorySearch: {        provider: "openai", // or "gemini", "voyage", "mistral", "bedrock", "local", "ollama", "lmstudio", "github-copilot", "openai-compatible"      },    },  },}

provider 也可以引用自定义 models.providers.<id> 条目（例如 ollama-5080），只要该条目将 api 设置为 "ollama"，或设置为另一个带有记忆嵌入适配器的提供商 ID。

对于无需 API key 的本地嵌入，请安装官方 llama.cpp provider 插件，并设置 provider: "local"：

openclaw plugins install @openclaw/llama-cpp-provider

源码检出仍然需要原生构建批准：pnpm approve-builds，然后运行 pnpm rebuild node-llama-cpp。

某些 OpenAI 兼容嵌入端点需要非对称 input_type 标签，例如搜索使用 "query"，索引块使用 "document"/"passage"。请使用 queryInputType 和 documentInputType 设置这些值；参见记忆配置参考。

支持的提供商

搜索工作原理

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” 可匹配 “the machine running OpenClaw”）。
• BM25 关键词搜索匹配精确术语（ID、错误字符串、配置键）。

如果只有一条路径可用，则仅运行该路径。

仅 FTS 模式。 设置 provider: "none" 可有意禁用嵌入，并仅使用关键词搜索。若 provider 未设置或设置为 "auto"，在没有配置嵌入凭证时，也会回退到仅关键词排序且不报错；provider: "local"（GGUF/llama.cpp provider）失败时也是如此。

显式提供商不可用。 如果你显式指定任何其他提供商（例如 openai、ollama、gemini），而它在请求时变得不可用（凭证错误、网络失败），memory_search 会报告记忆不可用，而不是静默降级为仅 FTS 结果。这样可以让配置损坏的提供商保持可见。若要有意使用仅 FTS 召回，请设置 provider: "none"；或修复提供商/凭证配置以恢复语义排序。

提升搜索质量

两个可选功能有助于处理大量笔记历史。

时间衰减

旧笔记会逐渐降低排序权重，使近期信息优先浮现。使用默认 30 天半衰期时，上个月的笔记得分为其原始权重的 50%。MEMORY.md 和 memory/ 下其他无日期文件是常青内容，永不衰减；只有带日期的 memory/YYYY-MM-DD.md 文件会衰减。

MMR（多样性）

减少重复结果。如果五条笔记都提到同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复同一内容。

同时启用两者

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

多模态记忆

使用 gemini-embedding-2-preview 时，你可以在 Markdown 之外同时索引图像和音频。这仅适用于 memorySearch.extraPaths 下的文件；默认记忆根（MEMORY.md、memory/*.md）仍仅支持 Markdown。搜索查询仍是文本，但会匹配视觉和音频内容。设置方法参见记忆配置参考。

会话记忆搜索

可以选择索引会话转录，使 memory_search 能召回较早的对话。这是可选功能：设置 experimental.sessionMemory: true，并将 "sessions" 添加到 sources（默认 sources 为 ["memory"]）。

会话命中遵循 tools.sessions.visibility：默认 "tree" 仅暴露当前会话及其派生的会话。若要从不同会话中召回无关的同一智能体会话（例如来自私信的 Gateway 网关分发会话），请将可见性扩大为 "agent"。

使用 QMD 后端时，还要设置 memory.qmd.sessions.enabled: true，以便将转录导出到 QMD 集合；仅设置 experimental.sessionMemory 和 sources 不会把转录导出到 QMD。参见配置参考。

故障排查

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

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

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

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

相关

• 记忆概览
• 主动记忆
• 内置记忆引擎
• 记忆配置参考