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

1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned

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

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

Réponse :

{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}

Exemples

Trouver les mémoires de déploiement

# FTS5 peut en manquer — la sémantique les attrape toutes
curl .../memory/semantic-search?q=deployment+process

Renvoie les mémoires sur « deployment », « release », « publishing », « rolling out », etc.

Trouver les schémas d'authentification

curl .../memory/semantic-search?q=how+do+users+log+in

Renvoie les mémoires sur le login, l'auth, le JWT, la gestion de session, OAuth, etc.

Trouver des mémoires similaires

# Trouver les mémoires similaires à une spécifique
curl .../memory/related/mem_001

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 — POST /memory/embed-batch 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 (text-embedding-3-small, text-embedding-3-large)
• Modèles locaux (via Ollama ou similaire)
• Personnalisé (implémentez l'interface embeddings)

Configurez via des variables d'environnement :

EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small

Génération par lot

Pour les minds avec beaucoup de mémoires sans embeddings :

# Générer des embeddings pour jusqu'à 100 mémoires
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Vérifier la progression
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

Performance

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 POST /memory/embed-batch 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é :

• GET /memory/semantic-search renvoie 503 Service Unavailable
• POST /memory fonctionne toujours (simplement aucun embedding généré)
• La recherche FTS5 fonctionne toujours

Bonnes pratiques

Prochaines étapes

• Recherche FTS5
• API Memory
• Architecture