记忆搜索

memory_search 从你的记忆文件中查找相关笔记，即使措辞与原始文本不同也能找到。它会将记忆切分为小块，并使用嵌入、关键词或两者同时进行搜索。

快速开始¶

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

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

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

对于无需 API 密钥的本地嵌入，请安装并配置官方 llama.cpp 提供商，然后设置 provider: "local"：

openclaw plugins install @openclaw/llama-cpp-provider

在交互式设置中只需选择一次 llama.cpp。OpenClaw 会安装经过验证的 llama-server，下载嵌入 GGUF，并写入其托管服务配置。

某些兼容 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 --> D["Recency and importance"]
    D --> R["MMR diversity"]
    R --> O["Top results"]

• 向量搜索匹配相似含义（"gateway host" 匹配 "the machine running OpenClaw"）。
• BM25 关键词搜索匹配精确术语（ID、错误字符串、配置键）。
• 文件名搜索将路径与笔记正文分开索引。精确的完整路径、基名和文件名词干排在部分路径匹配之前，而片段和正文关键词分数仍来自笔记内容。

如果只有一条路径可用，则这条路径单独运行。

内置引擎随后应用确定性排序：

hybrid relevance × recency decay × importance multiplier

重要性在条目由已在流程中包含模型的记忆工作流写入时评分一次。缺失的重要性为中性，因此现有索引会保留其先前的相关性信号。带日期的每日笔记以 30 天半衰期衰减；而 MEMORY.md 和 USER.md 等精选文件则长期有效。这遵循 Generative Agents (arXiv:2304.03442) 中的相关性、近期性和重要性结果，且无需在查询时进行模型调用。

MMR 随后对已评分的混合候选集重新排序，以减少冗余片段。它不会改变分数、阈值资格，也不会发起另一个提供商调用。

当所有排名结果都低于配置的最低分数时，搜索会保留关键词匹配。混合搜索也可以用仅关键词匹配来填充剩余的结果槽位。这些规则同样适用于项目会话；仅语义匹配仍需达到配置的最低分数。

确定性触发召回¶

在符合条件的交互轮次中，内置引擎还会将入站消息与存储在已索引条目上的短触发短语进行比较。强匹配可以在回复之前向隐藏上下文添加最多三个紧凑条目。预过滤器使用现有的关键词和向量检索路径，不会运行召回模型。

自动注入刻意比 memory_search 更严格：只有被提升、受信任的条目才符合条件。在索引出处可用之前，这意味着仅来自根目录 MEMORY.md 和 USER.md 的条目。每日笔记、导入的转录文本和会话转录文本仍可通过显式记忆工具或 Active Memory 升级使用，但绝不会自动注入。

仅 FTS 模式。 将 provider 设置为 "none" 可有意禁用嵌入，并仅使用关键词搜索。当嵌入设置或请求失败时，provider 未设置或设置为 "auto" 会回退到仅关键词排序，provider: "local"（GGUF/llama.cpp 提供商）也是如此。创建时回退仍会为关键词搜索索引文本，包括在首次搜索之前的手动和后台索引。即使没有匹配项，memory_search 也会在 debug.embeddingBootstrap 中包含脱敏后的嵌入引导原因。

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

提升搜索质量¶

混合搜索默认启用两轮确定性排序过程。

时效衰减¶

旧笔记的排序权重会逐渐降低，从而让较新的信息优先呈现。 在默认的 30 天半衰期下，上个月的笔记得分仅为原始权重的 50%。 MEMORY.md、USER.md 以及 memory/ 目录下未标注日期的文件始终保持原有权重。 带日期的 YYYY-MM-DD.md 和 YYYY-MM-DD-<slug>.md 文件在任意目录层级都会衰减， 包括会话记忆笔记和嵌套的梦境报告。

会话转录命中结果使用索引期间捕获的源活动时间戳。 保留的转录档案使用其索引时的文件修改时间。 单条消息的时间戳仍作为来源元数据保留，不参与决定来源的时效权重。

MMR（多样性）¶

减少冗余结果。如果五条笔记都提到同一路由器配置，MMR 会更倾向于选择相关性相近但内容不同的结果， 而不是重复几乎相同的片段。固定的相关性偏置设置使用 lambda 0.7， 并基于片段 token 计算 Jaccard 重叠度。其局部计算量为 O(k²)： 常规默认设置下，每条检索路径请求 200 个候选结果，重叠计算前最多有 400 个唯一的非精确候选； 范围更广的项目和标识符搜索仍分别设有独立上限。

多模态记忆¶

使用 gemini-embedding-2 时，你可以将图片和音频与 Markdown 一同索引。 这仅适用于 memory.search.extraPaths 下的文件；默认记忆根目录（MEMORY.md、memory/*.md）仍仅支持 Markdown。 搜索查询仍为文本形式，但会与视觉和音频内容进行匹配。 有关设置方法，请参阅记忆配置参考。

会话记忆搜索¶

如需从会话转录文本中进行精确的全文召回，请使用 sessions_search， 然后通过 sessions_history 打开结果。会话记忆搜索仍是语义化的实验性补充手段。

你可以选择性地为会话转录文本建立索引，以便 memory_search 能够召回更早的对话。 此为可选启用功能：设置 experimental.sessionMemory: true， 并将 "sessions" 添加到 sources（默认 sources 为 ["memory"]）。

使用 corpus: "memory" 可仅搜索记忆笔记。 不包含会话转录文本的结果不会加载会话历史，也不会执行会话可见性查找。

会话命中结果遵循 tools.sessions.visibility 设置，其默认值为 "all"。 memory_search 仍只搜索所选代理的索引语料库；如需在 Gateway 上跨代理搜索转录文本，请使用 sessions_search。可见的转录文本可能包含其他用户的对话。 跨代理会话访问默认开启，并由 tools.agentToAgent 管控；设置 enabled: false 可阻止 常规跨代理访问（请求方拥有的原生子代理和 ACP 子会话在 tree 或 all 模式下仍可访问）， 或使用 allow 来限制特定的代理对。按对等方设置的 session.dmScope 用于隔离 DM 上下文， 但不会限制通过会话工具对转录文本的访问。选择显式的 "agent" 进行同代理召回， "tree" 表示当前范围加上派生范围（主代理拥有全代理范围的例外），或 "self" 进行严格的当前会话召回。 沙箱仅派生钳制以及隐身排除规则仍然适用。

故障排除¶

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

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

本地嵌入超时？ ollama、lmstudio 和 local 使用更长的提供方批次截止时间。 在重建索引之前，先运行 openclaw memory status --deep 检查受管服务器端点。

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

相关文档¶

• 记忆概述
• 记忆架构
• 活动记忆
• 内置记忆引擎
• 记忆配置参考
• Memory LanceDB