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

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

Risposta:

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

# 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

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

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

Trova memorie simili

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

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

Generazione batch

Per menti con molte memorie sprovviste di embedding:

# 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

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

Prossimi passi

• Ricerca FTS5
• Memory API
• Architettura