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

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

Antwort:

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

# 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

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

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

Ähnliche Memories finden

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

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

Batch-Generierung

Für Minds mit vielen Memories ohne Embeddings:

# 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

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

Nächste Schritte

• FTS5-Suche
• Memory-API
• Architektur