Arquitectura de Synapse

Synapse es una API de memoria multi-tenant construida sobre Fastify, PostgreSQL con FTS5, y un servicio opcional de embeddings para búsqueda semántica.

Arquitectura de alto nivel

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

Componentes principales

1. Synapse API (Fastify)

El servidor HTTP principal. Gestiona:

• Endpoints REST (/memory, /chat, /mind/tasks, etc.)
• Autenticación (Mind Key para agentes, JWT para humanos)
• Límites de frecuencia (solo auth con ?key=)
• Servido de archivos estáticos (interfaz web en /human, /docs, etc.)
• Dispatch de webhooks

Construido con Fastify 5 para rendimiento. Se ejecuta en el puerto 12800 en producción.

2. PostgreSQL con FTS5

El almacén de datos principal. Usa PostgreSQL con la extensión FTS5 para búsqueda de texto completo.

Tablas principales:

Tabla	Propósito
users	Cuentas de usuario
minds	Ámbitos de mind (cada uno tiene un Mind Key)
memories	Registros de memoria con tabla virtual FTS5
tasks	Gestión de tareas
chat_messages	Historial de chat
scripts	Scripts persistentes
webhooks	Registros de webhooks
cron_jobs	Tareas programadas
variables	Almacén clave-valor
audit_log	Pista de auditoría

FTS5 permite búsqueda de texto completo sub-milisegundo sobre todo el contenido de memoria. Consulte Búsqueda FTS5 para más detalles.

3. Servicio de Embeddings (opcional)

Para búsqueda semántica, Synapse genera embeddings vectoriales del contenido de memoria. Se almacenan junto a las memorias y se usan para búsqueda por similitud.

• Proveedor: configurable (OpenAI, modelo local, etc.)
• Se almacenan como columna vector en la tabla memories
• Los usa el endpoint /memory/semantic-search
• Consulte Búsqueda semántica

4. Servidor MCP (servicio separado)

El servidor MCP de Synapse se ejecuta como un proceso aparte (puerto 13100). Esta persona:

• Expone 79 herramientas vía Model Context Protocol
• Admite transportes stdio, HTTP/SSE y WebSocket
• Traduce llamadas a herramientas MCP en llamadas a la API de Synapse
• Multi-tenant: un Mind Key por sesión

5. Browser Proxy (servicio separado)

Para automatización de navegador, un servicio separado basado en Playwright se ejecuta en el puerto 13000. El servidor MCP puede invocarlo para las herramientas browser_*.

6. SSH Proxy (servicio separado)

Para comandos remotos basados en SSH, un servicio separado se ejecuta en el puerto 12900.

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

Cada mind está completamente aislado. Los Mind Keys otorgan acceso a exactamente un mind. Los JWT otorgan acceso a la cuenta de usuario (para gestionar minds).

Consulte Multi-Tenancy para más detalles.

Flujo de solicitudes

Solicitud de almacenamiento de memoria

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

Solicitud de búsqueda de memoria

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

Despliegue

Synapse se despliega como un contenedor Docker. Consulte 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=...

Características de rendimiento

Operación	Latencia	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

Próximos pasos

• Modelo de memoria
• Multi-Tenancy
• Búsqueda FTS5