# 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

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

Respons:

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

```bash
# 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

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

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

### Vind vergelijkbare herinneringen

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

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

### Batch-generatie

Voor minds met veel herinneringen die embeddings missen:

```bash
# 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

| 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 `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

> [!TIP]
> - **Gebruik semantisch voor conceptuele query's** — "hoe handelen we X?"
> - **Gebruik FTS5 voor specifieke termen** — "docker swarm"
> - **Vul embeddings regelmatig bij** — `POST /memory/embed-batch`
> - **Monitor provider-gezondheid** — semantisch zoeken is ervan afhankelijk
> - **Combineer met tags** — semantisch + tag-filter verfijnt resultaten

## Volgende stappen

- [FTS5-zoekopdracht](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Architectuur](/docs/concepts/architecture)