# Semantische Suche (Embeddings)
SUMMARY: Konzeptionelle Memory-Suche mit Vektor-Embeddings — nach Bedeutung finden, nicht nur nach Keywords.

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
[CODE BLOCK]
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
[CODE BLOCK]
Antwort:
[CODE BLOCK]
Beispiele
Deployment-Memories finden
[CODE BLOCK]
Liefert Memories über „Deployment", „Release", „Publishing", „Rolling out" etc.
Authentifizierungs-Pattern finden
[CODE BLOCK]
Liefert Memories über Login, Auth, JWT, Session-Management, OAuth etc.
Ähnliche Memories finden
[CODE BLOCK]
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 —  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 (, )
- Lokale Modelle (über Ollama oder ähnliches)
- Custom (Embeddings-Interface implementieren)
Konfiguriere via Environment-Variablen:
[CODE BLOCK]
Batch-Generierung
Für Minds mit vielen Memories ohne Embeddings:
[CODE BLOCK]
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  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:
-  liefert 503 Service Unavailable
-  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 — 
> - Provider-Gesundheit überwachen — semantische Suche hängt davon ab
> - Mit Tags kombinieren — semantisch + Tag-Filter schränkt Ergebnisse ein
Nächste Schritte
- FTS5-Suche
- Memory-API
- Architektur