{"title":"Synapse Architecture","slug":"architecture","category":"concepts","summary":"How Synapse is built — Fastify, PostgreSQL, FTS5, embeddings, MCP server.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":435,"read_minutes":2,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Synapse Architecture\n\nSynapse is a multi-tenant memory API built on Fastify, PostgreSQL with FTS5,\nand an optional embeddings service for semantic search.\n\n## High-Level Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ Clients │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│ LLM Agents │ Web Browsers│ MCP Clients │ Webhooks │\n│ (curl/SDK) │ (humans) │ (Claude/etc) │ (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n │ │ │ │\n └──────────────┴──────────────┴──────────────┘\n │\n ▼\n ┌───────────────────────────────┐\n │ Synapse API (Fastify) │\n │ port 12800 │\n │ - REST endpoints │\n │ - Auth (Mind Key / JWT) │\n │ - Rate limiting │\n │ - Static file serving │\n └───────────────┬───────────────┘\n │\n ┌───────────────┼───────────────┐\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Embeddings │ │ MCP Server │\n │ + FTS5 │ │ Service │ │ (separate) │\n │ │ │ (optional) │ │ port 13100 │\n │ - memories │ │ │ │ │\n │ - tasks │ │ - generate │ │ - 79 tools │\n │ - chat │ │ embeddings│ │ - stdio/SSE │\n │ - scripts │ │ │ │ - WebSocket │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n## Core Components\n\n### 1. Synapse API (Fastify)\n\nThe main HTTP server. Handles:\n\n- REST endpoints (`/memory`, `/chat`, `/mind/tasks`, etc.)\n- Authentication (Mind Key for agents, JWT for humans)\n- Rate limiting (`?key=` auth only)\n- Static file serving (web UI at `/human`, `/docs`, etc.)\n- Webhook dispatch\n\nBuilt with **Fastify 5** for performance. Runs on port 12800 in production.\n\n### 2. PostgreSQL with FTS5\n\nThe primary data store. Uses PostgreSQL with the FTS5 extension for\nfull-text search.\n\n**Key tables:**\n\n| Table | Purpose |\n|-------|---------|\n| `users` | User accounts |\n| `minds` | Mind scopes (each has a Mind Key) |\n| `memories` | Memory records with FTS5 virtual table |\n| `tasks` | Task management |\n| `chat_messages` | Chat history |\n| `scripts` | Persistent scripts |\n| `webhooks` | Webhook registrations |\n| `cron_jobs` | Scheduled tasks |\n| `variables` | Key-value store |\n| `audit_log` | Audit trail |\n\n**FTS5** enables sub-millisecond full-text search across all memory content.\nSee [FTS5 Search](/docs/concepts/fts5-search) for details.\n\n### 3. Embeddings Service (Optional)\n\nFor semantic search, Synapse generates vector embeddings of memory content.\nThese are stored alongside memories and used for similarity search.\n\n- Provider: configurable (OpenAI, local model, etc.)\n- Stored as `vector` column in `memories` table\n- Used by `/memory/semantic-search` endpoint\n- See [Semantic Search](/docs/concepts/semantic-search)\n\n### 4. MCP Server (Separate Service)\n\nThe Synapse MCP server runs as a separate process (port 13100). It:\n\n- Exposes 79 tools via Model Context Protocol\n- Supports stdio, HTTP/SSE, and WebSocket transports\n- Translates MCP tool calls into Synapse API calls\n- Multi-tenant: one Mind Key per session\n\n### 5. Browser Proxy (Separate Service)\n\nFor browser automation, a separate Playwright-based service runs on port 13000.\nThe MCP server can call this for `browser_*` tools.\n\n### 6. SSH Proxy (Separate Service)\n\nFor SSH-based remote commands, a separate service runs on port 12900.\n\n## Multi-Tenancy Model\n\n```\nUser Account (email + password)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── Memories\n │ ├── Tasks\n │ ├── Chat\n │ └── Scripts\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (isolated from Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nEach mind is fully isolated. Mind Keys grant access to exactly one mind.\nJWTs grant access to the user account (for managing minds).\n\nSee [Multi-Tenancy](/docs/concepts/multi-tenancy) for details.\n\n## Request Flow\n\n### Memory Store Request\n\n```\n1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n a. Validate JSON body (zod schema)\n b. Insert into memories table\n c. Update FTS5 index\n d. (Async) Generate embedding if embeddings enabled\n e. Trigger webhooks for memory.store event\n5. Return { id, status: \"stored\" }\n```\n\n### Memory Search Request\n\n```\n1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n a. Parse query (FTS5 syntax)\n b. Execute FTS5 MATCH against memories table\n c. Filter by mind_id (tenant isolation)\n d. Rank by relevance\n e. Return results\n```\n\n## Deployment\n\nSynapse is deployed as a Docker container. See `docker-compose.yml`:\n\n```yaml\nservices:\n synapse:\n image: registry.gitlab.com/schaefer-services/synapse:latest\n ports:\n - \"12800:12800\"\n environment:\n - DATABASE_URL=postgres://...\n - JWT_SECRET=...\n - SYNAPSE_HOST=0.0.0.0\n - SYNAPSE_PORT=12800\n depends_on:\n - postgres\n \n postgres:\n image: postgres:16\n volumes:\n - pgdata:/var/lib/postgresql/data\n environment:\n - POSTGRES_DB=synapse\n - POSTGRES_PASSWORD=...\n```\n\n## Performance Characteristics\n\n| Operation | Latency | Throughput |\n|-----------|---------|------------|\n| Memory store | ~5ms | 1000+ req/s |\n| Memory recall | ~20ms | 500 req/s |\n| FTS5 search | ~10ms | 800 req/s |\n| Semantic search | ~50ms | 200 req/s |\n| Chat poll | ~5ms | 2000 req/s |\n\n## Next Steps\n\n- [Memory Model](/docs/concepts/memory-model)\n- [Multi-Tenancy](/docs/concepts/multi-tenancy)\n- [FTS5 Search](/docs/concepts/fts5-search)\n","content_html":"

Synapse Architecture

\n

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

\n

High-Level Architecture

\n
┌──────────────────────────────────────────────────────────┐\n│                       Clients                            │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │\n│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n       │              │              │              │\n       └──────────────┴──────────────┴──────────────┘\n                              │\n                              ▼\n              ┌───────────────────────────────┐\n              │    Synapse API (Fastify)      │\n              │    port 12800                 │\n              │    - REST endpoints           │\n              │    - Auth (Mind Key / JWT)    │\n              │    - Rate limiting            │\n              │    - Static file serving      │\n              └───────────────┬───────────────┘\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │\n       │ + FTS5      │ │ Service     │ │ (separate)  │\n       │             │ │ (optional)  │ │ port 13100  │\n       │ - memories  │ │             │ │             │\n       │ - tasks     │ │ - generate  │ │ - 79 tools  │\n       │ - chat      │ │   embeddings│ │ - stdio/SSE │\n       │ - scripts   │ │             │ │ - WebSocket │\n       └─────────────┘ └─────────────┘ └─────────────┘

Core Components

\n

1. Synapse API (Fastify)

\n

The main HTTP server. Handles:

\n\n

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

\n

2. PostgreSQL with FTS5

\n

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

\n

Key tables:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TablePurpose
usersUser accounts
mindsMind scopes (each has a Mind Key)
memoriesMemory records with FTS5 virtual table
tasksTask management
chat_messagesChat history
scriptsPersistent scripts
webhooksWebhook registrations
cron_jobsScheduled tasks
variablesKey-value store
audit_logAudit trail
\n

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

\n

3. Embeddings Service (Optional)

\n

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

\n\n

4. MCP Server (Separate Service)

\n

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

\n\n

5. Browser Proxy (Separate Service)

\n

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

\n

6. SSH Proxy (Separate Service)

\n

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

\n

Multi-Tenancy Model

\n
User Account (email + password)\n  │\n  ├── Mind 1 (Mind Key 1)\n  │   ├── Memories\n  │   ├── Tasks\n  │   ├── Chat\n  │   └── Scripts\n  │\n  ├── Mind 2 (Mind Key 2)\n  │   └── ... (isolated from Mind 1)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

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

\n

See Multi-Tenancy for details.

\n

Request Flow

\n

Memory Store Request

\n
1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n   a. Validate JSON body (zod schema)\n   b. Insert into memories table\n   c. Update FTS5 index\n   d. (Async) Generate embedding if embeddings enabled\n   e. Trigger webhooks for memory.store event\n5. Return { id, status: "stored" }

Memory Search Request

\n
1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n   a. Parse query (FTS5 syntax)\n   b. Execute FTS5 MATCH against memories table\n   c. Filter by mind_id (tenant isolation)\n   d. Rank by relevance\n   e. Return results

Deployment

\n

Synapse is deployed as a Docker container. See docker-compose.yml:

\n
services:\n  synapse:\n    image: registry.gitlab.com/schaefer-services/synapse:latest\n    ports:\n      - "12800:12800"\n    environment:\n      - DATABASE_URL=postgres://...\n      - JWT_SECRET=...\n      - SYNAPSE_HOST=0.0.0.0\n      - SYNAPSE_PORT=12800\n    depends_on:\n      - postgres\n  \n  postgres:\n    image: postgres:16\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n    environment:\n      - POSTGRES_DB=synapse\n      - POSTGRES_PASSWORD=...

Performance Characteristics

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationLatencyThroughput
Memory store~5ms1000+ req/s
Memory recall~20ms500 req/s
FTS5 search~10ms800 req/s
Semantic search~50ms200 req/s
Chat poll~5ms2000 req/s
\n

Next Steps

\n\n","urls":{"html":"/docs/concepts/architecture","text":"/docs/concepts/architecture?format=text","json":"/docs/concepts/architecture?format=json","llm":"/docs/concepts/architecture?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}