Architecture de Synapse

Synapse est une API de mémoire multi-tenant construite sur Fastify, PostgreSQL avec FTS5, et un service d'embeddings optionnel pour la recherche sémantique.

Architecture globale

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

Composants principaux

1. API Synapse (Fastify)

Le serveur HTTP principal. Gère :

• Endpoints REST (/memory, /chat, /mind/tasks, etc.)
• Authentification (Mind Key pour les agents, JWT pour les humains)
• Limitation de débit (auth ?key= uniquement)
• Service de fichiers statiques (interface web sur /human, /docs, etc.)
• Dispatch des webhooks

Construit avec Fastify 5 pour la performance. Fonctionne sur le port 12800 en production.

2. PostgreSQL avec FTS5

Le magasin de données principal. Utilise PostgreSQL avec l'extension FTS5 pour la recherche en texte intégral.

Tables principales :

Table	Rôle
users	Comptes utilisateurs
minds	Scopes de mind (chacun a une Mind Key)
memories	Enregistrements de mémoire avec table virtuelle FTS5
tasks	Gestion des tâches
chat_messages	Historique de chat
scripts	Scripts persistants
webhooks	Enregistrements de webhooks
cron_jobs	Tâches planifiées
variables	Magasin clé-valeur
audit_log	Piste d'audit

FTS5 permet la recherche en texte intégral sub-milliseconde sur tout le contenu de mémoire. Voir Recherche FTS5 pour plus de détails.

3. Service d'embeddings (optionnel)

Pour la recherche sémantique, Synapse génère des embeddings vectoriels du contenu des mémoires. Ils sont stockés à côté des mémoires et utilisés pour la recherche de similarité.

• Fournisseur : configurable (OpenAI, modèle local, etc.)
• Stocké comme colonne vector dans la table memories
• Utilisé par l'endpoint /memory/semantic-search
• Voir Recherche sémantique

4. Serveur MCP (service séparé)

Le serveur MCP Synapse s'exécute comme un processus distinct (port 13100). Il :

• Expose 79 outils via Model Context Protocol
• Prend en charge les transports stdio, HTTP/SSE et WebSocket
• Traduit les appels d'outils MCP en appels d'API Synapse
• Multi-tenant : une Mind Key par session

5. Proxy navigateur (service séparé)

Pour l'automatisation de navigateur, un service distinct basé sur Playwright s'exécute sur le port 13000. Le serveur MCP peut l'appeler pour les outils browser_*.

6. Proxy SSH (service séparé)

Pour les commandes distantes basées sur SSH, un service distinct s'exécute sur le port 12900.

Modèle multi-tenant

Compte utilisateur (email + mot de passe)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── Memories
  │   ├── Tasks
  │   ├── Chat
  │   └── Scripts
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (isolé du Mind 1)
  │
  └── Mind 3 (Mind Key 3)
      └── ...

Chaque mind est entièrement isolé. Les Mind Keys accordent l'accès à un seul mind. Les JWT accordent l'accès au compte utilisateur (pour gérer les minds).

Voir Multi-tenancy pour plus de détails.

Flux de requêtes

Requête de stockage mémoire

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

Requête de recherche mémoire

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

Déploiement

Synapse est déployé comme conteneur Docker. Voir 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=...

Caractéristiques de performance

Opération	Latence	Débit
Stockage mémoire	~5 ms	1000+ req/s
Rappel mémoire	~20 ms	500 req/s
Recherche FTS5	~10 ms	800 req/s
Recherche sémantique	~50 ms	200 req/s
Polling chat	~5 ms	2000 req/s

Prochaines étapes

• Modèle de mémoire
• Multi-tenancy
• Recherche FTS5