docs: v1.4 - 新增语义搜索升级方案（方案A，待执行）

- 状态：待执行，需要 OpenAI API Key
- 内容：OpenAI text-embedding-3-large 配置步骤、费用估算、注意事项
- 标注与 QMD reranker 崩溃问题的关联风险

OpenClaw对话和记忆优化初步方案.md

@@ -298,7 +298,7 @@ Before doing anything else:
 
 ---
 
-*本文档由 Ami + 阿米狗共同研究整理，2026-02-17，v1.1 更新于同日，v1.2 QMD 修复记录追加于同日，v1.3 BM25 迁移记录追加于同日*
+*本文档由 Ami + 阿米狗共同研究整理，2026-02-17，v1.1 更新于同日，v1.2 QMD 修复记录追加于同日，v1.3 BM25 迁移记录追加于同日，v1.4 语义搜索升级方案追加于同日*
 
 ---
 
@@ -604,3 +604,74 @@ FROM documents_fts WHERE documents_fts MATCH '暗语' LIMIT 5;
 - 接入 OpenAI `text-embedding-3-large` API
 - 或使用 1B+ 参数的本地 GGUF embedding 模型
 - 届时恢复混合搜索（BM25 + 向量），调整 `vectorWeight` / `textWeight`
+
+---
+
+## 附录：语义搜索升级方案（方案 A）（v1.4）
+
+> 状态：**待执行**（需要 OpenAI API Key）  
+> 记录于 2026-02-17
+
+### 背景
+
+当前系统使用纯 BM25（`qmd search`）做记忆召回，精确关键词效果好，但无法处理语义模糊查询（如：记不住原话、换了说法搜不到）。
+
+本地 300M embedding 模型（embeddinggemma-300M）质量不足以支撑语义搜索（已验证），`qmd query`（混合搜索）因 reranker 崩溃问题无法使用。
+
+### 方案内容
+
+将 OpenClaw 的 memory embedding provider 切换为 OpenAI，启用高质量向量索引。
+
+#### 所需条件
+
+- OpenAI API Key（`sk-...`）
+- 有效配额（`text-embedding-3-large` 费率：$0.13 / 百万 tokens）
+
+#### 预计费用
+
+个人使用场景下，MEMORY.md + memory/*.md + session 历史总量约几十万字符，每次全量重建索引消耗 < $0.01，日常增量更新接近免费。
+
+#### 执行步骤
+
+1. **修改 OpenClaw 配置**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "enabled": true,
+        "provider": "openai",
+        "model": "text-embedding-3-large",
+        "remote": {
+          "apiKey": "sk-YOUR_KEY_HERE"
+        },
+        "fallback": "none"
+      }
+    }
+  }
+}
+```
+
+2. **切换 QMD wrapper 回混合搜索**
+
+修改 `/Users/mini/clawd/scripts/qmd-wrapper.sh`，将 `search` 改回 `vsearch` 或 `query`（待测试哪种与 OpenAI embedding 配合更好）。
+
+3. **触发索引重建**
+
+```bash
+# 手动触发 QMD 重新 embed 所有文档
+XDG_CACHE_HOME=~/.openclaw/agents/main/qmd/xdg-cache \
+XDG_CONFIG_HOME=~/.openclaw/agents/main/qmd/xdg-config \
+/Users/mini/.bun/bin/qmd embed
+```
+
+4. **验证**
+
+在新会话中搜索一段换了说法的内容（如用"账号合租"搜索"iShare"相关内容），确认语义命中。
+
+#### 注意事项
+
+- OpenClaw 的 `memorySearch` 与 `memory.backend: "qmd"` 是两套独立机制；配置后需验证 `provider` 显示为 `"openai"` 而非 `"qmd"` 才说明 embedding 生效
+- QMD 的 reranker 崩溃问题（chunk > 2062 tokens）是否依然存在需重新测试；如仍崩溃，`qmd-wrapper.sh` 应保持用 `vsearch` 替代 `query`
+- API Key 请勿直接写入 `openclaw.json`（会明文存储在 `~/.openclaw/`），建议使用环境变量或 gateway `env.vars` 配置