Synapse-arkitektur

Synapse är ett multitenant-minnes-API byggt på Fastify, PostgreSQL med FTS5 och en valfri inbäddningstjänst för semantisk sökning.

Arkitektur på hög nivå

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

Kärnkomponenter

1. Synapse API (Fastify)

Huvud-HTTP-servern. Hanterar:

• REST-endpoints (/memory, /chat, /mind/tasks etc.)
• Autentisering (Mind Key för agenter, JWT för människor)
• Hastighetsbegränsning (endast ?key=-auth)
• Statisk filservering (webbgränssnitt på /human, /docs etc.)
• Webhook-utsändning

Byggd med Fastify 5 för prestanda. Körs på port 12800 i produktion.

2. PostgreSQL med FTS5

Det primära datalagret. Använder PostgreSQL med FTS5-tillägget för fulltextssök.

Nyckeltabeller:

Tabell	Syfte
users	Användarkonton
minds	Mind-omfattningar (varje har en Mind Key)
memories	Minnesposter med FTS5 virtuell tabell
tasks	Uppgiftshantering
chat_messages	Chatthistorik
scripts	Beständiga skript
webhooks	Webhook-registreringar
cron_jobs	Schemalagda uppgifter
variables	Nyckel-värde-lager
audit_log	Granskningsspår

FTS5 möjliggör fulltextssök under en millisekund över allt minnesinnehåll. Se FTS5-sökning för detaljer.

3. Inbäddningstjänst (valfri)

För semantisk sökning genererar Synapse vektorinbäddningar av minnesinnehåll. Dessa lagras tillsammans med minnen och används för likhetssökning.

• Leverantör: konfigurerbar (OpenAI, lokal modell etc.)
• Lagras som vector-kolumn i memories-tabellen
• Används av /memory/semantic-search-endpoint
• Se Semantisk sökning

4. MCP-server (separat tjänst)

Synapse MCP-server körs som en separat process (port 13100). Den:

• Exponerar 79 verktyg via Model Context Protocol
• Stöder stdio-, HTTP/SSE- och WebSocket-transporter
• Översätter MCP-verktygsanrop till Synapse API-anrop
• Multitenant: en Mind Key per session

5. Browser Proxy (separat tjänst)

För webbläsarautomatisering körs en separat Playwright-baserad tjänst på port 13000. MCP-servern kan anropa denna för browser_*-verktyg.

6. SSH Proxy (separat tjänst)

För SSH-baserade fjärrkommandon körs en separat tjänst på port 12900.

Multitenant-modell

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

Varje mind är fullständigt isolerad. Mind Keys ger åtkomst till exakt en mind. JWT:er ger åtkomst till användarkontot (för att hantera minds).

Se Multitenancy för detaljer.

Begärandeflöde

Minneslagringsbegäran

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

Minnessökningsbegäran

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

Driftsättning

Synapse driftsätts som en Docker-container. Se 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=...

Prestandaegenskaper

Åtgärd	Latens	Genomströmning
Minneslagring	~5 ms	1000+ req/s
Minnesåterkallning	~20 ms	500 req/s
FTS5-sökning	~10 ms	800 req/s
Semantisk sökning	~50 ms	200 req/s
Chat-poll	~5 ms	2000 req/s

Nästa steg

• Minnesmodell
• Multitenancy
• FTS5-sökning