## 摘要

关键词搜索只能精确匹配，搜"偏好"找不到"喜好"，搜"怎么解决"找不到"解决方案"。OpenClaw 的 `memory_search` 用向量检索和相似度排序解决这个问题，让 Agent 能按语义召回 `MEMORY.md` 和 `memory/` 日志中的相关内容。本文讲清工具签名与返回格式、相关性分数区间、`maxResults` 和 `minScore` 的调优策略，并用用户偏好、历史决策、问题检索、任务进度四个场景演示查询写法。读完本文，你能为 Agent 装上"过目不忘"的语义检索能力，并掌握参数调优的边界。

> 📌 版本声明：本文基于 OpenClaw 最新稳定版编写。`memory_search` 的参数、返回字段和底层 provider 可能随版本调整，落地前请以官方文档与 `AGENTS.md` 说明为准。

@[toc]

## 一、为什么需要语义搜索

### 1.1 传统关键词搜索的局限

| 问题 | 说明 | 示例 |
|------|------|------|
| 关键词匹配 | 只能精确匹配，同义词失效 | 搜"偏好"找不到"喜好" |
| 无语义理解 | 不理解查询意图 | 搜"怎么解决"找不到"解决方案" |
| 排序能力弱 | 无法按相关性排序 | 最相关结果排在后面 |
| 上下文缺失 | 无法关联相关内容 | 找不到同一话题的分散记录 |

这四个问题在日志和长期记忆的场景里尤其致命：记忆文件分散在 `MEMORY.md` 和多个 `memory/YYYY-MM-DD.md` 里，用户提问又往往用自然语言，关键词匹配的召回率会很低。

### 1.2 语义搜索的优势

```mermaid
graph LR
    A[用户查询] --> B[向量化]
    B --> C[相似度计算]
    C --> D[按相关性排序]
    D --> E[返回 top-N 结果]
    
    subgraph 传统搜索
        F[查询] --> G[关键词精确匹配]
        G --> H[返回命中结果]
    end
    
    A -.->|对照| F
```

语义搜索的核心链路是"查询→向量化→相似度计算→排序→召回"。它不要求用户说对关键词，只要语义接近就能召回。图中的传统搜索分支用于对照，突出语义搜索在排序和模糊匹配上的优势。

![1.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/54512f34ae585b2e1112b670fec61e07.png)
> 🖼️ **图1：语义搜索 vs 关键词搜索对比图** —— 展示两种检索链路的差异与排序优势。

### 1.3 memory_search 核心能力

| 能力 | 说明 | 效果 |
|------|------|------|
| 语义理解 | 理解查询的真实意图 | 搜"不喜欢"能召回"偏好" |
| 模糊匹配 | 容忍表达差异 | 搜"飞书"能召回"Feishu" |
| 相关性排序 | 按相似度排序结果 | 最相关结果排最前 |
| 多源检索 | 同时搜索多个记忆文件 | 一次查询覆盖全部日志 |

## 二、memory_search 工具详解

### 2.1 工具签名

```python
memory_search(
    query: str,            # 搜索查询文本
    maxResults: int = 5,   # 最大返回结果数
    minScore: float = 0.5  # 最小相关性分数阈值
)
```

`memory_search` 只有三个参数：`query` 是必填的查询文本，`maxResults` 默认 5，`minScore` 默认 0.5。三个参数分别控制"查什么、返回多少、返回多差"，是后文所有调优的起点。

### 2.2 参数详解

| 参数 | 类型 | 默认值 | 作用 |
|------|------|--------|------|
| `query` | string | 必填 | 搜索查询文本 |
| `maxResults` | int | 5 | 返回的最大结果数 |
| `minScore` | float | 0.5 | 结果的最低相关性分数（0-1） |

调参的直觉：结果太多就提高 `minScore` 或减少 `maxResults`；结果太少或不相关就降低 `minScore` 或增加 `maxResults`。但这两个方向不是总能同时满足，需要结合查询词一起调整。

### 2.3 返回格式

```json
{
  "results": [
    {
      "path": "MEMORY.md",
      "lines": "15-18",
      "content": "表达风格：简洁直接，不喜欢啰嗦",
      "score": 0.92
    },
    {
      "path": "memory/2026-04-10.md",
      "lines": "5-8",
      "content": "用户反馈：文章太长了，希望更简洁",
      "score": 0.78
    }
  ],
  "provider": "none",
  "citations": "auto",
  "mode": "fts-only"
}
```

返回结果里每个条目都带 `path`（来源文件）、`lines`（行范围）、`content`（命中内容）和 `score`（相关性分数）。这四个字段足够还原上下文，也能用于引用标注。`provider` 和 `mode` 字段反映底层检索方式，本地部署时可能显示为 `none` 或 `fts-only`，不影响结果使用。

## 三、相关性分数解读

### 3.1 分数区间

| 分数 | 含义 | 建议动作 |
|------|------|----------|
| 0.9-1.0 | 高度相关 | 直接使用 |
| 0.7-0.9 | 相关 | 参考使用 |
| 0.5-0.7 | 弱相关 | 需要人工判断 |
| < 0.5 | 不相关 | 默认不返回 |

分数是 `minScore` 过滤的依据，也是结果排序的依据。理解分数区间后，调 `minScore` 就有明确目标：想让结果更"精炼"就往高调，想"宁可多召回"就往低调。

### 3.2 分数不是唯一标准

```mermaid
stateDiagram-v2
    [*] --> 拿到结果
    拿到结果 --> 判断分数: score >= 0.9
    判断分数 --> 直接使用
    拿到结果 --> 参考判断: 0.7 <= score < 0.9
    参考判断 --> 参考使用
    拿到结果 --> 谨慎判断: 0.5 <= score < 0.7
    谨慎判断 --> 结合上下文判断
    拿到结果 --> 过滤: score < 0.5
    过滤 --> 重试调整: 结果不足
    重试调整 --> 拿到结果
```

状态机展示"分数区间→处理动作"的映射，以及分数不足时的重试回路。它提醒我们：分数只是第一道过滤，`score` 在 0.5-0.7 之间的结果需要结合上下文判断，而不是照单全收。

![2.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/9fa0e5725f73990056a7762614f44af0.png)
> 🖼️ **图2：相关性分数区间状态图** —— 展示四个分数区间对应的处理动作与重试回路。

## 四、搜索策略与参数调优

### 4.1 查询优化技巧

| 技巧 | 说明 | 示例 |
|------|------|------|
| 提取关键词 | 用词组而非长句 | "文章结构 决策" |
| 组合查询 | 组合多个关键词 | "用户 偏好 文章" |
| 尝试同义词 | 换不同表达 | "偏好 / 喜好 / 倾向" |
| 加上下文 | 补充限定信息 | "Gateway 启动失败 解决方案" |

查询质量直接决定召回质量。优先用"关键词组合"而不是完整长句，因为向量化检索对词组的区分度更好。

### 4.2 参数调优决策

```mermaid
flowchart TD
    A[第一次搜索] --> B{结果数量合适?}
    B -->|太多| C[提高 minScore 或减少 maxResults]
    B -->|太少| D[降低 minScore 或增加 maxResults]
    B -->|合适| E[看相关性]
    C --> E
    D --> E
    E --> F{相关性达标?}
    F -->|是| G[使用结果]
    F -->|否| H[优化查询词]
    H --> A
```

调参流程的核心是"先看数量，再看相关性，最后改查询词"。数量不合适先动 `minScore` 和 `maxResults`；数量合适但相关性低，说明查询词没写对，需要换关键词或加上下文。

![3.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/c0633dde1f375f9a82f0f0df26e57581.png)
> 🖼️ **图3：参数调优决策树** —— 展示结果数量与相关性判断驱动的 minScore / maxResults 调整。

### 4.3 场景参数建议

| 场景 | maxResults | minScore | 查询策略 |
|------|-----------|----------|----------|
| 精确查找 | 3 | 0.7 | 关键词组合 |
| 广泛搜索 | 10 | 0.4 | 单个关键词 |
| 决策追溯 | 5 | 0.6 | 决策相关词 |
| 问题检索 | 5 | 0.5 | 问题+解决 |

这组建议是一个起点。精确查找要"少而准"，所以 `maxResults` 小、`minScore` 高；广泛搜索要"多而全"，所以反过来。实际使用时按返回结果微调，不要死记这组数字。

## 五、四大实战场景

### 5.1 用户偏好查询

用户问"我之前说过喜欢什么样的文章风格？"，AI 内部调用：

```python
memory_search(
    query="用户 文章 风格 偏好",
    maxResults=5,
    minScore=0.5
)
```

返回可能命中 `MEMORY.md` 中的"表达风格：简洁直接"（score 0.92）和日志中的"文章太长了，希望更简洁"（score 0.78）。AI 据此回答："你偏好简洁直接的风格，文章不要太长。"这个场景的关键是查询词要覆盖"用户+主题+偏好"三个要素。

### 5.2 历史决策追溯

用户问"我们为什么选择 5 阶段的文章结构？"，AI 内部调用：

```python
memory_search(
    query="文章结构 阶段 决策 原因",
    maxResults=3,
    minScore=0.6
)
```

返回可能命中日志中的"决策：文章采用 5 阶段结构，原因：由浅入深更符合学习曲线"（score 0.89）。这个场景需要较高的 `minScore`，因为决策追溯只想要最相关的那几条，宁可漏掉也不要噪音。

### 5.3 问题解决方案检索

用户问"之前 Gateway 启动失败是怎么解决的？"，AI 内部调用：

```python
memory_search(
    query="Gateway 启动失败 解决方案",
    maxResults=5,
    minScore=0.5
)
```

返回可能命中多个日期的日志，包括端口占用、配置文件路径错误等不同情况。AI 需要按分数排序，优先使用最相关的解法，其他作为补充。这个场景适合中等阈值，因为同类问题可能有多个历史记录。

### 5.4 任务进度查询

用户问"我们的文章项目进度怎么样了？"，AI 内部调用：

```python
memory_search(
    query="文章 项目 进度 完成",
    maxResults=3,
    minScore=0.5
)
```

返回可能命中 `MEMORY.md` 中的项目上下文（score 0.88）和当天日志中的进度（score 0.82）。AI 综合两处结果，给出"已完成 42 篇，完成率 42%"的结论。这个场景的查询词要同时覆盖"项目+进度+完成"，才能同时召回长期和短期记录。

![4.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/14f94ce019274bc0ed92849fcc4fefdd.png)
> 🖼️ **图4：四大查询场景矩阵图** —— 用矩阵对比偏好、决策、问题、进度四类场景的参数与查询词。

## 六、高级搜索技巧

### 6.1 组合查询与时间范围

```python
# 组合查询：用户关于文章的所有反馈
memory_search(
    query="用户 文章 反馈 意见 建议",
    maxResults=10,
    minScore=0.4
)

# 时间范围限定：先确定日期范围再搜索
from datetime import date, timedelta
today = date(2026, 4, 13)
for i in range(7):
    d = today - timedelta(days=i)
    content = read(f"memory/{d.strftime('%Y-%m-%d')}.md")
```

组合查询用宽泛关键词 + 低阈值把同一话题的反馈都召回；时间范围限定则先圈定日期再读文件，适合"只看最近一周"这类需求。两者选择的标准是：跨日期、跨语义的用组合查询；有明确时间窗的用范围限定。

### 6.2 多轮搜索

```mermaid
timeline
    title 多轮搜索的逐步收敛
    section 第一轮
        用关键词初查 : 拿到一批结果
        评估数量 : 太多或太少
    section 第二轮
        调整 minScore : 过滤噪音
        或增加 maxResults : 扩大召回
        评估相关性 : 仍然不相关?
    section 第三轮
        换同义词 : 重新描述查询
        或加上下文 : 补充限定信息
        最终使用 : 结果收敛
```

多轮搜索是"试错-收敛"的过程。第一轮拿到结果后先评估数量，第二轮调参数，第三轮如果还不行就换查询词。每一轮都有明确的调整方向，避免盲目重试。

### 6.3 搜索结果后处理

```python
def process_search_results(results):
    """对搜索结果做结构化后处理"""
    processed = []
    for r in results:
        processed.append({
            "source": r["path"],
            "content": r["content"],
            "relevance": r["score"],
            "date": r["path"].split("/")[-1].replace(".md", "")
        })
    processed.sort(key=lambda x: x["relevance"], reverse=True)
    return processed
```

后处理把返回结果转换成结构化数据，按分数排序并提取日期，供后续回答使用。`r["path"]` 拆出文件名再解析日期，是日志场景里很实用的一步，能直接展示"这条结果来自哪天"。

## 七、搜索性能优化

### 7.1 索引与查询优化

| 优化项 | 说明 | 效果 |
|------|------|------|
| 定期重建索引 | 更新向量索引 | 提高准确性 |
| 缓存热点查询 | 缓存常用结果 | 降低延迟 |
| 精简查询 | 用关键词而非长句 | 提高匹配精度 |
| 避免重复查询 | 合并相似查询 | 减少计算 |

性能优化的优先级是"先查得准，再查得快"。索引重建保证数据最新，查询缓存降低重复开销，精简查询提升单次命中质量。

### 7.2 结果优化

```python
# 结果去重 + 摘要
def dedupe_and_summarize(results):
    seen = set()
    merged = []
    for r in results:
        key = r["content"][:40]  # 用前40字做去重键
        if key not in seen:
            seen.add(key)
            merged.append(r)
    return merged
```

这段代码对结果做去重，用内容前 40 字作为去重键，避免同一句话在多个文件中重复召回。去重后结果更干净，回答时也更少冗余。注意去重键长度要适中，太短会把不同句子误判为重复。

## 八、常见问题与解决

### Q1：搜索结果不准确怎么办？

优化查询关键词、调整 `minScore`、尝试同义词、补充上下文，必要时用多轮搜索收敛。

### Q2：搜索结果太多怎么办？

提高 `minScore`、减少 `maxResults`、用更精确的查询词。

### Q3：搜索结果太少怎么办？

降低 `minScore`、增加 `maxResults`、用更宽泛的关键词。

### Q4：搜索速度慢怎么办？

减少搜索范围、启用查询缓存、定期重建索引、清理过期日志降低索引体量。

## 九、适用边界与风险提示

### 9.1 不适用场景

- **需要精确的结构化数据查询**：语义搜索适合非结构化记忆，精确的字段过滤应使用数据库查询。
- **依赖分数做硬决策**：`score` 是启发式指标，不应作为唯一决策依据，高风险操作仍需人工确认。
- **海量知识库检索**：文件记忆适合个人偏好和项目上下文；百万级知识条目应使用专业向量数据库。

### 9.2 需要注意的点

- `minScore` 和 `maxResults` 需要按场景调优，默认值不是最优解。
- 分数在 0.5-0.7 之间的结果要结合上下文判断，不要机械照搬。
- 语义搜索的召回质量依赖查询词质量，AI 写查询词时应多用关键词组合而非长句。

### 9.3 版本与时效

`memory_search` 的参数、返回字段、底层 provider 可能随版本变化。落地前对照官方文档和 `AGENTS.md` 核对。

## 十、总结

OpenClaw `memory_search` 的核心是"向量检索 + 相关性排序 + 多源召回"，它解决了关键词搜索"搜不到同义词、排不准相关性"的痛点，让 Agent 能按语义从 `MEMORY.md` 和 `memory/` 日志中找回相关记忆。

本文的核心结论是：**查询要精炼，参数要按场景调，分数只是参考不是结论**。`query` 用关键词组合而非长句；`maxResults` 和 `minScore` 按"精确/广泛"两类场景区分；分数在 0.5-0.7 之间的结果需要结合上下文判断。

语义搜索的价值不在于"记住一切"，而在于"在需要的时候找得回"。用好这套机制，Agent 的长期记忆就不再是单向写入的文件堆，而是可检索、可复用的知识库。

## 参考资料

1. OpenClaw 官方文档：https://docs.openclaw.ai
2. OpenClaw GitHub：https://github.com/openclaw/openclaw
3. 向量空间模型：https://baike.baidu.com/item/向量空间模型



关键词搜索只能精确匹配，搜"偏好"找不到"喜好"，搜"怎么解决"找不到"解决方案"。OpenClaw 的 memory_search 用向量检索和相似度排序解决这个问题，让 Agent 能按语义召回 MEMORY.md 和 memory/ 日志中的相关内容。本文讲清工具签名与返回格式、相关性分数区间、maxResults 和 minScore 的调优策略，并用用户偏好、历史决策、问题检索、任务进度四个场景演示查询写法。读完本文，你能为 Agent 装上"过目不忘"的语义检索能力，并掌握参数调优的边界。

OpenClaw memory_search 语义搜索实战：向量检索与参数调优

关键词搜索只能精确匹配，搜"偏好"找不到"喜好"，搜"怎么解决"找不到"解决方案"。OpenClaw 的 memory_search 用向量检索和相似度排序解决这个问题，让 Agent 能按语义召回 MEMORY.md 和 memory/ 日志中的相关内容。本文讲清工具签名与返回格式、相关性分数区间、maxResults 和 minScore 的调优策略，并用用户偏好、历史决策、问题检索、任务进度

项目经理

人工智能

OpenClaw memory_search采用向量检索与相关性排序，解决关键词搜索无法语义匹配的问题，支持按语义从MEMORY.md及日志中召回相关内容。本文详解工具签名与返回格式，剖析相关性分数区间，提供maxResults和minScore调优策略，并通过用户偏好、历史决策、问题检索、任务进度四大场景展示查询写法，助您为Agent构建高效语义记忆检索能力。

向量数据库

结构化数据

代码解释

数据库

OpenClaw

GitHub

Agent

Solid

腾讯云双十一大促

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenClaw memory_search采用向量检索与相关性排序，解决关键词搜索无法语义匹配的问题，支持按语义从MEMORY.md及日志中召回相关内容。本文详解工具签名与返回格式，剖析相关性分数区间，提供maxResults和minScore调优策略，并通过用户偏好、历史决策、问题检索、任务进度四大场景展示查询写法...

OpenClaw memory_search 语义搜索实战：向量检索与参数调优-腾讯云开发者社区-腾讯云

OpenClaw memory_search 语义搜索实战：向量检索与参数调优

OpenClaw memory_search 语义搜索实战：向量检索与参数调优

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐