Appearance
本页介绍 OpenClaw memory_search 工具的工作原理：双路检索（BM25 关键词 + 向量语义）并行执行后加权合并。支持 MMR 多样性过滤、时间衰减、多模态索引（Gemini），以及 7 个 embedding provider 对比。
Memory Search（记忆搜索）
memory_search 从你的 memory 文件中找出相关笔记，即使措辞与原文不同也能命中。它的原理是：将 memory 切成小块，通过 embedding、关键词，或两者结合进行搜索。
快速开始
配置了 OpenAI、Gemini、Voyage 或 Mistral API Key 时，memory search 自动启用。显式指定 provider：
json5
{
agents: {
defaults: {
memorySearch: {
provider: "openai", // 或 "gemini", "local", "ollama" 等
},
},
},
}不想使用 API Key 的本地 embedding 方案，使用 provider: "local"（需要 node-llama-cpp）。
支持的 Embedding Provider
| Provider | ID | 需要 API Key | 说明 |
|---|---|---|---|
| OpenAI | openai | 是 | 自动检测，速度快 |
| Gemini | gemini | 是 | 支持图片/音频索引 |
| Voyage | voyage | 是 | 自动检测 |
| Mistral | mistral | 是 | 自动检测 |
| Bedrock | bedrock | 否 | AWS 凭据链解析时自动检测 |
| Ollama | ollama | 否 | 本地运行，需显式配置 |
| Local | local | 否 | GGUF 模型，约 0.6 GB 下载 |
搜索工作原理
OpenClaw 并行运行两条检索路径，合并结果：
- 向量搜索：找到语义相近的笔记（"gateway host" 能匹配含 "运行 OpenClaw 的机器" 的内容）
- BM25 关键词搜索：精确匹配 ID、报错字符串、配置 key 等
任一路径不可用时（无 embedding 或无 FTS），另一条路径单独运行。
提升搜索质量
笔记量大时，以下两个可选功能可以帮助提升召回质量：
时间衰减（Temporal Decay）
老笔记的排名权重随时间降低，使最近的信息优先浮现。默认半衰期 30 天，上个月的笔记评分降至 50%。MEMORY.md 这类常青文件不参与衰减。
如果你的 agent 有数月的日常笔记，且旧信息一直排在新上下文前面，建议启用时间衰减。
MMR（多样性过滤）
减少重复结果。如果 5 条笔记都提到同一个路由器配置，MMR 会让 top 结果覆盖不同话题，而不是重复显示。
如果
memory_search总是从不同日记文件返回近乎重复的片段，建议启用 MMR。
同时启用
json5
{
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
mmr: { enabled: true },
temporalDecay: { enabled: true },
},
},
},
},
},
}多模态记忆
使用 Gemini Embedding 2，可以在 Markdown 旁边索引图片和音频文件。搜索查询仍为文本，但能匹配视觉和音频内容。详见Memory 配置参考。
会话记忆搜索
可选择将会话记录纳入索引，使 memory_search 能召回历史对话。通过 memorySearch.experimental.sessionMemory 启用（opt-in）。详见配置参考。
排查
没有结果？ 运行 openclaw memory status 检查索引状态。若为空，运行 openclaw memory index --force
只有关键词匹配，没有语义结果？ Embedding provider 可能未配置，用 openclaw memory status --deep 检查
CJK 中文找不到？ 用 openclaw memory index --force 重建 FTS 索引
常见问题
Q: 只有关键词搜索，没有向量搜索，效果差很多吗？
A: 精确词匹配够用，但无法做语义近义词搜索。例如搜"部署"找不到含"上线"的内容。有免费 Embedding 额度（如 Gemini）时建议开启向量搜索。
Q: 本地离线能用语义搜索吗？
A: 可以。设置 provider: "ollama" 并安装对应 embedding 模型，或使用 provider: "local"（自动下载约 0.6 GB GGUF 模型）。
Q: MMR 会不会把重要结果过滤掉？
A: MMR 侧重多样性，如果有多条笔记都是有效答案，可能只保留其中一条。对于精确查询（比如找某个具体错误），不启用 MMR 效果通常更好。