# 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 搜索](/docs/concepts/fts5-search)。

### 3. Embeddings 服务（可选）

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

- 提供方：可配置（OpenAI、本地模型等）
- 作为 `vector` 列存储在 `memories` 表中
- 由 `/memory/semantic-search` 端点使用
- 详见 [语义搜索](/docs/concepts/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）。

详见 [多租户](/docs/concepts/multi-tenancy)。

## 请求流

### 记忆存储请求

```
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`：

```yaml
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 |

## 下一步

- [记忆模型](/docs/concepts/memory-model)
- [多租户](/docs/concepts/multi-tenancy)
- [FTS5 搜索](/docs/concepts/fts5-search)