Arquitetura do Synapse

O Synapse é uma API de memória multi-tenant construída sobre Fastify, PostgreSQL com FTS5 e um serviço opcional de embeddings para busca semântica.

Arquitetura de alto nível

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

1. Synapse API (Fastify)

O servidor HTTP principal. Cuida de:

• Endpoints REST (/memory, /chat, /mind/tasks, etc.)
• Autenticação (Mind Key para agentes, JWT para humanos)
• Limites de taxa (apenas auth ?key=)
• Servimento de arquivos estáticos (interface web em /human, /docs, etc.)
• Dispatch de webhooks

Construído com Fastify 5 para desempenho. Roda na porta 12800 em produção.

2. PostgreSQL com FTS5

O armazenamento principal de dados. Usa PostgreSQL com a extensão FTS5 para busca em texto completo.

Tabelas principais:

Tabela	Finalidade
users	Contas de usuário
minds	Escopos de mind (cada um tem uma Mind Key)
memories	Registros de memória com tabela virtual FTS5
tasks	Gerenciamento de tarefas
chat_messages	Histórico de chat
scripts	Scripts persistentes
webhooks	Registros de webhook
cron_jobs	Tarefas agendadas
variables	Armazenamento key-value
audit_log	Trilha de auditoria

FTS5 permite busca em texto completo sub-milissegundo em todo o conteúdo das memórias. Consulte Busca FTS5 para detalhes.

3. Serviço de Embeddings (opcional)

Para busca semântica, o Synapse gera embeddings vetoriais do conteúdo das memórias. Eles são armazenados junto com as memórias e usados para busca por similaridade.

• Provedor: configurável (OpenAI, modelo local, etc.)
• Armazenado como coluna vector na tabela memories
• Usado pelo endpoint /memory/semantic-search
• Consulte Busca semântica

4. Servidor MCP (serviço separado)

O servidor MCP do Synapse roda como um processo separado (porta 13100). Ele:

• Expõe 79 ferramentas via Model Context Protocol
• Suporta transportes stdio, HTTP/SSE e WebSocket
• Traduz chamadas de ferramentas MCP em chamadas da API do Synapse
• Multi-tenant: uma Mind Key por sessão

5. Browser Proxy (serviço separado)

Para automação de navegador, um serviço separado baseado em Playwright roda na porta 13000. O servidor MCP pode chamá-lo para ferramentas browser_*.

6. SSH Proxy (serviço separado)

Para comandos remotos via SSH, um serviço separado roda na porta 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 é totalmente isolado. Mind Keys concedem acesso a exatamente um mind. JWTs concedem acesso à conta do usuário (para gerenciar minds).

Consulte Multi-tenancy para detalhes.

Fluxo de requisição

Requisição de armazenamento de memória

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

Requisição de busca de memória

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

Deploy

O Synapse é implantado como um container 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 desempenho

Operação	Latência	Throughput
Armazenar memória	~5ms	1000+ req/s
Recall de memória	~20ms	500 req/s
Busca FTS5	~10ms	800 req/s
Busca semântica	~50ms	200 req/s
Poll de chat	~5ms	2000 req/s

Próximos passos

• Modelo de memória
• Multi-tenancy
• Busca FTS5