openclaw-memory-config/references/memory-search.md

Memory Search 参考

官方来源：

• https://docs.openclaw.ai/concepts/memory-search
• https://docs.openclaw.ai/reference/memory-config
• https://docs.openclaw.ai/concepts/memory

当前关键点

• 默认 builtin 引擎使用 per-agent SQLite、FTS/BM25 与可选向量检索。
• 通用 OpenAI-compatible embeddings 端点使用 provider: "openai-compatible"，避免继承 OpenAI chat 凭据。
• provider 也可指向兼容的 models.providers.<id>。
• 显式远程 provider 运行时不可用会 fail closed；provider: "none" 才是明确的 FTS-only。
• 改 provider、model、输入类型、sources、scope、chunking 或 tokenizer 后需要显式重建索引。
• API Key 使用 SecretRef；Codex OAuth 不能用于 embeddings。

官方默认值

• chunking.tokens: 400
• chunking.overlap: 80
• query.maxResults: 6
• query.minScore: 0.35
• hybrid.enabled: true
• hybrid.vectorWeight: 0.7
• hybrid.textWeight: 0.3
• hybrid.candidateMultiplier: 4
• mmr.enabled: false
• mmr.lambda: 0.7
• temporalDecay.enabled: false
• temporalDecay.halfLifeDays: 30

先用默认值。重复命中明显时启用 MMR；旧的 dated daily notes 经常压过新内容时启用 temporal decay。非日期文件和 MEMORY.md 不衰减。

可选能力

• 非对称 embeddings：设置 queryInputType 与 documentInputType。
• session transcripts：同时启用 experimental.sessionMemory 并在 sources 加入 sessions；注意存储、隐私和索引成本。
• QMD session search 还需 memory.qmd.sessions.enabled: true。
• multimodal：仅对 extraPaths 下的图像/音频生效，需 Gemini embedding-2；会上传二进制内容，应明确确认。
• local embeddings：需要官方 llama.cpp provider 插件；安装和原生构建必须单独安全审计与确认。

排障

• 无结果：openclaw memory status，必要时重建索引。
• 只有关键词：用 openclaw memory status --deep 检查 embedding。
• 显式 provider 不可用：修复认证/网络；不会静默退回 FTS。
• CJK 检索异常：重建 FTS 索引。
• openclaw memory 未注册：检查 active memory plugin，而不是直接重建。