# Ricerca semantica (embedding)

Synapse supporta la ricerca semantica usando embedding vettoriali. A differenza
di FTS5 (corrispondenza per parola chiave), la ricerca semantica trova le
memorie per **significato** — anche se nessuna parola chiave corrisponde.

## Come funziona

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

### Cosa sono gli embedding?

Gli embedding sono rappresentazioni vettoriali numeriche del testo. Testo con
significato simile ha vettori simili. Synapse genera un vettore (es. 1536
dimensioni) per il contenuto di ogni memoria.

### Similarità del coseno

Per trovare memorie semanticamente simili, Synapse calcola la similarità del
coseno tra il vettore della query e ogni vettore di memoria. Similarità più
alta = più rilevante.

## Quando usare la ricerca semantica

### Usi la ricerca semantica quando:

- Vuole "memorie su X" dove X è descritto diversamente da come è salvato
- FTS5 non restituisce risultati (nessuna corrispondenza di parola chiave)
- Vuole raggruppamento concettuale (es. tutte le memorie "deployment", anche se alcune dicono "release")
- La query è una domanda: "come gestiamo l'autenticazione?"

### Usi FTS5 quando:

- Conosce le parole chiave esatte
- Ha bisogno di logica booleana (AND, OR, NOT)
- Ha bisogno di risposta sub-millisecond
- Vuole corrispondenza di frase

## Endpoint

### GET /memory/semantic-search

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

Risposta:

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

## Esempi

### Trova memorie sul deployment

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

Restituisce memorie su "deployment", "release", "publishing", "rolling out",
ecc.

### Trova pattern di autenticazione

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

Restituisce memorie su login, auth, JWT, gestione sessioni, OAuth, ecc.

### Trova memorie simili

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

Usa similarità semantica (tramite tag condivisi E vettori di embedding).

## Generazione degli embedding

### Quando vengono generati gli embedding?

- **Su memorizzazione** — se il servizio embedding è configurato, l'embedding viene generato in modo sincrono
- **Generazione batch** — `POST /memory/embed-batch` genera embedding per le memorie che ne sono sprovviste
- **Aggiornamenti asincroni** — quando il contenuto viene aggiornato, l'embedding viene rigenerato

### Provider di embedding

Synapse supporta provider di embedding configurabili:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Modelli locali** (tramite Ollama o simili)
- **Personalizzato** (implementi l'interfaccia embeddings)

Configuri tramite variabili di ambiente:

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

### Generazione batch

Per menti con molte memorie sprovviste di embedding:

```bash
# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Prestazioni

| Operazione | Latenza |
|-----------|---------|
| Genera embedding (OpenAI) | 100-200ms |
| Ricerca semantica (1k memorie) | 50-100ms |
| Ricerca semantica (10k memorie) | 200-500ms |
| Generazione batch (100 memorie) | 10-20s |

> [!NOTE]
> La ricerca semantica è più lenta di FTS5 a causa del calcolo vettoriale. Usi
> FTS5 per parole chiave note, semantica per query concettuali.

## Limitazioni

### Costo degli embedding

Se usa OpenAI, generare embedding costa denaro (~$0,02 per 1M token per
text-embedding-3-small). Per 10.000 memorie con una media di 100 token ciascuna,
sono ~$0,02 — trascurabile.

### Cold start

Le memorie salvate prima che gli embedding fossero configurati non avranno
embedding. Esegua `POST /memory/embed-batch` per backfill.

### Dipendenza dal provider

Se il provider di embedding è down, la ricerca semantica fallisce in modo
grazioso (restituisce risultati vuoti o errore). FTS5 continua a funzionare.

## Quando gli embedding non sono disponibili

Se il servizio embedding non è configurato:

- `GET /memory/semantic-search` restituisce 503 Service Unavailable
- `POST /memory` funziona comunque (solo senza embedding generato)
- La ricerca FTS5 funziona ancora

## Best practice

> [!TIP]
> - **Usi la semantica per query concettuali** — "come gestiamo X?"
> - **Usi FTS5 per termini specifici** — "docker swarm"
> - **Faccia backfill degli embedding regolarmente** — `POST /memory/embed-batch`
> - **Monitori la salute del provider** — la ricerca semantica dipende da esso
> - **Combini con i tag** — semantica + filtro tag restringe i risultati

## Prossimi passi

- [Ricerca FTS5](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Architettura](/docs/concepts/architecture)