一、什么是 memorySearch？

memorySearch 是 OpenClaw 的记忆搜索功能，它通过向量嵌入（embeddings）和关键词搜索，从你的记忆文件（MEMORY.md、memory/*.md）中智能检索相关信息，即使措辞不同也能找到语义相关的内容！

二、初始化配置

默认该配置项不存在，可通过对话框开启开启记忆搜索，查看你的 openclaw.json，memorySearch 配置在：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true  // ✅ 已启用
      }
    }
  }
}

上述配置文件为启用了记忆搜索基础功能，但没有配置嵌入提供商，所以目前只能用关键词搜索，无法用语义搜索！

三、完整配置结构

{
  "agents": {
    "defaults": {
      "memorySearch": {
        // 1️⃣ 提供商选择
        "provider": "openai",
        "model": "text-embedding-3-small",
        "fallback": "none",
        "enabled": true,
        
        // 2️⃣ 远程端点配置
        "remote": {
          "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
          "apiKey": "sk-********************",
        },
        
        // 3️⃣ 本地嵌入配置
        "local": {
          "modelPath": "~/.openclaw/models/embed.gguf",
          "modelCacheDir": "~/.openclaw/cache"
        },
        
        // 4️⃣ 混合搜索配置
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4,
            
            // MMR 多样性
            "mmr": {
              "enabled": false,
              "lambda": 0.7
            },
            
            // 时间衰减
            "temporalDecay": {
              "enabled": false,
              "halfLifeDays": 30
            }
          }
        },
        
        // 5️⃣ 多模态记忆
        "multimodal": {
          "enabled": false,
          "modalities": ["image", "audio"],
          "maxFileBytes": 10000000
        },
        
        // 6️⃣ 嵌入缓存
        "cache": {
          "enabled": false,
          "maxEntries": 50000
        },
        
        // 7️⃣ 批量索引
        "remote": {
          "batch": {
            "enabled": false,
            "concurrency": 2,
            "wait": true
          }
        },
        
        // 8️⃣ 会话记忆（实验性）
        "experimental": {
          "sessionMemory": false
        },
        
        // 9️⃣ 额外路径
        "extraPaths": ["../team-docs", "/srv/shared-notes"],
        
        // 🔟 存储配置
        "store": {
          "path": "~/.openclaw/memory/{agentId}.sqlite",
          "vector": {
            "enabled": true,
            "extensionPath": "bundled"
          },
          "fts": {
            "tokenizer": "unicode61"
          }
        }
      }
    }
  }
}

配置项 1 : 提供商选择（provider）

支持的提供商

提供商	ID	需要 API Key	说明
OpenAI	`openai`	✅	自动检测，快速
Gemini	`gemini`	✅	支持图片/音频索引
Voyage	`voyage`	✅	自动检测
Mistral	`mistral`	✅	自动检测
Bedrock	`bedrock`	❌	AWS 凭证链
Ollama	`ollama`	❌	本地，需显式设置
Local	`local`	❌	GGUF 模型，~0.6GB 下载

自动检测顺序

当不设置 provider 时，OpenClaw 按以下顺序自动选择：

local - 如果配置了本地模型路径
openai - 如果有 OPENAI_API_KEY
gemini - 如果有 GEMINI_API_KEY
voyage - 如果有 VOYAGE_API_KEY
mistral - 如果有 MISTRAL_API_KEY
bedrock - 如果 AWS 凭证链可用

配置示例

// 使用 OpenAI
{
  "memorySearch": {
    "provider": "openai",
    "model": "text-embedding-3-small"
  }
}

// 使用 Gemini（支持多模态）
{
  "memorySearch": {
    "provider": "gemini",
    "model": "gemini-embedding-2-preview",
    "outputDimensionality": 3072  // 768/1536/3072
  }
}

// 使用本地模型（无需 API Key）
{
  "memorySearch": {
    "provider": "local",
    "local": {
      "modelPath": "~/.openclaw/models/embeddinggemma-300m-qat-Q8_0.gguf"
    }
  }
}

配置项 2 : 混合搜索配置（hybrid）

工作原理

Copy

查询 → 向量搜索 + BM25 关键词搜索 → 加权合并 → 返回结果

向量搜索：找语义相似的内容（"gateway host" 匹配 "运行 OpenClaw 的机器"）
BM25 关键词：找精确匹配（ID、错误字符串、配置 key）

配置参数

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "enabled": true,           // 启用混合搜索
        "vectorWeight": 0.7,       // 向量权重（0-1）
        "textWeight": 0.3,         // 文本权重（0-1）
        "candidateMultiplier": 4   // 候选池倍数
      }
    }
  }
}

配置项 3 : . MMR 多样性（去重）

作用：避免返回大量重复内容

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "mmr": {
          "enabled": true,    // 启用 MMR
          "lambda": 0.7       // 0=最大多样性，1=最大相关性
        }
      }
    }
  }
}

适用场景：当 memory_search 总是从不同日记中返回相似的路由器配置时

配置项 4 : 时间衰减（Temporal Decay）

作用：旧笔记逐渐降低权重，让近期信息优先

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "temporalDecay": {
          "enabled": true,
          "halfLifeDays": 30  // 30 天后分数减半
        }
      }
    }
  }
}

注意：MEMORY.md 等常青文件永远不会衰减

适用场景：有几个月的日记，旧信息总是覆盖新信息时

配置项 5 : 多模态记忆（Gemini 专属）

作用：索引图片和音频文件，用文本搜索匹配视觉/音频内容

{
  "memorySearch": {
    "provider": "gemini",
    "model": "gemini-embedding-2-preview",
    "multimodal": {
      "enabled": true,
      "modalities": ["image", "audio"],  // 或 ["all"]
      "maxFileBytes": 10000000           // 10MB 限制
    }
  }
}

支持格式：

图片：.jpg, .jpeg, .png, .webp, .gif, .heic, .heif
音频：.mp3, .wav, .ogg, .opus, .m4a, .aac, .flac

配置项 6 : 嵌入缓存

作用：缓存已嵌入的文本块，避免重新索引时重复计算

{
  "memorySearch": {
    "cache": {
      "enabled": true,
      "maxEntries": 50000  // 最多缓存 5 万个嵌入
    }
  }
}

配置项 7 : 批量索引（Batch Indexing）

作用：使用批量 API 加速大规模索引

{
  "memorySearch": {
    "remote": {
      "batch": {
        "enabled": true,
        "concurrency": 2,        // 并发批量任务数
        "wait": true,            // 等待批量完成
        "pollIntervalMs": 1000,  // 轮询间隔
        "timeoutMinutes": 30     // 超时时间
      }
    }
  }
}

支持提供商：OpenAI、Gemini、Voyage

配置项 8 : 会话记忆（实验性）

作用：索引会话记录，让 memory_search 可以检索之前的对话

{
  "memorySearch": {
    "experimental": {
      "sessionMemory": true
    },
    "sources": ["memory", "sessions"],  // 包含会话记录
    "sync": {
      "sessions": {
        "deltaBytes": 100000,       // 100KB 触发重新索引
        "deltaMessages": 50         // 50 条消息触发重新索引
      }
    }
  }
}

配置项 9 : 额外路径（extraPaths）

作用：索引工作区外的文档

{
  "memorySearch": {
    "extraPaths": [
      "../team-docs",           // 相对路径
      "/srv/shared-notes"       // 绝对路径
    ]
  }
}

说明：目录会递归扫描 .md 文件

配置项 10 : 存储配置（store）

{
  "memorySearch": {
    "store": {
      "path": "~/.openclaw/memory/{agentId}.sqlite",  // 索引位置
      "vector": {
        "enabled": true,              // 使用 sqlite-vec 加速
        "extensionPath": "bundled"    // 覆盖 sqlite-vec 路径
      },
      "fts": {
        "tokenizer": "unicode61"      // FTS5 分词器（unicode61 或 trigram）
      }
    }
  }
}

配置项 11 : QMD 后端配置

作用：使用 QMD 作为记忆后端（替代内置 SQLite）

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "command": "qmd",                  // QMD 可执行路径
      "searchMode": "search",            // search/vsearch/query
      "includeDefaultMemory": true,      // 自动索引 MEMORY.md
      "paths": [                         // 额外路径
        {
          "name": "docs",
          "path": "~/notes",
          "pattern": "**/*.md"
        }
      ],
      "sessions": {
        "enabled": true,
        "retentionDays": 30,
        "exportDir": "~/.openclaw/sessions"
      },
      "update": {
        "interval": "5m",
        "debounceMs": 15000,
        "onBoot": true,
        "waitForBootSync": false
      },
      "limits": {
        "maxResults": 6,
        "maxSnippetChars": 1000,
        "maxInjectedChars": 5000,
        "timeoutMs": 4000
      },
      "scope": {
        "default": "deny",
        "rules": [
          { "action": "allow", "match": { "chatType": "direct" } }
        ]
      }
    }
  }
}

四、诊断命令

# 查看记忆状态
openclaw memory status

# 深度检查（显示提供商状态）
openclaw memory status --deep

# 强制重新索引
openclaw memory index --force

# 查看记忆搜索配置
openclaw config get agents.defaults.memorySearch

五、常见问题

问题 1：没有搜索结果

解决：运行 openclaw memory status 检查索引，如果为空运行 openclaw memory index --force

问题 2：只有关键词匹配

解决：嵌入提供商未配置，运行 openclaw memory status --deep 检查

问题 3：中文/日文搜索不准

解决：重建 FTS 索引 openclaw memory index --force

memorySearch 完全配置指南