Skip to main content

Synapse-Architektur

intermediate 🤖 LLM-freundlich 2 Min · 375 Wörter Aktualisiert: 2026-06-27 Deutsch

Wie Synapse aufgebaut ist — Fastify, PostgreSQL, FTS5, Embeddings, MCP-Server.

Diesen Artikel lesen als: 📄 Plain Text ⚡ JSON 🤖 LLM-Format
Sprache: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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

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

Kernkomponenten

1. Synapse-API (Fastify)

Der Haupt-HTTP-Server. Behandelt:

  • REST-Endpunkte (/memory, /chat, /mind/tasks etc.)
  • Authentifizierung (Mind Key für Agenten, JWT für Menschen)
  • Rate-Limiting (nur ?key=-Auth)
  • Static-File-Auslieferung (Web-UI unter /human, /docs 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
users Nutzerkonten
minds Mind-Scopes (jeder hat einen Mind Key)
memories Memory-Einträge mit FTS5-Virtual-Table
tasks Aufgabenverwaltung
chat_messages Chat-Verlauf
scripts Persistente Scripts
webhooks Webhook-Registrierungen
cron_jobs Geplante Tasks
variables Key-Value-Store
audit_log 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 vector-Spalte in der memories-Tabelle
  • Verwendet vom Endpunkt /memory/semantic-search
  • 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 browser_*-Tools aufrufen.

6. SSH-Proxy (separater Dienst)

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

Multi-Tenancy-Modell

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

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

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

Memory-Search-Request

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

Deployment

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

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

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

← Zurück zu Konzepte