# Busca em texto completo FTS5

O Synapse usa FTS5 (Full-Text Search 5) para busca de memória rápida e flexível.
Esta página explica como funciona e como usá-lo de forma eficaz.

## O que é FTS5?

FTS5 é uma extensão do SQLite (também disponível no PostgreSQL via extensões)
que oferece capacidades de busca em texto completo. Ele:

- Indexa conteúdo textual para busca rápida por palavras-chave
- Suporta operadores booleanos (AND, OR, NOT)
- Suporta correspondência de frases com aspas
- Suporta correspondência por prefixo com `*`
- Classifica resultados por relevância

O Synapse usa FTS5 para indexar todo o conteúdo das memórias, permitindo busca
sub-milissegundo entre milhares de memórias.

## Como o Synapse usa FTS5

Quando você faz `POST /memory`:

1. O conteúdo da memória é armazenado na tabela `memories`
2. O conteúdo também é inserido na tabela virtual FTS5
3. FTS5 automaticamente tokeniza e indexa o conteúdo

Quando você faz `GET /memory/search?q=...`:

1. O Synapse faz parse da consulta usando a sintaxe FTS5
2. Executa um `MATCH` contra o índice FTS5
3. Filtra por `mind_id` (isolamento de tenant)
4. Retorna resultados classificados

## Sintaxe de consulta

### Busca simples por palavra-chave

```
?q=docker
```

Retorna memórias contendo "docker".

### Múltiplas palavras-chave (AND implícito)

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

Retorna memórias contendo TANTO "docker" QUANTO "swarm".

### Correspondência de frase

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

Retorna memórias contendo a frase exata "docker swarm".

### Correspondência por prefixo

```
?q=docker*
```

Retorna memórias contendo palavras que começam com "docker" (ex.: "dockers",
"dockerfile", "dockerize").

### Booleano OR

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

Retorna memórias contendo "docker" OU "kubernetes".

### Booleano NOT

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

Retorna memórias contendo "docker" mas NÃO "swarm".

### Agrupamento

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

Retorna memórias contendo "docker" ou "kubernetes", mas não "test".

## Exemplos práticos

### Encontrar memórias sobre um projeto

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

### Encontrar frase exata

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

### Excluir memórias de teste

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

### Buscar por tecnologia

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

## Ranking

FTS5 classifica resultados por relevância usando o algoritmo BM25. Fatores:

- Frequência do termo (com que frequência o termo aparece)
- Frequência inversa de documentos (termos mais raros recebem classificação maior)
- Comprimento do documento (documentos mais curtos com o termo recebem classificação maior)
- Peso da coluna (title > content)

Os resultados são retornados em ordem de classificação (mais relevantes primeiro).

## Desempenho

| Operação | Latência |
|----------|----------|
| Busca em 100 memórias | < 5ms |
| Busca em 1.000 memórias | < 10ms |
| Busca em 10.000 memórias | < 25ms |
| Busca em 100.000 memórias | < 100ms |

FTS5 é altamente otimizado para workloads com muita leitura.

## Limitações

### Stemming

FTS5 não faz stemming por padrão. "running" e "run" são termos diferentes.

**Solução alternativa:** Use correspondência por prefixo: `?q=run*`

### Tolerância a typos

FTS5 não suporta correspondência fuzzy. Um typo não retornará resultados.

**Solução alternativa:** Use busca semântica (`/memory/semantic-search`) para
correspondência conceitual.

### Stop words

Palavras comuns (the, a, an, is) são indexadas mas podem não ser úteis para
busca. FTS5 lida com isso automaticamente.

## FTS5 vs busca semântica

| Aspecto | FTS5 | Busca semântica |
|---------|------|-----------------|
| Velocidade | Sub-milissegundo | 50-100ms |
| Correspondência | Palavras-chave exatas | Conceitual |
| Tolerância a typos | Nenhuma | Alguma |
| Stemming | Nenhum | Implícito |
| Requer embeddings | Não | Sim |
| Melhor para | Termos específicos | Conceitos |

Use FTS5 quando você conhece as palavras-chave. Use busca semântica quando você
quer "memórias sobre X" onde X é descrito de outra forma.

## Melhores práticas

> [!TIP]
> - **Use termos específicos** — "docker swarm" supera "container orchestration"
> - **Aspas para frases** — `"docker swarm"` garante correspondência de frase
> - **Use prefixo para variações** — `deploy*` captura "deploy", "deployment", "deploying"
> - **Exclua ruído** — `-test` filtra memórias de teste
> - **Combine com tags** — `?q=docker&tag=production` estreita os resultados

## Próximos passos

- [Busca semântica](/docs/concepts/semantic-search)
- [API de Memória](/docs/api/memory)
- [Melhores práticas de memória](/docs/guides/memory-best-practices)