# Ricerca full-text FTS5

Synapse usa FTS5 (Full-Text Search 5) per la ricerca nelle memorie veloce e
flessibile. Questa pagina spiega come funziona e come usarlo efficacemente.

## Cos'è FTS5?

FTS5 è un'estensione SQLite (disponibile anche in PostgreSQL tramite estensioni)
che fornisce funzionalità di ricerca full-text. Essa:

- Indicizza il contenuto testuale per la ricerca veloce per parola chiave
- Supporta operatori booleani (AND, OR, NOT)
- Supporta la corrispondenza di frasi con virgolette
- Supporta la corrispondenza di prefisso con `*`
- Classifica i risultati per rilevanza

Synapse usa FTS5 per indicizzare tutti i contenuti delle memorie, abilitando
ricerca sub-millisecond su migliaia di memorie.

## Come Synapse usa FTS5

Quando fa `POST /memory`:

1. Il contenuto della memoria viene salvato nella tabella `memories`
2. Il contenuto viene anche inserito nella tabella virtuale FTS5
3. FTS5 tokenizza e indicizza automaticamente il contenuto

Quando fa `GET /memory/search?q=...`:

1. Synapse analizza la query usando la sintassi FTS5
2. Esegue un `MATCH` contro l'indice FTS5
3. Filtra per `mind_id` (isolamento tenant)
4. Restituisce i risultati classificati

## Sintassi delle query

### Ricerca semplice per parola chiave

```
?q=docker
```

Restituisce le memorie che contengono "docker".

### Più parole chiave (AND implicito)

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

Restituisce le memorie che contengono SIA "docker" E "swarm".

### Corrispondenza di frase

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

Restituisce le memorie che contengono la frase esatta "docker swarm".

### Corrispondenza di prefisso

```
?q=docker*
```

Restituisce le memorie che contengono parole che iniziano con "docker" (es.
"dockers", "dockerfile", "dockerize").

### OR booleano

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

Restituisce le memorie che contengono "docker" OR "kubernetes".

### NOT booleano

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

Restituisce le memorie che contengono "docker" ma NON "swarm".

### Raggruppamento

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

Restituisce le memorie che contengono "docker" o "kubernetes", ma non "test".

## Esempi pratici

### Trova memorie su un progetto

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

### Trova frase esatta

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

### Escludi memorie di test

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

### Trova per tecnologia

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

## Classificazione

FTS5 classifica i risultati per rilevanza usando l'algoritmo BM25. Fattori:

- Frequenza del termine (quanto spesso appare il termine)
- Inverse document frequency (termini più rari ottengono classifiche più alte)
- Lunghezza del documento (documenti più corti con il termine ottengono classifica più alta)
- Peso della colonna (title > content)

I risultati vengono restituiti in ordine di classifica (più rilevanti per primi).

## Prestazioni

| Operazione | Latenza |
|-----------|---------|
| Ricerca su 100 memorie | < 5ms |
| Ricerca su 1.000 memorie | < 10ms |
| Ricerca su 10.000 memorie | < 25ms |
| Ricerca su 100.000 memorie | < 100ms |

FTS5 è altamente ottimizzato per workload con molti read.

## Limitazioni

### Stemming

FTS5 non fa stemming per default. "running" e "run" sono termini diversi.

**Soluzione:** Usi la corrispondenza di prefisso: `?q=run*`

### Tolleranza ai refusi

FTS5 non supporta il fuzzy matching. Un refuso non restituirà risultati.

**Soluzione:** Usi la ricerca semantica (`/memory/semantic-search`) per
corrispondenza concettuale.

### Stop word

Le parole comuni (the, a, an, is) vengono indicizzate ma potrebbero non essere
utili per la ricerca. FTS5 le gestisce automaticamente.

## FTS5 vs ricerca semantica

| Aspetto | FTS5 | Ricerca semantica |
|--------|------|-----------------|
| Velocità | Sub-millisecond | 50-100ms |
| Corrispondenza | Parole chiave esatte | Concettuale |
| Tolleranza ai refusi | Nessuna | Qualcuna |
| Stemming | Nessuno | Implicito |
| Richiede embedding | No | Sì |
| Ideale per | Termini specifici | Concetti |

Usi FTS5 quando conosce le parole chiave. Usi la ricerca semantica quando vuole
"memorie su X" dove X è descritto diversamente.

## Best practice

> [!TIP]
> - **Usi termini specifici** — "docker swarm" batte "container orchestration"
> - **Usi virgolette per le frasi** — `"docker swarm"` garantisce corrispondenza di frase
> - **Usi il prefisso per le variazioni** — `deploy*` cattura "deploy", "deployment", "deploying"
> - **Escluda il rumore** — `-test` filtra le memorie di test
> - **Combini con i tag** — `?q=docker&tag=production` restringe i risultati

## Prossimi passi

- [Ricerca semantica](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Best practice per la memoria](/docs/guides/memory-best-practices)