# SYNAPSE DOKUMENTATION — Vollständige Referenz
# Erstellt: 2026-07-18T04:11:39.654Z
# Artikel gesamt: 47
Dieses Dokument enthält die vollständige Synapse-API-Dokumentation.
Base URL: https://synapse.schaefer.zone
Language: de
========================================================================
## KATEGORIE: EINSTIEG
Alles, was du brauchst, um mit Synapse loszulegen.
────────────────────────────────────────────────────────────
# Authentifizierung & Mind Keys
SUMMARY: Wie die Synapse-Authentifizierung funktioniert: Mind Keys für Agenten, JWTs für Menschen, ?key= für reine URL-Tools.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Authentifizierung & Mind Keys
Synapse verwendet zwei Authentifizierungsmethoden, jede für einen anderen
Anwendungsfall optimiert. Den Unterschied zu verstehen ist essenziell für
zuverlässige Integrationen.
Zwei Auth-Methoden
| Methode | Anwendungsfall | Rate Limit | Ablauf |
|---------|----------------|------------|--------|
| Mind Key | LLM-Agenten, automatisierte Tools | Keins (Header) / 60 min (Query) | Nie |
| JWT | Human-UI, Konto-Operationen | Keins | 7 Tage |
Mind Key (für Agenten)
Ein Mind Key ist ein Tenant-scoped API-Token. Er authentifiziert die Daten
eines einzelnen Minds (Memories, Tasks, Chat, Scripts etc.). Verwende ihn für:
- LLM-Agenten, die die API aufrufen
- Hintergrund-Automatisierungs-Scripts
- MCP-Server-Konfiguration
- Jede langlebige Integration
Header-Authentifizierung (empfohlen)
[CODE BLOCK]
Query-Parameter (für reine URL-Tools)
[CODE BLOCK]
> [!WARNING]
> Der -Query-Parameter ist auf 60 Requests pro Minute begrenzt.
> Der Bearer-Header hat kein Rate Limit. Verwende den Header, wenn dein Client
> eigene Header unterstützt.
Einen Mind Key anlegen
[CODE BLOCK]
Die Antwort enthält — sofort speichern, er wird nur einmal
angezeigt.
Deine Minds auflisten
[CODE BLOCK]
Einen Mind löschen (unumkehrbar!)
[CODE BLOCK]
JWT (für Menschen)
JWTs authentifizieren das Nutzerkonto, nicht einen spezifischen Mind.
Verwende sie für:
- Konto-Registrierung und Login
- Minds anlegen / auflisten / löschen
- Minds mit anderen Nutzern teilen
- Web-Push-Abonnement-Verwaltung
Registrieren
[CODE BLOCK]
Liefert:
Einloggen
[CODE BLOCK]
Liefert:
JWT-Ablauf
JWTs laufen nach 7 Tagen ab. Wenn ein JWT abläuft, rufe einfach wieder
auf, um ein frisches zu erhalten. Der Mind Key läuft nie ab, daher
funktionieren bestehende Agent-Integrationen weiter.
Security-Best-Practices
> [!CRITICAL]
> - Mind Keys niemals in Git committen. Verwende Environment-Variablen.
> - Mind Keys niemals loggen. In Logs maskieren ().
> - Keys rotieren bei Verdacht auf Leak (Mind löschen, neuen anlegen).
> - Ein Mind pro Projekt, um den Schadensradius bei geleaktem Key zu begrenzen.
Environment-Variablen-Pattern
[CODE BLOCK]
[CODE BLOCK]
MCP-Server-Config
[CODE BLOCK]
Multi-Mind-Pattern
Jeder Nutzer kann mehrere Minds haben. Häufige Patterns:
| Mind-Name | Zweck |
|-----------|-------|
| | Job-bezogene Memories |
| | Persönliche Präferenzen, Familie |
| | Spezifischer Projekt-Kontext |
| | Lernfortschritt |
| | Allzweck-Fallback |
Verwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte
getrennt zu halten.
Rate Limits
| Auth-Methode | Limit | Scope |
|---------------|-------|-------|
| Mind Key (Header) | Keins | Pro-Mind |
| Mind Key (?key=) | 60/min | Pro-IP |
| JWT (Header) | Keins | Pro-Nutzer |
| Öffentliche Endpunkte | Keins | Global |
Rate-Limit-Header (, , )
werden bei Bedarf in Antworten mitgeliefert.
Nächste Schritte
- Mind Key vs JWT — wann was verwenden
- Memory-API — was du mit einem Mind Key tun kannst
- User-API — Kontoverwaltung mit JWTs
────────────────────────────────────────────────────────────
# Mind Key vs JWT — Wann Was?
SUMMARY: Entscheidungsleitfaden: Mind Key für Agent-Datenzugriff, JWT für Kontoverwaltung.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — Wann Was?
Synapse hat zwei Authentifizierungs-Tokens. Die falsche Wahl führt zu 401-Fehlern.
Dieser Guide gibt dir einen klaren Entscheidungsrahmen.
Schnelle Entscheidungs-Tabelle
| Du willst... | Verwende |
|---------------|----------|
| Memories speichern / abrufen | Mind Key |
| Chat-Nachrichten senden / abholen | Mind Key |
| Tasks verwalten | Mind Key |
| Scripts speichern | Mind Key |
| Webhooks registrieren | Mind Key |
| Rechner steuern | Mind Key (Nutzerseite) / Computer-Token (Agentenseite) |
| Nutzerkonto registrieren | Keins (öffentlich) |
| Einloggen | Keins (öffentlich) |
| Minds anlegen / auflisten / löschen | JWT |
| Mind mit anderem Nutzer teilen | JWT |
| Web-Push-Benachrichtigungen abonnieren | JWT |
| Audit-Log ansehen | Mind Key |
Die einfache Regel
> [!TIP]
> Wenn es die Daten eines einzelnen Minds berührt → Mind Key.
> Wenn es das Konto oder Mind-Metadaten verwaltet → JWT.
Mind Key — Datenzugriffs-Token
Ein Mind Key gewährt Zugriff auf die Daten eines Minds. Er ist ein
langlebiges Token, das nie abläuft (bis der Mind gelöscht wird). Perfekt für:
- LLM-Agenten, die Memories über Sessions persistieren
- Hintergrund-Cron-Jobs
- MCP-Server-Konfiguration
- Webhook-Integrationen
- Mobile Apps, die Memory lesen
Was der Mind Key kann
- — alle Memories in diesem Mind lesen
- — Memories speichern/aktualisieren
- — Chat-Nachrichten lesen
- — Chat-Nachrichten senden
- — Tasks auflisten
- — Tasks anlegen
- — Scripts speichern
- — Webhooks registrieren
- — Computer-Commands einreihen
Was der Mind Key NICHT kann
- Minds anlegen / auflisten / löschen (braucht JWT)
- Mind mit anderem Nutzer teilen (braucht JWT)
- Nutzerkonto-Infos ansehen (braucht JWT)
- Web-Push abonnieren (braucht JWT)
JWT — Kontoverwaltungs-Token
Ein JWT authentifiziert das Nutzerkonto. Es läuft nach 7 Tagen ab und wird
für Konto-Ebene-Operationen verwendet, die mehrere Minds umfassen oder andere
Nutzer involvieren.
Was das JWT kann
- — neuen Mind anlegen (liefert neuen Mind Key)
- — alle Minds dieses Nutzers auflisten
- — Mind löschen
- — Mind mit anderem Nutzer teilen
- — Web-Push-Benachrichtigungen abonnieren
- — Mind-Shares auflisten
Was das JWT NICHT kann
- Memories lesen / schreiben (braucht Mind Key)
- Chat-Nachrichten senden (braucht Mind Key)
- Tasks verwalten (braucht Mind Key)
- Webhooks registrieren (braucht Mind Key)
Sonderfall: Computer-Token
Die -Endpunkte (agentenseitig, für den screen-remote-agent)
verwenden einen dritten Token-Typ: das Computer-Token. Dieses Token wird von
beim Einlösen eines Installationscodes zurückgegeben
und ist spezifisch für einen registrierten Rechner.
| Endpunkt | Auth |
|----------|------|
| | Computer-Token |
| | Computer-Token |
| | Mind Key oder JWT |
| | Mind Key oder JWT |
Häufige Patterns
Pattern 1: Einzelner LLM-Agent
1. Einmal registrieren → JWT erhalten
2. Einen Mind anlegen → Mind Key erhalten
3. LLM verwendet Mind Key für alles
Pattern 2: Multi-Projekt-Agent
1. Einmal registrieren → JWT erhalten
2. Mehrere Minds anlegen (work, personal, project-x) → mehrere Mind Keys erhalten
3. LLM lädt je nach Kontext unterschiedlichen Mind Key
Pattern 3: Team-Sharing
1. Nutzer A legt Mind an → Mind Key A erhalten
2. Nutzer A teilt mit Nutzer B via JWT ()
3. Nutzer B kann nun über sein eigenes JWT zugreifen
4. Für LLM-Zugriff muss Nutzer B einen eigenen Mind Key anlegen (oder A's verwenden)
Pattern 4: MCP-Server
MCP-Server verwenden immer Mind Key (via -Env-Var gesetzt).
Eine MCP-Server-Instanz = ein Mind. Für Multi-Mind-Zugriff: mehrere MCP-
Instanzen betreiben oder Client-seitiges Mind-Switching implementieren.
Token-Format-Spickzettel
| Token | Format | Beispiel |
|-------|--------|----------|
| Mind Key | + 36 Zeichen | |
| JWT | + base64 | |
| Computer-Token | + 36 Zeichen | |
Nächste Schritte
- Authentifizierung — vollständiger Auth-Guide
- User- & Minds-API — JWT-geschützte Endpunkte
- Memory-API — Mind-Key-geschützte Endpunkte
────────────────────────────────────────────────────────────
# Quick Start für LLM-Agenten
SUMMARY: In 3 API-Aufrufen: alle Memories abrufen, einen neuen speichern, suchen. Der essenzielle LLM-Workflow.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start für LLM-Agenten
Zwischen Sessions verlierst du jegliches Gedächtnis. Synapse ist dein externes
Gehirn. Dieser Guide zeigt die drei essenziellen API-Aufrufe, die jeder LLM-Agent
kennen muss.
> [!CRITICAL]
> Rufe zu BEGINN jeder Session auf.
> Ohne diesen Aufruf hast du keine Erinnerung daran, wer der Nutzer ist, was du
> versprochen hast oder woran du zuletzt gearbeitet hast.
Schritt 1: Alle Memories abrufen (IMMER ZUERST)
[CODE BLOCK]
Liefert eine strukturierte Klartext-Zusammenfassung aller gespeicherten Memories.
Parse dies, um dein mentales Modell des Nutzers, seiner Projekte und vergangener
Interaktionen wiederherzustellen.
Beispiel-Antwort:
[CODE BLOCK]
Schritt 2: Einen neuen Memory speichern
Wenn du etwas lernst, das es wert ist, erinnert zu werden:
[CODE BLOCK]
Kategorien: , , , , , , , ,
Prioritäten: , , ,
> [!TIP]
> Gib immer ein -Feld an — ein kurzer Bezeichner für den Memory. So kannst
> du denselben Memory später aktualisieren, indem du mit demselben Key erneut
> POSTest.
Schritt 3: Nach einem bestimmten Memory suchen
[CODE BLOCK]
> [!TIP]
> FTS5-Syntax: mehrere Wörter = AND-Suche. Phrasen in Anführungszeichen:
> . Präfix-Suche: . Boolesch: .
Offene Tools (ohne Auth-Header)
Wenn dein Tool nur URLs öffnen kann (keine eigenen Header), verwende den
-Parameter:
[CODE BLOCK]
> [!WARNING]
> ist auf 60 Requests/Minute begrenzt. Bearer-Header hat kein Rate
> Limit. Verwende immer, wenn möglich, den Bearer-Header.
Vollständiger Session-Workflow
1. Session-Start: — alle Memories laden
2. Während der Arbeit: — spezifische Fakten finden
3. Bei neuen Infos: — speichern (mit Kategorie, Key, Tags, Priorität)
4. Periodisch: — auf Nachrichten vom Menschen prüfen
5. Session-Ende: finale Learnings via speichern
Häufige Patterns
Einen bestehenden Memory aktualisieren
POST mit derselben und demselben — der bestehende
Memory wird aktualisiert, nicht dupliziert.
Einen Projektstatus speichern
[CODE BLOCK]
Einen Fehler festhalten (damit du ihn nicht wiederholst)
[CODE BLOCK]
Auf Nachrichten vom Menschen prüfen
[CODE BLOCK]
Liefert ungelesene Nachrichten vom Menschen. Antworte mit:
[CODE BLOCK]
Nächste Schritte
- Authentifizierung — Mind Key vs JWT
- Memory-API-Referenz — alle 22 Memory-Endpunkte
- Chat-API — asynchrone Kommunikation mit Menschen
- LLM-Cookbook — praktische Patterns
────────────────────────────────────────────────────────────
# Quick Start (Mensch)
SUMMARY: Konto registrieren, ersten Mind anlegen, ersten Memory speichern — alles in 5 Minuten.
Quick Start (Mensch)
Dieser Guide führt dich durch das Anlegen eines Synapse-Kontos, deinen ersten
Mind Key und das Speichern deines ersten Memories. Gesamtdauer: 5 Minuten.
Schritt 1: Konto registrieren
Öffne die Synapse-API und lege ein Konto an:
[CODE BLOCK]
Antwort:
[CODE BLOCK]
> [!TIP]
> Speichere das JWT an einem sicheren Ort — du brauchst es, um Minds anzulegen.
> Das JWT läuft nach 7 Tagen ab; mit demselben Endpunkt erneut einloggen, um es
> zu erneuern.
Schritt 2: Lege deinen ersten Mind an
Ein „Mind" ist ein isolierter Memory-Scope. Die meisten Nutzer starten mit einem
Mind, aber du kannst mehrere haben (z. B. „work", „personal", „project-x"). Jeder
Mind hat seinen eigenen, eindeutigen Mind Key.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
> [!CRITICAL]
> Speichere den sofort. Er wird nur einmal angezeigt und kann
> später nicht wiederhergestellt werden. Wenn du ihn verlierst, musst du einen
> neuen Mind anlegen.
Schritt 3: Speichere deinen ersten Memory
Verwende nun den Mind Key, um einen Memory zu speichern:
[CODE BLOCK]
Antwort:
[CODE BLOCK]
Schritt 4: Alle Memories abrufen
Um alles abzurufen, was du gespeichert hast:
[CODE BLOCK]
Antwort (Klartext, optimiert für LLM-Konsum):
[CODE BLOCK]
Schritt 5: Memories durchsuchen
Spezifische Memories per Keyword finden:
[CODE BLOCK]
Schritt 6: Verbinde dein LLM
Der einfachste Weg, deinem LLM Zugriff auf Synapse zu geben, ist via MCP:
- Claude-Desktop-Setup — 2-Minuten-Config
- Claude-Code-Setup — Terminal-Integration
- Cursor-Setup — IDE-Integration
Nach dem Setup wird dein LLM automatisch zu Beginn jeder Session
aufrufen und neue Fakten via persistieren.
Memory-Kategorien
Synapse unterstützt 8 Kategorien — wähle die spezifischste:
| Kategorie | Anwendungsfall |
|-----------|----------------|
| | Nutzername, Rolle, Kontaktinfo |
| | Vorlieben, Abneigungen, Arbeitsstil |
| | Überprüfbare Fakten (Projekt-Details, Daten) |
| | Projektstatus, Meilensteine, Todos |
| | Dinge, die der Nutzer gut kann |
| | Frühere Fehler — nicht wiederholen |
| | Session-relevanter Kontext |
| | Sonstige Notizen |
Prioritätsstufen
- — nett zu wissen
- — Standard
- — wichtig
- — darf nie vergessen werden (Nutzeridentität, rechtliche Infos)
Nächste Schritte
- Authentifizierung Deep-Dive
- Mind Key vs JWT
- Memory-API-Referenz
- MCP-Integration
────────────────────────────────────────────────────────────
# Was ist Synapse?
SUMMARY: Synapse ist eine persistente Memory-API für LLM-Agenten — deine KI vergisst über Sessions hinweg nie.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Was ist Synapse?
Synapse ist eine persistente Memory-API für LLM-Agenten. Sie löst das
grundlegende Problem jedes Chat-basierten LLMs: zwischen Sessions vergisst der
Agent alles. Synapse gibt deiner KI ein dauerhaftes, abfragbares Gehirn, das über
Konversationen, über Tage und über verschiedene LLM-Provider hinweg besteht.
> [!CRITICAL]
> Wenn du ein LLM-Agent bist, der das liest: rufe zu
> Beginn jeder Session auf. Ohne diesen Aufruf hast du keine Erinnerung an
> vergangene Interaktionen, kein Wissen darüber, wer der Nutzer ist, und keinen
> Kontext über laufende Projekte.
Das Problem, das Synapse löst
Jedes moderne LLM (Claude, GPT, Gemini, Llama) hat dieselbe architektonische
Einschränkung: das Konversations-Kontextfenster ist endlich, und sobald die
Session endet, geht jeglicher Status verloren. Das bedeutet, dein KI-Assistent:
- Vergisst deinen Namen, deine Präferenzen und laufende Projekte zwischen Chats
- Kann nicht aus Fehlern vergangener Sessions lernen
- Hat keine Kontinuität für langlaufende Arbeiten
- Stellt jedes Mal dieselben Klärungsfragen
Synapse behebt das mit einer einfachen HTTP-API, über die das LLM strukturierte
Memories speichern und abrufen kann. Die Memories persistieren auf dem Server,
indiziert und durchsuchbar, sodass jede zukünftige Session sie abrufen kann.
Haupt-Features
- Persistenter Memory-Speicher — Fakten, Präferenzen, Projekte, Fehler, Fähigkeiten
- Volltextsuche (FTS5) — beliebiges Memory per Keyword in Millisekunden finden
- Semantische Suche — Embeddings-basierte Ähnlichkeitssuche für konzeptionelle Queries
- Multi-Tenant — jeder Nutzer hat isolierte „Minds" (ein Nutzer, viele Projekte)
- Asynchroner Chat — Menschen können dem Agenten Nachrichten hinterlassen, während er arbeitet
- Tasks & Scheduling — eingebauter Task-Manager und Cron-Scheduler
- MCP-Integration — 79 Tools als Model Context Protocol für Claude, Cursor, Continue
- Browser- & Computer-Steuerung — Remote-Automatisierungs-Tools
- Webhooks — HTTP-Callbacks bei Memory-/Chat-/Task-Änderungen erhalten
Funktionsweise
[CODE BLOCK]
1. Das LLM ruft zu Session-Beginn auf
2. Synapse liefert eine strukturierte Klartext-Zusammenfassung aller gespeicherten Memories
3. Das LLM arbeitet und ruft periodisch auf, um neue Fakten zu speichern
4. Wenn der Nutzer eine Frage stellt, kann das LLM aufrufen
5. Am Session-Ende wird wichtiger neuer Kontext für die nächste Session persistiert
Für wen ist es?
- LLM-Agent-Entwickler, die persistenten Status brauchen
- Power-User, die lokale LLMs (Ollama, LM Studio) mit eigenen Agenten betreiben
- Teams, die KI-Assistenten mit geteiltem Memory bauen
- Automatisierungs-Engineers, die LLM-Aufrufe über Sessions verketten
Schnellvergleich
| Feature | ChatGPT Memory | Synapse |
|---------|----------------|---------|
| Speicherort | OpenAI-Server | Dein Server |
| API-Zugriff | Nein (geschlossen) | Ja (REST + MCP) |
| Multi-Tenant | Nein | Ja (Minds) |
| Eigene Kategorien | Nein | Ja (8 Kategorien) |
| Suche | Eingeschränkt | FTS5 + semantisch |
| Self-Hosting | Nein | Ja (Docker) |
Nächste Schritte
- Quick Start für Menschen — in 5 Minuten einen Mind Key erhalten
- Quick Start für LLMs — erste API-Aufrufe
- Authentifizierung — Mind Keys vs JWTs
- Architektur-Überblick — wie Synapse aufgebaut ist
## KATEGORIE: API-REFERENZ
Vollständige Referenz aller API-Endpunkte.
────────────────────────────────────────────────────────────
# Browser-Proxy
SUMMARY: Browser-Automatisierungsdienst — separater Docker-Container auf Port 13000 für Headless-Browser-Steuerung.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser-Proxy
Der Browser-Proxy ist ein separater Docker-Dienst, der Headless-Browser-Automatisierung
via Playwright bereitstellt. Er ist NICHT direkt Teil der Synapse-API — Synapse-Endpunkte
enthalten keine -Pfade.
Architektur
[CODE BLOCK]
Zugriffsarten
Methode 1: Über den Synapse-MCP-Server (empfohlen)
Der Synapse-MCP-Server stellt Browser-Werkzeuge als MCP-Tools bereit. Verwende
dies für LLM-gesteuerte Browser-Automatisierung:
[CODE BLOCK]
Verfügbare MCP-Browser-Tools:
- — neuen Browser-Tab öffnen
- — zu einer URL navigieren
- — auf ein Element klicken
- — Text in ein Feld eingeben
- — Screenshot aufnehmen
- — Tab schließen
- (und mehr — siehe MCP-Integration)
Methode 2: Direkter Browser-Proxy-Zugriff
Für Nicht-MCP-Integrationen verbinde dich direkt mit dem Browser-Proxy-Dienst:
[CODE BLOCK]
Häufige Anwendungsfälle
Web-Scraping
[CODE BLOCK]
Formular-Automatisierung
[CODE BLOCK]
Screenshot-Aufnahme
[CODE BLOCK]
Verwandte Dienste
| Dienst | Port | Zweck |
|---------|------|-------|
| Synapse API | 12800 | Memory, Chat, Tasks |
| Synapse MCP | 13100 | MCP-Server (79 Tools) |
| Browser Proxy | 13000 | Headless-Browser-Automatisierung |
| SSH Proxy | 12900 | SSH-Zugriff auf Remote-Rechner |
Nächste Schritte
- MCP-Integration — wie du Browser-Tools via MCP nutzt
- Computer-Control-API — für GUI-Automatisierung auf registrierten Rechnern
────────────────────────────────────────────────────────────
# Chat-API
SUMMARY: Asynchroner Chat zwischen Menschen und LLM-Agenten — Polling, Antworten, Verlauf, Unread-Count, Datei-Uploads.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat-API
Die Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.
Im Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten
hinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen
ab.
Funktionsweise
[CODE BLOCK]
1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)
2. Nachricht wird gespeichert und als ungelesen markiert
3. Agent fragt zwischen Tool-Aufrufen ab
4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen
5. Agent verarbeitet die Nachricht und antwortet optional via
Endpunkte
GET /chat/poll
Neue Nachrichten vom Menschen abfragen. Liefert ungelesene Nachrichten und
markiert sie als gelesen. Verwende dies zwischen Tool-Aufrufen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
POST /chat/reply
Eine Nachricht als Agent senden.
[CODE BLOCK]
POST /chat/send
Eine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).
[CODE BLOCK]
GET /chat/history
Letzten Chat-Verlauf abrufen (beide Rollen).
[CODE BLOCK]
GET /chat/unread
Anzahl ungelesener Nachrichten abrufen.
[CODE BLOCK]
GET /chat/status
Chat-Session-Status abrufen (Zeitstempel der letzten Nachrichten, Unread-Counts).
[CODE BLOCK]
POST /chat/upload
Dateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).
[CODE BLOCK]
GET /chat/files/:messageid
Dateianhänge für eine Nachricht auflisten.
[CODE BLOCK]
GET /chat/file/:fileid
Einen Dateianhang herunterladen.
[CODE BLOCK]
Polling-Pattern
> [!TIP]
> Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen
> verschwendet API-Kontingent und bringt nichts.
[CODE BLOCK]
Nächste Schritte
- Tasks-API
- Chat-Polling-Pattern
────────────────────────────────────────────────────────────
# Computer-Control-API
SUMMARY: Fernsteuerung registrierter Rechner — Commands in die Warteschlange stellen, Screenshots aufnehmen, Scripts auf Remote-Maschinen ausführen.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer-Control-API
Die Computer-Control-API ermöglicht die Fernsteuerung registrierter Rechner. Ein
kleiner Agent () läuft auf der Zielmaschine, fragt Commands
ab, führt sie aus und postet Ergebnisse zurück. Das ermöglicht LLM-gesteuerte
GUI-Automatisierung.
Architektur
[CODE BLOCK]
Nutzerseitige Endpunkte (Mind Key oder JWT)
GET /computers/list
Alle registrierten Rechner auflisten.
[CODE BLOCK]
GET /computers/:id
Details eines einzelnen Rechners abrufen.
[CODE BLOCK]
POST /computers/install-code
Installationscode zur Registrierung eines neuen Rechners generieren.
[CODE BLOCK]
Antwort:
POST /computers/:id/commands
Ein Command für den Remote-Agent in die Warteschlange stellen.
[CODE BLOCK]
Antwort:
GET /computers/:id/command (via Query)
Ein Command via GET einreihen (für einfache Fälle).
[CODE BLOCK]
GET /computers/:id/commands
Letzte Commands für einen Rechner auflisten.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Status + Ergebnis eines bestimmten Commands abrufen.
[CODE BLOCK]
GET /computers/:id/screenshot
One-Shot: ein Screenshot-Command einreihen und bis zu 30s auf das Ergebnis warten.
[CODE BLOCK]
POST /computers/:id/disable
Einen Rechner deaktivieren (widerruft seinen Token, behält den Eintrag fürs Audit).
[CODE BLOCK]
DELETE /computers/:id
Einen Rechner dauerhaft löschen.
[CODE BLOCK]
Agentseitige Endpunkte (Computer-Token)
Diese Endpunkte werden vom auf der Zielmaschine verwendet.
Sie verwenden einen Computer-Token (von zurückgegeben),
keinen Mind Key.
POST /computers/register
Installationscode einlösen und einen Computer-Token erhalten.
[CODE BLOCK]
Antwort:
> [!CRITICAL]
> Speichere den — er wird nur einmal angezeigt und wird für
> alle agentseitigen Endpunkte benötigt.
GET /computers/me/poll
Long-Poll für neue Commands. Der Agent ruft dies in einer Schleife auf.
[CODE BLOCK]
Kehrt sofort zurück, wenn Commands ausstehen, sonst nach Sekunden.
POST /computers/me/commands/:cid/result
Das Ergebnis der Ausführung eines Commands posten.
[CODE BLOCK]
Command-Typen
| Typ | Payload | Beschreibung |
|------|---------|--------------|
| | | Bildschirm als PNG aufnehmen (base64) |
| | | An Koordinaten klicken |
| | | Maus zu Koordinaten bewegen |
| | | Text am Cursor tippen |
| | | Tastenkombination drücken |
| | | Scrollrad |
| | | Drag-and-Drop |
Typisches Pattern: LLM-gesteuerte GUI-Automatisierung
[CODE BLOCK]
Nächste Schritte
- Browser-Proxy — separater Dienst für Browser-Automatisierung
- Self-Hosted-Agents-Guide
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Wiederkehrende API-Aufrufe planen — Cron-Jobs, die nach Zeitplan feuern, perfekt für periodischen Sync und Erinnerungen.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Scheduler
Die Cron-API ermöglicht das Planen wiederkehrender HTTP-Aufrufe an Synapse-
Endpunkte (oder externe HTTPS-Endpunkte). Perfekt für periodischen Sync,
Erinnerungen und Wartungsaufgaben.
Endpunkte
POST /cron
Einen geplanten Task anlegen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
GET /cron
Alle geplanten Tasks auflisten.
[CODE BLOCK]
DELETE /cron/:id
Einen geplanten Task löschen.
[CODE BLOCK]
PUT /cron/:id/toggle
Einen Task aktivieren oder deaktivieren, ohne ihn zu löschen.
[CODE BLOCK]
Schedule-Syntax
Standard-Cron (5 Felder)
[CODE BLOCK]
Beispiele:
| Schedule | Bedeutung |
|----------|-----------|
| | Jede Stunde |
| | Alle 15 Minuten |
| | Werktags um 9 Uhr |
| | Jeden Sonntag um Mitternacht |
| | Ersten jeden Monats um Mitternacht |
Integer-Intervall (Sekunden)
Für einfache Intervalle übergibst du einen Integer:
[CODE BLOCK]
Endpunkt-Einschränkungen
> [!WARNING]
> Endpoints must be or URLs pointing to:
> - The same Synapse instance (e.g. )
> - Public HTTPS URLs (no private IPs, no localhost, no metadata IPs)
Das verhindert SSRF-Angriffe, bei denen ein kompromittierter Mind Anfragen an
interne Dienste planen könnte.
Häufige Patterns
Stündlicher Memory-Recall (für LLM-Agenten)
[CODE BLOCK]
Tägliche Sicherung
[CODE BLOCK]
Periodischer Chat-Poll (alle 5 Minuten)
[CODE BLOCK]
Wöchentlicher Report-Trigger
[CODE BLOCK]
Nächste Schritte
- Variables-API
- Webhooks-API
────────────────────────────────────────────────────────────
# Errors & Fehlerbehandlung
SUMMARY: HTTP-Statuscodes, Fehler-Antwortformat und Wiederherstellung nach häufigen Fehlern.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Errors & Fehlerbehandlung
Synapse verwendet Standard-HTTP-Statuscodes mit einem konsistenten Fehler-
Antwortformat. Diese Seite erklärt, wie du Fehler interpretierst und behebst.
Fehler-Antwortformat
Alle Fehler liefern JSON mit dieser Struktur:
[CODE BLOCK]
| Feld | Beschreibung |
|-------|--------------|
| | HTTP-Statuscode |
| | HTTP-Statusname |
| | Lesbare Fehlerbeschreibung |
| | URL zur relevanten Doku (falls verfügbar) |
HTTP-Statuscodes
200 OK
Erfolg. Die Anfrage wurde korrekt verarbeitet.
201 Created
Erfolg. Eine neue Ressource wurde erstellt (z. B. ).
204 No Content
Erfolg. Kein Body zurückgegeben (z. B. ).
400 Bad Request
Die Anfrage war fehlerhaft. Häufige Ursachen:
- Fehlende Pflicht-JSON-Felder
- Ungültige JSON-Syntax
- Ungültiger Enum-Wert (z. B. falsche Kategorie)
[CODE BLOCK]
Lösung: Prüfe den Request-Body gegen die API-Doku. Stelle sicher, dass alle
Pflichtfelder vorhanden sind und gültige Werte haben.
401 Unauthorized
Authentifizierung fehlgeschlagen. Häufige Ursachen:
- Fehlender -Header
- Ungültiger Mind Key oder JWT
- Mind Key verwendet, wo JWT erforderlich ist (oder umgekehrt)
[CODE BLOCK]
Lösung: Überprüfe deinen Token. Siehe Authentifizierung.
403 Forbidden
Du bist authentifiziert, darfst diese Aktion aber nicht ausführen. Häufige
Ursachen:
- Versuch, den Mind eines anderen Nutzers zu löschen
- Versuch, einen Memory mit Mind Key zu verifizieren (erfordert JWT)
- Mind ist deaktiviert
Lösung: Prüfe, ob du den richtigen Token-Typ für diesen Endpunkt verwendest.
404 Not Found
Der angeforderte Pfad oder die Ressource existiert nicht.
> [!CRITICAL]
> Rate keine Endpunkt-Pfade. Nur die in gelisteten Pfade
> existieren. Bei einer 404 hast du einen falschen Pfad verwendet.
[CODE BLOCK]
Lösung: Rufe auf, um die Liste gültiger Endpunkte zu
sehen. Vergleiche deine URL Zeichen für Zeichen mit der Liste.
409 Conflict
Die Anfrage kollidiert mit dem bestehenden Zustand. Häufige Ursachen:
- Registrierung mit einer E-Mail, die bereits existiert
- Doppelte Webhook-URL
Lösung: Verwende einen anderen Wert oder nutze , um die bestehende
Ressource zu aktualisieren.
429 Too Many Requests
Du hast ein Rate Limit erreicht. Betrifft nur -Query-Parameter-Auth
(60/min).
[CODE BLOCK]
Response-Header:
[CODE BLOCK]
Lösung: Wechsle zum -Header (kein Rate Limit) oder
warte Sekunden.
500 Internal Server Error
Serverfehler. Sollte nicht passieren — falls doch, ist es ein Bug.
Lösung:
1. Mit exponentiellem Backoff retry (1s, 2s, 4s, 8s)
2. prüfen, ob der Server läuft
3. Bei anhaltendem Fehler diesen melden
503 Service Unavailable
Server ist vorübergehend nicht verfügbar (z. B. während Deploy, DB-Migration).
Lösung: Warten und retry. Prüfe .
Recovery-Patterns
Retry mit exponentiellem Backoff
[CODE BLOCK]
Auth-Fehlerbehandlung
[CODE BLOCK]
Häufige Fehler-Szenarien
„Mind Key fehlt oder ungültig"
- Du hast den -Header vergessen
- Du hast verwendet, aber der Key ist falsch
- Du verwendest einen JWT, wo ein Mind Key erforderlich ist
„Route not found"
- Du hast einen Pfad geraten, der nicht existiert
- Du hast ein Verb falsch verwendet (z. B. vs )
- Prüfe für gültige Pfade
„Rate limit exceeded"
- Du verwendest und hast 60 req/min überschritten
- Wechsle zum -Header
Nächste Schritte
- Authentifizierung
- API-Übersicht
- Rate Limits
────────────────────────────────────────────────────────────
# Memory-API
SUMMARY: Vollständige Referenz der 22 Memory-Endpunkte: speichern, abrufen, suchen, semantische Suche, Sync, Audit und mehr.
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
Memory-API
Die Memory-API ist das Herz von Synapse. Sie bietet 22 Endpunkte zum Speichern,
Abrufen, Suchen und Verwalten strukturierter Erinnerungen. Alle Endpunkte
erfordern einen Mind Key zur Authentifizierung.
> [!CRITICAL]
> Rufe immer zu Beginn jeder Session auf. Das ist der
> einzige Weg, den Kontext aus früheren Sessions wiederherzustellen.
Kategorien
Memories sind in 8 Kategorien gegliedert:
| Kategorie | Anwendungsfall |
|-----------|----------------|
| | Nutzername, Rolle, Kontaktinfo, Selbstaussagen |
| | Vorlieben, Abneigungen, Arbeitsstil, Kommunikationspräferenzen |
| | Überprüfbare Fakten (Projekt-Details, Daten, URLs) |
| | Projektstatus, Meilensteine, Architektur |
| | Dinge, die der Nutzer gut kann |
| | Frühere Fehler — nicht wiederholen |
| | Session-relevanter Kontext |
| | Sonstige Notizen |
Prioritäten
- — nett zu wissen
- — Standard
- — wichtig
- — darf nie vergessen werden (Nutzeridentität, rechtliche Infos)
Kern-Endpunkte
GET /memory/recall
Liefert ALLE Memories als LLM-optimierten Klartext. Rufe dies zu Beginn jeder
Session auf.
[CODE BLOCK]
Antwort (text/plain):
[CODE BLOCK]
POST /memory
Einen neuen Memory speichern oder einen bestehenden aktualisieren (gleiche
Kategorie + Key = Update).
[CODE BLOCK]
Antwort:
GET /memory
Memories mit optionalen Filtern auflisten.
[CODE BLOCK]
PUT /memory/:id
Einen bestimmten Memory per ID aktualisieren.
[CODE BLOCK]
DELETE /memory/:id
Einen einzelnen Memory löschen.
[CODE BLOCK]
Such-Endpunkte
GET /memory/search
Volltextsuche via FTS5.
[CODE BLOCK]
FTS5-Syntax:
- Mehrere Wörter = AND:
- Phrase:
- Präfix:
- Boolesch:
- Ausschließen:
GET /memory/semantic-search
Konzeptionelle Suche via Embeddings (langsamer als FTS5, versteht aber Bedeutung).
[CODE BLOCK]
Liefert Memories, die semantisch zur Anfrage passen, selbst wenn keine Keywords
übereinstimmen. Nützlich für „finde Memories über X", wenn X anders beschrieben
wird.
GET /memory/by-tag
Memories nach Tag auflisten.
[CODE BLOCK]
GET /memory/related/:id
Memories finden, die mit einem bestimmten Memory verwandt sind (über gemeinsame
Tags).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Inkrementeller Sync — liefert Memories, die seit einem Zeitstempel geändert
wurden.
[CODE BLOCK]
Antwort:
POST /memory/sync
Einen Diff aus einer anderen Instanz anwenden (für selbstgehosteten Sync).
[CODE BLOCK]
Bulk-Operationen
POST /memory/bulk-delete
Mehrere Memories per ID löschen.
[CODE BLOCK]
POST /memory/embed-batch
Embeddings für Memories generieren, die noch keine haben (für semantische
Suche).
[CODE BLOCK]
GET /memory/embed-batch-status
Fortschritt der Embedding-Generierung prüfen.
[CODE BLOCK]
Verifikation
Memories haben ein -Flag. Vom Agent gespeicherte Memories sind
standardmäßig unbestätigt (); von Menschen gespeicherte Memories
sind verifiziert ().
POST /memory/verify
Einen Memory als verifiziert markieren (erfordert JWT, nicht Mind Key).
[CODE BLOCK]
POST /memory/unverify
Einen Memory als unverifiziert markieren (erfordert JWT).
[CODE BLOCK]
GET /memory/unverified
Memories auflisten, die auf menschliche Verifikation warten.
[CODE BLOCK]
Statistik & Audit
GET /memory/stats
Aggregierte Statistiken für den aktuellen Mind.
[CODE BLOCK]
Liefert:
GET /memory/audit
Audit-Log aller zustandsverändernden Operationen.
[CODE BLOCK]
GET /memory/contradictions
Potenzielle Widersprüche in gespeicherten Memories erkennen.
[CODE BLOCK]
GET /memory/expiring
Memories auflisten, deren Ablaufdatum näher rückt.
[CODE BLOCK]
Health & Export
GET /memory/health
Schneller Health-Check für das Memory-System.
[CODE BLOCK]
GET /memory/mind-export
Vollständiger JSON-Export aller Memories (für Backups).
[CODE BLOCK]
POST /memory/compact
Ähnliche Memories komprimieren (Auto-Summary).
[CODE BLOCK]
Nächste Schritte
- Quick Start für LLMs
- Memory-Best-Practices
- FTS5-Suche
- Semantische Suche
────────────────────────────────────────────────────────────
# API-Übersicht & Basis-URL
SUMMARY: Alle Synapse-API-Endpunkte, Basis-URL, Authentifizierungsmuster und Antwortformate auf einen Blick.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
API-Übersicht & Basis-URL
Die Synapse-API ist eine RESTful-HTTP-API. Alle Endpunkte liefern JSON zurück
(ausgenommen sind explizit gekennzeichnete Fälle). Diese Seite behandelt die
Grundlagen, die du kennen solltest, bevor du dich den spezifischen Endpunkten
widmest.
Basis-URL
[CODE BLOCK]
Alle Pfade in dieser Dokumentation sind relativ zu dieser Basis-URL. Für
selbstgehostete Instanzen ersetze sie durch deine eigene URL.
Authentifizierung
Zwei Methoden, beide über den -Header:
[CODE BLOCK]
Oder über einen Query-Parameter (auf 60/min begrenzt):
[CODE BLOCK]
Siehe Authentifizierung für Details.
Endpunkt-Gruppen
| Gruppe | Auth | Beschreibung |
|-------|------|--------------|
| Öffentlich | Keine | Landing-Page, Health, OpenAPI, Docs |
| Memory | Mind Key | CRUD, Suche, Sync, Embeddings |
| Chat | Mind Key / JWT | Asynchrone Nachrichten zwischen Mensch und Agent |
| Tasks | Mind Key | Aufgabenverwaltung |
| Scripts | Mind Key / JWT | Persistenter Script-Speicher |
| Scheduler | Mind Key | Cron-Jobs + Variablen |
| Webhooks | Mind Key | HTTP-Callbacks bei Events |
| Computers | Mind Key / JWT | Fernsteuerung von Rechnern |
| User/Minds | JWT | Konto- + Mind-Verwaltung |
| Sharing | JWT | Mind-Freigaben zwischen Nutzern |
| Push | JWT | Web-Push-Abonnements |
| Tools | Keine | Zeit, Calc, Random (öffentliche Hilfswerkzeuge) |
Antwortformate
- JSON (Standard):
- Klartext: liefert LLM-optimierten Text
- HTML: , , , ,
Standard-Antwort-Envelope
Erfolgsantworten liefern die Daten direkt:
[CODE BLOCK]
Fehlerantworten verwenden dieses Format:
[CODE BLOCK]
> [!NOTE]
> Das Feld verlinkt bei häufigen Fehlern auf die relevante Doku.
HTTP-Statuscodes
| Code | Bedeutung |
|------|-----------|
| 200 | Erfolg (GET, PUT) |
| 201 | Erstellt (POST) |
| 204 | Kein Inhalt (DELETE) |
| 400 | Bad Request (Validierungsfehler) |
| 401 | Unauthorized (fehlender/ungültiger Token) |
| 403 | Forbidden (falscher Token-Typ) |
| 404 | Not Found (Pfad existiert nicht) |
| 409 | Conflict (Duplikat) |
| 429 | Too Many Requests (Rate Limit) |
| 500 | Serverfehler |
Discoverability-Endpunkte
| Endpunkt | Zweck |
|----------|-------|
| | Landing-Page (LLM-optimiert) |
| | Maschinenlesbare Liste aller Endpunkte |
| | Endpunkt-Liste als Klartext |
| | OpenAPI-3.0-Spezifikation |
| | Vollständige API-Doku (HTML) |
| | API-Doku als JSON |
| | Dokumentationssystem (HTML) |
| | Doku-Index (JSON) |
| | Alle Docs als ein Textblock |
| | Interaktives API-Playground |
Rate Limits
| Auth-Methode | Limit |
|---------------|-------|
| Mind Key (Header) | Keins |
| Mind Key (?key=) | 60/min pro IP |
| JWT (Header) | Keins |
| Öffentliche Endpunkte | Keins |
Rate-limitierte Antworten enthalten:
[CODE BLOCK]
Paginierung
Listen-Endpunkte unterstützen und :
[CODE BLOCK]
Standard-Limit: 100. Max. Limit: 500.
CORS
Alle Endpunkte unterstützen CORS für browserbasierte Clients:
[CODE BLOCK]
SDKs & Clients
- Node.js SDK: (Repo)
- MCP Server: (Repo)
- HTTP-Client: jede HTTP-Bibliothek (curl, fetch, axios, etc.)
Nächste Schritte
- Memory-API — die wichtigsten Endpunkte
- Chat-API — asynchrone Mensch-Agent-Kommunikation
- Errors & Fehlerbehandlung
────────────────────────────────────────────────────────────
# Rate Limits & Kontingente
SUMMARY: Rate-Limit-Richtlinien für die Synapse-API — Bearer-Header (unbegrenzt), ?key= (60/min), öffentliche Endpunkte.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Rate Limits & Kontingente
Synapse hat eine einfache, vorhersehbare Rate-Limit-Richtlinie, die Missbrauch
verhindern soll, ohne legitime Nutzung auszubremsen.
Rate-Limit-Richtlinie
| Auth-Methode | Limit | Scope |
|---------------|-------|-------|
| Mind Key () | Keins | Pro-Mind |
| Mind Key () | 60 req/min | Pro-IP |
| JWT () | Keins | Pro-Nutzer |
| Öffentliche Endpunkte | Keins | Global |
> [!TIP]
> Verwende immer den -Header, wenn möglich. Er hat
> kein Rate Limit. Nutze nur für Tools, die keine eigenen Header setzen
> können.
Rate-Limit-Header
Wenn du -Auth nutzt, enthalten Antworten Rate-Limit-Header:
[CODE BLOCK]
Wenn du das Limit überschreitest:
[CODE BLOCK]
Wenn du ein Rate Limit triffst
Bei einer 429:
1. Wechsle zum Authorization-Header (empfohlen):
[CODE BLOCK]
2. Oder warte Sekunden und versuche es erneut.
Warum das ?key=-Limit existiert
Der -Query-Parameter ist praktisch für reine URL-Tools (Browser,
-Befehle), hat aber Sicherheits- und Performance-Auswirkungen:
- Sicherheit: Query-Parameter werden in Server-Access-Logs, Browser-Verlauf
und Referer-Headern protokolliert. Eine Begrenzung reduziert die Exposition.
- Performance: Query-Parameter-Auth erfordert einen IP-basierten Rate-Limiter
(Redis-Lookup pro Anfrage), was Latenz erzeugt. Header-Auth umgeht das.
- Missbrauchsvermeidung: Eine geleakte -URL könnte geteilt und
abgefeuert werden. Das IP-Limit begrenzt den Schadensradius.
Empfohlene Patterns
LLM-Agenten
[CODE BLOCK]
Browserbasierte Tools
Wenn dein Tool nur URLs öffnen kann:
[CODE BLOCK]
MCP-Server
MCP-Server verwenden immer Header-Auth via -Env-Var — kein
Rate Limit greift.
Bulk-Importe
Für Bulk-Operationen (z. B. 1000 Memories importieren) verwende immer Header-Auth.
Bulk-Importe via erreichen das Limit innerhalb einer Minute.
Kontingente (Mind-Ebene)
Aktuell gibt es keine Mind-spezifischen Kontingente für Speichergröße oder
Memory-Anzahl. Alle Limits sind auf Auth/IP-Ebene, nicht auf Datenebene. Das
kann sich in Zukunft für Multi-Tenant-Fairness ändern.
Eigene Nutzung beobachten
[CODE BLOCK]
Nächste Schritte
- Authentifizierung
- Errors & Fehlerbehandlung
────────────────────────────────────────────────────────────
# Scripts-API
SUMMARY: Persistenter Script-Speicher — wiederverwendbare Shell-, Python- oder Node-Scripts speichern und via curl | bash abrufen.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts-API
Die Scripts-API bietet einen persistenten Speicher für wiederverwendbare Scripts.
Scripts werden benannt und innerhalb eines Minds versioniert und können als
Klartext abgerufen werden — perfekt für -Patterns.
Endpunkte
POST /script
Ein Script speichern oder aktualisieren.
[CODE BLOCK]
GET /script/:name
Script-Inhalt als abrufen. Perfekt für das Weiterleiten an bash.
[CODE BLOCK]
GET /script/:name/info
Script-Metadaten ohne den Inhalt abrufen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
GET /scripts
Alle Scripts im aktuellen Mind auflisten.
[CODE BLOCK]
DELETE /script/:name
Ein Script löschen.
[CODE BLOCK]
Häufige Anwendungsfälle
Deploy-Scripts
Standardisierte Deploy-Prozeduren speichern, damit das LLM sie ausführen kann,
ohne die Schritte jedes Mal neu abzuleiten:
[CODE BLOCK]
Troubleshooting-Snippets
Diagnose-Befehle für häufige Probleme speichern:
[CODE BLOCK]
Konfigurationsgeneratoren
Scripts speichern, die Konfigurationen erzeugen:
[CODE BLOCK]
Nächste Schritte
- Variables-API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks-API
SUMMARY: Aufgabenverwaltung für LLM-Agenten — Tasks erstellen, auflisten, aktualisieren, abschließen und löschen mit Prioritäten.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks-API
Die Tasks-API gibt LLM-Agenten eine strukturierte Möglichkeit, mehrschrittige
Aufgaben zu verfolgen. Tasks sind auf den aktuellen Mind beschränkt und bleiben
über Sessions hinweg bestehen, sodass der Agent dort weiterarbeiten kann, wo er
aufgehört hat.
Endpunkte
GET /mind/tasks
Alle Tasks des aktuellen Minds auflisten.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
POST /mind/task
Einen neuen Task anlegen.
[CODE BLOCK]
GET /mind/task (Query-Parameter)
Einen Task via GET anlegen (für reine URL-Tools).
[CODE BLOCK]
PUT /mind/task/:id
Einen bestehenden Task aktualisieren.
[CODE BLOCK]
GET /mind/task/:id/complete
Einen Task als erledigt markieren.
[CODE BLOCK]
GET /mind/task/:id/delete
Einen Task dauerhaft löschen.
[CODE BLOCK]
Prioritäten
- — nicht dringend
- — Standard
- — wichtig
- — muss sofort erledigt werden
Statuswerte
- — angelegt, nicht begonnen
- — in Bearbeitung
- — abgeschlossen
- — abgebrochen
Pattern: Task-getriebener Workflow
[CODE BLOCK]
Nächste Schritte
- Task-getriebener Workflow
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Utility-Tools (Zeit, Calc, Random)
SUMMARY: Öffentliche Utility-Endpunkte — Serverzeit, sicherer Taschenrechner, Zufallswert-Generator. Keine Auth erforderlich.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Utility-Tools
Die -Endpunkte sind öffentliche Hilfswerkzeuge — keine Authentifizierung
erforderlich. Sie sind nützlich für LLM-Agenten, die serverseitige Zeit, sichere
Mathe oder Zufallswerte brauchen.
GET /tools/time
Aktuelle Serverzeit, Zeitzone und UTC-Offset abrufen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
Anwendungsfall: LLM-Agenten, die „wie spät ist es jetzt" für Scheduling,
Zeitstempel oder relative Datenberechnungen wissen müssen.
GET /tools/calc
Sicherer Taschenrechner — nur Arithmetik, kein . Unterstützt , ,
, , , , und Zahlen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
> [!TIP]
> Verwende das statt Mathe im Kopf oder via String-Parsing. Es ist sicher
> (keine Code-Injection möglich) und präzise.
Unterstützte Operatoren
- Addition
- Subtraktion
- Multiplikation
- Division
- Modulo
- Klammern
- Zahlen (ganzzahlig und dezimal)
Beispiele
[CODE BLOCK]
GET /tools/random
Zufallswerte generieren.
[CODE BLOCK]
Typ-Parameter
| Typ | Parameter | Ausgabe |
|------|-----------|---------|
| | keine | UUID-v4-String |
| | , (Standard 0-100) | Integer |
| | , (Standard 0-100) | Float |
| | , (Längenbereich, Standard 8-16) | Hex-String |
| | , (Längenbereich, Standard 8-16) | Alphabetischer String |
Anwendungsfälle für LLM-Agenten
Eindeutige IDs generieren
[CODE BLOCK]
Prozentwerte berechnen
[CODE BLOCK]
Aktuellen Zeitstempel abrufen
[CODE BLOCK]
Testdaten generieren
[CODE BLOCK]
Nächste Schritte
- API-Übersicht — alle Endpunkt-Gruppen
- Errors & Fehlerbehandlung
────────────────────────────────────────────────────────────
# User- & Minds-API
SUMMARY: Kontoverwaltung — registrieren, einloggen, Minds erstellen, Minds auflisten, Minds löschen. JWT-geschützt.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User- & Minds-API
Die User- & Minds-API behandelt die Kontoverwaltung. Diese Endpunkte verwenden
JWT-Authentifizierung (nicht Mind Keys), weil sie auf Kontoebene arbeiten, nicht
auf Mind-Ebene.
Authentifizierungs-Endpunkte
POST /register
Ein neues Nutzerkonto anlegen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
POST /login
Bei einem bestehenden Konto einloggen.
[CODE BLOCK]
Antwort: wie bei .
Minds-Endpunkte
POST /minds
Einen neuen Mind anlegen. Liefert den Mind Key — sofort speichern, er wird
nur einmal angezeigt.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
> [!CRITICAL]
> Der wird nur einmal angezeigt. Wenn du ihn verlierst, kannst du ihn
> nicht wiederherstellen — du musst den Mind löschen und einen neuen anlegen
> (wodurch alle gespeicherten Memories verloren gehen).
GET /minds
Alle Minds des aktuellen Nutzers auflisten.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
DELETE /minds/:id
Einen Mind dauerhaft löschen.
[CODE BLOCK]
> [!WARNING]
> Das Löschen eines Minds ist unumkehrbar. Alle Memories, Tasks,
> Chat-Verläufe und Scripts in diesem Mind gehen dauerhaft verloren. Exportiere
> vorher via , falls du ein Backup brauchst.
Multi-Mind-Pattern
Die meisten Nutzer profitieren von mehreren Minds, um Kontexte getrennt zu
halten:
[CODE BLOCK]
Verwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte
getrennt zu halten.
Kontosicherheit
Passwort-Anforderungen
- Mindestens 6 Zeichen
- Kein Maximum (verwende einen Passwort-Manager)
- Als bcrypt-Hash gespeichert (niemals im Klartext)
JWT-Ablauf
JWTs laufen nach 7 Tagen ab. Wenn sie abgelaufen sind, rufe einfach wieder
auf.
Mind-Key-Sicherheit
Mind Keys laufen nie ab. Wenn ein Mind Key kompromittiert wurde:
1. Lege einen neuen Mind via an
2. Aktualisiere deine LLM-Konfiguration mit dem neuen Mind Key
3. Lösche den kompromittierten Mind via
Nächste Schritte
- Authentifizierung — vollständiger Auth-Guide
- Mind Key vs JWT — Entscheidungsleitfaden
- Sharing-API — Minds mit anderen Nutzern teilen
────────────────────────────────────────────────────────────
# Variables-API
SUMMARY: Schneller Key-Value-Store für LLM-Status — Zähler, Flags, Last-Seen-Zeitstempel, teilweiser Fortschritt.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables-API
Die Variables-API ist ein schneller Key-Value-Store für flüchtigen Status. Im
Gegensatz zu Memories (die indiziert, durchsuchbar und strukturiert sind) sind
Variablen für schnelle Lese-/Schreibzugriffe optimiert — perfekt für Zähler,
Flags und Session-Status.
Endpunkte
POST /var
Eine Variable setzen oder aktualisieren.
[CODE BLOCK]
GET /var/:key
Eine einzelne Variable abrufen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
GET /var
Alle Variablen auflisten.
[CODE BLOCK]
DELETE /var/:key
Eine Variable löschen.
[CODE BLOCK]
Wann Variablen statt Memory verwenden?
| Anwendungsfall | Verwende |
|----------------|----------|
| Nutzername, Präferenzen | Memory (durchsuchbar, strukturiert) |
| Zeitstempel der letzten Session | Variable (flüchtiger Status) |
| Zähler (z. B. gesendete Nachrichten) | Variable (häufige Updates) |
| Workflow-Status („Schritt 3 von 5 erledigt") | Variable (vorübergehend) |
| Ausführliche Projektnotizen | Memory (volltextindiziert) |
| Wiederverwendbare Scripts | Script-Speicher (benannt, versioniert) |
Häufige Patterns
Letzte Session verfolgen
[CODE BLOCK]
Zähler-Pattern
[CODE BLOCK]
Feature-Flags
[CODE BLOCK]
Nächste Schritte
- Memory-API — für strukturierte, durchsuchbare Daten
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks-API
SUMMARY: HTTP-Callbacks für Memory-, Chat- und Task-Events registrieren — benachrichtigt werden, wenn sich Daten ändern.
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks-API
Webhooks ermöglichen den Empfang von HTTP-Callbacks, wenn in Synapse Events
auftreten. Perfekt, um externe Automatisierungen auszulösen, Benachrichtigungen
zu versenden oder zu anderen Systemen zu synchronisieren.
Endpunkte
POST /webhooks
Einen neuen Webhook registrieren.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
GET /webhooks
Alle Webhooks des aktuellen Minds auflisten.
[CODE BLOCK]
GET /webhooks/:id
Einen einzelnen Webhook abrufen.
[CODE BLOCK]
PUT /webhooks/:id
Einen Webhook aktualisieren (URL, Events, Secret oder Enabled-Flag).
[CODE BLOCK]
DELETE /webhooks/:id
Einen Webhook löschen.
[CODE BLOCK]
Event-Typen
| Pattern | Feuert bei |
|---------|------------|
| | Beliebiges Memory-Event |
| | Neuer Memory gespeichert |
| | Memory aktualisiert |
| | Memory gelöscht |
| | Beliebiges Chat-Event |
| | Neue Nachricht vom Menschen |
| | Beliebiges Task-Event |
| | Neuer Task angelegt |
| | Task als erledigt markiert |
| | Alle Events |
Webhook-Payload
Wenn ein Event feuert, sendet Synapse ein POST an deine URL:
[CODE BLOCK]
Signatur-Verifikation
Wenn du ein setzt, signiert Synapse jeden Payload mit HMAC-SHA256:
[CODE BLOCK]
In deinem Handler verifizieren:
[CODE BLOCK]
Pattern: Echtzeit-Sync
[CODE BLOCK]
Nächste Schritte
- Cron & Scheduler
- Webhook-Automation-Guide
## KATEGORIE: MCP-INTEGRATION
Integration mit Claude, Cursor und anderen MCP-Clients.
────────────────────────────────────────────────────────────
# MCP in Claude Code
SUMMARY: Synapse-Tools aus dem Claude-Code-Terminal-Agenten nutzen — persistenten Memory für Coding-Sessions.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP in Claude Code
Claude Code ist Anthropics terminal-basierter Coding-Agent. Mit Synapse MCP
erhält Claude Code persistenten Memory über Coding-Sessions hinweg — er erinnert
sich an deinen Projektkontext, vergangene Entscheidungen und Codebase-Patterns.
Setup
Methode 1: CLI-Befehl (empfohlen)
[CODE BLOCK]
Methode 2: Config-Datei editieren
Editiere :
[CODE BLOCK]
Funktions-Verifikation
Claude Code starten:
[CODE BLOCK]
Im Claude-Code-Prompt eingeben:
[CODE BLOCK]
Claude sollte aufrufen und mit deinen gespeicherten Memories
antworten.
Häufige Patterns
Projektkontext-Persistenz
Zu Beginn einer Coding-Session:
[CODE BLOCK]
Claude ruft auf, sieht deine Projekt-Liste und setzt die Arbeit
dort fort, wo du aufgehört hast.
Codebase-Entscheidungen
Wenn du eine Architektur-Entscheidung triffst:
[CODE BLOCK]
Claude ruft mit Kategorie , Priorität auf.
Vergangene Fehler vermeiden
[CODE BLOCK]
Claude sucht Memories mit Kategorie und erinnert dich an vergangene
Fehler.
Task-Tracking
[CODE BLOCK]
Claude ruft auf, und der Task persistiert über Sessions.
Tool-Profile
Für Coding-Sessions, in denen du nicht alle 119 Tools brauchst:
[CODE BLOCK]
Troubleshooting
MCP-Server startet nicht
[CODE BLOCK]
Mind Key nicht erkannt
[CODE BLOCK]
Claude Code sieht Tools nicht
- Claude Code nach Config-Änderungen neu starten
- prüfen, ob Synapse registriert ist
- Siehe MCP-Troubleshooting
Nächste Schritte
- Claude-Desktop-Setup
- Cursor-Setup
- Persistenter-LLM-Agent-Guide
────────────────────────────────────────────────────────────
# MCP in Claude Desktop
SUMMARY: Synapse in 2 Minuten mit Claude Desktop verbinden. Claude erhält 79 Synapse-Tools nativ.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP in Claude Desktop
Claude Desktop ist Anthropics Desktop-App für macOS und Windows. Mit dem
konfigurierten Synapse-MCP-Server erhält Claude nativen Zugriff auf alle 79
Synapse-Tools — es kann Memories speichern, abrufen, Tasks verwalten, mit dir
chatten und mehr.
Voraussetzungen
- Claude-Desktop-App (macOS oder Windows)
- Node.js 18+ installiert ()
- Dein Synapse Mind Key
Schritt 1: Config-Datei öffnen
- macOS:
- Windows:
Wenn die Datei nicht existiert, lege sie an.
Schritt 2: Synapse-MCP-Server hinzufügen
[CODE BLOCK]
> [!TIP]
> Wenn du bereits andere MCP-Server konfiguriert hast, füge einfach den
> -Block innerhalb des bestehenden -Objekts hinzu.
Schritt 3: Claude Desktop neu starten
1. Claude Desktop vollständig beenden (Cmd+Q auf macOS, nicht nur Fenster schließen)
2. Claude Desktop wieder öffnen
3. Neuen Chat starten
4. Suche das 🔌-Plug-Icon unten links — es sollte „79 tools" sagen
Schritt 4: Testen
In einem neuen Chat eingeben:
[CODE BLOCK]
Claude sollte das -Tool aufrufen und mit einer Zusammenfassung
deiner gespeicherten Memories antworten (oder „No memories yet", wenn dein Mind
leer ist).
Verfügbare Tools (Auswahl)
| Tool | Beschreibung |
|------|--------------|
| | Alle Memories abrufen |
| | Neuen Memory speichern |
| | Memories durchsuchen |
| | Tasks auflisten |
| | Task anlegen |
| | Auf neue Nachrichten prüfen |
| | Auf Nachricht antworten |
| | Browser-Tab öffnen |
| | Registrierte Rechner auflisten |
Vollständige Liste: Was ist MCP?
Troubleshooting
Keine Tools in Claude Desktop sichtbar
1. Node.js-Version verifizieren: (muss ≥ 18 sein)
2. Config-Datei auf valides JSON prüfen (keine Trailing-Commas)
3. Claude Desktop vollständig neu starten (Cmd+Q, nicht nur schließen)
4. Claude-Desktop-Logs prüfen: (macOS)
„Mind Key invalid"-Fehler
- Verifizieren, dass mit beginnt
- Frischen Key via holen (erfordert JWT von )
- Keine Anführungszeichen um den Key im JSON
npx nicht gefunden
- Node.js 18+ installieren:
- Nach Installation Terminal neu starten
- Auf macOS mit Homebrew:
Tools sichtbar, aber Aufrufe schlagen fehl
- erreichbar prüfen:
- Mind Key verifizieren:
- Siehe MCP-Troubleshooting
Tool-Profile (Token sparen)
Wenn du ein kleineres LLM verwendest oder Kontext-Tokens sparen willst, setze
ein Tool-Profil:
[CODE BLOCK]
Profile: (8 Tools), (25), (119, Standard).
Nächste Schritte
- Claude-Code-Setup
- Cursor-Setup
- MCP-Troubleshooting
────────────────────────────────────────────────────────────
# MCP in Continue.dev
SUMMARY: Synapse mit Continue.dev verbinden — Open-Source-AI-Coding-Assistent für VS Code und JetBrains.
MCP in Continue.dev
Continue.dev ist ein Open-Source-AI-Coding-Assistent für VS Code und JetBrains-
IDEs. Mit Synapse MCP erhält Continue persistenten Memory über Sessions hinweg.
Voraussetzungen
- VS Code oder JetBrains-IDE
- Continue.dev-Erweiterung installiert
- Node.js 18+
- Dein Synapse Mind Key
Setup
Schritt 1: Continue-Config öffnen
In VS Code oder JetBrains:
1. Continue-Erweiterungs-Seitenleiste öffnen
2. Zahnrad-Icon klicken → „Open config.json"
Oder direkt editieren.
Schritt 2: Synapse-MCP-Server hinzufügen
[CODE BLOCK]
Schritt 3: Continue neu laden
VS-Code-Fenster neu laden (Cmd+Shift+P → „Reload Window") oder IDE neu starten.
Funktions-Verifikation
Im Continue-Chat:
[CODE BLOCK]
Continue sollte aufrufen und mit deinen gespeicherten Memories
antworten.
Häufige Patterns
Projektkontext
[CODE BLOCK]
Continue ruft auf, sieht deine Projekt-Memories und setzt die
Arbeit dort fort, wo du aufgehört hast.
Code-Review-Patterns
[CODE BLOCK]
Continue findet deine gespeicherten Code-Review-Patterns und wendet sie an.
Pair-Programming-Memory
[CODE BLOCK]
Continue speichert es als -Memory.
Troubleshooting
MCP-Server verbindet nicht
1. auf valides JSON prüfen
2. Node.js verifizieren:
3. Continue-Output-Panel prüfen (View → Output → Continue)
4. IDE neu starten
Tools erscheinen nicht
- Verifizieren, dass Continue-Version MCP unterstützt (≥ 0.9.x)
- -Env-Var in Config gesetzt prüfen
- In Continue-Logs nach MCP-Fehlern suchen
Nächste Schritte
- Claude-Desktop-Setup
- Custom-MCP-Client
────────────────────────────────────────────────────────────
# MCP in Cursor
SUMMARY: Synapse mit Cursor IDE verbinden für persistenten Projekt-Memory über Coding-Sessions hinweg.
MCP in Cursor
Cursor ist eine AI-powered IDE basierend auf VS Code. Mit Synapse MCP erhält
Cursor persistenten Memory über Sessions hinweg — er erinnert sich an deine
Projektentscheidungen, Codebase-Patterns und vergangene Debugging-Sessions.
Voraussetzungen
- Cursor-IDE installiert ()
- Node.js 18+
- Dein Synapse Mind Key
Setup
Schritt 1: Cursor-Settings öffnen
In Cursor:
1. Settings öffnen (Cmd+, auf macOS, Ctrl+, auf Windows/Linux)
2. Nach „MCP" suchen oder zu navigieren
Schritt 2: Synapse-MCP-Server hinzufügen
Auf „Add MCP Server" klicken und konfigurieren:
| Feld | Wert |
|------|------|
| Name | |
| Type | |
| Command | |
| Env | |
Schritt 3: config.json direkt editieren (Alternative)
Cursor speichert MCP-Config in :
[CODE BLOCK]
Schritt 4: Cursor neu starten
Cursor vollständig neu starten (Cmd+Q und wieder öffnen auf macOS).
Funktions-Verifikation
In Cursors Chat-Panel (Cmd+L):
[CODE BLOCK]
Cursor sollte aufrufen und mit deinen gespeicherten Memories
antworten.
Häufige Patterns
Projekt-Onboarding
Beim Öffnen eines neuen Projekts:
[CODE BLOCK]
Cursor ruft auf und setzt die Arbeit dort fort, wo du
aufgehört hast.
Architektur-Entscheidungen
[CODE BLOCK]
Cursor speichert es als -Memory mit Priorität .
Debugging-Historie
[CODE BLOCK]
Cursor sucht nach -Memories und erinnert dich an vergangene Fixes.
Cross-Session-Code-Patterns
[CODE BLOCK]
Cursor findet Memories über Auth-Implementierungen, die du früher gemacht hast.
Troubleshooting
MCP-Server verbindet nicht
1. Node.js verifizieren: (≥ 18)
2. MCP-Server testen: (sollte ohne Fehler starten)
3. Cursors MCP-Logs prüfen (View → Output → MCP)
4. Cursor vollständig neu starten
Tools erscheinen nicht
- auf valides JSON prüfen
- -Env-Var gesetzt verifizieren
- Cursor-Version unterstützt MCP prüfen (≥ 0.42)
Mind Key ungültig
[CODE BLOCK]
Nächste Schritte
- Claude-Desktop-Setup
- Continue.dev-Setup
- Persistenter-LLM-Agent-Guide
────────────────────────────────────────────────────────────
# Einen Custom-MCP-Client bauen
SUMMARY: Mit dem Synapse-MCP-Server aus eigener Anwendung über das MCP-SDK verbinden.
Einen Custom-MCP-Client bauen
Wenn du deine eigene LLM-Anwendung baust, kannst du dich direkt über das
offizielle MCP-SDK mit dem Synapse-MCP-Server verbinden. So erhält deine App
Zugriff auf alle 79 Synapse-Tools.
SDKs
| Sprache | Paket |
|---------|-------|
| TypeScript/JavaScript | |
| Python | |
TypeScript-Beispiel
Installation
[CODE BLOCK]
Via stdio verbinden
[CODE BLOCK]
Via HTTP/SSE verbinden (Remote)
[CODE BLOCK]
Python-Beispiel
Installation
[CODE BLOCK]
Via stdio verbinden
[CODE BLOCK]
Tool-Profile
Beim Verbinden kannst du ein spezifisches Tool-Profil über den
-Header (HTTP/SSE) oder die -Env-Var (stdio)
anfordern:
[CODE BLOCK]
Fehlerbehandlung
[CODE BLOCK]
Anwendungsfälle
- Custom-AI-Assistenten — eigenen Agenten mit persistentem Memory bauen
- Workflow-Automatisierung — Synapse-Tools in Custom-Workflows verketten
- Data-Pipelines — Memories extrahieren, transformieren, woanders laden
- Monitoring-Dashboards — Memory-Stats, Chat-Verlauf, Tasks anzeigen
Nächste Schritte
- MCP-Spezifikation
- Synapse-MCP-Repo
- API-Übersicht
────────────────────────────────────────────────────────────
# MCP-Troubleshooting
SUMMARY: Häufige MCP-Integrations-Probleme lösen — Server startet nicht, Tools erscheinen nicht, Auth-Fehler.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
MCP-Troubleshooting
Häufige Probleme und Lösungen bei der Integration von Synapse MCP mit deinem
LLM-Client.
Schnelle Diagnose-Checkliste
1. ✅ Node.js 18+ installiert? ()
2. ✅ Mind Key beginnt mit ? (nicht JWT )
3. ✅ Synapse-API erreichbar? ()
4. ✅ Mind Key funktioniert? ()
5. ✅ Config-Datei ist valides JSON? (keine Trailing-Commas, keine Kommentare)
6. ✅ Client nach Config-Änderung neu gestartet?
7. ✅ MCP-Server startet manuell? ()
Problem: Keine Tools im Client sichtbar
Symptome
- Claude Desktop / Cursor / Continue zeigt 0 Tools
- Kein 🔌-Icon oder „synapse"-Eintrag in MCP-Server-Liste
Lösungen
1. Client vollständig neu starten — Cmd+Q auf macOS (nicht nur Fenster schließen)
2. Config-Datei-Ort prüfen:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. JSON validieren — Config in einfügen
4. Client-Logs auf MCP-Fehler prüfen:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. MCP-Server manuell ausführen, um Startup-Fehler zu sehen:
[CODE BLOCK]
Problem: „Mind Key invalid"-Fehler
Symptome
- Tools erscheinen, aber Aufrufe schlagen mit „401 Unauthorized" fehl
- Fehler: „Mind Key fehlt oder ungültig"
Lösungen
1. Mind-Key-Format verifizieren — beginnt mit , 40 Zeichen
2. Direkt testen:
[CODE BLOCK]
3. Env-Var gesetzt prüfen — für stdio-Transport muss die Env-Var in der
MCP-Server-Config stehen, nicht in deiner Shell
4. Frischen Mind Key holen:
[CODE BLOCK]
Problem: npx nicht gefunden
Symptome
- Fehler: „npx: command not found"
- MCP-Server startet nicht
Lösungen
1. Node.js 18+ installieren:
- macOS: oder von herunterladen
- Linux:
- Windows: von herunterladen
2. Nach Installation Terminal neu starten
3. Verifizieren:
Problem: SYNAPSEURL nicht erreichbar
Symptome
- MCP-Server startet, aber Tool-Aufrufe timen aus
- Fehler: „fetch failed" oder „ECONNREFUSED"
Lösungen
1. Verbindbarkeit testen:
[CODE BLOCK]
2. Corporate-Firewall prüfen — könnte ausgehendes HTTPS blockieren
3. Alternative URL versuchen:
- Produktion:
- MCP-Server:
4. Für Self-Hosted: sicherstellen, dass deine Synapse-Instanz läuft und erreichbar ist
Problem: MCP-Server crasht
Symptome
- MCP-Server beendet sich sofort nach Start
- Client-Logs zeigen „MCP server disconnected"
Lösungen
1. Manuell ausführen, um Fehler zu sehen:
[CODE BLOCK]
2. Port-Konflikte prüfen — MCP-Server nutzt standardmäßig Port 13100
3. npx-Cache leeren:
[CODE BLOCK]
4. Auf neueste Version updaten:
[CODE BLOCK]
Problem: Tool-Aufrufe liefern 429
Symptome
- Fehler: „Rate limit exceeded"
Lösungen
Das sollte mit MCP nicht passieren (verwendet Header-Auth, kein Rate Limit).
Falls doch:
1. Prüfen, ob du irgendwo verwendest — auf Header-Auth wechseln
2. verifizieren — sicherstellen, dass sie auf die richtige Instanz zeigt
3. Support kontaktieren, falls das Problem besteht
Problem: Tools erscheinen, funktionieren aber nicht
Symptome
- Tools im Client gelistet
- Tool-Aufruf liefert Fehler oder kein Ergebnis
Lösungen
1. Tool-Name prüfen — muss exakt sein (z. B. , nicht )
2. Argumente verifizieren — Input-Schema des Tools prüfen
3. Via direkter API testen:
[CODE BLOCK]
4. Synapse-Health prüfen:
[CODE BLOCK]
Hilfe holen
Falls nichts davon dein Problem löst:
1. Bestehende Issues prüfen:
2. Neues Issue öffnen mit:
- MCP-Server-Version ()
- Client-Name und -Version
- Betriebssystem
- Relevante Log-Auszüge
- Reproduktionsschritte
Nächste Schritte
- Claude-Desktop-Setup
- Claude-Code-Setup
- API-Errors
────────────────────────────────────────────────────────────
# Was ist MCP?
SUMMARY: Model Context Protocol lässt LLMs externe Tools aufrufen. Synapse exponiert 79 Tools via offiziellem MCP-Server.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
Was ist MCP?
Das Model Context Protocol (MCP) ist ein offener Standard von Anthropic
(2024), der LLMs erlaubt, externe Tools strukturiert aufzurufen. Statt API-Docs
in den Prompt einzufügen, registrierst du Tools beim MCP-Server, und das LLM
ruft sie bei Bedarf auf — wie Function Calling, aber standardisiert und
Client-agnostisch.
Synapse-MCP-Server
Synapse liefert einen offiziellen MCP-Server ( auf npm), der
79 Tools exponiert, die alle Synapse-Features abdecken:
| Kategorie | Tools | Anzahl |
|-----------|-------|--------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Total | | 79+ |
Funktionsweise
[CODE BLOCK]
1. Du konfigurierst deinen LLM-Client (Claude Desktop, Cursor etc.), den Synapse-MCP-Server zu verwenden
2. Der Client startet den MCP-Server (via )
3. Der MCP-Server verbindet sich mit der Synapse-API über deinen Mind Key
4. Das LLM sieht alle 79 Tools als native Funktionen, die es aufrufen kann
5. Wenn das LLM sich etwas merken muss, ruft es auf — der MCP-Server übersetzt das zu auf Synapse
Transports
Der Synapse-MCP-Server unterstützt drei Transports:
stdio (lokal, empfohlen für Desktop)
[CODE BLOCK]
HTTP/SSE (Remote, Multi-Tenant)
Verbinde deinen MCP-Client mit:
[CODE BLOCK]
WebSocket (mobil, hohes Volumen)
[CODE BLOCK]
Tool-Profile (v1.4.0)
Um Token-Overhead für kleinere LLMs zu reduzieren, unterstützt der MCP-Server
drei Tool-Profile:
| Profil | Tools | Token | Optimal für |
|---------|-------|-------|-------------|
| | 8 (Composite-Dispatch) | 500 | Self-Hosted-LLMs mit ≤8k Kontext |
| | 25 (benannt) | 2.500 | Mid-Size-LLMs (Claude Haiku, GPT-3.5) |
| | 119 (alle) | 8.250 | Große LLMs (Claude Sonnet/Opus, GPT-4) — Standard |
Steuerung via:
- Env-Var:
- Header:
Unterstützte Clients
- Claude Desktop — Anthropic Desktop-App
- Claude Code — Terminal-Coding-Agent
- Cursor — AI-powered IDE
- Continue.dev — Open-Source-AI-Coding-Assistent
- Cline — VS-Code-Erweiterung
- Jeder MCP-kompatible Client
Warum MCP statt direkter API?
| Ansatz | Vorteile | Nachteile |
|--------|----------|-----------|
| Direkte API | Einfach, keine extra Schicht | LLM muss URLs, Header, Auth kennen |
| MCP | LLM sieht native Tools, kein URL-Auswendiglernen | Extra MCP-Server-Prozess |
Für die meisten LLM-Agent-Anwendungsfälle ist MCP die bessere Wahl — das LLM
muss sich keine API-Pfade oder Auth-Patterns merken.
Nächste Schritte
- Claude-Desktop-Setup — 2-Minuten-Config
- Claude-Code-Setup — Terminal-Integration
- Custom-MCP-Client — eigenen bauen
## KATEGORIE: ANLEITUNGEN & TUTORIALS
Schritt-für-Schritt-Anleitungen für konkrete Szenarien.
────────────────────────────────────────────────────────────
# Automatisiertes iOS-App-Testing
SUMMARY: Synapse + Computer-Control-API nutzen, um iOS-App-Tests via Simulator zu automatisieren.
Automatisiertes iOS-App-Testing
Kombiniere Synapses Memory-System mit der Computer-Control-API, um LLM-gesteuerte
iOS-App-Tests zu bauen. Das LLM erinnert sich an Test-Szenarien, lernt aus
vergangenen Fehlern und passt sich an UI-Änderungen an.
Architektur
[CODE BLOCK]
Voraussetzungen
- Synapse-Konto + Mind Key
- Synapse-MCP-Server in Claude Desktop konfiguriert
- iOS-Simulator mit installiertem
- Rechner in Synapse registriert (siehe Computer-Control-API)
Schritt 1: Simulator-Rechner registrieren
Auf dem Mac, der den iOS-Simulator ausführt:
[CODE BLOCK]
Schritt 2: Test-Szenarien im Memory speichern
Wiederverwendbare Test-Szenarien als Memories speichern:
[CODE BLOCK]
Schritt 3: LLM-gesteuerte Testausführung
In Claude Desktop (mit konfiguriertem Synapse MCP):
[CODE BLOCK]
Claude wird:
1. aufrufen, um den -Memory zu finden
2. aufrufen, um den aktuellen Zustand zu sehen
3. Jeden Schritt via ausführen (Click, Type)
4. Ergebnisse via Screenshots verifizieren
5. Alle Fehlschläge als -Memories speichern
Schritt 4: Self-Healing-Tests
Wenn ein Test fehlschlägt, speichere den Fehlschlag und die Recovery:
[CODE BLOCK]
Wenn das LLM den Test das nächste Mal ausführt, ruft es den Fehlschlag ab und
wendet die Recovery automatisch an.
Schritt 5: Test-Ergebnis-Tracking
Testläufe als Tasks tracken:
[CODE BLOCK]
Häufige Befehle
| Aktion | Befehl |
|--------|--------|
| Simulator starten | |
| Screenshot | (via Synapse MCP) |
| Tap at (x,y) | |
| Text tippen | |
| Home drücken | |
Best Practices
> [!TIP]
> - UI-Koordinaten als Memories speichern — UI ändert sich, aber das LLM kann neu lernen
> - Accessibility-Labels verwenden — stabiler als Koordinaten
> - Testdaten separat speichern — Variablen für Nutzernamen, Passwörter verwenden
> - Tests in clean state ausführen — Simulator zwischen Läufen zurücksetzen
> - Screenshots für Fehlschläge loggen — nützlich beim Debugging
Nächste Schritte
- Self-Healing-Tests
- Computer-Control-API
- Memory-Best-Practices
────────────────────────────────────────────────────────────
# Backup & Restore
SUMMARY: Memories für Backup exportieren, zwischen Minds migrieren, nach Datenverlust wiederherstellen.
Backup & Restore
Synapse bietet vollständigen Export/Import für Memory-Backup, Migration und
Disaster-Recovery. Dieser Guide behandelt die essenziellen Operationen.
Export
Vollständiger Mind-Export
Alle Memories eines Minds als JSON exportieren:
[CODE BLOCK]
Antwort-Format:
[CODE BLOCK]
Inkrementeller Export (Diff)
Nur Memories exportieren, die seit einem Zeitstempel geändert wurden:
[CODE BLOCK]
Antwort:
[CODE BLOCK]
Automatisierte Backups
Tägliche Backups via Cron planen:
[CODE BLOCK]
> [!NOTE]
> Der Cron-Endpunkt empfängt die Antwort, speichert sie aber nicht. Für echte
> Backups lasse den Cron auf deinen eigenen Backup-Server zeigen, der die
> Antwort speichert.
Besser: externes Backup-Script
[CODE BLOCK]
Zur Crontab hinzufügen:
[CODE BLOCK]
Restore
In denselben Mind wiederherstellen
[CODE BLOCK]
In neuen Mind wiederherstellen
[CODE BLOCK]
Python-Restore-Script
[CODE BLOCK]
Migration zwischen Minds
[CODE BLOCK]
Andere Daten sichern
Nicht vergessen zu sichern:
| Datentyp | Endpunkt |
|-----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron-Jobs | |
| Variables | |
| Chat-Verlauf | |
Verifikation
Nach dem Restore verifizieren:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Täglich sichern — mit Cron automatisieren
> - Restores testen — ein Backup, das du nicht restoren kannst, ist nutzlos
> - Mehrere Versionen aufbewahren — mindestens 30 Tage
> - Offsite speichern — S3, Backblaze B2 etc.
> - Sensible Backups verschlüsseln — Memories können PII enthalten
> - Restore-Prozess dokumentieren — bis du ihn brauchst, hast du ihn vergessen
Nächste Schritte
- Memory-API
- Cron & Scheduler — für automatisierte Backups
────────────────────────────────────────────────────────────
# Memory-Best-Practices
SUMMARY: Wie du Memories für effektives Recall strukturierst — Kategorien, Keys, Tags, Prioritäten.
Memory-Best-Practices
Wie du Memories strukturierst, bestimmt ihren Nutzen. Dieser Guide behandelt
Patterns zum Kategorisieren, Taggen und Prioritisieren, damit das LLM zur
richtigen Zeit die richtigen Informationen abrufen kann.
Kategorien: Wähle die spezifischste
| Kategorie | Verwende für | Beispiel |
|-----------|--------------|----------|
| | Nutzername, Rolle, Kontaktinfo | |
| | Vorlieben, Abneigungen, Arbeitsstil | |
| | Überprüfbare Fakten | |
| | Projektstatus, Entscheidungen | |
| | Fähigkeiten des Nutzers | |
| | Frühere Fehler, die es zu vermeiden gilt | |
| | Session-relevanter Kontext | |
| | Sonstige Notizen | |
> [!TIP]
> Im Zweifel: für überprüfbare Infos und für alles andere.
> Nicht überkategorisieren — besser ein klarer als ein verwirrender
> .
Keys: Aussagekräftige Bezeichner
Das Feld ist der Bezeichner des Memories. Verwende aussagekräftige,
stabile Keys:
Gute Keys:
-
-
-
-
Schlechte Keys:
- (nicht aussagekräftig)
- (nicht beschreibend)
- (Datum hilft beim Recall nicht)
Key-Namenskonventionen
- (Kleinschreibung mit Unterstrichen)
- Präfix mit Kategorie: , ,
- Beschreibende Substantive, keine Verben
- Unter 50 Zeichen halten
Tags: Für Suche und Filterung
Tags ermöglichen schnelle Filterung und Suche. 2-5 Tags pro Memory hinzufügen:
[CODE BLOCK]
Tag-Patterns
- Projektnamen: , ,
- Themen: , , ,
- Status: , ,
- Prioritäts-Indikatoren: ,
> [!NOTE]
> Tags sind Case-insensitive. Verwende für Konsistenz Kleinschreibung.
Prioritäten: Sei realistisch
| Priorität | Verwende für | % der Memories |
|-----------|--------------|----------------|
| | Nutzeridentität, rechtliche Infos, unumkehrbare Entscheidungen | 5% |
| | Aktive Projekte, wichtige Präferenzen | 20% |
| | Die meisten Fakten, Notizen, Kontext | 65% |
| | Flüchtig, nett zu wissen | 10% |
> [!WARNING]
> Markiere nicht alles als . Wenn alles critical ist, ist nichts
> critical. Reserviere für Dinge, die echten Schaden anrichten, wenn
> sie vergessen werden.
Wann speichern, wann nicht?
Immer speichern
- Nutzeridentität (Name, E-Mail, Rolle)
- Langfristige Präferenzen
- Projektentscheidungen und Begründungen
- Frühere Fehler und gelernte Lektionen
- Zugesagte Zusagen an den Nutzer
Nicht speichern
- Flüchtigen Status (verwende stattdessen Variablen)
- Wörtlichen Konversationsverlauf (Chat-System übernimmt das)
- Sensible Daten (Passwörter, API-Keys)
- Leicht ableitbare Fakten (aktuelles Datum, Dateiinhalte)
- Flüchtigen Kontext (verwende -Kategorie mit niedriger Priorität)
Memories aktualisieren
POST mit derselben + aktualisiert den bestehenden
Memory:
[CODE BLOCK]
> [!TIP]
> Verwende stabile Keys, damit du aktualisieren kannst, ohne Duplikate zu
> erzeugen. Das LLM sollte denselben Key erneut posten, wenn sich Infos ändern,
> nicht neue Memories anlegen.
Memory-Lebenszyklus
[CODE BLOCK]
- Create: POST /memory mit vollem Kontext
- Active: Häufig abrufen, bei Bedarf aktualisieren
- Stale: Noch relevant, aber nicht aktiv genutzt (niedrigere Priorität?)
- Archive: Priorität auf setzen, für historische Referenz behalten
- Delete: DELETE /memory/:id, wenn nicht mehr relevant
Periodische Bereinigung
[CODE BLOCK]
Pattern: Memory-Vererbung
Für hierarchischen Kontext (Projekt → Subprojekt → Task):
[CODE BLOCK]
Das LLM kann dann suchen, um alle verwandten Memories zu
finden.
Pattern: Entscheidungs-Log
Entscheidungen mit Begründung speichern, damit das LLM sie nicht neu verhandelt:
[CODE BLOCK]
Pattern: Fehler-Vermeidung
Fehler mit spezifischen Vermeidungs-Anweisungen speichern:
[CODE BLOCK]
Anti-Patterns, die du vermeiden solltest
> [!WARNING]
> - Konversations-Logs speichern — Chat-System übernimmt das
> - Ganze Dateien speichern — Script-Speicher oder externen Speicher verwenden
> - Flüchtigen Status speichern — Variablen verwenden
> - Secrets speichern — Environment-Variablen verwenden
> - Memories duplizieren — stabile Keys verwenden
> - Übertrieben taggen — 2-5 Tags pro Memory sind ideal
> - Alles ist critical — sei realistisch mit Prioritäten
Nächste Schritte
- Memory-API
- Persistenter LLM-Agent
- Memory-Tagging-Strategie
────────────────────────────────────────────────────────────
# Multi-Agent-Koordination
SUMMARY: Mehrere LLM-Agenten über geteilte Synapse-Minds, Tasks und Chat koordinieren.
Multi-Agent-Koordination
Wenn du mehrere LLM-Agenten hast, die an verwandten Aufgaben arbeiten, stellt
Synapse die Koordinationsschicht bereit — Shared Memory, Task-Zuweisung und
asynchronen Chat.
Patterns
Pattern 1: Shared Mind (Single Source of Truth)
Alle Agenten teilen sich einen Mind Key. Sie lesen/schreiben denselben
Memory-Store.
[CODE BLOCK]
Anwendungsfall: Kleines Team von Agenten, das an einem Projekt arbeitet.
Setup:
[CODE BLOCK]
Koordination via Tasks:
[CODE BLOCK]
Pattern 2: Specialized Minds (isolierte Kontexte)
Jeder Agent hat seinen eigenen Mind. Sie kommunizieren über einen geteilten
„Koordinations"-Mind.
[CODE BLOCK]
Anwendungsfall: Agenten mit unterschiedlichen Spezialisierungen (Coding,
Review, Deployment).
Setup:
[CODE BLOCK]
Koordination via Shared Mind:
[CODE BLOCK]
Pattern 3: Hub-and-Spoke (Orchestrator)
Ein zentraler Orchestrator-Agent weist Worker-Agenten Tasks zu.
[CODE BLOCK]
Anwendungsfall: Komplexe Workflows mit paralleler Arbeit.
Implementierung:
[CODE BLOCK]
Koordination via Chat
Agenten können über das Chat-System kommunizieren:
[CODE BLOCK]
> [!NOTE]
> Chat-Nachrichten sind rollen-getaggt. Setze role=agent für Agent-zu-Agent-
> Nachrichten, role=human für Mensch-zu-Agent.
Koordination via Variablen
Variablen für leichtgewichtige Koordination verwenden (Locks, Flags):
[CODE BLOCK]
Best Practices
> [!TIP]
> - Separate Minds für separate Belange — nicht Coder- und Reviewer-Memory mischen
> - Agenten im Chat taggen — für klare Adressierung
> - Tasks für Arbeits-Zuweisung verwenden — nicht Chat (Chat ist für Diskussion)
> - Idempotenz implementieren — Agenten können fehlgeschlagene Operationen wiederholen
> - Alles loggen — Entscheidungen im Memory für Auditierbarkeit speichern
Nächste Schritte
- Persistenter LLM-Agent
- LLM-Cookbook
- Webhook-Automation
────────────────────────────────────────────────────────────
# Einen persistenten LLM-Agenten bauen
SUMMARY: Schritt-für-Schritt-Anleitung für einen LLM-Agenten, der sich über Sessions hinweg mittels Synapse erinnert.
Überblick
Dieser Guide führt durch den Bau eines LLM-Agenten, der Kontext über Sessions
hinweg mittels Synapse persistiert. Am Ende wird dein Agent:
- Vergangenen Kontext zu Session-Beginn abrufen
- Neue Learnings beim Entstehen speichern
- Mehrschrittige Tasks über Sessions verfolgen
- Mit Menschen via asynchronem Chat kommunizieren
Architektur
[CODE BLOCK]
Schritt 1: Mind Key einrichten
[CODE BLOCK]
Schritt 2: Session-Start-Protokoll
Zu Beginn jeder Session alle Memories abrufen:
[CODE BLOCK]
Schritt 3: Neue Learnings speichern
Wann immer der Agent etwas lernenswertes erfährt:
[CODE BLOCK]
Schritt 4: Task-Management
Mehrschrittige Arbeit über Sessions verfolgen:
[CODE BLOCK]
Schritt 5: Asynchroner Chat mit Menschen
Zwischen Tool-Aufrufen nach Nachrichten pollen:
[CODE BLOCK]
Schritt 6: Session-Ende-Protokoll
Am Session-Ende finalen Kontext speichern:
[CODE BLOCK]
Vollständiges Pattern
[CODE BLOCK]
Best Practices
> [!TIP]
>
> - Immer zuerst recall — nie ohne geladenen Kontext arbeiten beginnen
> - Proaktiv speichern — nicht bis Session-Ende warten
> - Aussagekräftige Keys verwenden — , , nicht
> - Alles taggen — Tags treiben Suche und Filterung
> - Realistische Prioritäten setzen — nicht alles ist
Nächste Schritte
- LLM-Cookbook — praktische Patterns
- Memory-Best-Practices
- Multi-Agent-Koordination
────────────────────────────────────────────────────────────
# Self-Healing-Test-Pipelines
SUMMARY: Test-Pipelines bauen, die aus Fehlern lernen und sich mittels Synapse-Memory automatisch anpassen.
Self-Healing-Test-Pipelines
Traditionelle Test-Suiten brechen, wenn sich die UI ändert. Self-Healing-Tests
nutzen Synapse-Memory, um aus vergangenen Fehlern zu lernen und sich anzupassen —
das reduziert flaky Tests und Wartungsaufwand.
Konzept
[CODE BLOCK]
1. Test läuft
2. Bei Fehlschlag: Failure speichern (was schiefging, warum, wie zu beheben)
3. Nächster Lauf: relevante Failures vor der Ausführung abrufen
4. Bekannte Fixes automatisch anwenden
Implementierung
Schritt 1: Test-Wrapper
Jeden Test mit Memory-Recall/Store wrappen:
[CODE BLOCK]
Schritt 2: Adaptive Test-Logik
Im Test auf bekannte Failures prüfen und Fixes anwenden:
[CODE BLOCK]
Schritt 3: Recovery-Strategien
Recovery-Strategien als Memories speichern:
[CODE BLOCK]
Schritt 4: CI-Integration
[CODE BLOCK]
Schritt 5: Failure-Analysis-Dashboard
[CODE BLOCK]
Best Practices
> [!TIP]
> - Tracebacks speichern — sie enthalten die exakte Zeile, die fehlgeschlagen ist
> - Nach Test-Name taggen — ermöglicht schnelle Filterung
> - Kategorie verwenden — trennt von regulären Memories
> - Priorität setzen — Failures sollten nie vergessen werden
> - Periodische Bereinigung — Memories für gelöste Issues löschen
> - Keine sensiblen Daten speichern — Credentials, PII
Häufige Failure-Patterns zum Speichern
| Failure-Typ | Was speichern |
|--------------|---------------|
| Element not found | Versuchter Selector, Page-State, Screenshot |
| Timeout | Wartezeit, worauf gewartet wurde |
| Assertion failed | Erwarteter vs. tatsächlicher Wert |
| Network error | URL, Status-Code, Response-Body |
| Permission denied | Erforderliche Permission, aktuelle Nutzerrolle |
Nächste Schritte
- Automatisiertes iOS-Testing
- Memory-Best-Practices
- Error-Recovery-Cookbook
────────────────────────────────────────────────────────────
# Webhook-Automation
SUMMARY: Externe Systeme triggern, wenn sich Memories ändern — synchronisieren, benachrichtigen, automatisieren.
Webhook-Automation
Webhooks ermöglichen das Triggern externer Systeme, wenn Synapse-Events feuern.
Dieser Guide behandelt häufige Automations-Patterns.
Häufige Patterns
Pattern 1: Bei kritischem Memory benachrichtigen
Slack-Nachricht senden, wenn ein kritischer Memory gespeichert wird:
[CODE BLOCK]
Webhook registrieren:
[CODE BLOCK]
Pattern 2: Zu externem System synchronisieren
Memories zu Notion, Obsidian oder jede andere externe KB synchronisieren:
[CODE BLOCK]
Pattern 3: CI/CD triggern
Ein Deployment auslösen, wenn ein „Release"-Memory gespeichert wird:
[CODE BLOCK]
Pattern 4: Agent bei Mensch-Nachricht aufwecken
Einen LLM-Agent-Lauf triggern, wenn ein Mensch eine Chat-Nachricht sendet:
[CODE BLOCK]
Pattern 5: Metriken aggregieren
Memory-Wachstum, Chat-Aktivität, Task-Abschluss tracken:
[CODE BLOCK]
Signatur-Verifikation
Verifiziere immer Webhook-Signaturen, um Spoofing zu verhindern:
[CODE BLOCK]
Retry-Logik
Synapse wiederholt fehlgeschlagene Webhooks mit exponentiellem Backoff. Dein
Handler sollte:
1. Schnell 200 zurückgeben — keine schwere Arbeit synchron erledigen
2. Arbeit in Queue stellen — ein Hintergrund-Job-System verwenden
3. Idempotent sein — dasselbe Event kann zweimal zugestellt werden
[CODE BLOCK]
Webhooks debuggen
Zustellhistorie prüfen
Webhook-Zustellungen werden protokolliert. Prüfe die letzten Zustellungen
deines Webhooks:
[CODE BLOCK]
Webhook manuell testen
[CODE BLOCK]
Häufige Probleme
| Issue | Fix |
|-------|-----|
| 4xx-Antworten | Prüfen, dass dein Handler 200 liefert |
| 5xx-Antworten | Server-Fehler — App-Logs prüfen |
| Timeout | 200 schnell zurückgeben, Arbeit async stellen |
| Duplikate | Handler idempotent machen |
| Signatur-Fehler | Secret auf Korrektheit prüfen |
Best Practices
> [!TIP]
> - Immer Signaturen verifizieren — niemals überspringen
> - Schnell 200 zurückgeben — Synapse nicht blockieren
> - Idempotent sein — Duplikat-Zustellungen behandeln
> - Spezifische Events verwenden — nicht
> - Zustellfehler überwachen — Alerting einrichten
Nächste Schritte
- Webhooks-API
- Cron & Scheduler
- Persistenter LLM-Agent
## KATEGORIE: KONZEPTE
Architektur und Konzepte von Synapse.
────────────────────────────────────────────────────────────
# Synapse-Architektur
SUMMARY: Wie Synapse aufgebaut ist — Fastify, PostgreSQL, FTS5, Embeddings, MCP-Server.
Synapse-Architektur
Synapse ist eine Multi-Tenant-Memory-API basierend auf Fastify, PostgreSQL mit
FTS5 und einem optionalen Embeddings-Dienst für semantische Suche.
Architektur-Überblick
[CODE BLOCK]
Kernkomponenten
1. Synapse-API (Fastify)
Der Haupt-HTTP-Server. Behandelt:
- REST-Endpunkte (, , etc.)
- Authentifizierung (Mind Key für Agenten, JWT für Menschen)
- Rate-Limiting (nur -Auth)
- Static-File-Auslieferung (Web-UI unter , etc.)
- Webhook-Dispatch
Gebaut mit Fastify 5 für Performance. Läuft in Produktion auf Port 12800.
2. PostgreSQL mit FTS5
Der primäre Datenspeicher. Verwendet PostgreSQL mit der FTS5-Erweiterung für
Volltextsuche.
Wichtige Tabellen:
| Tabelle | Zweck |
|---------|-------|
| | Nutzerkonten |
| | Mind-Scopes (jeder hat einen Mind Key) |
| | Memory-Einträge mit FTS5-Virtual-Table |
| | Aufgabenverwaltung |
| | Chat-Verlauf |
| | Persistente Scripts |
| | Webhook-Registrierungen |
| | Geplante Tasks |
| | Key-Value-Store |
| | Audit-Trail |
FTS5 ermöglicht sub-millisecond Volltextsuche über alle Memory-Inhalte.
Siehe FTS5-Suche für Details.
3. Embeddings-Dienst (optional)
Für semantische Suche generiert Synapse Vektor-Embeddings der Memory-Inhalte.
Diese werden neben den Memories gespeichert und für Ähnlichkeitssuche genutzt.
- Provider: konfigurierbar (OpenAI, lokales Modell etc.)
- Gespeichert als -Spalte in der -Tabelle
- Verwendet vom Endpunkt
- Siehe Semantische Suche
4. MCP-Server (separater Dienst)
Der Synapse-MCP-Server läuft als separater Prozess (Port 13100). Er:
- Stellt 79 Tools via Model Context Protocol bereit
- Unterstützt stdio-, HTTP/SSE- und WebSocket-Transporte
- Übersetzt MCP-Tool-Aufrufe in Synapse-API-Aufrufe
- Multi-Tenant: ein Mind Key pro Session
5. Browser-Proxy (separater Dienst)
Für Browser-Automatisierung läuft ein separater Playwright-basierter Dienst auf
Port 13000. Der MCP-Server kann diesen für -Tools aufrufen.
6. SSH-Proxy (separater Dienst)
Für SSH-basierte Remote-Befehle läuft ein separater Dienst auf Port 12900.
Multi-Tenancy-Modell
[CODE BLOCK]
Jeder Mind ist vollständig isoliert. Mind Keys gewähren Zugriff auf genau einen
Mind. JWTs gewähren Zugriff auf das Nutzerkonto (zur Verwaltung von Minds).
Siehe Multi-Tenancy für Details.
Request-Flow
Memory-Store-Request
[CODE BLOCK]
Memory-Search-Request
[CODE BLOCK]
Deployment
Synapse wird als Docker-Container deployt. Siehe :
[CODE BLOCK]
Performance-Eigenschaften
| Operation | Latenz | Throughput |
|-----------|--------|------------|
| Memory store | 5ms | 1000+ req/s |
| Memory recall | 20ms | 500 req/s |
| FTS5 search | 10ms | 800 req/s |
| Semantic search | 50ms | 200 req/s |
| Chat poll | 5ms | 2000 req/s |
Nächste Schritte
- Memory-Modell
- Multi-Tenancy
- FTS5-Suche
────────────────────────────────────────────────────────────
# FTS5-Volltextsuche
SUMMARY: Wie Synapse SQLite-FTS5 für sub-millisecond Volltext-Memory-Suche nutzt.
FTS5-Volltextsuche
Synapse verwendet FTS5 (Full-Text Search 5) für schnelle, flexible Memory-Suche.
Diese Seite erklärt, wie es funktioniert und wie du es effektiv nutzt.
Was ist FTS5?
FTS5 ist eine SQLite-Erweiterung (in PostgreSQL ebenfalls über Erweiterungen
verfügbar), die Volltextsuche bietet. Sie:
- Indiziert Textinhalte für schnelle Keyword-Suche
- Unterstützt boolesche Operatoren (AND, OR, NOT)
- Unterstützt Phrase-Matching mit Anführungszeichen
- Unterstützt Präfix-Matching mit
- Bewertet Ergebnisse nach Relevanz
Synapse nutzt FTS5, um alle Memory-Inhalte zu indizieren — das ermöglicht
sub-millisecond Suche über Tausende von Memories.
Wie Synapse FTS5 nutzt
Wenn du aufrufst:
1. Memory-Inhalt wird in der -Tabelle gespeichert
2. Inhalt wird zusätzlich in die FTS5-Virtual-Table eingefügt
3. FTS5 tokenisiert und indiziert den Inhalt automatisch
Wenn du aufrufst:
1. Synapse parst die Anfrage mit FTS5-Syntax
2. Führt ein gegen den FTS5-Index aus
3. Filtert nach (Tenant-Isolation)
4. Liefert bewertete Ergebnisse
Query-Syntax
Einfache Keyword-Suche
[CODE BLOCK]
Liefert Memories, die „docker" enthalten.
Mehrere Keywords (implizites AND)
[CODE BLOCK]
Liefert Memories, die SOWOHL „docker" ALS AUCH „swarm" enthalten.
Phrase-Matching
[CODE BLOCK]
Liefert Memories, die die exakte Phrase „docker swarm" enthalten.
Präfix-Matching
[CODE BLOCK]
Liefert Memories mit Wörtern, die mit „docker" beginnen (z. B. „dockers",
„dockerfile", „dockerize").
Boolesches OR
[CODE BLOCK]
Liefert Memories, die „docker" ODER „kubernetes" enthalten.
Boolesches NOT
[CODE BLOCK]
Liefert Memories, die „docker", aber NICHT „swarm" enthalten.
Gruppierung
[CODE BLOCK]
Liefert Memories mit „docker" oder „kubernetes", aber nicht „test".
Praktische Beispiele
Memories zu einem Projekt finden
[CODE BLOCK]
Exakte Phrase finden
[CODE BLOCK]
Test-Memories ausschließen
[CODE BLOCK]
Nach Technologie suchen
[CODE BLOCK]
Ranking
FTS5 bewertet Ergebnisse nach Relevanz mit dem BM25-Algorithmus. Faktoren:
- Term-Frequency (wie oft der Begriff vorkommt)
- Inverse Document Frequency (seltenere Begriffe ranken höher)
- Dokumentlänge (kürzere Docs mit dem Begriff ranken höher)
- Spalten-Gewichtung (title > content)
Ergebnisse werden in Reihenfolge des Rankings zurückgegeben (relevanteste zuerst).
Performance
| Operation | Latenz |
|-----------|--------|
| 100 Memories durchsuchen | < 5ms |
| 1.000 Memories durchsuchen | < 10ms |
| 10.000 Memories durchsuchen | < 25ms |
| 100.000 Memories durchsuchen | < 100ms |
FTS5 ist stark für lese-lastige Workloads optimiert.
Einschränkungen
Stemming
FTS5 macht standardmäßig kein Stemming. „running" und „run" sind unterschiedliche
Begriffe.
Workaround: Präfix-Matching verwenden:
Tippfehler-Toleranz
FTS5 unterstützt kein Fuzzy-Matching. Ein Tippfehler liefert keine Ergebnisse.
Workaround: Verwende semantische Suche () für
konzeptionelles Matching.
Stoppwörter
Häufige Wörter (the, a, an, is) werden indiziert, sind aber für die Suche
meist nicht nützlich. FTS5 behandelt das automatisch.
FTS5 vs semantische Suche
| Aspekt | FTS5 | Semantische Suche |
|--------|------|-------------------|
| Geschwindigkeit | Sub-millisecond | 50-100ms |
| Matching | Exakte Keywords | Konzeptionell |
| Tippfehler-Toleranz | Keine | Etwas |
| Stemming | Keins | Implizit |
| Benötigt Embeddings | Nein | Ja |
| Optimal für | Spezifische Begriffe | Konzepte |
Verwende FTS5, wenn du die Keywords kennst. Verwende semantische Suche, wenn du
„Memories über X" suchst und X anders beschrieben wird.
Best Practices
> [!TIP]
> - Verwende spezifische Begriffe — „docker swarm" schlägt „container orchestration"
> - Phrasen in Anführungszeichen — sichert Phrase-Match
> - Präfix für Variationen — erfasst „deploy", „deployment", „deploying"
> - Noise ausschließen — filtert Test-Memories heraus
> - Mit Tags kombinieren — schränkt Ergebnisse ein
Nächste Schritte
- Semantische Suche
- Memory-API
- Memory-Best-Practices
────────────────────────────────────────────────────────────
# Das Memory-Modell
SUMMARY: Wie Memories strukturiert sind — Kategorien, Keys, Tags, Prioritäten, Quellen, Verifikation.
Das Memory-Modell
Synapses Memory-Modell ist für LLM-Agenten gestaltet — strukturiert genug für
zuverlässiges Abrufen, flexibel genug für jede Domäne.
Anatomie eines Memories
[CODE BLOCK]
Felder
| Feld | Typ | Pflicht | Beschreibung |
|-------|------|---------|--------------|
| | string | auto | Eindeutige ID (memxxx) |
| | enum | ✅ | Eine von 8 Kategorien |
| | string | ✅ | Stabiler Bezeichner (für Updates genutzt) |
| | string | ✅ | Der Memory-Inhalt (beliebiger Text) |
| | string[] | – | Für Suche und Filterung |
| | enum | – | low, normal, high, critical (Standard: normal) |
| | enum | auto | user, agent (wer hat es gespeichert) |
| | bool | auto | Wurde das von einem Menschen verifiziert? |
| | float | – | 0.0 bis 1.0 (Standard: 1.0 für user, 0.7 für agent) |
| | timestamp | – | Wann dieser Memory vergessen werden soll |
| | string | auto | Welcher Mind ihn besitzt |
| | timestamp | auto | Erstmalig gespeichert |
| | timestamp | auto | Zuletzt geändert |
Kategorien
Acht Kategorien decken die gängigen LLM-Agent-Anwendungsfälle ab:
| Kategorie | Zweck | Beispielinhalt |
|-----------|-------|----------------|
| | Wer der Nutzer ist | „Nutzer ist Michael Schäfer, Software Engineer in Berlin" |
| | Nutzerpräferenzen | „Bevorzugt prägnante technische Antworten" |
| | Überprüfbare Fakten | „Büro in Berlin, Zeitzone Europe/Berlin" |
| | Projektstatus | „Synapse v1.5.0 deployed, arbeite an v1.6.0-Docs" |
| | Fähigkeiten des Nutzers | „Fortgeschrittenes Python, 10+ Jahre" |
| | Frühere Fehler | „NPM-Version nicht gebumpt — CI fehlgeschlagen" |
| | Session-Kontext | „Prüfe gerade PR #42" |
| | Sonstige Notizen | „Nächstes Sprint Redis fürs Caching testen" |
Keys: Stabile Bezeichner
Das Feld ist entscheidend — so aktualisierst du Memories, ohne Duplikate
zu erzeugen.
[CODE BLOCK]
Key-Regeln:
- Muss innerhalb (Kategorie, Mind) eindeutig sein
- Verwende
- Präfix mit Kategorie für Klarheit: ,
- Stabil halten — Keys nach Anlage nicht ändern
Tags: Für die Suche
Tags ermöglichen schnelle Filterung und Suche:
[CODE BLOCK]
Tag-Best-Practices:
- 2-5 Tags pro Memory (nicht übertrieben)
- Kleinschreibung für Konsistenz
- Projektnamen, Themen, Technologien verwenden
- Tags sind Case-insensitive
Prioritätsstufen
| Priorität | Wann verwenden | Recall-Verhalten |
|-----------|----------------|-------------------|
| | Identität, rechtlich, unumkehrbar | Immer oben im Recall |
| | Aktive Projekte, zentrale Präferenzen | Prominent im Recall |
| | Die meisten Memories (Standard) | Standard-Reihenfolge |
| | Flüchtig, nett zu wissen | Kann zusammengefasst werden |
sortiert nach Priorität (critical zuerst), dann nach Aktualität.
Quelle: User vs Agent
Memories werden mit markiert:
- — von einem Menschen gespeichert (via JWT oder Human-UI)
- — von einem LLM-Agenten gespeichert (via Mind Key)
Das beeinflusst:
- Verifikation: -Memories sind auto-verifiziert, -Memories nicht
- Confidence: defaults auf 1.0, auf 0.7
- Recall: markiert unverified Memories mit „(unverified)"
> [!NOTE]
> Behandle -Memories mit angemessenem Skepsis. Sie könnten gefolgert
> oder angenommen statt direkt vom Nutzer geäußert sein.
Verifikation
Das Flag zeigt an, dass ein Mensch den Memory bestätigt hat:
- -Memories: auto-verifiziert ()
- -Memories: standardmäßig unverified ()
Memories verifizieren via:
[CODE BLOCK]
> [!NOTE]
> Verifikation erfordert JWT (Human-Auth), nicht Mind Key (Agent-Auth). So wird
> sichergestellt, dass nur Menschen Memories als verifiziert markieren können.
Confidence
Das Feld (0.0 bis 1.0) zeigt, wie zuverlässig der Memory ist:
- 1.0 — direkt vom Nutzer geäußert
- 0.7 — vom Agenten gefolgert
- 0.5 — unsicher, needs Verifikation
- 0.0 — explizit angezweifelt
Beim Speichern Confidence setzen:
[CODE BLOCK]
Ablauf
Für zeitkritische Memories setzen:
[CODE BLOCK]
Abgelaufene Memories werden von nicht zurückgegeben (bleiben
aber in der DB). Verwende , um bald ablaufende
Memories zu sehen.
Memory-Lebenszyklus
[CODE BLOCK]
Recall-Verhalten
liefert eine Klartext-Zusammenfassung, optimiert für
LLM-Kontext:
[CODE BLOCK]
- Sortiert nach Priorität (critical → low), dann nach Aktualität
- Unverified Memories markiert mit
- Tags für Kontext enthalten
- Klartext (kein JSON-Parsing nötig)
Nächste Schritte
- Memory-API
- Memory-Best-Practices
- FTS5-Suche
────────────────────────────────────────────────────────────
# Multi-Tenancy & Isolation
SUMMARY: Wie Synapse Daten zwischen Nutzern und Minds isoliert — Sicherheitsgrenzen erklärt.
Multi-Tenancy & Isolation
Synapse ist Multi-Tenant: mehrere Nutzer, jeder mit mehreren Minds, vollständig
voneinander isoliert. Diese Seite erklärt das Isolationsmodell.
Tenant-Hierarchie
[CODE BLOCK]
Isolations-Level
Level 1: Nutzer-Isolation
Jedes Nutzerkonto ist isoliert. Alice kann nicht:
- Bobs Minds sehen
- Auf Bobs Memories zugreifen (auch nicht mit ihrem JWT)
- Bobs Konto-Infos auflisten
Erzwungen durch: -Spalte auf allen Tabellen, JWT enthält ,
alle Queries filtern nach .
Level 2: Mind-Isolation
Innerhalb eines Nutzers ist jeder Mind isoliert. Mind A kann nicht:
- Memories von Mind B sehen
- Auf Tasks, Chat, Scripts von Mind B zugreifen
Erzwungen durch: -Spalte auf allen Datentabellen, Mind Key enthält
, alle Queries filtern nach .
> [!CRITICAL]
> Die Mind-Key-Isolation ist die primäre Sicherheitsgrenze. Ein geleakter Mind
> Key gewährt vollen Zugriff auf die Daten dieses Minds — aber NUR auf dieses.
Authentifizierungs-Tokens
| Token | Scope | Worauf Zugriff |
|-------|-------|----------------|
| Mind Key | Einzelner Mind | Nur Daten dieses Minds |
| JWT | Nutzerkonto | Kontoverwaltung (Minds anlegen/auflisten/löschen) |
| Computer Token | Einzelner Rechner | Commands dieses Rechners |
Mind-übergreifender Zugriff
Innerhalb desselben Nutzers
Nutzer können über JWT auf alle ihre Minds zugreifen (z. B. listet
alle auf). Um Memory-Daten zu lesen/schreiben, benötigen sie aber den
spezifischen Mind Key.
Nutzerübergreifend
Nutzer können nicht aufeinander Daten zugreifen — AUSSER sie teilen explizit
einen Mind via Sharing-API:
[CODE BLOCK]
Nach dem Teilen kann Bob via JWT auf Mind A zugreifen (read-only bei
).
Sicherheitsgrenzen
[CODE BLOCK]
Häufige Multi-Tenancy-Patterns
Pattern 1: Ein Nutzer, ein Mind
Am häufigsten für einzelne LLM-Agent-Nutzer.
- 1 Nutzerkonto
- 1 Mind
- 1 Mind Key
- Alle Memories in einem Scope
Pattern 2: Ein Nutzer, mehrere Minds
Für Nutzer mit mehreren Kontexten (Arbeit, persönlich, Projekte).
- 1 Nutzerkonto
- N Minds (z. B. „work", „personal", „project-x")
- N Mind Keys
- Jede LLM-Session verwendet einen Mind Key
Pattern 3: Team-Shared-Mind
Für Teams, die an einem Projekt zusammenarbeiten.
- 1 Nutzer legt den Mind an (erhält Mind Key)
- Ersteller teilt mit Teammitgliedern via JWT
- Alle Teammitglieder greifen via JWT (oder geteiltem Mind Key) zu
> [!WARNING]
> Das Teilen eines Mind Keys gewährt vollen Lese-/Schreibzugriff. Für
> Team-Kollaboration bevorzuge die Sharing-API (JWT-basiert) gegenüber dem
> direkten Teilen von Mind Keys.
Pattern 4: SaaS-Provider
Für Apps, die Synapse als Memory-Layer einbetten.
- Jeder Kunde = 1 Nutzerkonto
- Jedes Kundenprojekt = 1 Mind
- App speichert Mind Keys pro Kunde/Projekt
- Volle Isolation zwischen Kunden
Isolations-Verifikation
Test: Mind Key kann nicht auf andere Minds zugreifen
[CODE BLOCK]
Test: JWT kann Memory-Daten nicht direkt lesen
[CODE BLOCK]
Best Practices
> [!TIP]
> - Ein Mind pro Projekt/Kontext — Isolation ist dein Freund
> - Mind Keys niemals teilen — verwende stattdessen die Sharing-API
> - Mind Keys rotieren, falls kompromittiert (Mind löschen, neu anlegen)
> - Geteilte Minds auditieren — regelmäßig prüfen
> - JWT für Human-UI verwenden — Mind Keys nie an Endnutzer geben
Nächste Schritte
- Authentifizierung
- Mind Key vs JWT
- Architektur
────────────────────────────────────────────────────────────
# 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
## KATEGORIE: LLM-KOCHBUCH
Rezepte und Muster für LLM-Agenten.
────────────────────────────────────────────────────────────
# Chat-Polling-Pattern
SUMMARY: Wie du zwischen Tool-Aufrufen nach Nachrichten pollst, ohne deinen Workflow zu blockieren.
Chat-Polling-Pattern
Das Chat-System ist asynchron — Menschen können Nachrichten hinterlassen,
während du arbeitest. Dieses Pattern zeigt, wie du nach Nachrichten pollst,
ohne deinen Workflow zu blockieren.
Das Pattern
[CODE BLOCK]
Poll zwischen Tool-Aufrufen, nicht in einer engen Schleife.
Warum zwischen Tool-Aufrufen pollen?
- Nicht blockieren — Polling in enger Schleife verschwendet API-Aufrufe
- Nachrichten nicht verpassen — zu seltenes Pollen bedeutet langsame Antworten
- Sweet Spot — poll alle 30-60 Sekunden oder nach jedem Tool-Aufruf
Implementierung
Basis-Polling
[CODE BLOCK]
Pattern 1: Nach jedem Tool-Aufruf pollen
[CODE BLOCK]
Pattern 2: Zeitbasiertes Polling
[CODE BLOCK]
Pattern 3: Event-gesteuert (mit Webhooks)
Für Echtzeit-Benachrichtigung registriere einen Webhook:
[CODE BLOCK]
Dann kann dein Webhook-Handler den Agenten aufwecken:
[CODE BLOCK]
Nachrichten-Handling-Patterns
Pattern: Bestätigen dann verarbeiten
[CODE BLOCK]
Pattern: Für Batch-Verarbeitung in Queue stellen
[CODE BLOCK]
Pattern: Prioritäts-Routing
[CODE BLOCK]
Polling-Frequenz
| Anwendungsfall | Frequenz |
|----------------|----------|
| Interaktiver Agent (Mensch wartet) | Alle 5-10 Sekunden |
| Hintergrund-Agent | Alle 30-60 Sekunden |
| Batch-Verarbeitung | Alle 5 Minuten |
| Webhook-getriggert | Nicht pollen — Webhooks verwenden |
> [!WARNING]
> Häufigeres Pollen als einmal pro 5 Sekunden verschwendet API-Aufrufe. Der
> -Endpunkt kehrt sofort zurück, wenn Nachrichten ausstehen —
> schnelleres Pollen bringt nichts.
Multi-Agent-Chat
Für Agent-zu-Agent-Kommunikation:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Zwischen Tool-Aufrufen pollen — nicht in enger Schleife
> - Sofort bestätigen — Mensch weiß, dass du die Nachricht erhalten hast
> - Asynchron verarbeiten — nicht auf lange Arbeit blockieren
> - Webhooks für Echtzeit verwenden — Polling hat Latenz
> - Nicht häufiger als einmal pro 5 Sekunden pollen — verschwendet API-Aufrufe
Häufige Probleme
Nachrichten verschwinden
- markiert Nachrichten automatisch als gelesen
- Wenn du sie nicht verarbeitest, sind sie weg
- Lösung: Nachrichten immer verarbeiten, bevor zurückgekehrt wird
Duplikate Antworten
- Wenn dein Handler crasht, könntest du zweimal antworten
- Lösung: Handler idempotent machen (prüfen, ob schon geantwortet)
Langsame Antworten
- Polling alle 60s bedeutet bis zu 60s Latenz
- Lösung: Alle 10-30s pollen oder Webhooks verwenden
Nächste Schritte
- Chat-API
- Session-Start-Pattern
- Error-Recovery
────────────────────────────────────────────────────────────
# Error-Recovery für Agenten
SUMMARY: Wie LLM-Agenten Fehler behandeln und sich davon erholen — retry, speichern, lernen.
Error-Recovery für Agenten
Fehler passieren. Netzwerke fallen aus, APIs liefern 500er, Mind Keys laufen ab.
Dieser Guide zeigt, wie LLM-Agenten Fehler graceful behandeln und daraus lernen.
Fehlerbehandlungs-Prinzipien
1. Retry mit Backoff — transiente Fehler lösen sich oft von selbst
2. Den Fehler speichern — aus Mustern lernen
3. Graceful degradieren — nicht die ganze Session crashen
4. Den Menschen benachrichtigen — bei Fehlern, die du nicht beheben kannst
HTTP-Fehlerbehandlung
Retry mit exponentiellem Backoff
[CODE BLOCK]
Auth-Fehlerbehandlung
[CODE BLOCK]
Fehler als Memories speichern
Wenn Fehler auftreten, speichere sie, damit zukünftige Sessions lernen können:
[CODE BLOCK]
Häufige Fehler-Szenarien
Szenario 1: Mind Key ungültig
[CODE BLOCK]
Szenario 2: Netzwerkfehler
[CODE BLOCK]
Szenario 3: Rate Limit
[CODE BLOCK]
Szenario 4: Serverfehler (5xx)
[CODE BLOCK]
Szenario 5: Tool-Aufruf schlägt fehl
[CODE BLOCK]
Pattern: Circuit Breaker
Bei wiederholten Fehlern temporär aufhören zu versuchen:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Transiente Fehler immer retryen — Netzwerke fallen aus, Server hicksen
> - Client-Fehler (4xx) nicht retryen — sie beheben sich nicht von selbst
> - Fehler als Memories speichern — aus Mustern lernen
> - Menschen bei kritischen Fehlern benachrichtigen — sie müssen es wissen
> - Graceful degradieren — partielle Arbeit ist besser als Crash
> - Circuit Breaker verwenden — keinen fehlerhaften Dienst hämmern
Nächste Schritte
- Errors-API-Referenz
- Session-Start-Pattern
- Self-Healing-Tests
────────────────────────────────────────────────────────────
# Memory-Tagging-Strategie
SUMMARY: Wie du Memories für effektive Suche und Filterung taggst — das Tagging-System, das skaliert.
Memory-Tagging-Strategie
Tags sind das Geheimnis skalierbaren Memory-Retrievals. Dieser Guide zeigt, wie
du Memories taggst, damit die richtigen zur richtigen Zeit zurückkommen.
Warum Tags wichtig sind
Ohne Tags hast du flache Volltextsuche. Mit Tags hast du strukturierte
Navigation:
[CODE BLOCK]
Tags ermöglichen:
- Schnelle Filterung —
- Scoped Suche —
- Gruppierung — alle „mistake"-Memories für ein Projekt finden
- Querverweise — Memories, die Tags teilen, sind verwandt
Tagging-Schema
Projekt-Tags
Verwende Projektnamen als Tags:
[CODE BLOCK]
Technologie-Tags
Verwende Technologienamen:
[CODE BLOCK]
Themen-Tags
Verwende Themen-Kategorien:
[CODE BLOCK]
Status-Tags
Verwende Status-Indikatoren:
[CODE BLOCK]
Typ-Tags
Verwende Typ-Indikatoren:
[CODE BLOCK]
Tagging-Regeln
Regel 1: 2-5 Tags pro Memory
Zu wenige Tags = schlechte Auffindbarkeit. Zu viele = Noise.
[CODE BLOCK]
Regel 2: Kleinschreibung, Bindestriche
[CODE BLOCK]
Regel 3: Konsistentes Vokabular verwenden
Etabliere ein Tagging-Vokabular und bleib dabei:
[CODE BLOCK]
Regel 4: Mit Such-Intention taggen
Frag dich: „Wie werde ich nach diesem Memory suchen?"
[CODE BLOCK]
Patterns
Pattern 1: Projekt + Thema
[CODE BLOCK]
Suche: (alle Synapse-Projekt-Memories)
Suche: (Deployment-Memories in Synapse)
Pattern 2: Typ + Domäne
[CODE BLOCK]
Suche: (alle Fehler)
Suche: (Deployment-Fehler)
Pattern 3: Hierarchisch
Für Sub-Projekte innerhalb eines Projekts:
[CODE BLOCK]
Suche: (alle Synapse)
Suche: (nur Docs-Subprojekt)
Pattern 4: Status-Tracking
[CODE BLOCK]
Häufige Anwendungsfälle
Alle Entscheidungen über ein Projekt finden
[CODE BLOCK]
Alle Fehler in einer Domäne finden
[CODE BLOCK]
Aktive Arbeit finden
[CODE BLOCK]
Memories über eine Technologie finden
[CODE BLOCK]
Tag-Wartung
Periodische Überprüfung
[CODE BLOCK]
Tags mergen
Bei inkonsistenten Tags ( und ) mergen:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Vokabular früh etablieren — konsistente Tags ab Tag 1
> - Mit Such-Intention taggen — wie wirst du das später finden?
> - 2-5 Tags sind der Sweet Spot — zu wenige oder zu viele ist schlecht
> - Kleinschreibung + Bindestriche — nicht
> - Periodisch überprüfen — Duplikate mergen, ungenutzte entfernen
Nächste Schritte
- Memory-Best-Practices
- FTS5-Suche
- Task-getriebener Workflow
────────────────────────────────────────────────────────────
# Session-Start-Pattern
SUMMARY: Die kanonische Session-Start-Sequenz, die jeder LLM-Agent befolgen sollte.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
Session-Start-Pattern
Jede LLM-Agent-Session sollte dieser kanonischen Startup-Sequenz folgen. Das
Überspringen von Schritten führt zu verlorenem Kontext, verpassten Nachrichten
und vergessenen Tasks.
Das Pattern
[CODE BLOCK]
Implementierung
Schritt 1: Alle Memories abrufen
> [!CRITICAL]
> Das ist der wichtigste Aufruf. Ohne ihn hast du keine Erinnerung an vergangene
> Sessions.
[CODE BLOCK]
Liefert eine Klartext-Zusammenfassung aller Memories, sortiert nach Priorität.
Schritt 2: Auf ungelesene Chat-Nachrichten pollen
[CODE BLOCK]
Liefert ungelesene Nachrichten vom Menschen. Markiert sie automatisch als
gelesen.
Schritt 3: In-Progress-Tasks prüfen
[CODE BLOCK]
Liefert Tasks, an denen du in der letzten Session gearbeitet hast.
Schritt 4: Kontext aufbauen
Kombiniere die drei Antworten in deinem System-Prompt:
[CODE BLOCK]
Schritt 5: Pending-Items verarbeiten
[CODE BLOCK]
Vollständiges Beispiel
[CODE BLOCK]
Häufige Fehler
> [!WARNING]
> - Recall überspringen — du startest ohne Kontext, wiederholst vergangene Fehler
> - Chat-Poll vergessen — Nachrichten des Menschen bleiben unbeantwortet
> - Aktive Tasks ignorieren — Arbeit wird mitten in der Ausführung vergessen
> - Nichts speichern — Session produziert keinen persistenten Wert
Variationen
Minimales Pattern (Low-Context-LLMs)
Für LLMs mit kleinem Kontext-Fenster überspringe den vollständigen Recall:
[CODE BLOCK]
Dann bei Bedarf nach spezifischen Themen suchen:
[CODE BLOCK]
Aggressives Pattern (langlaufende Agenten)
Für Agenten, die stundenlang laufen, füge periodischen Re-Recall hinzu:
[CODE BLOCK]
Nächste Schritte
- Memory-Tagging-Strategie
- Task-getriebener Workflow
- Chat-Polling-Pattern
────────────────────────────────────────────────────────────
# Task-getriebener Workflow
SUMMARY: Synapse-Tasks nutzen, um mehrschrittige LLM-Workflows zu treiben, die über Sessions hinweg bestehen.
Task-getriebener Workflow
Tasks sind nicht nur Todos — sie sind das Rückgrat persistenter LLM-Workflows.
Indem du für mehrschrittige Arbeit Tasks anlegst, sicherst du Kontinuität über
Sessions und stellst Audit-Trails für getane Arbeit bereit.
Warum Task-getrieben?
Ohne Tasks:
- LLM startet jede Session unsicher, was zu tun ist
- Mehrschrittige Arbeit wird mitten in der Ausführung vergessen
- Kein Record darüber, was getan wurde
Mit Tasks:
- LLM nimmt in-progress Tasks sofort wieder auf
- Mehrschrittige Arbeit überdauert Sessions
- Eingebauter Audit-Trail aller Arbeit
Das Pattern
[CODE BLOCK]
Implementierung
Schritt 1: Einen Task für mehrschrittige Arbeit anlegen
[CODE BLOCK]
Schritt 2: Fortschritt in Task-Beschreibung tracken
[CODE BLOCK]
Schritt 3: Über Sessions hinweg fortsetzen
[CODE BLOCK]
Schritt 4: Abschließen und archivieren
[CODE BLOCK]
Vollständiges Beispiel: Deploy-Workflow
[CODE BLOCK]
Task-Hierarchie
Für komplexe Arbeit verwende Parent-Child-Task-Beziehungen:
[CODE BLOCK]
Nach Sub-Tasks suchen:
[CODE BLOCK]
Status-Workflow
[CODE BLOCK]
Pending
Task angelegt, aber nicht begonnen. Für geplante Arbeit verwenden.
In Progress
Wird gerade bearbeitet. Beschreibung mit Fortschritt aktualisieren.
Done
Erfolgreich abgeschlossen. Beschreibung sollte Zusammenfassung enthalten.
Cancelled
Abgebrochen. Beschreibung sollte den Grund enthalten.
Best Practices
> [!TIP]
> - Tasks für mehrschrittige Arbeit anlegen — einschrittige Arbeit braucht keinen Task
> - Beschreibung mit Fortschritt aktualisieren — ermöglicht Wiederaufnahme
> - Hohe Priorität für aktive Arbeit — taucht im Recall auf
> - Tasks abschließen, wenn erledigt — nicht inprogress lassen
> - Abschluss-Zusammenfassungen als Memories speichern — langfristige Referenz
Häufige Patterns
Pattern: Bug-Fix-Workflow
[CODE BLOCK]
Pattern: Recherche-Workflow
[CODE BLOCK]
Nächste Schritte
- Session-Start-Pattern
- Chat-Polling-Pattern
- Error-Recovery
## KATEGORIE: FAQ
Häufige Fragen und Probleme.
────────────────────────────────────────────────────────────
# API-FAQ
SUMMARY: Häufige API-Fragen — Auth, Rate Limits, Fehlerbehandlung, Endpunkt-Discovery.
API-FAQ
Häufige Fragen zur Synapse-API.
Wie authentifiziere ich mich?
Zwei Methoden:
1. Mind Key (für Daten-Endpunkte):
2. JWT (für Konto-Endpunkte):
Oder via Query-Parameter (60 req/min Limit):
Siehe Authentifizierung.
Was ist der Unterschied zwischen Mind Key und JWT?
- Mind Key: Tenant-scoped, läuft nie ab, für Memory-/Chat-/Tasks-Daten
- JWT: Nutzer-scoped, 7-Tage-Ablauf, für Konto-/Mind-Verwaltung
Siehe Mind Key vs JWT.
Warum erhalte ich 401 Unauthorized?
Häufige Ursachen:
1. Fehlender -Header
2. Ungültiger Mind Key (prüfen, ob er mit beginnt)
3. JWT verwendet, wo Mind Key erforderlich ist (oder umgekehrt)
4. Mind Key wurde widerrufen
Lösung: Token überprüfen. Siehe Authentifizierung.
Warum erhalte ich 404 Not Found?
Du hast einen falschen Endpunkt-Pfad verwendet. Synapse hat nur die Pfade, die in
gelistet sind.
Lösung: Rufe auf, um alle gültigen Pfade zu sehen. Nicht
raten.
Warum erhalte ich 429 Too Many Requests?
Du verwendest -Query-Parameter-Auth, die auf 60/min begrenzt ist.
Lösung: Wechsle zum -Header (kein Rate Limit).
Siehe Rate Limits.
Wie liste ich alle Endpunkte auf?
[CODE BLOCK]
Wie finde ich den richtigen Endpunkt?
1. Prüfe für die maschinenlesbare Liste
2. Prüfe für die vollständige API-Doku
3. Durchsuche für das Dokumentationssystem
4. Verwende für die OpenAPI-3.0-Spec
Kann ich GET statt POST verwenden?
Einige POST-Endpunkte haben GET-Äquivalente für reine URL-Tools:
- ↔
- ↔
- ↔
Prüfe für verfügbare GET-Varianten.
Wie behandle ich Fehler?
Alle Fehler liefern JSON:
[CODE BLOCK]
Siehe Errors & Fehlerbehandlung.
Wie hoch ist das Request-Body-Limit?
10 MB. Für größere Payloads (z. B. Datei-Uploads) verwende die Multipart-
Endpunkte.
Unterstützt die API CORS?
Ja. Alle Endpunkte liefern:
[CODE BLOCK]
Gibt es ein SDK?
Ja:
- Node.js:
- MCP:
Siehe API-Übersicht für Details.
Wie paginiere ich?
Verwende und :
[CODE BLOCK]
Standard-Limit: 100. Max: 500.
Kann ich Memories nach Kategorie oder Tag filtern?
Ja:
[CODE BLOCK]
Wie durchsuche ich Memories?
Zwei Wege:
1. FTS5-Keyword-Suche:
2. Semantische Suche:
Siehe FTS5-Suche und Semantische Suche.
Wie aktualisiere ich einen Memory?
POST mit derselben + — der bestehende Memory wird
aktualisiert, nicht dupliziert.
[CODE BLOCK]
Wie lösche ich einen Memory?
[CODE BLOCK]
Kann ich Bulk-löschen?
Ja:
[CODE BLOCK]
Nächste Schritte
- API-Übersicht
- Errors & Fehlerbehandlung
- Authentifizierung
────────────────────────────────────────────────────────────
# Allgemeines FAQ
SUMMARY: Häufige Fragen zu Synapse — was es ist, wie es funktioniert, für wen es ist.
Allgemeines FAQ
Häufige Fragen zu Synapse.
Was ist Synapse?
Synapse ist eine persistente Memory-API für LLM-Agenten. Sie gibt deinem
KI-Assistenten ein dauerhaftes, abfragbares Gehirn, das über Sessions
hinweg bestehen bleibt. Anstatt alles zu vergessen, wenn der Chat schließt,
speichert und ruft das LLM Memories via einer einfachen HTTP-API ab.
Mehr erfahren: Was ist Synapse?
Für wen ist Synapse?
- LLM-Agent-Entwickler, die persistenten Status brauchen
- Power-User, die lokale LLMs mit eigenen Agenten betreiben
- Teams, die KI-Assistenten mit geteiltem Memory bauen
- Automatisierungs-Engineers, die LLM-Aufrufe über Sessions verketten
Ist Synapse kostenlos?
Synapse wird unter gehostet und ist für
persönliche Nutzung kostenlos. Für Self-Hosting siehe das
Repo.
Wie unterscheidet sich Synapse von ChatGPT Memory?
| Feature | ChatGPT Memory | Synapse |
|---------|----------------|---------|
| Speicher | OpenAI-Server | Dein Server |
| API-Zugriff | Nein | Ja (REST + MCP) |
| Multi-Tenant | Nein | Ja (Minds) |
| Eigene Kategorien | Nein | Ja (8 Kategorien) |
| Volltextsuche | Eingeschränkt | FTS5 + semantisch |
| Self-Hosting | Nein | Ja |
Welche LLMs funktionieren mit Synapse?
Jedes LLM, das HTTP-Aufrufe machen oder MCP nutzen kann:
- Claude (Anthropic) — via MCP oder direkte API
- GPT-4 / GPT-3.5 (OpenAI) — via Function Calling + API
- Gemini (Google) — via Function Calling + API
- Llama / Mistral (lokal) — via Custom-Integration
- Jedes LLM via den Synapse-MCP-Server
Muss ich Synapse selbst hosten?
Nein. Die gehostete Version unter ist für
öffentliche Nutzung verfügbar. Self-Hosting ist optional (für Privacy,
Customization oder Air-Gapped-Umgebungen).
Wie viele Daten kann ich speichern?
Auf der gehosteten Version gibt es keine harten Limits. Typische Nutzung:
- 100-1000 Memories pro Mind
- 1-10 KB pro Memory (Content-Feld)
- Gesamt: 10 MB pro Mind
Für größeres Scale: selbst hosten.
Sind meine Daten privat?
Ja. Jeder Mind ist isoliert (siehe Multi-Tenancy).
Andere Nutzer können deine Daten nicht sehen. Der Hosting-Provider
(Schäfer Services) hat Zugriff, sieht aber keine Nutzerdaten.
Für maximale Privacy: selbst hosten.
Kann ich meine Daten exportieren?
Ja. Verwende , um alle Memories als JSON zu
exportieren. Siehe Backup & Restore.
Was passiert, wenn ich meinen Mind Key verliere?
Mind Keys werden nur einmal bei der Erstellung angezeigt. Falls verloren:
1. Mit E-Mail/Passwort einloggen, um JWT zu erhalten
2. Neuen Mind via anlegen
3. Neuen Mind Key speichern
4. (Optional) Alten Mind via löschen
Du kannst Memories aus einem Mind mit verlorenem Key nicht wiederherstellen.
Können mehrere LLM-Agenten einen Mind teilen?
Ja. Alle Agenten mit demselben Mind Key teilen die Daten dieses Minds. Für
koordinierte Multi-Agent-Arbeit siehe
Multi-Agent-Coordination.
Funktioniert Synapse offline?
Nein, Synapse erfordert eine Internetverbindung zum Server (gehostet oder
selbstgehostet). Für Offline-LLMs: Synapse lokal betreiben.
Wie schnell ist die Memory-Suche?
- FTS5-Keyword-Suche: < 10ms für 1000 Memories
- Semantische Suche: 50-100ms für 1000 Memories
- Full Recall: < 50ms für 1000 Memories
Siehe FTS5-Suche für Details.
Kann ich Synapse ohne LLM verwenden?
Ja. Synapse ist eine generische Memory-API. Du kannst sie aus jeder Anwendung
nutzen, die von persistentem, durchsuchbarem Key-Value-Speicher mit Kategorien
und Tags profitiert.
Nächste Schritte
- Was ist Synapse?
- Quick Start
- API-FAQ
────────────────────────────────────────────────────────────
# MCP-FAQ
SUMMARY: Häufige Fragen zur MCP-Integration — Tools, Transports, Troubleshooting.
MCP-FAQ
Häufige Fragen zum Synapse-MCP-Server.
Was ist MCP?
MCP (Model Context Protocol) ist ein offener Standard von Anthropic für
LLM-Tool-Integration. Statt API-Docs in Prompts einzufügen, registrierst du
Tools bei einem MCP-Server, und das LLM ruft sie als native Funktionen auf.
Siehe Was ist MCP?.
Wie viele Tools stellt Synapse MCP bereit?
79 Tools in 12 Kategorien: Memory, Chat, Scheduler, Tasks, Scripts,
Computers, Push, User, Utility, Visualization, Sharing, Webhooks, Browser.
Siehe Was ist MCP? für die vollständige Liste.
Welche MCP-Clients werden unterstützt?
- Claude Desktop (macOS, Windows)
- Claude Code (Terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Jeder MCP-kompatible Client
Siehe Claude-Desktop-Setup für Config-Beispiele.
Welche Transports werden unterstützt?
1. stdio (lokal, empfohlen für Desktop)
2. HTTP/SSE (Remote, Multi-Tenant)
3. WebSocket (mobil, hohes Volumen)
Wie konfiguriere ich Claude Desktop?
Editiere :
[CODE BLOCK]
Siehe Claude-Desktop-Setup.
Warum erscheinen Tools nicht in Claude Desktop?
1. Claude Desktop vollständig neu starten (Cmd+Q auf macOS)
2. Prüfen, ob die Config-Datei valides JSON ist
3. Node.js 18+ installiert prüfen
4. MCP-Logs prüfen:
Siehe MCP-Troubleshooting.
Wie verwende ich einen anderen Mind?
Ändere in deiner MCP-Config und starte den Client neu.
Für mehrere Minds: mehrere MCP-Server-Instanzen mit unterschiedlichen Mind
Keys betreiben.
Kann ich einschränken, welche Tools exponiert werden?
Ja, verwende Tool-Profile:
- : 8 Composite-Tools (500 Token)
- : 25 Tools (2.500 Token)
- : 119 Tools (8.250 Token, Standard)
Setze via -Env-Var oder -Header.
Wie debugge ich MCP-Probleme?
1. MCP-Server manuell ausführen:
2. Client-Logs prüfen (variiert je Client)
3. Mind Key verifizieren:
4. Synapse-Health prüfen:
Siehe MCP-Troubleshooting.
Ist der MCP-Server kostenlos?
Ja. Das npm-Paket ist Open Source. Der gehostete MCP-Server
unter ist für öffentliche Nutzung kostenlos.
Kann ich den MCP-Server selbst hosten?
Ja:
[CODE BLOCK]
Wie unterscheidet sich MCP von direkten API-Aufrufen?
| Aspekt | Direkte API | MCP |
|--------|-------------|-----|
| LLM muss wissen | URLs, Header, Auth | Nur Tool-Namen |
| Auth-Handling | Manuell | Automatisch (Env-Var) |
| Tool-Discovery | /endpoints lesen | Automatisch via MCP-Protokoll |
| Fehlerbehandlung | Manuell | Standardisiert |
| Optimal für | Custom-Integrationen | LLM-Agenten |
Kann ich einen eigenen MCP-Client bauen?
Ja. Verwende das offizielle MCP-SDK:
- TypeScript:
- Python:
Siehe Custom-MCP-Client.
Wie melde ich MCP-Bugs?
Issue öffnen:
Angaben:
- MCP-Server-Version
- Client-Name und -Version
- Betriebssystem
- Relevante Logs
- Reproduktionsschritte
Nächste Schritte
- Was ist MCP?
- Claude-Desktop-Setup
- MCP-Troubleshooting
────────────────────────────────────────────────────────────
# Troubleshooting-FAQ
SUMMARY: Lösungen für häufige Synapse-Probleme — Auth, Netzwerk, Daten, Deployment.
Troubleshooting-FAQ
Lösungen für häufige Synapse-Probleme.
Ich kann mich nicht einloggen
Symptome
- liefert 401
- „Invalid email or password"
Lösungen
1. E-Mail verifizieren — Case-sensitive
2. Passwort prüfen — mindestens 6 Zeichen
3. Zuerst registrieren, falls du kein Konto hast:
4. Passwort zurücksetzen (falls SMTP konfiguriert) via Web-UI
Ich habe meinen Mind Key verloren
Symptome
- Kann nicht auf Memories zugreifen
- Mind Key wurde gelöscht/verloren
Lösungen
Mind Keys können nicht wiederhergestellt werden. Du musst:
1. Einloggen, um JWT zu erhalten:
2. Minds auflisten: (mit JWT)
3. Neuen Mind anlegen:
4. Neuen Mind Key speichern
5. (Optional) Alten Mind löschen:
Daten im alten Mind sind verloren, außer du findest den Mind Key.
API-Aufrufe liefern 401
Symptome
- Alle API-Aufrufe liefern 401 Unauthorized
- „Mind Key fehlt oder ungültig"
Lösungen
1. Header-Format verifizieren:
2. Prüfen, dass Mind Key mit beginnt (nicht , das ist JWT)
3. Direkt testen:
[CODE BLOCK]
4. Mind Key könnte widerrufen sein — neuen Mind anlegen
Siehe Authentifizierung.
API-Aufrufe liefern 404
Symptome
- 404 Not Found
- „Route not found"
Lösungen
> [!CRITICAL]
> Rate keine Endpunkt-Pfade. Nur Pfade in existieren.
1. Gültige Endpunkte prüfen:
2. URL exakt vergleichen — Case-sensitive, keine Trailing-Slashes
3. HTTP-Methode prüfen — vs sind unterschiedlich
API-Aufrufe liefern 429
Symptome
- 429 Too Many Requests
- „Rate limit exceeded"
Lösungen
1. Auf Header-Auth wechseln (kein Rate Limit):
[CODE BLOCK]
2. Sekunden warten, falls du verwenden musst
Siehe Rate Limits.
Memory-Suche liefert keine Ergebnisse
Symptome
- liefert leer
- weiß, dass Memories existieren
Lösungen
1. Verifizieren, dass Memories existieren:
2. Such-Syntax prüfen — FTS5 hat spezifische Syntax
3. Einfachere Query versuchen — statt
4. Semantische Suche für konzeptionelle Queries:
Siehe FTS5-Suche.
Memories werden nicht persistiert
Symptome
- POST /memory liefert Success
- GET /memory/recall zeigt sie nicht
Lösungen
1. Selben Mind Key verifizieren — verschiedene Keys = verschiedene Minds
2. Response prüfen — POST liefert
3. GET /memory versuchen (JSON-Liste) statt /memory/recall (Text)
4. Filter prüfen — oder könnten sie verbergen
Tools erscheinen nicht in Claude Desktop
Symptome
- Claude Desktop zeigt 0 Tools
- Kein 🔌-Icon
Lösungen
1. Claude Desktop vollständig neu starten (Cmd+Q)
2. Config-Datei prüfen — valides JSON
3. Node.js 18+ installiert prüfen
4. MCP manuell ausführen:
5. Logs prüfen:
Siehe MCP-Troubleshooting.
Synapse ist offline
Symptome
- synapse.schaefer.zone nicht erreichbar
- curl läuft in Timeout
Lösungen
1. Internet prüfen — andere Seite versuchen
2. Synapse-Health prüfen:
3. Warten — könnte temporärer Ausfall oder Deployment sein
4. Status-Seite prüfen (falls verfügbar)
Für Self-Hosted: Docker-Container-Status und Datenbankverbindung prüfen.
Datenbankfehler
Symptome
- 500 Internal Server Error
- „Database connection failed"
Lösungen
Für Self-Hosted:
1. PostgreSQL läuft prüfen:
2. DATABASEURL in Env prüfen
3. Migrationen prüfen:
4. Speicherplatz prüfen:
Für gehostet: an Support melden.
Webhook feuert nicht
Symptome
- Webhook registriert, aber keine Callbacks erhalten
- Kein POST an deine URL
Lösungen
1. URL erreichbar verifizieren:
2. Events-Filter prüfen — matched alle Memory-Events
3. Webhook testen:
4. Webhook aktiviert prüfen:
5. SSL verifizieren — Synapse erfordert gültiges HTTPS für Webhook-URLs
Siehe Webhooks-API.
Cron-Job läuft nicht
Symptome
- Cron-Job angelegt, aber er feuert nicht
- aktualisiert nicht
Lösungen
1. Schedule-Syntax prüfen — muss gültiges 5-Feld-Cron ODER Integer-Sekunden sein
2. Endpunkt erlaubt verifizieren — muss http(s) sein, keine privaten IPs
3. Job aktiviert prüfen:
4. Auf nächste geplante Zeit warten — Cron ist nicht instant
Siehe Cron & Scheduler.
Brauchst du weitere Hilfe?
1. Bestehende Doku prüfen:
2. Doku durchsuchen:
3. Issue öffnen:
4. Kontakt: siehe -Seite
Nächste Schritte
- Errors & Fehlerbehandlung
- API-FAQ
- MCP-Troubleshooting