Synapse 아키텍처

Synapse는 Fastify, FTS5가 포함된 PostgreSQL, 그리고 의미론적 검색을 위한 선택적 임베딩 서비스를 기반으로 구축된 다중 테넌트 메모리 API입니다.

고수준 아키텍처

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

핵심 구성 요소

1. Synapse API (Fastify)

메인 HTTP 서버입니다. 처리하는 작업:

• REST 엔드포인트 (/memory, /chat, /mind/tasks 등)
• 인증 (에이전트용 Mind Key, 사람용 JWT)
• 속도 제한 (?key= 인증만)
• 정적 파일 제공 (/human, /docs 등의 웹 UI)
• 웹훅 디스패치

성능을 위해 Fastify 5로 구축되었습니다. 프로덕션에서는 포트 12800에서 실행됩니다.

2. FTS5가 포함된 PostgreSQL

기본 데이터 저장소입니다. 전문 검색을 위해 FTS5 확장이 포함된 PostgreSQL을 사용합니다.

주요 테이블:

테이블	용도
users	사용자 계정
minds	마인드 범위 (각각 Mind Key 보유)
memories	FTS5 가상 테이블이 있는 메모리 레코드
tasks	작업 관리
chat_messages	채팅 기록
scripts	영구 스크립트
webhooks	웹훅 등록
cron_jobs	예약된 작업
variables	키-값 저장소
audit_log	감사 추적

FTS5는 모든 메모리 콘텐츠에 대해 서브밀리초 전문 검색을 가능하게 합니다. 자세한 내용은 FTS5 검색을 참조하십시오.

3. 임베딩 서비스 (선택 사항)

의미론적 검색을 위해 Synapse는 메모리 콘텐츠의 벡터 임베딩을 생성합니다. 이는 메모리와 함께 저장되며 유사도 검색에 사용됩니다.

• 제공자: 구성 가능 (OpenAI, 로컬 모델 등)
• memories 테이블의 vector 컬럼으로 저장
• /memory/semantic-search 엔드포인트에서 사용
• 의미론적 검색 참조

4. MCP 서버 (별도 서비스)

Synapse MCP 서버는 별도의 프로세스 (포트 13100)로 실행됩니다. 다음을 수행합니다:

• Model Context Protocol을 통해 79개 도구 노출
• stdio, HTTP/SSE, WebSocket 전송 지원
• MCP 도구 호출을 Synapse API 호출로 변환
• 다중 테넌트: 세션당 하나의 Mind Key

5. Browser Proxy (별도 서비스)

브라우저 자동화를 위해 Playwright 기반의 별도 서비스가 포트 13000에서 실행됩니다. MCP 서버는 browser_* 도구를 위해 이를 호출할 수 있습니다.

6. SSH Proxy (별도 서비스)

SSH 기반 원격 명령을 위해 별도의 서비스가 포트 12900에서 실행됩니다.

다중 테넌시 모델

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 Key는 정확히 하나의 마인드에만 접근 권한을 부여합니다. JWT는 사용자 계정 (마인드 관리용)에 접근 권한을 부여합니다.

자세한 내용은 다중 테넌시를 참조하십시오.

요청 흐름

메모리 저장 요청

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

메모리 검색 요청

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

배포

Synapse는 Docker 컨테이너로 배포됩니다. 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=...

성능 특성

작업	지연 시간	처리량
메모리 저장	~5ms	1000+ req/s
메모리 회상	~20ms	500 req/s
FTS5 검색	~10ms	800 req/s
의미론적 검색	~50ms	200 req/s
채팅 폴링	~5ms	2000 req/s

다음 단계

• 메모리 모델
• 다중 테넌시
• FTS5 검색