feat: Remote Worker Architecture (Docker/Cloud Deployment)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

customable/claude-mem#69

jack commented

2026-01-22 15:28:22 +00:00

Owner

Description

Enable running the claude-mem worker remotely (Docker, cloud, or external server) while only requiring minimal local components for hook interception.

Current Architecture

┌─────────────────────────────────────────┐
│              LOCAL (all-in-one)         │
├─────────────────────────────────────────┤
│ • Hooks (intercept Claude Code events)  │
│ • Worker Service (port 37777)           │
│ • AI Processing (Claude SDK)            │
│ • SQLite Database                       │
│ • Vector DB (Chroma/Qdrant)             │
│ • Web Viewer UI                         │
└─────────────────────────────────────────┘

Proposed Architecture

┌─────────────────────┐     HTTP/SSE      ┌─────────────────────────┐
│   LOCAL (minimal)   │ ←───────────────→ │   REMOTE (Docker/Cloud) │
├─────────────────────┤                   ├─────────────────────────┤
│ • Hooks (intercept) │                   │ • Worker Service        │
│ • Event forwarding  │                   │ • AI Processing (SDK)   │
│ • Context injection │                   │ • SQLite Database       │
│                     │                   │ • Vector DB (Chroma)    │
│ ~50 LOC thin client │                   │ • Web Viewer UI         │
└─────────────────────┘                   └─────────────────────────┘

Benefits

Docker Deployment: Run Worker + DB + Chroma as a containerized stack
Team Sharing: Multiple developers share a single memory instance
Performance: Heavy AI processing on dedicated/powerful server
Thin Client: Minimal local footprint, only hooks required
Multi-Machine: Same memory across laptop, desktop, CI/CD

Implementation Plan

Phase 1: Remote Worker Support

Add CLAUDE_MEM_REMOTE_URL setting (e.g., https://claude-mem.company.com)
Add CLAUDE_MEM_REMOTE_TOKEN for authentication
Modify hooks to forward events via HTTP instead of local worker
Context injection fetches from remote API

Phase 2: Thin Client Mode

Create minimal hook-only package
Skip local worker startup when remote URL configured
Health check for remote connectivity

Phase 3: Docker Support

Create Dockerfile for worker service
Create docker-compose.yml with worker + chroma + optional postgres
Environment variable configuration
Volume mounts for persistent data

Phase 4: Authentication & Security

API token authentication
Optional HTTPS enforcement
Rate limiting for remote connections
Project-level access control

Configuration Example

// ~/.claude-mem/settings.json
{
  "CLAUDE_MEM_REMOTE_URL": "https://claude-mem.internal:37777",
  "CLAUDE_MEM_REMOTE_TOKEN": "secret-token",
  "CLAUDE_MEM_LOCAL_WORKER": false
}

Docker Compose Example

version: '3.8'
services:
  claude-mem:
    image: customable/claude-mem:latest
    ports:
      - "37777:37777"
    volumes:
      - claude-mem-data:/data
    environment:
      - CLAUDE_MEM_PROVIDER=gemini
      - CLAUDE_MEM_GEMINI_API_KEY=${GEMINI_API_KEY}
      
  chroma:
    image: chromadb/chroma:latest
    volumes:
      - chroma-data:/chroma/chroma

volumes:
  claude-mem-data:
  chroma-data:

Supersedes #34 (HTTP/SSE Transport)
Supersedes #9 (HTTP/SSE Transport)
Enables #24 (Memory sharing and collaboration)

## Description Enable running the claude-mem worker remotely (Docker, cloud, or external server) while only requiring minimal local components for hook interception. ## Current Architecture ``` ┌─────────────────────────────────────────┐ │ LOCAL (all-in-one) │ ├─────────────────────────────────────────┤ │ • Hooks (intercept Claude Code events) │ │ • Worker Service (port 37777) │ │ • AI Processing (Claude SDK) │ │ • SQLite Database │ │ • Vector DB (Chroma/Qdrant) │ │ • Web Viewer UI │ └─────────────────────────────────────────┘ ``` ## Proposed Architecture ``` ┌─────────────────────┐ HTTP/SSE ┌─────────────────────────┐ │ LOCAL (minimal) │ ←───────────────→ │ REMOTE (Docker/Cloud) │ ├─────────────────────┤ ├─────────────────────────┤ │ • Hooks (intercept) │ │ • Worker Service │ │ • Event forwarding │ │ • AI Processing (SDK) │ │ • Context injection │ │ • SQLite Database │ │ │ │ • Vector DB (Chroma) │ │ ~50 LOC thin client │ │ • Web Viewer UI │ └─────────────────────┘ └─────────────────────────┘ ``` ## Benefits - **Docker Deployment**: Run Worker + DB + Chroma as a containerized stack - **Team Sharing**: Multiple developers share a single memory instance - **Performance**: Heavy AI processing on dedicated/powerful server - **Thin Client**: Minimal local footprint, only hooks required - **Multi-Machine**: Same memory across laptop, desktop, CI/CD ## Implementation Plan ### Phase 1: Remote Worker Support - [ ] Add `CLAUDE_MEM_REMOTE_URL` setting (e.g., `https://claude-mem.company.com`) - [ ] Add `CLAUDE_MEM_REMOTE_TOKEN` for authentication - [ ] Modify hooks to forward events via HTTP instead of local worker - [ ] Context injection fetches from remote API ### Phase 2: Thin Client Mode - [ ] Create minimal hook-only package - [ ] Skip local worker startup when remote URL configured - [ ] Health check for remote connectivity ### Phase 3: Docker Support - [ ] Create `Dockerfile` for worker service - [ ] Create `docker-compose.yml` with worker + chroma + optional postgres - [ ] Environment variable configuration - [ ] Volume mounts for persistent data ### Phase 4: Authentication & Security - [ ] API token authentication - [ ] Optional HTTPS enforcement - [ ] Rate limiting for remote connections - [ ] Project-level access control ## Configuration Example ```json // ~/.claude-mem/settings.json { "CLAUDE_MEM_REMOTE_URL": "https://claude-mem.internal:37777", "CLAUDE_MEM_REMOTE_TOKEN": "secret-token", "CLAUDE_MEM_LOCAL_WORKER": false } ``` ## Docker Compose Example ```yaml version: '3.8' services: claude-mem: image: customable/claude-mem:latest ports: - "37777:37777" volumes: - claude-mem-data:/data environment: - CLAUDE_MEM_PROVIDER=gemini - CLAUDE_MEM_GEMINI_API_KEY=${GEMINI_API_KEY} chroma: image: chromadb/chroma:latest volumes: - chroma-data:/chroma/chroma volumes: claude-mem-data: chroma-data: ``` ## Related Issues - Supersedes #34 (HTTP/SSE Transport) - Supersedes #9 (HTTP/SSE Transport) - Enables #24 (Memory sharing and collaboration)

jonas.hanisch referenced this issue from a commit

2026-01-22 15:59:44 +00:00

feat: add remote worker architecture (#69)

jack referenced this issue from a pull request that will close it,

2026-01-22 16:00:00 +00:00

feat: add remote worker architecture (#69) #70

jack closed this issue

2026-01-22 16:03:25 +00:00

jack referenced this issue from a commit

2026-01-22 16:03:26 +00:00

Merge pull request 'feat: add remote worker architecture (#69)' (#70) from feat/remote-worker-69 into main

jack added the