# Recherche sémantique (embeddings)
SUMMARY: Recherche de mémoire conceptuelle utilisant des embeddings vectoriels — trouver par signification, pas seulement par mots-clés.

Recherche sémantique (embeddings)
Synapse prend en charge la recherche sémantique utilisant des embeddings vectoriels.
Contrairement à FTS5 (correspondance par mots-clés), la recherche sémantique trouve
les mémoires par signification — même si aucun mot-clé ne correspond.
Comment ça marche
[CODE BLOCK]
Que sont les embeddings ?
Les embeddings sont des représentations vectorielles numériques du texte. Le texte
avec une signification similaire a des vecteurs similaires. Synapse génère un vecteur
(ex. 1536 dimensions) pour le contenu de chaque mémoire.
Similarité cosinus
Pour trouver les mémoires sémantiquement similaires, Synapse calcule la similarité
cosinus entre le vecteur de requête et chaque vecteur de mémoire. Similarité plus
élevée = plus pertinent.
Quand utiliser la recherche sémantique
Utilisez la recherche sémantique quand :
- Vous voulez « des mémoires sur X » où X est décrit différemment que stocké
- FTS5 ne renvoie aucun résultat (aucune correspondance de mot-clé)
- Vous voulez un regroupement conceptuel (ex. toutes les mémoires « deployment », même si certaines disent « release »)
- La requête est une question : « comment gérons-nous l'authentification ? »
Utilisez FTS5 quand :
- Vous connaissez les mots-clés exacts
- Vous avez besoin de logique booléenne (AND, OR, NOT)
- Vous avez besoin d'une réponse sub-milliseconde
- Vous voulez la correspondance de phrase
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Réponse :
[CODE BLOCK]
Exemples
Trouver les mémoires de déploiement
[CODE BLOCK]
Renvoie les mémoires sur « deployment », « release », « publishing », « rolling out »,
etc.
Trouver les schémas d'authentification
[CODE BLOCK]
Renvoie les mémoires sur le login, l'auth, le JWT, la gestion de session, OAuth, etc.
Trouver des mémoires similaires
[CODE BLOCK]
Utilise la similarité sémantique (via tags partagés ET vecteurs d'embedding).
Génération d'embeddings
Quand les embeddings sont-ils générés ?
- Au stockage de mémoire — si le service d'embeddings est configuré, l'embedding est généré de manière synchrone
- Génération par lot —  génère des embeddings pour les mémoires qui en manquent
- Mises à jour asynchrones — quand le contenu est mis à jour, l'embedding est régénéré
Fournisseurs d'embeddings
Synapse prend en charge des fournisseurs d'embeddings configurables :
- OpenAI (, )
- Modèles locaux (via Ollama ou similaire)
- Personnalisé (implémentez l'interface embeddings)
Configurez via des variables d'environnement :
[CODE BLOCK]
Génération par lot
Pour les minds avec beaucoup de mémoires sans embeddings :
[CODE BLOCK]
Performance
| Opération | Latence |
|-----------|---------|
| Génération d'embedding (OpenAI) | 100-200 ms |
| Recherche sémantique (1k mémoires) | 50-100 ms |
| Recherche sémantique (10k mémoires) | 200-500 ms |
| Génération par lot (100 mémoires) | 10-20 s |
> [!NOTE]
> La recherche sémantique est plus lente que FTS5 en raison du calcul vectoriel.
> Utilisez FTS5 pour les mots-clés connus, sémantique pour les requêtes conceptuelles.
Limites
Coût des embeddings
Si vous utilisez OpenAI, générer des embeddings coûte de l'argent (0,02 $ par 1M
tokens pour text-embedding-3-small). Pour 10 000 mémoires de 100 tokens en moyenne,
cela représente 0,02 $ — négligeable.
Démarrage à froid
Les mémoires stockées avant la configuration des embeddings n'en auront pas. Exécutez
 pour les rétroalimenter.
Dépendance au fournisseur
Si le fournisseur d'embeddings est en panne, la recherche sémantique échoue
gracieusement (renvoie des résultats vides ou une erreur). FTS5 fonctionne toujours.
Quand les embeddings ne sont pas disponibles
Si le service d'embeddings n'est pas configuré :
-  renvoie 503 Service Unavailable
-  fonctionne toujours (simplement aucun embedding généré)
- La recherche FTS5 fonctionne toujours
Bonnes pratiques
> [!TIP]
> - Utilisez sémantique pour les requêtes conceptuelles — « comment gérons-nous X ? »
> - Utilisez FTS5 pour les termes spécifiques — « docker swarm »
> - Rétroalimentez les embeddings régulièrement — 
> - Surveillez la santé du fournisseur — la recherche sémantique en dépend
> - Combinez avec les tags — sémantique + filtre de tag affine les résultats
Prochaines étapes
- Recherche FTS5
- API Memory
- Architecture