# Semantisch zoeken (Embeddings)
SUMMARY: Conceptueel zoeken in herinneringen met vector-embeddings — vind op betekenis, niet alleen op trefwoorden.

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
[CODE BLOCK]
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
[CODE BLOCK]
Respons:
[CODE BLOCK]
Voorbeelden
Vind deployment-herinneringen
[CODE BLOCK]
Retourneert herinneringen over "deployment", "release", "publishing", "rolling out",
enz.
Vind authenticatie-patronen
[CODE BLOCK]
Retourneert herinneringen over login, auth, JWT, sessiebeheer, OAuth, enz.
Vind vergelijkbare herinneringen
[CODE BLOCK]
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 —  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 (, )
- Lokale modellen (via Ollama of vergelijkbaar)
- Aangepast (implementeer de embeddings-interface)
Configureer via omgevingsvariabelen:
[CODE BLOCK]
Batch-generatie
Voor minds met veel herinneringen die embeddings missen:
[CODE BLOCK]
Prestaties
| Bewerking | Latentie |
|-----------|----------|
| Embedding genereren (OpenAI) | 100-200ms |
| Semantisch zoeken (1k herinneringen) | 50-100ms |
| Semantisch zoeken (10k herinneringen) | 200-500ms |
| Batch-generatie (100 herinneringen) | 10-20s |
> [!NOTE]
> Semantisch zoeken is langzamer dan FTS5 vanwege vectorberekening. Gebruik FTS5
> voor bekende trefwoorden, semantisch voor conceptuele query's.
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  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:
-  retourneert 503 Service Unavailable
-  blijft werken (alleen geen embedding gegenereerd)
- FTS5-zoekopdracht blijft werken
Best practices
> [!TIP]
> - Gebruik semantisch voor conceptuele query's — "hoe handelen we X?"
> - Gebruik FTS5 voor specifieke termen — "docker swarm"
> - Vul embeddings regelmatig bij — 
> - Monitor provider-gezondheid — semantisch zoeken is ervan afhankelijk
> - Combineer met tags — semantisch + tag-filter verfijnt resultaten
Volgende stappen
- FTS5-zoekopdracht
- Memory API
- Architectuur