Episode 5: Worker Service — Claude-Mem's Heart

⏱ Est. reading time: 10 min Updated on 5/7/2026

This episode's scenario: Hooks only capture data and toss it to the Worker. The heavy lifting — compression, storage, search, Web UI streaming — is all handled by the Worker Service.

5.1 The Worker's Role

The Worker Service is a background HTTP server on localhost:37777. It's the hub of Claude-Mem's architecture.

5.2 Why Bun Instead of Node.js?

Feature Node.js Bun
SQLite driver Requires better-sqlite3 (C++ compilation) Built-in bun:sqlite (ready to go)
Process management Needs PM2 or similar Bun manages subprocesses natively
Startup speed ~200ms ~30ms
Install size Larger Smaller (single binary)

5.3 Core API Endpoints

Health Check

curl http://localhost:37777/api/health
# → {"status":"ok"}

Context Retrieval (called by SessionStart)

curl http://localhost:37777/api/context?project=my-blog

Returns recent Observations and Summaries for context injection.

Receive New Observation (called by PostToolUse)

Worker's internal processing flow:

graph TD
    A["Receive raw tool data"] --> B["Claude Agent SDK
begins compression"]
    B --> C["Extract key information"]
    C --> D["Generate structured data"]
    D --> D1["title: Fix comment FK constraint"]
    D --> D2["narrative: The developer found..."]
    D --> D3["facts: Used cascade delete..."]
    D --> D4["type: bugfix"]

    D1 --> E["SQLite INSERT"]
    D2 --> E
    D3 --> E
    D4 --> E
    E --> F["FTS5 index update"]

    D1 --> G["ChromaDB vectorization"]
    D2 --> G
    G --> H["Vector index update"]

    E --> I["SSE push to Web UI"]
    H --> I

    style A fill:#6366f1,color:#fff
    style B fill:#f59e0b,color:#000
    style I fill:#10b981,color:#fff

AI Compression Ratios

Raw Data Tokens After Compression Tokens Ratio
500-line file contents ~8,000 "Read auth.ts JWT validation logic" + facts ~200 40x
200 lines of npm test output ~3,000 "Ran tests: 15 passed, 1 failed (comment API timeout)" ~100 30x
Large file diff ~5,000 "Modified comment API, added input validation" + concepts ~150 33x

5.4 Web Viewer UI

Visit http://localhost:37777 (without /api) for a live dashboard:

  • 🔴 Real-time Observation stream (SSE — no page refresh needed)
  • 🔍 Search functionality
  • ⚙️ Configuration management
  • 📊 Statistics
  • 🔄 Version switching (stable / beta)

5.5 Troubleshooting the Worker

Worker Not Running

ps aux | grep bun | grep claude-mem
# If no process, reinstall:
npx claude-mem install

Port Conflict

lsof -i :37777
# Change port in settings:
# ~/.claude-mem/settings.json → "WORKER_PORT": 37778

Checking Logs

tail -f ~/.claude-mem/logs/worker.log

Hands-On Exercise

  1. Verify Worker is running: curl http://localhost:37777/api/health
  2. Work on the blog project in Claude Code
  3. Monitor Worker logs in real time: tail -f ~/.claude-mem/logs/worker.log
  4. Open the Web Viewer UI and watch the live SSE stream
  5. Test the search API: curl "http://localhost:37777/api/search?q=blog"

Coming Up Next

The Worker stores data, but how do you retrieve it efficiently? Dumping all memories into Claude would burn massive tokens. Next episode: the 3-layer progressive retrieval — Claude-Mem's "money-saving secret."

➡️ Episode 6: 3-Layer Progressive Retrieval — Claude-Mem's Money-Saving Secret