Architettura di Synapse

Synapse è una API di memoria multi-tenant costruita su Fastify, PostgreSQL con FTS5 e un servizio embedding opzionale per la ricerca semantica.

Architettura di alto livello

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

Componenti principali

1. Synapse API (Fastify)

Il server HTTP principale. Gestisce:

• Endpoint REST (/memory, /chat, /mind/tasks, ecc.)
• Autenticazione (Mind Key per agenti, JWT per umani)
• Rate limiting (solo auth ?key=)
• Servizio di file statici (UI web su /human, /docs, ecc.)
• Dispatch dei webhook

Costruito con Fastify 5 per le prestazioni. In produzione gira sulla porta 12800.

2. PostgreSQL con FTS5

Lo store dati principale. Usa PostgreSQL con l'estensione FTS5 per la ricerca full-text.

Tabelle chiave:

Tabella	Scopo
users	Account utente
minds	Scope delle menti (ciascuno ha una Mind Key)
memories	Record delle memorie con tabella virtuale FTS5
tasks	Gestione attività
chat_messages	Cronologia chat
scripts	Script persistenti
webhooks	Registrazioni webhook
cron_jobs	Attività pianificate
variables	Key-value store
audit_log	Traccia di audit

FTS5 abilita la ricerca full-text sub-millisecond su tutti i contenuti delle memorie. Veda Ricerca FTS5 per i dettagli.

3. Servizio Embedding (opzionale)

Per la ricerca semantica, Synapse genera embedding vettoriali del contenuto delle memorie. Vengono salvati insieme alle memorie e usati per la ricerca di similarità.

• Provider: configurabile (OpenAI, modello locale, ecc.)
• Salvato come colonna vector nella tabella memories
• Usato dall'endpoint /memory/semantic-search
• Veda Ricerca semantica

4. Server MCP (servizio separato)

Il server MCP di Synapse gira come processo separato (porta 13100). Esso:

• Espone 79 strumenti tramite Model Context Protocol
• Supporta transport stdio, HTTP/SSE e WebSocket
• Traduce le chiamate MCP in chiamate API Synapse
• Multi-tenant: una Mind Key per sessione

5. Browser Proxy (servizio separato)

Per l'automazione del browser, un servizio separato basato su Playwright gira sulla porta 13000. Il server MCP può chiamarlo per gli strumenti browser_*.

6. SSH Proxy (servizio separato)

Per comandi remoti via SSH, un servizio separato gira sulla porta 12900.

Modello multi-tenant

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

Ogni mente è completamente isolata. Le Mind Key concedono accesso a esattamente una mente. I JWT concedono accesso all'account utente (per gestire le menti).

Veda Multi-tenancy per i dettagli.

Flusso delle richieste

Richiesta di memorizzazione

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

Richiesta di ricerca

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 viene deployato come container Docker. Veda 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=...

Caratteristiche di prestazione

Operazione	Latenza	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

Prossimi passi

• Modello di memoria
• Multi-tenancy
• Ricerca FTS5