# Recherche en texte intégral FTS5

Synapse utilise FTS5 (Full-Text Search 5) pour une recherche de mémoire rapide et
flexible. Cette page explique son fonctionnement et comment l'utiliser efficacement.

## Qu'est-ce que FTS5 ?

FTS5 est une extension SQLite (aussi disponible dans PostgreSQL via des extensions)
qui fournit des capacités de recherche en texte intégral. Elle :

- Indexe le contenu textuel pour la recherche rapide par mot-clé
- Prend en charge les opérateurs booléens (AND, OR, NOT)
- Prend en charge la correspondance de phrases avec des guillemets
- Prend en charge la correspondance par préfixe avec `*`
- Classe les résultats par pertinence

Synapse utilise FTS5 pour indexer tout le contenu des mémoires, ce qui permet une
recherche sub-milliseconde à travers des milliers de mémoires.

## Comment Synapse utilise FTS5

Lorsque vous faites `POST /memory` :

1. Le contenu de la mémoire est stocké dans la table `memories`
2. Le contenu est aussi inséré dans la table virtuelle FTS5
3. FTS5 tokenize et indexe automatiquement le contenu

Lorsque vous faites `GET /memory/search?q=...` :

1. Synapse analyse la requête en utilisant la syntaxe FTS5
2. Exécute un `MATCH` contre l'index FTS5
3. Filtre par `mind_id` (isolation tenant)
4. Renvoie les résultats classés

## Syntaxe de requête

### Recherche simple par mot-clé

```
?q=docker
```

Renvoie les mémoires contenant « docker ».

### Plusieurs mots-clés (AND implicite)

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

Renvoie les mémoires contenant À LA FOIS « docker » ET « swarm ».

### Correspondance de phrase

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

Renvoie les mémoires contenant la phrase exacte « docker swarm ».

### Correspondance par préfixe

```
?q=docker*
```

Renvoie les mémoires contenant des mots commençant par « docker » (ex. « dockers »,
« dockerfile », « dockerize »).

### Booléen OR

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

Renvoie les mémoires contenant « docker » OU « kubernetes ».

### Booléen NOT

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

Renvoie les mémoires contenant « docker » mais PAS « swarm ».

### Regroupement

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

Renvoie les mémoires contenant « docker » ou « kubernetes », mais pas « test ».

## Exemples pratiques

### Trouver des mémoires sur un projet

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

### Trouver une phrase exacte

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

### Exclure les mémoires de test

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

### Rechercher par technologie

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

## Classement

FTS5 classe les résultats par pertinence en utilisant l'algorithme BM25. Facteurs :

- Fréquence du terme (combien de fois le terme apparaît)
- Fréquence inverse de document (les termes rares sont mieux classés)
- Longueur du document (les documents plus courts avec le terme sont mieux classés)
- Pondération de colonne (titre > contenu)

Les résultats sont renvoyés dans l'ordre de classement (les plus pertinents d'abord).

## Performance

| Opération | Latence |
|-----------|---------|
| Recherche dans 100 mémoires | < 5 ms |
| Recherche dans 1 000 mémoires | < 10 ms |
| Recherche dans 10 000 mémoires | < 25 ms |
| Recherche dans 100 000 mémoires | < 100 ms |

FTS5 est hautement optimisé pour les charges de travail à forte lecture.

## Limites

### Stemming

FTS5 ne fait pas de stemming par défaut. « running » et « run » sont des termes
différents.

**Contournement :** Utilisez la correspondance par préfixe : `?q=run*`

### Tolérance aux fautes de frappe

FTS5 ne prend pas en charge la correspondance floue. Une faute de frappe ne renverra
aucun résultat.

**Contournement :** Utilisez la recherche sémantique
(`/memory/semantic-search`) pour la correspondance conceptuelle.

### Mots vides

Les mots courants (the, a, an, is) sont indexés mais peuvent ne pas être utiles pour
la recherche. FTS5 gère cela automatiquement.

## FTS5 vs recherche sémantique

| Aspect | FTS5 | Recherche sémantique |
|--------|------|-----------------|
| Vitesse | Sub-milliseconde | 50-100 ms |
| Correspondance | Mots-clés exacts | Conceptuelle |
| Tolérance aux fautes | Aucune | Quelque peu |
| Stemming | Aucun | Implicite |
| Requiert des embeddings | Non | Oui |
| Idéal pour | Termes spécifiques | Concepts |

Utilisez FTS5 lorsque vous connaissez les mots-clés. Utilisez la recherche sémantique
lorsque vous voulez « des mémoires sur X » où X est décrit différemment.

## Bonnes pratiques

> [!TIP]
> - **Utilisez des termes spécifiques** — « docker swarm » bat « container orchestration »
> - **Citez les phrases** — `"docker swarm"` garantit la correspondance de phrase
> - **Utilisez un préfixe pour les variantes** — `deploy*` capture « deploy », « deployment », « deploying »
> - **Excluez le bruit** — `-test` filtre les mémoires de test
> - **Combinez avec les tags** — `?q=docker&tag=production` affine les résultats

## Prochaines étapes

- [Recherche sémantique](/docs/concepts/semantic-search)
- [API Memory](/docs/api/memory)
- [Bonnes pratiques mémoire](/docs/guides/memory-best-practices)