# FTS5 全文搜索

Synapse 使用 FTS5（Full-Text Search 5）实现快速、灵活的记忆搜索。本页介绍其工作原理以及如何高效使用。

## 什么是 FTS5？

FTS5 是一个 SQLite 扩展（也可通过扩展在 PostgreSQL 中使用），提供全文搜索能力。它能够：

- 为文本内容建立索引以实现快速关键词搜索
- 支持布尔运算符（AND、OR、NOT）
- 支持用引号进行短语匹配
- 支持用 `*` 进行前缀匹配
- 按相关性对结果排序

Synapse 使用 FTS5 为所有记忆内容建立索引，可在数千条记忆上实现亚毫秒级搜索。

## Synapse 如何使用 FTS5

当你 `POST /memory` 时：

1. 记忆内容存储到 `memories` 表
2. 内容也插入到 FTS5 虚拟表
3. FTS5 自动分词并建立索引

当你 `GET /memory/search?q=...` 时：

1. Synapse 使用 FTS5 语法解析查询
2. 对 FTS5 索引执行 `MATCH`
3. 按 `mind_id` 过滤（租户隔离）
4. 返回排序后的结果

## 查询语法

### 简单关键词搜索

```
?q=docker
```

返回包含 "docker" 的记忆。

### 多关键词（隐式 AND）

```
?q=docker+swarm
?q=docker%20swarm
```

返回同时包含 "docker" 和 "swarm" 的记忆。

### 短语匹配

```
?q="docker+swarm"
?q=%22docker%20swarm%22
```

返回包含完整短语 "docker swarm" 的记忆。

### 前缀匹配

```
?q=docker*
```

返回包含以 "docker" 开头的词的记忆（例如 "dockers"、"dockerfile"、"dockerize"）。

### 布尔 OR

```
?q=docker+OR+kubernetes
```

返回包含 "docker" 或 "kubernetes" 的记忆。

### 布尔 NOT

```
?q=docker+-swarm
?q=docker+NOT+swarm
```

返回包含 "docker" 但不包含 "swarm" 的记忆。

### 分组

```
?q=(docker+OR+kubernetes)+-test
```

返回包含 "docker" 或 "kubernetes" 但不包含 "test" 的记忆。

## 实用示例

### 查找关于某个项目的记忆

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"
```

### 查找精确短语

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"
```

### 排除测试记忆

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=production+-test"
```

### 按技术查找

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"
```

## 排序

FTS5 使用 BM25 算法按相关性排序。影响因素：

- 词频（词条出现频率）
- 逆文档频率（更稀有的词条排名更高）
- 文档长度（包含该词条的较短文档排名更高）
- 列权重（标题 > 内容）

结果按相关性返回（最相关的在前）。

## 性能

| 操作 | 延迟 |
|-----------|---------|
| 搜索 100 条记忆 | < 5ms |
| 搜索 1,000 条记忆 | < 10ms |
| 搜索 10,000 条记忆 | < 25ms |
| 搜索 100,000 条记忆 | < 100ms |

FTS5 针对读密集型工作负载做了高度优化。

## 局限性

### 词干提取

FTS5 默认不做词干提取。"running" 和 "run" 是不同的词条。

**变通方案：** 使用前缀匹配：`?q=run*`

### 拼写容错

FTS5 不支持模糊匹配。拼写错误会返回零结果。

**变通方案：** 使用语义搜索（`/memory/semantic-search`）进行概念匹配。

### 停用词

常见词（the、a、an、is）会被索引，但对搜索意义不大。FTS5 会自动处理。

## FTS5 与语义搜索对比

| 方面 | FTS5 | 语义搜索 |
|--------|------|-----------------|
| 速度 | 亚毫秒级 | 50-100ms |
| 匹配方式 | 精确关键词 | 概念 |
| 拼写容错 | 无 | 一定程度 |
| 词干提取 | 无 | 隐式 |
| 是否需要嵌入 | 否 | 是 |
| 适合场景 | 具体术语 | 概念 |

当你知道关键词时使用 FTS5。当你想找“关于 X 的记忆”且 X 用不同方式描述时，使用语义搜索。

## 最佳实践

> [!TIP]
> - **使用具体术语** — "docker swarm" 优于 "container orchestration"
> - **为短语加引号** — `"docker swarm"` 确保短语匹配
> - **用前缀覆盖变体** — `deploy*` 可捕获 "deploy"、"deployment"、"deploying"
> - **排除噪声** — `-test` 过滤掉测试记忆
> - **结合标签** — `?q=docker&tag=production` 缩小结果范围

## 下一步

- [语义搜索](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [记忆最佳实践](/docs/guides/memory-best-practices)