{"title":"Semantisch zoeken (Embeddings)","slug":"semantic-search","category":"concepts","summary":"Conceptueel zoeken in herinneringen met vector-embeddings — vind op betekenis, niet alleen op trefwoorden.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":506,"read_minutes":3,"lang":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# Semantisch zoeken (Embeddings)\n\nSynapse ondersteunt semantisch zoeken met behulp van vector-embeddings. In tegenstelling\ntot FTS5 (trefwoordovereenkomst) vindt semantisch zoeken herinneringen op **betekenis** —\nzelfs als er geen trefwoorden overeenkomen.\n\n## Hoe het werkt\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### Wat zijn embeddings?\n\nEmbeddings zijn numerieke vectorrepresentaties van tekst. Tekst met vergelijkbare\nbetekenis heeft vergelijkbare vectoren. Synapse genereert een vector (bijv. 1536 dimensies)\nvoor de inhoud van elke herinnering.\n\n### Cosinus-similariteit\n\nOm semantisch vergelijkbare herinneringen te vinden, berekent Synapse de cosinus-similariteit\ntussen de query-vector en elke memory-vector. Hogere similariteit = meer\nrelevant.\n\n## Wanneer semantisch zoeken gebruiken\n\n### Gebruik semantisch zoeken wanneer:\n\n- U \"herinneringen over X\" wilt waarbij X anders wordt omschreven dan opgeslagen\n- FTS5 geen resultaten retourneert (geen trefwoordovereenkomst)\n- U conceptuele groepering wilt (bijv. alle \"deployment\"-herinneringen, zelfs als sommige \"release\" zeggen)\n- De query een vraag is: \"hoe handelen we authenticatie?\"\n\n### Gebruik FTS5 wanneer:\n\n- U exacte trefwoorden kent\n- U booleaanse logica nodig heeft (AND, OR, NOT)\n- U sub-milliseconde respons nodig hebt\n- U zinsovereenkomst wilt\n\n## Eindpunt\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nRespons:\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## Voorbeelden\n\n### Vind deployment-herinneringen\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nRetourneert herinneringen over \"deployment\", \"release\", \"publishing\", \"rolling out\",\nenz.\n\n### Vind authenticatie-patronen\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nRetourneert herinneringen over login, auth, JWT, sessiebeheer, OAuth, enz.\n\n### Vind vergelijkbare herinneringen\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nGebruikt semantische similariteit (via gedeelde tags EN embedding-vectoren).\n\n## Embedding-generatie\n\n### Wanneer worden embeddings gegenereerd?\n\n- **Bij memory-opslag** — als embeddings-service is geconfigureerd, wordt embedding synchroon gegenereerd\n- **Batch-generatie** — `POST /memory/embed-batch` genereert embeddings voor herinneringen die deze missen\n- **Asynchrone updates** — wanneer inhoud wordt bijgewerkt, wordt embedding opnieuw gegenereerd\n\n### Embedding-providers\n\nSynapse ondersteunt configureerbare embedding-providers:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Lokale modellen** (via Ollama of vergelijkbaar)\n- **Aangepast** (implementeer de embeddings-interface)\n\nConfigureer via omgevingsvariabelen:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Batch-generatie\n\nVoor minds met veel herinneringen die embeddings missen:\n\n```bash\n# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# Check progress\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Prestaties\n\n| Bewerking | Latentie |\n|-----------|----------|\n| Embedding genereren (OpenAI) | 100-200ms |\n| Semantisch zoeken (1k herinneringen) | 50-100ms |\n| Semantisch zoeken (10k herinneringen) | 200-500ms |\n| Batch-generatie (100 herinneringen) | 10-20s |\n\n> [!NOTE]\n> Semantisch zoeken is langzamer dan FTS5 vanwege vectorberekening. Gebruik FTS5\n> voor bekende trefwoorden, semantisch voor conceptuele query's.\n\n## Beperkingen\n\n### Kosten van embeddings\n\nBij gebruik van OpenAI kost het genereren van embeddings geld (~$0,02 per 1M tokens\nvoor text-embedding-3-small). Voor 10.000 herinneringen met gemiddeld 100 tokens elk,\nis dat ~$0,02 — verwaarloosbaar.\n\n### Cold start\n\nHerinneringen die zijn opgeslagen voordat embeddings waren geconfigureerd, hebben geen\nembeddings. Voer `POST /memory/embed-batch` uit om bij te vullen.\n\n### Provider-afhankelijkheid\n\nAls de embeddings-provider niet beschikbaar is, faalt semantisch zoeken graceful\n(retourneert lege resultaten of een fout). FTS5 blijft werken.\n\n## Wanneer embeddings niet beschikbaar zijn\n\nAls embeddings-service niet is geconfigureerd:\n\n- `GET /memory/semantic-search` retourneert 503 Service Unavailable\n- `POST /memory` blijft werken (alleen geen embedding gegenereerd)\n- FTS5-zoekopdracht blijft werken\n\n## Best practices\n\n> [!TIP]\n> - **Gebruik semantisch voor conceptuele query's** — \"hoe handelen we X?\"\n> - **Gebruik FTS5 voor specifieke termen** — \"docker swarm\"\n> - **Vul embeddings regelmatig bij** — `POST /memory/embed-batch`\n> - **Monitor provider-gezondheid** — semantisch zoeken is ervan afhankelijk\n> - **Combineer met tags** — semantisch + tag-filter verfijnt resultaten\n\n## Volgende stappen\n\n- [FTS5-zoekopdracht](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architectuur](/docs/concepts/architecture)\n","content_html":"

Semantisch zoeken (Embeddings)

\n

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

\n

Hoe het werkt

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

Wat zijn embeddings?

\n

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

\n

Cosinus-similariteit

\n

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

\n

Wanneer semantisch zoeken gebruiken

\n

Gebruik semantisch zoeken wanneer:

\n\n

Gebruik FTS5 wanneer:

\n\n

Eindpunt

\n

GET /memory/semantic-search

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

Respons:

\n
{\n  "results": [\n    {\n      "id": "mem_001",\n      "category": "project",\n      "key": "project_synapse_deployment",\n      "content": "Synapse deployed using Docker Swarm on vps1...",\n      "tags": ["docker", "swarm", "deployment"],\n      "similarity": 0.89\n    },\n    {\n      "id": "mem_042",\n      "category": "fact",\n      "key": "kubernetes_cluster",\n      "content": "We use Kubernetes for production orchestration...",\n      "tags": ["kubernetes", "orchestration"],\n      "similarity": 0.84\n    }\n  ]\n}

Voorbeelden

\n

Vind deployment-herinneringen

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

Retourneert herinneringen over "deployment", "release", "publishing", "rolling out",\nenz.

\n

Vind authenticatie-patronen

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

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

\n

Vind vergelijkbare herinneringen

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

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

\n

Embedding-generatie

\n

Wanneer worden embeddings gegenereerd?

\n\n

Embedding-providers

\n

Synapse ondersteunt configureerbare embedding-providers:

\n\n

Configureer via omgevingsvariabelen:

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

Batch-generatie

\n

Voor minds met veel herinneringen die embeddings missen:

\n
# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'\n\n# Check progress\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

Prestaties

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
BewerkingLatentie
Embedding genereren (OpenAI)100-200ms
Semantisch zoeken (1k herinneringen)50-100ms
Semantisch zoeken (10k herinneringen)200-500ms
Batch-generatie (100 herinneringen)10-20s
\n
Semantisch zoeken is langzamer dan FTS5 vanwege vectorberekening. Gebruik FTS5\nvoor bekende trefwoorden, semantisch voor conceptuele query's.

Beperkingen

\n

Kosten van embeddings

\n

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

\n

Cold start

\n

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

\n

Provider-afhankelijkheid

\n

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

\n

Wanneer embeddings niet beschikbaar zijn

\n

Als embeddings-service niet is geconfigureerd:

\n\n

Best practices

\n

Volgende stappen

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}