Synapse Architecture

Synapse เป็น multi-tenant memory API ที่สร้างบน Fastify, PostgreSQL พร้อม FTS5 และ embeddings service ที่เป็นตัวเลือกสำหรับ semantic search

Architecture ระดับสูง

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

Core Components

1. Synapse API (Fastify)

HTTP server หลัก จัดการ:

• REST endpoint (/memory, /chat, /mind/tasks, etc.)
• Authentication (Mind Key สำหรับ agent, JWT สำหรับ human)
• Rate limiting (เฉพาะ auth ผ่าน ?key=)
• Static file serving (web UI ที่ /human, /docs, etc.)
• Webhook dispatch

สร้างด้วย Fastify 5 เพื่อประสิทธิภาพ รันบน port 12800 ใน production

2. PostgreSQL with FTS5

data store หลัก ใช้ PostgreSQL พร้อม FTS5 extension สำหรับ full-text search

ตารางหลัก:

ตาราง	วัตถุประสงค์
users	บัญชีผู้ใช้
minds	Mind scope (แต่ละอันมี Mind Key)
memories	Memory record พร้อม FTS5 virtual table
tasks	การจัดการ task
chat_messages	ประวัติแช็ต
scripts	Script แบบถาวร
webhooks	การลงทะเบียน webhook
cron_jobs	Task ที่ตั้งเวลาไว้
variables	Key-value store
audit_log	Audit trail

FTS5 เปิดใช้งาน full-text search ในระดับ sub-millisecond ทั่วเนื้อหา memory ทั้งหมด ดูรายละเอียดที่ FTS5 Search

3. Embeddings Service (Optional)

สำหรับ semantic search Synapse สร้าง vector embeddings ของเนื้อหา memory ซึ่งเก็บไว้กับ memory และใช้สำหรับ similarity search

• Provider: กำหนดค่าได้ (OpenAI, local model, etc.)
• เก็บเป็น vector column ในตาราง memories
• ใช้โดย endpoint /memory/semantic-search
• ดู Semantic Search

4. MCP Server (Service แยกต่างหาก)

Synapse MCP server รันเป็น process แยกต่างหาก (port 13100) ทำหน้าที่:

• เปิดเผย 79 tool ผ่าน Model Context Protocol
• รองรับ stdio, HTTP/SSE และ WebSocket transport
• แปล MCP tool call เป็น Synapse API call
• Multi-tenant: หนึ่ง Mind Key ต่อ session

5. Browser Proxy (Service แยกต่างหาก)

สำหรับ browser automation service แยกต่างหากที่ใช้ Playwright รันบน port 13000 MCP server สามารถเรียกสิ่งนี้สำหรับ tool browser_*

6. SSH Proxy (Service แยกต่างหาก)

สำหรับคำสั่งระยะไกลผ่าน SSH service แยกต่างหากรันบน port 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

การไหลของ Request

Request เก็บ Memory

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

Request ค้นหา Memory

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

Deployment

Synapse deploy เป็น Docker container ดู 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=...

คุณลักษณะด้านประสิทธิภาพ

การดำเนินการ	Latency	Throughput
Memory store	~5ms	1000+ req/s
Memory recall	~20ms	500 req/s
FTS5 search	~10ms	800 req/s
Semantic search	~50ms	200 req/s
Chat poll	~5ms	2000 req/s

ขั้นตอนถัดไป

• Memory Model
• Multi-Tenancy
• FTS5 Search