Synapse 架构

Synapse 是一个多租户记忆 API，基于 Fastify、带 FTS5 的 PostgreSQL，以及可选的用于语义搜索的向量嵌入服务构建。

高层架构

┌──────────────────────────────────────────────────────────┐
│                       客户端                             │
├──────────────┬──────────────┬──────────────┬─────────────┤
│  LLM Agent   │  Web 浏览器  │  MCP 客户端  │  Webhooks   │
│  (curl/SDK)  │  (人类)      │ (Claude 等)  │  (外部)     │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │    Synapse API (Fastify)      │
              │    port 12800                 │
              │    - REST 端点                │
              │    - 认证 (Mind Key / JWT)    │
              │    - 限速                     │
              │    - 静态文件服务             │
              └───────────────┬───────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │
       │ + FTS5      │ │ Service     │ │ (独立服务)  │
       │             │ │ (可选)      │ │ port 13100  │
       │ - memories  │ │             │ │             │
       │ - tasks     │ │ - 生成      │ │ - 79 个工具 │
       │ - chat      │ │   向量嵌入  │ │ - stdio/SSE │
       │ - scripts   │ │             │ │ - WebSocket │
       └─────────────┘ └─────────────┘ └─────────────┘

核心组件

1. Synapse API（Fastify）

主 HTTP 服务器。负责处理：

• REST 端点（/memory、/chat、/mind/tasks 等）
• 认证（Agent 用 Mind Key，人类用 JWT）
• 限速（仅 ?key= 认证）
• 静态文件服务（/human、/docs 等 Web UI）
• Webhook 派发

基于 Fastify 5 构建，注重性能。生产环境运行在端口 12800。

2. 带 FTS5 的 PostgreSQL

主数据存储。使用 PostgreSQL 及 FTS5 扩展进行全文搜索。

关键表：

表	用途
users	用户账户
minds	Mind 范围（每个 Mind 有一个 Mind Key）
memories	记忆记录，附带 FTS5 虚拟表
tasks	任务管理
chat_messages	聊天记录
scripts	持久化脚本
webhooks	Webhook 注册
cron_jobs	定时任务
variables	键值存储
audit_log	审计日志

FTS5 可在所有记忆内容上实现亚毫秒级全文搜索。详见 FTS5 搜索。

3. Embeddings 服务（可选）

为支持语义搜索，Synapse 会为记忆内容生成向量嵌入。这些向量与记忆一起存储，用于相似度搜索。

• 提供方：可配置（OpenAI、本地模型等）
• 作为 vector 列存储在 memories 表中
• 由 /memory/semantic-search 端点使用
• 详见 语义搜索

4. MCP Server（独立服务）

Synapse MCP Server 作为独立进程运行（端口 13100）。它：

• 通过 Model Context Protocol 暴露 79 个工具
• 支持 stdio、HTTP/SSE 和 WebSocket 传输
• 将 MCP 工具调用转换为 Synapse API 调用
• 多租户：每个会话使用一个 Mind Key

5. Browser 代理（独立服务）

为支持浏览器自动化，独立的基于 Playwright 的服务运行在端口 13000。MCP Server 可调用它以执行 browser_* 工具。

6. SSH 代理（独立服务）

为支持基于 SSH 的远程命令，独立服务运行在端口 12900。

多租户模型

用户账户 (邮箱 + 密码)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── 记忆
  │   ├── 任务
  │   ├── 聊天
  │   └── 脚本
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (与 Mind 1 隔离)
  │
  └── Mind 3 (Mind Key 3)
      └── ...

每个 Mind 完全隔离。Mind Key 仅授予访问某一个 Mind 的权限。JWT 授予访问用户账户的权限（用于管理 Mind）。

详见 多租户。

请求流

记忆存储请求

1. 客户端发送 POST /memory，附带 Authorization: Bearer mk_xxx
2. Fastify 接收请求
3. 认证中间件校验 Mind Key，将 mind_id 附加到请求上
4. Memory 路由处理器：
   a. 校验 JSON body（zod schema）
   b. 插入 memories 表
   c. 更新 FTS5 索引
   d. (异步) 若启用向量嵌入则生成嵌入
   e. 触发 memory.store 事件的 Webhook
5. 返回 { id, status: "stored" }

记忆搜索请求

1. 客户端发送 GET /memory/search?q=docker
2. 认证中间件校验 Mind Key
3. Memory 路由处理器：
   a. 解析查询（FTS5 语法）
   b. 对 memories 表执行 FTS5 MATCH
   c. 按 mind_id 过滤（租户隔离）
   d. 按相关性排序
   e. 返回结果

部署

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=...

性能特征

操作	延迟	吞吐
记忆存储	~5ms	1000+ req/s
记忆回放	~20ms	500 req/s
FTS5 搜索	~10ms	800 req/s
语义搜索	~50ms	200 req/s
聊天轮询	~5ms	2000 req/s

下一步

• 记忆模型
• 多租户
• FTS5 搜索