Synapse Mimarisi

Synapse, Fastify, FTS5 ile PostgreSQL ve anlamsal arama için isteğe bağlı bir gömme hizmeti üzerine inşa edilmiş çok kiracılı bir bellek API'sidir.

Üst Düzey Mimari

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

Çekirdek Bileşenler

1. Synapse API (Fastify)

Ana HTTP sunucusu. Şunları ele alır:

• REST uç noktaları (/memory, /chat, /mind/tasks vb.)
• Kimlik doğrulama (ajanlar için Mind Key, insanlar için JWT)
• Hız sınırlaması (yalnızca ?key= kimlik doğrulaması)
• Statik dosya sunumu (/human, /docs vb. web arayüzü)
• Webhook dağıtımı

Performans için Fastify 5 ile inşa edilmiştir. Üretimde 12800 portunda çalışır.

2. FTS5 ile PostgreSQL

Birincil veri deposu. Tam metin arama için FTS5 uzantısına sahip PostgreSQL kullanır.

Önemli tablolar:

Tablo	Amaç
users	Kullanıcı hesapları
minds	Mind kapsamları (her birinin bir Mind Key'i vardır)
memories	FTS5 sanal tablosuyla bellek kayıtları
tasks	Görev yönetimi
chat_messages	Sohbet geçmişi
scripts	Kalıcı betikler
webhooks	Webhook kayıtları
cron_jobs	Zamanlanmış görevler
variables	Anahtar-değer deposu
audit_log	Denetim izi

FTS5, tüm bellek içeriğinde milisaniyenin altında tam metin arama sağlar. Detaylar için bkz. FTS5 Arama.

3. Gömme Hizmeti (İsteğe Bağlı)

Anlamsal arama için Synapse, bellek içeriğinin vektör gömmelerini üretir. Bunlar belleklerle birlikte saklanır ve benzerlik araması için kullanılır.

• Sağlayıcı: yapılandırılabilir (OpenAI, yerel model vb.)
• memories tablosunda vector sütunu olarak saklanır
• /memory/semantic-search uç noktası tarafından kullanılır
• Bkz. Anlamsal Arama

4. MCP Sunucusu (Ayrı Hizmet)

Synapse MCP sunucusu ayrı bir süreç (port 13100) olarak çalışır. Şunları yapar:

• Model Context Protocol üzerinden 79 araç sunar
• stdio, HTTP/SSE ve WebSocket taşıyıcılarını destekler
• MCP araç çağrılarını Synapse API çağrılarına çevirir
• Çok kiracılı: oturum başına bir Mind Key

5. Browser Proxy (Ayrı Hizmet)

Tarayıcı otomasyonu için, 13000 portunda Playwright tabanlı ayrı bir hizmet çalışır. MCP sunucusu bunu browser_* araçları için çağırabilir.

6. SSH Proxy (Ayrı Hizmet)

SSH tabanlı uzak komutlar için, 12900 portunda ayrı bir hizmet çalışır.

Çok Kiracılılık Modeli

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

Her mind tamamen izoledir. Mind Key'ler tam olarak bir mind'e erişim sağlar. JWT'ler kullanıcı hesabına erişim sağlar (mind'leri yönetmek için).

Detaylar için bkz. Çok Kiracılılık.

İstek Akışı

Bellek Saklama İsteği

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

Bellek Arama İsteği

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

Dağıtım

Synapse bir Docker konteyneri olarak dağıtılır. Bkz. 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=...

Performans Karakteristikleri

İşlem	Gecikme	Verim
Bellek saklama	~5ms	1000+ istek/sn
Bellek geri çağırma	~20ms	500 istek/sn
FTS5 arama	~10ms	800 istek/sn
Anlamsal arama	~50ms	200 istek/sn
Sohbet poll	~5ms	2000 istek/sn

Sonraki Adımlar

• Bellek Modeli
• Çok Kiracılılık
• FTS5 Arama