Worker Daemon Service
Relevant source files
The following files were used as context for generating this wiki page:
The Worker Daemon Service is the central orchestrator of the claude-mem project, functioning as an Express-based HTTP server that manages AI memory operations, session lifecycles, and data persistence. It runs as a background process, typically on port 37777, and acts as a bridge between frontend hooks (Claude Code/Cursor), the database layer (SQLite and Chroma), and the Model Context Protocol (MCP) search server.
Sources: src/services/worker/README.md:7-10, src/services/worker-service.ts:13-17
The service provides a comprehensive API for initializing sessions, capturing observations via the Claude Agent SDK, generating session summaries, and performing semantic searches. It is designed for high availability and includes self-recovery mechanisms, such as cleaning up orphaned vector database processes and resetting stuck message queues during startup.
Sources: src/services/worker-service.ts:503-524, src/services/worker/README.md:28-60
Architecture Overview
The Worker Service architecture is based on a slim orchestrator pattern that delegates specific domain logic to dedicated route handlers and background services.
The diagram above illustrates the request flow from external hooks and UI into the Worker Service, and its subsequent interaction with AI agents and database layers.
Sources: src/services/worker/README.md:12-25, src/services/worker-service.ts:241-267
Core Components
| Component | Responsibility | File Path |
|---|---|---|
| WorkerService | Main orchestrator; handles startup, background initialization, and process signals. | src/services/worker-service.ts |
| SDKAgent | Interfaces with Claude Agent SDK to process observations and summaries. | src/services/worker/SDKAgent.ts |
| MCP Search Server | Handles semantic search tools via the Model Context Protocol. | src/servers/mcp-server.ts |
| SessionManager | Tracks active sessions and coordinates processing queues. | src/services/worker/SessionManager.ts |
| DatabaseManager | Manages connections to SQLite and Chroma vector databases. | src/services/worker/DatabaseManager.ts |
Sources: src/services/worker/README.md:27-42, src/services/worker-service.ts:241-252
Lifecycle and Process Management
The service utilizes a "health-check-first" approach for process management. It manages its own state using a PID file located in ~/.claude-mem/worker.pid to track the running instance's process ID and port.
Sources: src/services/worker-service.ts:60-64, plugin/scripts/worker-cli.js:154-158
Startup Flow
- Health Check: The service first checks if the port (default 37777) is active via
/api/health. - Version Matching: If a worker is running, it compares the running version with the installed plugin version. Mismatches trigger an automatic restart.
- Daemon Spawning: If the port is free, the service spawns itself as a detached background process.
- Background Initialization: Once the HTTP server is listening, it performs "slow" tasks: cleaning orphaned
chroma-mcpprocesses, initializing DB connections, and connecting to the MCP server.
Sources: src/services/worker-service.ts:503-535, src/services/worker-service.ts:875-900
Shutdown Procedure
The shutdown sequence is designed to prevent "zombie ports," especially on Windows, where child processes might inherit socket handles.
API Endpoints
The Worker Service exposes several categories of REST endpoints for session management and data retrieval.
Administrative and Health Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/health | GET | Returns basic status, build ID, and initialization flags. |
/api/readiness | GET | Returns 200 only when background initialization (MCP/DB) is complete. |
/api/version | GET | Returns the build-time version of the running worker. |
/api/admin/shutdown | POST | Triggers graceful shutdown (Localhost only). |
Sources: src/services/worker-service.ts:312-345, src/services/worker-service.ts:408-415
Session Lifecycle Endpoints
Managed by SessionRoutes.ts, these endpoints handle the flow of AI interactions.
POST /sessions/init: Initialize a new session for a project.POST /sessions/:sessionId/observations: Add new tool usage data.POST /sessions/:sessionId/summarize: Trigger the AI to generate a progress summary.POST /sessions/:sessionId/complete: Mark a session as finished.
Sources: src/services/worker/README.md:52-62
Background AI Processing (SDKAgent)
The SDKAgent is the primary service responsible for the asynchronous processing of observations. It spawns a Claude subprocess via the Anthropic Agent SDK to parse tool logs into structured memory.
Observation Processing Loop
Key implementation details for SDKAgent:
- Disallowed Tools: The SDK agent is strictly an observer. Tools like
Bash,Read, andWriteare disallowed to prevent infinite execution loops. - Backlog Recovery: During startup, the service calls
processPendingQueuesto restart SDK agents for sessions that were interrupted by a crash.
Sources: src/services/worker/SDKAgent.ts:55-70, src/services/worker-service.ts:586-620
Configuration and Environment
Configuration is loaded from ~/.claude-mem/settings.json. The SettingsRoutes class provides an interface to manage these values.
| Setting | Type | Default | Description |
|---|---|---|---|
CLAUDE_MEM_WORKER_PORT | Number | 37777 | HTTP port for the daemon. |
CLAUDE_MEM_PROVIDER | String | claude | AI provider (claude, gemini, openrouter). |
CLAUDE_MEM_MODEL | String | claude-sonnet-4-5 | Model used for memory processing. |
CLAUDE_MEM_DATA_DIR | Path | ~/.claude-mem | Directory for DB and logs. |
Sources: src/services/worker/http/routes/SettingsRoutes.ts:161-200, src/shared/worker-utils.ts:25-30
The Worker Daemon Service ensures persistent intelligence across development sessions by maintaining a non-blocking, background presence that captures and indexes technical context in real-time.
Sources: src/services/worker/README.md:7-10, src/services/worker-service.ts:13-17