Worker API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Worker API is an Express-based HTTP server that serves as the central orchestrator for the claude-mem system. Running on port 37777 (by default), it manages the persistent memory lifecycle, including session initialization, tool usage observation capture, and semantic summary generation. The API acts as a bridge between lifecycle hooks (plugin scripts), the SQLite/Chroma databases, and the Model Context Protocol (MCP) search tools.
The architecture follows a modular route organization where feature areas are separated into distinct classes. This ensures a clean separation of concerns between session management, data retrieval, search operations, and system settings.
Sources: src/services/worker/README.md:5-20, src/services/worker-service.ts:16-25
Architecture and Request Flow
The Worker Service coordinates requests from various sources, primarily lifecycle hooks triggered by Claude Code or Cursor. It delegates business logic to specialized managers (e.g., DatabaseManager, SessionManager) and proxies search requests through an internal MCP client.
The diagram shows the multi-layered architecture where requests enter via hooks or the MCP server, pass through middleware, and are handled by specific route managers that interact with the database and AI agents.
Sources: src/services/worker/README.md:24-30, src/services/worker-service.ts:148-180
Core API Sections
Session Management (/api/sessions)
These endpoints handle the lifecycle of memory sessions. They are responsible for creating new session contexts, appending observations from tool usage, and triggering the final summarization process.
| Endpoint | Method | Description |
|---|---|---|
/api/sessions/init | POST | Initializes a new session with project context and starting prompt. |
/api/sessions/:sessionId/observations | POST | Adds new tool usage observations to a specific session. |
/api/sessions/:sessionId/summarize | POST | Triggers the AI agent to generate a session summary. |
/api/sessions/:sessionId/complete | POST | Marks a session as finished. |
Sources: src/services/worker/README.md:46-56, src/services/worker-service.ts:241-260
Data Retrieval (/api/data)
These endpoints provide access to stored memory entities for the web viewer or other integrations.
| Endpoint | Method | Description |
|---|---|---|
/api/observations | GET | Paginated list of all tool observations. |
/api/summaries | GET | Paginated list of session summaries. |
/api/stats | GET | Database statistics (counts of sessions, observations, etc.). |
/api/projects | GET | List of all registered project names. |
Sources: src/services/worker/README.md:58-71, src/services/worker-service.ts:262-265
Search and Context (/api/search & /api/context)
The search endpoints are unique because they often proxy requests to the MCP Search Server. This allows for complex semantic queries while maintaining a lightweight HTTP interface.
The sequence shows how the worker handles context injection requests, which are critical for providing Claude with relevant history at the start of a session.
Sources: src/services/worker/README.md:73-90, src/services/worker-service.ts:291-325, src/servers/mcp-server.ts:36-50
System and Admin Endpoints
The Worker provides several administrative endpoints restricted to localhost to ensure security.
Health and Readiness
GET /api/health: Returns basic status, build ID, and whether initialization is complete.GET /api/readiness: Returns200 OKonly when background tasks (like database loading and MCP connection) are finished.GET /api/version: Returns the built-in version of the worker service.
Sources: src/services/worker-service.ts:192-225, src/shared/worker-utils.ts:68-80
Admin Controls
These endpoints require localhost access via security middleware.
| Endpoint | Method | Action |
|---|---|---|
/api/admin/restart | POST | Triggers a worker restart (managed by PM2 or the Windows wrapper). |
/api/admin/shutdown | POST | Gracefully shuts down the worker, closing DBs and clearing PID files. |
Sources: src/services/worker/http/middleware.ts:66-88, src/services/worker-service.ts:275-300
Configuration and Settings API
The SettingsRoutes class manages user preferences stored in ~/.claude-mem/settings.json.
// Example: Validating settings in SettingsRoutes.ts
private validateSettings(settings: any): { valid: boolean; error?: string } {
if (settings.CLAUDE_MEM_WORKER_PORT) {
const port = parseInt(settings.CLAUDE_MEM_WORKER_PORT, 10);
if (isNaN(port) || port < 1024 || port > 65535) {
return { valid: false, error: 'CLAUDE_MEM_WORKER_PORT must be between 1024 and 65535' };
}
}
// ... further validations
return { valid: true };
}
Sources: src/services/worker/http/routes/SettingsRoutes.ts:140-155
Branch and Update Management
The API facilitates system updates and branch switching, specifically for users testing beta features.
POST /api/branch/switch: Switches the underlying Git branch and restarts the worker.POST /api/branch/update: Pulls the latest code for the current branch.
Sources: src/services/worker/http/routes/SettingsRoutes.ts:101-135
Summary
The Worker API Endpoints constitute the primary interface for the claude-mem ecosystem. By centralizing session logic, AI agent coordination, and administrative tasks into an HTTP service, the system achieves portability and allows for real-time monitoring via the Web Viewer. The architecture ensures that critical operations like search are optimized through a 3-layer workflow (Search -> Timeline -> Fetch), significantly reducing token consumption.
Sources: src/services/worker/README.md:105-115, src/servers/mcp-server.ts:114-130