# Ricerca semantica (embedding)
SUMMARY: Ricerca concettuale delle memorie usando embedding vettoriali — trova per significato, non solo per parole chiave.

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
[CODE BLOCK]
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
[CODE BLOCK]
Risposta:
[CODE BLOCK]
Esempi
Trova memorie sul deployment
[CODE BLOCK]
Restituisce memorie su "deployment", "release", "publishing", "rolling out",
ecc.
Trova pattern di autenticazione
[CODE BLOCK]
Restituisce memorie su login, auth, JWT, gestione sessioni, OAuth, ecc.
Trova memorie simili
[CODE BLOCK]
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 —  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 (, )
- Modelli locali (tramite Ollama o simili)
- Personalizzato (implementi l'interfaccia embeddings)
Configuri tramite variabili di ambiente:
[CODE BLOCK]
Generazione batch
Per menti con molte memorie sprovviste di embedding:
[CODE BLOCK]
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  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:
-  restituisce 503 Service Unavailable
-  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 — 
> - 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
- Memory API
- Architettura