# Semantische Suche (Embeddings)

Synapse unterstützt semantische Suche mittels Vektor-Embeddings. Anders als FTS5
(Keyword-Matching) findet die semantische Suche Memories nach **Bedeutung** —
selbst wenn keine Keywords übereinstimmen.

## Funktionsweise

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

### Was sind Embeddings?

Embeddings sind numerische Vektor-Repräsentationen von Text. Text mit ähnlicher
Bedeutung hat ähnliche Vektoren. Synapse generiert einen Vektor (z. B. 1536
Dimensionen) für den Inhalt jedes Memories.

### Cosine-Ähnlichkeit

Um semantisch ähnliche Memories zu finden, berechnet Synapse die
Cosine-Ähnlichkeit zwischen dem Query-Vektor und jedem Memory-Vektor. Höhere
Ähnlichkeit = relevanter.

## Wann semantische Suche verwenden?

### Verwende semantische Suche, wenn:

- Du „Memories über X" suchst, wobei X anders beschrieben ist als gespeichert
- FTS5 keine Ergebnisse liefert (kein Keyword-Match)
- Du konzeptionelle Gruppierung willst (z. B. alle „Deployment"-Memories, auch wenn manche „Release" sagen)
- Die Anfrage eine Frage ist: „wie gehen wir mit Authentifizierung um?"

### Verwende FTS5, wenn:

- Du exakte Keywords kennst
- Du boolesche Logik brauchst (AND, OR, NOT)
- Du sub-millisecond-Antwort brauchst
- Du Phrase-Matching willst

## Endpunkt

### GET /memory/semantic-search

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

Antwort:

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

## Beispiele

### Deployment-Memories finden

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

Liefert Memories über „Deployment", „Release", „Publishing", „Rolling out" etc.

### Authentifizierungs-Pattern finden

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

Liefert Memories über Login, Auth, JWT, Session-Management, OAuth etc.

### Ähnliche Memories finden

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

Verwendet semantische Ähnlichkeit (über gemeinsame Tags UND Embedding-Vektoren).

## Embedding-Generierung

### Wann werden Embeddings generiert?

- **Beim Speichern eines Memories** — wenn der Embeddings-Dienst konfiguriert ist, wird das Embedding synchron generiert
- **Batch-Generierung** — `POST /memory/embed-batch` generiert Embeddings für Memories, die keine haben
- **Async-Updates** — bei Inhaltsänderung wird das Embedding neu generiert

### Embedding-Provider

Synapse unterstützt konfigurierbare Embedding-Provider:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Lokale Modelle** (über Ollama oder ähnliches)
- **Custom** (Embeddings-Interface implementieren)

Konfiguriere via Environment-Variablen:

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

### Batch-Generierung

Für Minds mit vielen Memories ohne Embeddings:

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

## Performance

| Operation | Latenz |
|-----------|--------|
| Embedding generieren (OpenAI) | 100-200ms |
| Semantische Suche (1k Memories) | 50-100ms |
| Semantische Suche (10k Memories) | 200-500ms |
| Batch-Generierung (100 Memories) | 10-20s |

> [!NOTE]
> Semantische Suche ist langsamer als FTS5 wegen der Vektor-Berechnung.
> Verwende FTS5 für bekannte Keywords, semantische für konzeptionelle Queries.

## Einschränkungen

### Embedding-Kosten

Bei Verwendung von OpenAI kostet die Embedding-Generierung Geld (~$0.02 pro 1M
Token für text-embedding-3-small). Bei 10.000 Memories mit durchschnittlich 100
Token sind das ~$0.02 — vernachlässigbar.

### Cold Start

Memories, die vor der Konfiguration der Embeddings gespeichert wurden, haben
keine Embeddings. Führe `POST /memory/embed-batch` zum Backfillen aus.

### Provider-Abhängigkeit

Wenn der Embeddings-Provider down ist, schlägt die semantische Suche graceful
fehl (leere Ergebnisse oder Fehler). FTS5 funktioniert weiterhin.

## Wenn Embeddings nicht verfügbar sind

Wenn der Embeddings-Dienst nicht konfiguriert ist:

- `GET /memory/semantic-search` liefert 503 Service Unavailable
- `POST /memory` funktioniert weiterhin (nur kein Embedding generiert)
- FTS5-Suche funktioniert weiterhin

## Best Practices

> [!TIP]
> - **Semantisch für konzeptionelle Queries** — „wie gehen wir mit X um?"
> - **FTS5 für spezifische Begriffe** — „docker swarm"
> - **Embeddings regelmäßig backfillen** — `POST /memory/embed-batch`
> - **Provider-Gesundheit überwachen** — semantische Suche hängt davon ab
> - **Mit Tags kombinieren** — semantisch + Tag-Filter schränkt Ergebnisse ein

## Nächste Schritte

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