# 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

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

Svar:

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

## Exempel

### Hitta driftsättningsminnen

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

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

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

### Hitta liknande minnen

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

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

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

## Prestanda

| Åtgärd | Latens |
|-----------|---------|
| Generera inbäddning (OpenAI) | 100–200 ms |
| Semantisk sökning (1k minnen) | 50–100 ms |
| Semantisk sökning (10k minnen) | 200–500 ms |
| Batchgenerering (100 minnen) | 10–20 s |

> [!NOTE]
> Semantisk sökning är långsammare än FTS5 på grund av vektorberäkning.
> Använd FTS5 för kända nyckelord, semantisk för begreppsliga frågor.

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

> [!TIP]
> - **Använd semantisk för begreppsliga frågor** — "hur hanterar vi X?"
> - **Använd FTS5 för specifika termer** — "docker swarm"
> - **Fyll i inbäddningar regelbundet** — `POST /memory/embed-batch`
> - **Övervaka leverantörshälsa** — semantisk sökning beror på den
> - **Kombinera med taggar** — semantisk + taggfilter snävar in resultatet

## Nästa steg

- [FTS5-sökning](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Arkitektur](/docs/concepts/architecture)