{"title":"Synapse-Architektur","slug":"architecture","category":"concepts","summary":"Wie Synapse aufgebaut ist — Fastify, PostgreSQL, FTS5, Embeddings, MCP-Server.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":375,"read_minutes":2,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Synapse-Architektur\n\nSynapse ist eine Multi-Tenant-Memory-API basierend auf Fastify, PostgreSQL mit\nFTS5 und einem optionalen Embeddings-Dienst für semantische Suche.\n\n## Architektur-Überblick\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ Clients │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│ LLM Agents │ Web Browsers│ MCP Clients │ Webhooks │\n│ (curl/SDK) │ (humans) │ (Claude/etc) │ (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n │ │ │ │\n └──────────────┴──────────────┴──────────────┘\n │\n ▼\n ┌───────────────────────────────┐\n │ Synapse API (Fastify) │\n │ port 12800 │\n │ - REST endpoints │\n │ - Auth (Mind Key / JWT) │\n │ - Rate limiting │\n │ - Static file serving │\n └───────────────┬───────────────┘\n │\n ┌───────────────┼───────────────┐\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Embeddings │ │ MCP Server │\n │ + FTS5 │ │ Service │ │ (separate) │\n │ │ │ (optional) │ │ port 13100 │\n │ - memories │ │ │ │ │\n │ - tasks │ │ - generate │ │ - 79 tools │\n │ - chat │ │ embeddings│ │ - stdio/SSE │\n │ - scripts │ │ │ │ - WebSocket │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n## Kernkomponenten\n\n### 1. Synapse-API (Fastify)\n\nDer Haupt-HTTP-Server. Behandelt:\n\n- REST-Endpunkte (`/memory`, `/chat`, `/mind/tasks` etc.)\n- Authentifizierung (Mind Key für Agenten, JWT für Menschen)\n- Rate-Limiting (nur `?key=`-Auth)\n- Static-File-Auslieferung (Web-UI unter `/human`, `/docs` etc.)\n- Webhook-Dispatch\n\nGebaut mit **Fastify 5** für Performance. Läuft in Produktion auf Port 12800.\n\n### 2. PostgreSQL mit FTS5\n\nDer primäre Datenspeicher. Verwendet PostgreSQL mit der FTS5-Erweiterung für\nVolltextsuche.\n\n**Wichtige Tabellen:**\n\n| Tabelle | Zweck |\n|---------|-------|\n| `users` | Nutzerkonten |\n| `minds` | Mind-Scopes (jeder hat einen Mind Key) |\n| `memories` | Memory-Einträge mit FTS5-Virtual-Table |\n| `tasks` | Aufgabenverwaltung |\n| `chat_messages` | Chat-Verlauf |\n| `scripts` | Persistente Scripts |\n| `webhooks` | Webhook-Registrierungen |\n| `cron_jobs` | Geplante Tasks |\n| `variables` | Key-Value-Store |\n| `audit_log` | Audit-Trail |\n\n**FTS5** ermöglicht sub-millisecond Volltextsuche über alle Memory-Inhalte.\nSiehe [FTS5-Suche](/docs/concepts/fts5-search) für Details.\n\n### 3. Embeddings-Dienst (optional)\n\nFür semantische Suche generiert Synapse Vektor-Embeddings der Memory-Inhalte.\nDiese werden neben den Memories gespeichert und für Ähnlichkeitssuche genutzt.\n\n- Provider: konfigurierbar (OpenAI, lokales Modell etc.)\n- Gespeichert als `vector`-Spalte in der `memories`-Tabelle\n- Verwendet vom Endpunkt `/memory/semantic-search`\n- Siehe [Semantische Suche](/docs/concepts/semantic-search)\n\n### 4. MCP-Server (separater Dienst)\n\nDer Synapse-MCP-Server läuft als separater Prozess (Port 13100). Er:\n\n- Stellt 79 Tools via Model Context Protocol bereit\n- Unterstützt stdio-, HTTP/SSE- und WebSocket-Transporte\n- Übersetzt MCP-Tool-Aufrufe in Synapse-API-Aufrufe\n- Multi-Tenant: ein Mind Key pro Session\n\n### 5. Browser-Proxy (separater Dienst)\n\nFür Browser-Automatisierung läuft ein separater Playwright-basierter Dienst auf\nPort 13000. Der MCP-Server kann diesen für `browser_*`-Tools aufrufen.\n\n### 6. SSH-Proxy (separater Dienst)\n\nFür SSH-basierte Remote-Befehle läuft ein separater Dienst auf Port 12900.\n\n## Multi-Tenancy-Modell\n\n```\nUser Account (email + password)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── Memories\n │ ├── Tasks\n │ ├── Chat\n │ └── Scripts\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (isolated from Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nJeder Mind ist vollständig isoliert. Mind Keys gewähren Zugriff auf genau einen\nMind. JWTs gewähren Zugriff auf das Nutzerkonto (zur Verwaltung von Minds).\n\nSiehe [Multi-Tenancy](/docs/concepts/multi-tenancy) für Details.\n\n## Request-Flow\n\n### Memory-Store-Request\n\n```\n1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n a. Validate JSON body (zod schema)\n b. Insert into memories table\n c. Update FTS5 index\n d. (Async) Generate embedding if embeddings enabled\n e. Trigger webhooks for memory.store event\n5. Return { id, status: \"stored\" }\n```\n\n### Memory-Search-Request\n\n```\n1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n a. Parse query (FTS5 syntax)\n b. Execute FTS5 MATCH against memories table\n c. Filter by mind_id (tenant isolation)\n d. Rank by relevance\n e. Return results\n```\n\n## Deployment\n\nSynapse wird als Docker-Container deployt. Siehe `docker-compose.yml`:\n\n```yaml\nservices:\n synapse:\n image: registry.gitlab.com/schaefer-services/synapse:latest\n ports:\n - \"12800:12800\"\n environment:\n - DATABASE_URL=postgres://...\n - JWT_SECRET=...\n - SYNAPSE_HOST=0.0.0.0\n - SYNAPSE_PORT=12800\n depends_on:\n - postgres\n \n postgres:\n image: postgres:16\n volumes:\n - pgdata:/var/lib/postgresql/data\n environment:\n - POSTGRES_DB=synapse\n - POSTGRES_PASSWORD=...\n```\n\n## Performance-Eigenschaften\n\n| Operation | Latenz | Throughput |\n|-----------|--------|------------|\n| Memory store | ~5ms | 1000+ req/s |\n| Memory recall | ~20ms | 500 req/s |\n| FTS5 search | ~10ms | 800 req/s |\n| Semantic search | ~50ms | 200 req/s |\n| Chat poll | ~5ms | 2000 req/s |\n\n## Nächste Schritte\n\n- [Memory-Modell](/docs/concepts/memory-model)\n- [Multi-Tenancy](/docs/concepts/multi-tenancy)\n- [FTS5-Suche](/docs/concepts/fts5-search)\n","content_html":"

Synapse-Architektur

\n

Synapse ist eine Multi-Tenant-Memory-API basierend auf Fastify, PostgreSQL mit\nFTS5 und einem optionalen Embeddings-Dienst für semantische Suche.

\n

Architektur-Überblick

\n
┌──────────────────────────────────────────────────────────┐\n│                       Clients                            │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │\n│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n       │              │              │              │\n       └──────────────┴──────────────┴──────────────┘\n                              │\n                              ▼\n              ┌───────────────────────────────┐\n              │    Synapse API (Fastify)      │\n              │    port 12800                 │\n              │    - REST endpoints           │\n              │    - Auth (Mind Key / JWT)    │\n              │    - Rate limiting            │\n              │    - Static file serving      │\n              └───────────────┬───────────────┘\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │\n       │ + FTS5      │ │ Service     │ │ (separate)  │\n       │             │ │ (optional)  │ │ port 13100  │\n       │ - memories  │ │             │ │             │\n       │ - tasks     │ │ - generate  │ │ - 79 tools  │\n       │ - chat      │ │   embeddings│ │ - stdio/SSE │\n       │ - scripts   │ │             │ │ - WebSocket │\n       └─────────────┘ └─────────────┘ └─────────────┘

Kernkomponenten

\n

1. Synapse-API (Fastify)

\n

Der Haupt-HTTP-Server. Behandelt:

\n\n

Gebaut mit Fastify 5 für Performance. Läuft in Produktion auf Port 12800.

\n

2. PostgreSQL mit FTS5

\n

Der primäre Datenspeicher. Verwendet PostgreSQL mit der FTS5-Erweiterung für\nVolltextsuche.

\n

Wichtige Tabellen:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TabelleZweck
usersNutzerkonten
mindsMind-Scopes (jeder hat einen Mind Key)
memoriesMemory-Einträge mit FTS5-Virtual-Table
tasksAufgabenverwaltung
chat_messagesChat-Verlauf
scriptsPersistente Scripts
webhooksWebhook-Registrierungen
cron_jobsGeplante Tasks
variablesKey-Value-Store
audit_logAudit-Trail
\n

FTS5 ermöglicht sub-millisecond Volltextsuche über alle Memory-Inhalte.\nSiehe FTS5-Suche für Details.

\n

3. Embeddings-Dienst (optional)

\n

Für semantische Suche generiert Synapse Vektor-Embeddings der Memory-Inhalte.\nDiese werden neben den Memories gespeichert und für Ähnlichkeitssuche genutzt.

\n\n

4. MCP-Server (separater Dienst)

\n

Der Synapse-MCP-Server läuft als separater Prozess (Port 13100). Er:

\n\n

5. Browser-Proxy (separater Dienst)

\n

Für Browser-Automatisierung läuft ein separater Playwright-basierter Dienst auf\nPort 13000. Der MCP-Server kann diesen für browser_*-Tools aufrufen.

\n

6. SSH-Proxy (separater Dienst)

\n

Für SSH-basierte Remote-Befehle läuft ein separater Dienst auf Port 12900.

\n

Multi-Tenancy-Modell

\n
User Account (email + password)\n  │\n  ├── Mind 1 (Mind Key 1)\n  │   ├── Memories\n  │   ├── Tasks\n  │   ├── Chat\n  │   └── Scripts\n  │\n  ├── Mind 2 (Mind Key 2)\n  │   └── ... (isolated from Mind 1)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

Jeder Mind ist vollständig isoliert. Mind Keys gewähren Zugriff auf genau einen\nMind. JWTs gewähren Zugriff auf das Nutzerkonto (zur Verwaltung von Minds).

\n

Siehe Multi-Tenancy für Details.

\n

Request-Flow

\n

Memory-Store-Request

\n
1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n   a. Validate JSON body (zod schema)\n   b. Insert into memories table\n   c. Update FTS5 index\n   d. (Async) Generate embedding if embeddings enabled\n   e. Trigger webhooks for memory.store event\n5. Return { id, status: "stored" }

Memory-Search-Request

\n
1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n   a. Parse query (FTS5 syntax)\n   b. Execute FTS5 MATCH against memories table\n   c. Filter by mind_id (tenant isolation)\n   d. Rank by relevance\n   e. Return results

Deployment

\n

Synapse wird als Docker-Container deployt. Siehe docker-compose.yml:

\n
services:\n  synapse:\n    image: registry.gitlab.com/schaefer-services/synapse:latest\n    ports:\n      - "12800:12800"\n    environment:\n      - DATABASE_URL=postgres://...\n      - JWT_SECRET=...\n      - SYNAPSE_HOST=0.0.0.0\n      - SYNAPSE_PORT=12800\n    depends_on:\n      - postgres\n  \n  postgres:\n    image: postgres:16\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n    environment:\n      - POSTGRES_DB=synapse\n      - POSTGRES_PASSWORD=...

Performance-Eigenschaften

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationLatenzThroughput
Memory store~5ms1000+ req/s
Memory recall~20ms500 req/s
FTS5 search~10ms800 req/s
Semantic search~50ms200 req/s
Chat poll~5ms2000 req/s
\n

Nächste Schritte

\n\n","urls":{"html":"/docs/concepts/architecture","text":"/docs/concepts/architecture?format=text","json":"/docs/concepts/architecture?format=json","llm":"/docs/concepts/architecture?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}