跳转至

记忆搜索

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,并写入其托管服务配置。

EmbeddingGemma 会自动为查询和索引文档使用其训练的任务前缀,包括通过 Ollama、LM Studio 和 OpenAI 兼容提供商。升级后,现有的无前缀 EmbeddingGemma 索引会在下一次搜索或同步时重建一次。OpenClaw 会生成新的嵌入,而不是复用无前缀的缓存条目。如果重建无法立即完成,关键词搜索仍可用;无需手动执行 memory index --force。请移除任何添加这些前缀的代理变通方案,以免前缀被应用两次。

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

支持的提供商

提供商 ID 需要 API 密钥 说明
Bedrock bedrock 否 使用 AWS 凭证链
DeepInfra deepinfra 是 默认模型 BAAI/bge-m3
Gemini gemini 是 支持图像/音频索引
GitHub Copilot github-copilot 否 使用你的 Copilot 订阅
本地 local 否 托管 llama.cpp GGUF,约 0.3 GB
LM Studio lmstudio 否 本地/自托管服务器
Mistral mistral 是 默认模型 mistral-embed
Ollama ollama 否 本地/自托管服务器
OpenAI openai 视情况而定 API 密钥或符合条件的 Codex OAuth
OpenAI 兼容 openai-compatible 通常 通用 /v1/embeddings 端点
Voyage voyage 是 默认模型 voyage-4-large

搜索工作原理

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"]
  • 向量搜索 匹配相似含义(“网关主机” 匹配 “运行 OpenClaw 的机器”)。
  • BM25 关键词搜索 匹配精确术语(ID、错误字符串、配置键)。它接受 NFC 和 NFD Unicode 拼写,无需重写笔记或重建现有索引,包括跨词混合这些形式的笔记。搜索首先要求所有查询词均出现。只有当正文搜索和文件名搜索都未找到匹配时,它才会使用任意查询词和特定语言的关键词扩展重试一次正文搜索,并按 BM25 排序。这可以在不扩大已有匹配结果的关键词查询的情况下恢复答案。
  • 文件名搜索 将路径与笔记正文分开索引。精确的完整路径、基名和文件名词干优先于部分路径匹配,而摘要和正文关键词分数仍来自笔记内容。

如果只有一条路径可用,则另一条单独运行。关键词加权保持有界,不会将不同的词法分数截断到相同最大值,因此在带日期的笔记衰减时,相关性仍会影响排序。

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

hybrid relevance × recency decay × importance multiplier

重要性在条目由已包含模型的记忆工作流写入时一次性评分。缺失的重要性为中性,因此现有索引保留其先前的相关性信号。带日期的每日笔记按 30 天半衰期衰减;MEMORY.md 和 USER.md 等精选文件为常青文件。这遵循生成式智能体(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 中包含 已脱敏的嵌入引导原因。

本地嵌入请求失败时,仍保留对匹配索引的关键词访问, 并在记忆状态和 Gateway 日志中记录降级后的提供程序。真正的模型 或索引配置不匹配仍会暂停搜索,而不是返回不匹配的数据。

显式提供程序不可用。 如果你显式指定其他提供程序 (例如 openai、ollama、gemini),而它在请求时 不可用(认证错误、网络故障),memory_search 会报告记忆 不可用,而不是静默降级为仅 FTS 结果。这样可以保持 配置损坏的提供程序可见。设置 provider: "none" 可有意 使用仅 FTS 召回,或修复提供程序/认证配置以恢复语义 排序。

如果显式提供程序返回的查询嵌入与索引的维度 数不同,搜索会报告不匹配,而不是比较这些 向量。请验证提供程序的模型,然后使用 openclaw memory index --force --agent <agent-id> 重建。

提升搜索质量

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

近期衰减

旧笔记会逐渐失去排序权重,以便近期信息优先显示。 在默认 30 天半衰期下,上个月笔记的得分为其 原始权重的 50%。MEMORY.md、USER.md 以及 memory/ 下无日期文件 保持常青。带日期的 YYYY-MM-DD.md 和 YYYY-MM-DD-<slug>.md 文件 会在任意深度衰减,包括会话记忆笔记和嵌套的 dreaming 报告。

会话转录命中使用索引期间捕获的源活动时间戳。 保留的转录归档使用其索引的文件修改时间。 单个消息时间戳仍作为来源元数据,不决定源的近期权重。

MMR(多样性)

减少冗余结果。如果五条笔记都提到相同的路由器配置, MMR 会优先选择相关性相似但内容不同的结果,而不是 重复几乎相同的片段。固定的相关性偏置设置使用 lambda 0.7,并对片段 token 使用 Jaccard 重叠。其本地工作量为 O(k²):普通默认值每次检索分支请求 200 个候选项,在重叠前 最多 400 个唯一非精确候选项;更广泛的项目和 标识符搜索仍分别设有上限。

Tip

无需配置。仅 FTS 和仅向量的回退路径不会 运行混合 MMR 流程。

多模态记忆

使用 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" 用于当前加 派生范围(main 有代理范围例外),或 "self" 用于严格的 当前会话召回。沙箱仅派生钳制和 隐身排除仍适用。

故障排除

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

只有关键词匹配? 你的嵌入提供程序可能未配置。请检查 openclaw memory status --deep。

本地嵌入超时? ollama、lmstudio 和 local 使用更长的 由提供程序拥有的批处理截止时间。在重建索引前,请运行 openclaw memory status --deep 检查托管服务器端点。

OpenAI 兼容的嵌入请求会遵循调用者的截止时间,包括 更长的索引预算,而不会受更早的 HTTP 头或正文超时影响。 深度状态探测使用提供程序的查询预算进行一次尝试:远程提供程序通常为 60 秒,local 为 5 分钟,除非提供程序 提供自己的查询预算。托管服务器就绪状态保留其单独的 预算。停滞的探测会报告 memory embedding probe timed out after Ns。

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw