# 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

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

Réponse :

```json
{
  "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

```bash
# 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

```bash
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

```bash
# 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 :

```bash
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 :

```bash
# 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

| 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
`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

> [!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** — `POST /memory/embed-batch`
> - **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](/docs/concepts/fts5-search)
- [API Memory](/docs/api/memory)
- [Architecture](/docs/concepts/architecture)