Архітектура Synapse

Synapse — це мультитенантний API пам'яті, побудований на Fastify, PostgreSQL із FTS5 та опціональній службі ембеддингів для семантичного пошуку.

Архітектура високого рівня

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

Основні компоненти

1. Synapse API (Fastify)

Головний HTTP-сервер. Обробляє:

• REST-кінцеві точки (/memory, /chat, /mind/tasks тощо)
• Автентифікацію (Mind Key для агентів, JWT для людей)
• Обмеження частоти (лише для автентифікації ?key=)
• Віддачу статичних файлів (веб-інтерфейс на /human, /docs тощо)
• Диспетчеризацію webhook-ів

Побудовано на Fastify 5 для високої продуктивності. У продакшені працює на порту 12800.

2. PostgreSQL з FTS5

Основне сховище даних. Використовує PostgreSQL із розширенням FTS5 для повнотекстового пошуку.

Основні таблиці:

Таблиця	Призначення
users	Облікові записи користувачів
minds	Області mind-ів (кожен має Mind Key)
memories	Записи спогадів із віртуальною таблицею FTS5
tasks	Керування завданнями
chat_messages	Історія чату
scripts	Постійні скрипти
webhooks	Реєстрації webhook-ів
cron_jobs	Заплановані завдання
variables	Сховище ключ-значення
audit_log	Журнал аудиту

FTS5 забезпечує повнотекстовий пошук за всіма спогадами з затримкою менше мілісекунди. Докладніше дивіться у пошуку FTS5.

3. Служба ембеддингів (опціональна)

Для семантичного пошуку Synapse генерує векторні ембеддинги вмісту спогадів. Вони зберігаються разом зі спогадами та використовуються для пошуку за подібністю.

• Постачальник: настроюваний (OpenAI, локальна модель тощо)
• Зберігається у колонці vector у таблиці memories
• Використовується кінцевою точкою /memory/semantic-search
• Дивіться Семантичний пошук

4. MCP-сервер (окрема служба)

MCP-сервер Synapse працює як окремий процес (порт 13100). Він:

• Надає 79 інструментів через Model Context Protocol
• Підтримує транспорти stdio, HTTP/SSE та WebSocket
• Перетворює виклики MCP-інструментів у виклики API Synapse
• Мультитенантний: один Mind Key на сесію

5. Браузерний проксі (окрема служба)

Для автоматизації браузера окрема служба на основі Playwright працює на порту 13000. MCP-сервер може викликати її для інструментів browser_*.

6. SSH-проксі (окрема служба)

Для віддалених команд через SSH окрема служба працює на порту 12900.

Модель мультитенантності

User Account (email + password)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── Memories
  │   ├── Tasks
  │   ├── Chat
  │   └── Scripts
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (ізольований від Mind 1)
  │
  └── Mind 3 (Mind Key 3)
      └── ...

Кожен mind повністю ізольований. Mind Keys надають доступ лише до одного mind-у. JWT надають доступ до облікового запису користувача (для керування mind-ами).

Докладніше дивіться у Мультитенантності.

Потік запитів

Запит на збереження спогаду

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

Запит на пошук спогадів

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

Розгортання

Synapse розгортається як Docker-контейнер. Дивіться 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=...

Характеристики продуктивності

Операція	Затримка	Пропускна здатність
Збереження спогаду	~5мс	1000+ запитів/с
Відкликання спогадів	~20мс	500 запитів/с
Пошук FTS5	~10мс	800 запитів/с
Семантичний пошук	~50мс	200 запитів/с
Опитування чату	~5мс	2000 запитів/с

Наступні кроки

• Модель пам'яті
• Мультитенантність
• Пошук FTS5