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

Memory Search 参考文档

来源：OpenClaw 官方文档

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

Memory Search 工作原理

两路并行检索，加权合并：

1. Vector Search（向量搜索）：通过 embedding 找语义相似的笔记
2. BM25 Keyword Search（关键词搜索）：找精确匹配（ID、错误字符串、配置键）

如只有一路可用，另一路单独运行。

Builtin Memory Engine（默认）

• 索引存储在 SQLite（per-agent）：~/.openclaw/memory/<agentId>.sqlite
• FTS5 全文索引 + 可选 sqlite-vec 向量扩展
• CJK 分词支持（中文/日文/韩文）
• 文件变更自动触发 reindex（1.5s debounce）
• 无额外依赖

Embedding Provider 配置

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "bge-large-zh-v1.5",
        "remote": {
          "baseUrl": "https://lapi.transiglobal.com/v1",
          "apiKey": "YOUR_KEY"
        }
      }
    }
  }
}

支持的 Provider

Provider	ID	自动检测	说明
OpenAI	openai	✅	默认 text-embedding-3-small
Gemini	gemini	✅	支持多模态（图片+音频）
Voyage	voyage	✅
Mistral	mistral	✅
Ollama	ollama	❌ 需显式设置	本地
Local	local	✅ 优先级最高	GGUF 模型，~0.6GB

自定义 OpenAI 兼容端点通过 remote.baseUrl + remote.apiKey 配置。

搜索参数详解

分块（Chunking）

参数	默认值	说明
chunking.tokens	400	每块 token 数
chunking.overlap	80	块间重叠

基础查询

参数	默认值	说明
query.maxResults	—	最大返回结果数
query.minScore	—	最低相关度阈值

混合搜索（Hybrid）

参数	默认值	说明
hybrid.enabled	true	启用混合搜索
hybrid.vectorWeight	0.7	向量权重
hybrid.textWeight	0.3	关键词权重
hybrid.candidateMultiplier	4	候选池倍数

MMR 去重

参数	默认值	说明
mmr.enabled	false	启用 MMR 重排序
mmr.lambda	0.7	0=最多样，1=最相关

时间衰减

参数	默认值	说明
temporalDecay.enabled	false	启用时间衰减
temporalDecay.halfLifeDays	30	半衰期天数

MEMORY.md 等常驻文件不参与衰减。

CLI 命令

openclaw memory status          # 查看索引状态
openclaw memory status --deep   # 深度检查（含 embedding）
openclaw memory index --force   # 强制重建索引
openclaw memory search "query"  # 命令行搜索

故障排查

• 无结果：openclaw memory status 检查索引，空则 openclaw memory index --force
• 只有关键词匹配：embedding provider 未配置，检查 openclaw memory status --deep
• CJK 搜索失败：openclaw memory index --force 重建 FTS
• sqlite-vec 加载失败：自动降级为进程内余弦相似度计算