Semantisk sökning (inbäddningar)

Synapse stöder semantisk sökning med vektorinbäddningar. Till skillnad från FTS5 (nyckelordsmatchning) hittar semantisk sökning minnen efter betydelse — även om inga nyckelord matchar.

Hur det fungerar

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

Vad är inbäddningar?

Inbäddningar är numeriska vektorrepresentationer av text. Text med liknande betydelse har liknande vektorer. Synapse genererar en vektor (t.ex. 1536 dimensioner) för varje minnes innehåll.

Cosine similarity

För att hitta semantiskt liknande minnen beräknar Synapse cosinuslikheten mellan frågevektorn och varje minnesvektor. Högre likhet = mer relevant.

När semantisk sökning ska användas

Använd semantisk sökning när:

• Ni vill ha "minnen om X" där X beskrivs annorlunda än lagrat
• FTS5 returnerar inga resultat (ingen nyckelordsmatchning)
• Ni vill ha begreppslig gruppering (t.ex. alla "deployment"-minnen, även om vissa säger "release")
• Frågan är en fråga: "hur hanterar vi autentisering?"

Använd FTS5 när:

• Ni känner till exakta nyckelord
• Ni behöver boolesk logik (AND, OR, NOT)
• Ni behöver svar under en millisekund
• Ni vill ha frasmatchning

Endpoint

GET /memory/semantic-search

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

Svar:

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

Exempel

Hitta driftsättningsminnen

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

Returnerar minnen om "deployment", "release", "publishing", "rolling out" etc.

Hitta autentiseringsmönster

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

Returnerar minnen om inloggning, auth, JWT, sessionshantering, OAuth etc.

Hitta liknande minnen

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

Använder semantisk likhet (via gemensamma taggar OCH inbäddningsvektorer).

Inbäddningsgenerering

När genereras inbäddningar?

• Vid minneslagring — om inbäddningstjänst är konfigurerad genereras inbäddning synkront
• Batchgenerering — POST /memory/embed-batch genererar inbäddningar för minnen som saknar dem
• Asynkrona uppdateringar — när innehåll uppdateras regenereras inbäddningen

Inbäddningsleverantörer

Synapse stöder konfigurerbara inbäddningsleverantörer:

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• Lokala modeller (via Ollama eller liknande)
• Anpassade (implementera inbäddningsgränssnittet)

Konfigurera via miljövariabler:

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

Batchgenerering

För minds med många minnen som saknar inbäddningar:

# 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

Prestanda

Begränsningar

Kostnad för inbäddningar

Om ni använder OpenAI kostar generering av inbäddningar pengar (~$0,02 per 1M tokens för text-embedding-3-small). För 10 000 minnen med i snitt 100 tokens var blir det ~$0,02 — försumbart.

Kallstart

Minnen som lagrats innan inbäddningar konfigurerades kommer inte att ha inbäddningar. Kör POST /memory/embed-batch för att fylla i.

Leverantörsberoende

Om inbäddningsleverantören är nere misslyckas semantisk sökning graciöst (returnerar tomma resultat eller fel). FTS5 fungerar fortfarande.

När inbäddningar inte är tillgängliga

Om inbäddningstjänst inte är konfigurerad:

• GET /memory/semantic-search returnerar 503 Service Unavailable
• POST /memory fungerar fortfarande (bara ingen inbäddning genererad)
• FTS5-sökning fungerar fortfarande

Bästa praxis

Nästa steg

• FTS5-sökning
• Memory API
• Arkitektur