Synapse Architecture

Synapse is a multi-tenant memory API built on Fastify, PostgreSQL with FTS5, and an optional embeddings service for semantic search.

High-Level Architecture

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

Core Components

1. Synapse API (Fastify)

The main HTTP server. Handles:

• REST endpoints (/memory, /chat, /mind/tasks, etc.)
• Authentication (Mind Key for agents, JWT for humans)
• Rate limiting (?key= auth only)
• Static file serving (web UI at /human, /docs, etc.)
• Webhook dispatch

Built with Fastify 5 for performance. Runs on port 12800 in production.

2. PostgreSQL with FTS5

The primary data store. Uses PostgreSQL with the FTS5 extension for full-text search.

Key tables:

Table	Purpose
users	User accounts
minds	Mind scopes (each has a Mind Key)
memories	Memory records with FTS5 virtual table
tasks	Task management
chat_messages	Chat history
scripts	Persistent scripts
webhooks	Webhook registrations
cron_jobs	Scheduled tasks
variables	Key-value store
audit_log	Audit trail

FTS5 enables sub-millisecond full-text search across all memory content. See FTS5 Search for details.

3. Embeddings Service (Optional)

For semantic search, Synapse generates vector embeddings of memory content. These are stored alongside memories and used for similarity search.

• Provider: configurable (OpenAI, local model, etc.)
• Stored as vector column in memories table
• Used by /memory/semantic-search endpoint
• See Semantic Search

4. MCP Server (Separate Service)

The Synapse MCP server runs as a separate process (port 13100). It:

• Exposes 79 tools via Model Context Protocol
• Supports stdio, HTTP/SSE, and WebSocket transports
• Translates MCP tool calls into Synapse API calls
• Multi-tenant: one Mind Key per session

5. Browser Proxy (Separate Service)

For browser automation, a separate Playwright-based service runs on port 13000. The MCP server can call this for browser_* tools.

6. SSH Proxy (Separate Service)

For SSH-based remote commands, a separate service runs on port 12900.

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

Each mind is fully isolated. Mind Keys grant access to exactly one mind. JWTs grant access to the user account (for managing minds).

See Multi-Tenancy for details.

Request Flow

Memory Store Request

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 Search Request

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 is deployed as a Docker container. See 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=...

Performance Characteristics

Operation	Latency	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

Next Steps

• Memory Model
• Multi-Tenancy
• FTS5 Search