Architektura Synapse

Synapse to wielodostępne API pamięci zbudowane na Fastify, PostgreSQL z FTS5 oraz opcjonalnej usłudze osadzeń do wyszukiwania semantycznego.

Architektura wysokiego poziomu

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

Główne komponenty

1. Synapse API (Fastify)

Główny serwer HTTP. Obsługuje:

• Endpointy REST (/memory, /chat, /mind/tasks itp.)
• Autoryzację (Mind Key dla agentów, JWT dla ludzi)
• Limity żądań (tylko autoryzacja ?key=)
• Serwowanie plików statycznych (interfejs WWW pod /human, /docs itp.)
• Wysyłanie webhooków

Zbudowany na Fastify 5 dla wydajności. W środowisku produkcyjnym działa na porcie 12800.

2. PostgreSQL z FTS5

Główny magazyn danych. Wykorzystuje PostgreSQL z rozszerzeniem FTS5 do wyszukiwania pełnotekstowego.

Kluczowe tabele:

Tabela	Przeznaczenie
users	Konta użytkowników
minds	Zakresy umysłów (każdy ma Mind Key)
memories	Rekordy wspomnień z tabelą wirtualną FTS5
tasks	Zarządzanie zadaniami
chat_messages	Historia czatu
scripts	Trwałe skrypty
webhooks	Rejestracje webhooków
cron_jobs	Zaplanowane zadania
variables	Magazyn klucz-wartość
audit_log	Ścieżka audytu

FTS5 umożliwia wyszukiwanie pełnotekstowe poniżej milisekundy w całej treści wspomnień. Szczegóły w sekcji Wyszukiwanie FTS5.

3. Usługa osadzeń (opcjonalna)

Do wyszukiwania semantycznego Synapse generuje wektorowe osadzenia treści wspomnień. Są one przechowywane razem ze wspomnieniami i używane do wyszukiwania podobieństwa.

• Dostawca: konfigurowalny (OpenAI, model lokalny itp.)
• Przechowywane jako kolumna vector w tabeli memories
• Używane przez endpoint /memory/semantic-search
• Patrz Wyszukiwanie semantyczne

4. Serwer MCP (osobna usługa)

Serwer MCP Synapse działa jako osobny proces (port 13100). Spełnia funkcje:

• Udostępnia 79 narzędzi przez Model Context Protocol
• Obsługuje transporty stdio, HTTP/SSE oraz WebSocket
• Tłumaczy wywołania narzędzi MCP na wywołania API Synapse
• Wielodostępność: jeden Mind Key na sesję

5. Proxy przeglądarki (osobna usługa)

Do automatyzacji przeglądarki działa osobna usługa oparta na Playwright na porcie 13000. Serwer MCP może ją wywoływać dla narzędzi browser_*.

6. Proxy SSH (osobna usługa)

Do zdalnych poleceń opartych na SSH działa osobna usługa na porcie 12900.

Model wielodostępności

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

Każdy umysł jest w pełni izolowany. Mind Key daje dostęp dokładnie do jednego umysłu. JWT dają dostęp do konta użytkownika (do zarządzania umysłami).

Szczegóły w sekcji Wielodostępność.

Przepływ żądania

Żądanie zapisu wspomnienia

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

Żądanie wyszukiwania wspomnień

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

Wdrożenie

Synapse jest wdrażany jako kontener Docker. Patrz 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=...

Charakterystyka wydajności

Operacja	Opóźnienie	Przepustowość
Zapis wspomnienia	~5 ms	1000+ żądań/s
Recall wspomnień	~20 ms	500 żądań/s
Wyszukiwanie FTS5	~10 ms	800 żądań/s
Wyszukiwanie semantyczne	~50 ms	200 żądań/s
Odpytywanie czatu	~5 ms	2000 żądań/s

Następne kroki

• Model pamięci
• Wielodostępność
• Wyszukiwanie FTS5