Arsitektur Synapse

Synapse adalah API memori multi-tenant yang dibangun di atas Fastify, PostgreSQL dengan FTS5, dan layanan embeddings opsional untuk pencarian semantik.

Arsitektur Tingkat Tinggi

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

Komponen Inti

1. Synapse API (Fastify)

Server HTTP utama. Menangani:

• Endpoint REST (/memory, /chat, /mind/tasks, dll.)
• Autentikasi (Mind Key untuk agen, JWT untuk manusia)
• Rate limiting (hanya autentikasi ?key=)
• Penyajian file statis (web UI di /human, /docs, dll.)
• Pengiriman webhook

Dibangun dengan Fastify 5 untuk performa. Berjalan di port 12800 di produksi.

2. PostgreSQL dengan FTS5

Penyimpanan data utama. Menggunakan PostgreSQL dengan ekstensi FTS5 untuk pencarian teks penuh.

Tabel utama:

Tabel	Tujuan
users	Akun pengguna
minds	Cakupan mind (masing-masing memiliki Mind Key)
memories	Catatan memori dengan tabel virtual FTS5
tasks	Manajemen tugas
chat_messages	Riwayat chat
scripts	Skrip persisten
webhooks	Pendaftaran webhook
cron_jobs	Tugas terjadwal
variables	Key-value store
audit_log	Jejak audit

FTS5 memungkinkan pencarian teks penuh sub-milidetik di seluruh konten memori. Lihat Pencarian FTS5 untuk detail.

3. Layanan Embeddings (Opsional)

Untuk pencarian semantik, Synapse membuat vektor embeddings dari konten memori. Ini disimpan bersama memori dan digunakan untuk pencarian kesamaan.

• Provider: dapat dikonfigurasi (OpenAI, model lokal, dll.)
• Disimpan sebagai kolom vector di tabel memories
• Digunakan oleh endpoint /memory/semantic-search
• Lihat Pencarian Semantik

4. MCP Server (Layanan Terpisah)

Synapse MCP server berjalan sebagai proses terpisah (port 13100). Server ini:

• Mengekspos 79 alat melalui Model Context Protocol
• Mendukung transport stdio, HTTP/SSE, dan WebSocket
• Menerjemahkan pemanggilan alat MCP menjadi pemanggilan API Synapse
• Multi-tenant: satu Mind Key per sesi

5. Browser Proxy (Layanan Terpisah)

Untuk otomasi browser, layanan terpisah berbasis Playwright berjalan di port 13000. MCP server dapat memanggil ini untuk alat browser_*.

6. SSH Proxy (Layanan Terpisah)

Untuk perintah remote berbasis SSH, layanan terpisah berjalan di port 12900.

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

Setiap mind sepenuhnya terisolasi. Mind Key memberikan akses ke tepat satu mind. JWT memberikan akses ke akun pengguna (untuk mengelola mind).

Lihat Multi-Tenancy untuk detail.

Alur Permintaan

Permintaan Penyimpanan Memori

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

Permintaan Pencarian Memori

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 di-deploy sebagai container Docker. Lihat 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=...

Karakteristik Performa

Operasi	Latensi	Throughput
Penyimpanan memori	~5ms	1000+ req/s
Recall memori	~20ms	500 req/s
Pencarian FTS5	~10ms	800 req/s
Pencarian semantik	~50ms	200 req/s
Polling chat	~5ms	2000 req/s

Langkah Berikutnya

• Model Memori
• Multi-Tenancy
• Pencarian FTS5