Semantisch zoeken (Embeddings)

Synapse ondersteunt semantisch zoeken met behulp van vector-embeddings. In tegenstelling tot FTS5 (trefwoordovereenkomst) vindt semantisch zoeken herinneringen op betekenis — zelfs als er geen trefwoorden overeenkomen.

Hoe het werkt

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

Wat zijn embeddings?

Embeddings zijn numerieke vectorrepresentaties van tekst. Tekst met vergelijkbare betekenis heeft vergelijkbare vectoren. Synapse genereert een vector (bijv. 1536 dimensies) voor de inhoud van elke herinnering.

Cosinus-similariteit

Om semantisch vergelijkbare herinneringen te vinden, berekent Synapse de cosinus-similariteit tussen de query-vector en elke memory-vector. Hogere similariteit = meer relevant.

Wanneer semantisch zoeken gebruiken

Gebruik semantisch zoeken wanneer:

• U "herinneringen over X" wilt waarbij X anders wordt omschreven dan opgeslagen
• FTS5 geen resultaten retourneert (geen trefwoordovereenkomst)
• U conceptuele groepering wilt (bijv. alle "deployment"-herinneringen, zelfs als sommige "release" zeggen)
• De query een vraag is: "hoe handelen we authenticatie?"

Gebruik FTS5 wanneer:

• U exacte trefwoorden kent
• U booleaanse logica nodig heeft (AND, OR, NOT)
• U sub-milliseconde respons nodig hebt
• U zinsovereenkomst wilt

Eindpunt

GET /memory/semantic-search

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

Respons:

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

Voorbeelden

Vind deployment-herinneringen

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

Retourneert herinneringen over "deployment", "release", "publishing", "rolling out", enz.

Vind authenticatie-patronen

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

Retourneert herinneringen over login, auth, JWT, sessiebeheer, OAuth, enz.

Vind vergelijkbare herinneringen

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

Gebruikt semantische similariteit (via gedeelde tags EN embedding-vectoren).

Embedding-generatie

Wanneer worden embeddings gegenereerd?

• Bij memory-opslag — als embeddings-service is geconfigureerd, wordt embedding synchroon gegenereerd
• Batch-generatie — POST /memory/embed-batch genereert embeddings voor herinneringen die deze missen
• Asynchrone updates — wanneer inhoud wordt bijgewerkt, wordt embedding opnieuw gegenereerd

Embedding-providers

Synapse ondersteunt configureerbare embedding-providers:

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• Lokale modellen (via Ollama of vergelijkbaar)
• Aangepast (implementeer de embeddings-interface)

Configureer via omgevingsvariabelen:

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

Batch-generatie

Voor minds met veel herinneringen die embeddings missen:

# 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

Prestaties

Beperkingen

Kosten van embeddings

Bij gebruik van OpenAI kost het genereren van embeddings geld (~$0,02 per 1M tokens voor text-embedding-3-small). Voor 10.000 herinneringen met gemiddeld 100 tokens elk, is dat ~$0,02 — verwaarloosbaar.

Cold start

Herinneringen die zijn opgeslagen voordat embeddings waren geconfigureerd, hebben geen embeddings. Voer POST /memory/embed-batch uit om bij te vullen.

Provider-afhankelijkheid

Als de embeddings-provider niet beschikbaar is, faalt semantisch zoeken graceful (retourneert lege resultaten of een fout). FTS5 blijft werken.

Wanneer embeddings niet beschikbaar zijn

Als embeddings-service niet is geconfigureerd:

• GET /memory/semantic-search retourneert 503 Service Unavailable
• POST /memory blijft werken (alleen geen embedding gegenereerd)
• FTS5-zoekopdracht blijft werken

Best practices

Volgende stappen

• FTS5-zoekopdracht
• Memory API
• Architectuur