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

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

Trouver une phrase exacte

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

Exclure les mémoires de test

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

Rechercher par technologie

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

Prochaines étapes

• Recherche sémantique
• API Memory
• Bonnes pratiques mémoire