Skip to main content

Synapse-architectuur

intermediate 🤖 LLM-vriendelijk 2 min · 396 woorden Bijgewerkt: 2026-06-27 Nederlands

Hoe Synapse is opgebouwd — Fastify, PostgreSQL, FTS5, embeddings, MCP-server.

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

Synapse-architectuur

Synapse is een multi-tenant memory-API gebouwd op Fastify, PostgreSQL met FTS5, en een optionele embeddings-service voor semantisch zoeken.

Architectuur op hoog niveau

┌──────────────────────────────────────────────────────────┐
│                       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 │
       └─────────────┘ └─────────────┘ └─────────────┘

Kerncomponenten

1. Synapse API (Fastify)

De hoofd-HTTP-server. Verwerkt:

  • REST-eindpunten (/memory, /chat, /mind/tasks, enz.)
  • Authenticatie (Mind Key voor agents, JWT voor mensen)
  • Ratelimiting (alleen ?key=-auth)
  • Statische bestandsweergave (web-UI op /human, /docs, enz.)
  • Webhook-dispatch

Gebouwd met Fastify 5 voor prestaties. Draait op poort 12800 in productie.

2. PostgreSQL met FTS5

De primaire datastore. Gebruikt PostgreSQL met de FTS5-extensie voor volledige-tekst zoekopdrachten.

Belangrijke tabellen:

Tabel Doel
users Gebruikersaccounts
minds Mind-scopes (elk heeft een Mind Key)
memories Memory-records met FTS5 virtuele tabel
tasks Taakbeheer
chat_messages Chatgeschiedenis
scripts Permanente scripts
webhooks Webhook-registraties
cron_jobs Geplande taken
variables Key-value-opslag
audit_log Audittrail

FTS5 maakt sub-milliseconde volledige-tekst zoekopdrachten mogelijk over alle memory-inhoud. Zie FTS5-zoekopdracht voor details.

3. Embeddings-service (optioneel)

Voor semantisch zoeken genereert Synapse vector-embeddings van memory-inhoud. Deze worden naast herinneringen opgeslagen en gebruikt voor similariteitszoekopdrachten.

  • Provider: configureerbaar (OpenAI, lokaal model, enz.)
  • Opgeslagen als vector-kolom in de memories-tabel
  • Gebruikt door het /memory/semantic-search-eindpunt
  • Zie Semantisch zoeken

4. MCP-server (aparte service)

De Synapse MCP-server draait als een apart proces (poort 13100). Deze:

  • Stelt 79 tools beschikbaar via Model Context Protocol
  • Ondersteunt stdio-, HTTP/SSE- en WebSocket-transporten
  • Vertaalt MCP-tool-aanroepen naar Synapse API-aanroepen
  • Multi-tenant: één Mind Key per sessie

5. Browser Proxy (aparte service)

Voor browserautomatisering draait een aparte Playwright-gebaseerde service op poort 13000. De MCP-server kan deze aanroepen voor browser_*-tools.

6. SSH Proxy (aparte service)

Voor SSH-gebaseerde commando's op afstand draait een aparte service op poort 12900.

Multi-tenant-model

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)
      └── ...

Elke mind is volledig geïsoleerd. Mind Keys verlenen toegang tot precies één mind. JWT's verlenen toegang tot het gebruikersaccount (voor het beheren van minds).

Zie Multi-tenancy voor details.

Verzoek-flow

Memory-opslagverzoek

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-zoekverzoek

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 wordt uitgerold als Docker-container. Zie 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=...

Prestatiekenmerken

Bewerking Latentie Doorvoer
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

Volgende stappen

← Terug naar Concepten