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

Synapse — это multi-tenant 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 и т. д.)
• Диспетчеризацию вебхуков

Построен на Fastify 5 для производительности. В продакшене работает на порту 12800.

2. PostgreSQL с FTS5

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

Ключевые таблицы:

Таблица	Назначение
users	Аккаунты пользователей
minds	Области mind (у каждого есть Mind Key)
memories	Записи памяти с виртуальной таблицей FTS5
tasks	Управление задачами
chat_messages	История чата
scripts	Постоянные скрипты
webhooks	Регистрации вебхуков
cron_jobs	Запланированные задачи
variables	Key-value хранилище
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-инструментов в вызовы Synapse API
• Multi-tenant: один Mind Key на сессию

5. Браузерный прокси (отдельный сервис)

Для автоматизации браузера запускается отдельный сервис на базе Playwright на порту 13000. MCP-сервер может вызывать его для инструментов browser_*.

6. SSH-прокси (отдельный сервис)

Для удалённых команд по SSH запускается отдельный сервис на порту 12900.

Модель multi-tenancy

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

Каждый mind полностью изолирован. Mind Key даёт доступ ровно к одному mind. JWT даёт доступ к аккаунту пользователя (для управления mind).

Подробнее см. Multi-tenancy.

Поток запросов

Запрос на сохранение памяти

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 запросов/с

Следующие шаги

• Модель памяти
• Multi-tenancy
• FTS5-поиск