refactor: require Bun globally, add auto-install, remove Windows executable approach (#243)

- Delete BinaryManager.ts - no longer needed
- Simplify ProcessManager.ts - single Bun spawn path for all platforms
- Update smart-install.js - auto-install Bun if missing (Windows/Unix)
- Update documentation to reflect Bun requirement

This simplifies the codebase by:
- Using Bun consistently across all platforms (hooks + worker)
- Eliminating binary download/hosting complexity
- Zero native dependencies with bun:sqlite
- Auto-installing Bun on first run if not present

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
2025-12-11 17:27:18 -05:00
committed by GitHub
parent 50c7603a37
commit d24d5dda04
6 changed files with 189 additions and 177 deletions
+29 -30
View File
@@ -1,16 +1,17 @@
---
title: "Worker Service"
description: "HTTP API and PM2 process management"
description: "HTTP API and Bun process management"
---
# Worker Service
The worker service is a long-running HTTP API built with Express.js and managed by PM2. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.
The worker service is a long-running HTTP API built with Express.js and managed natively by Bun. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.
## Overview
- **Technology**: Express.js HTTP server
- **Process Manager**: PM2
- **Runtime**: Bun (auto-installed if missing)
- **Process Manager**: Native Bun process management via ProcessManager
- **Port**: Fixed port 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
- **Location**: `src/services/worker-service.ts`
- **Built Output**: `plugin/scripts/worker-service.cjs`
@@ -322,28 +323,15 @@ DELETE /sessions/:sessionDbId
**Note**: As of v4.1.0, the cleanup hook no longer calls this endpoint. Sessions are marked complete instead of deleted to allow graceful worker shutdown.
## PM2 Management
## Bun Process Management
### Configuration
### Overview
The worker is configured via `ecosystem.config.cjs`:
```javascript
module.exports = {
apps: [{
name: 'claude-mem-worker',
script: './plugin/scripts/worker-service.cjs',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '1G',
env: {
NODE_ENV: 'production',
FORCE_COLOR: '1'
}
}]
};
```
The worker is managed by the native `ProcessManager` class which handles:
- Process spawning with Bun runtime
- PID file tracking at `~/.claude-mem/worker.pid`
- Health checks with automatic retry
- Graceful shutdown with SIGTERM/SIGKILL fallback
### Commands
@@ -366,7 +354,18 @@ npm run worker:status
### Auto-Start Behavior
As of v4.0.0, the worker service auto-starts when the SessionStart hook fires. Manual start is optional.
The worker service auto-starts when the SessionStart hook fires. Manual start is optional.
### Bun Requirement
Bun is required to run the worker service. If Bun is not installed, the smart-install script will automatically install it on first run:
- **Windows**: `powershell -c "irm bun.sh/install.ps1 | iex"`
- **macOS/Linux**: `curl -fsSL https://bun.sh/install | bash`
You can also install manually via:
- `winget install Oven-sh.Bun` (Windows)
- `brew install oven-sh/bun/bun` (macOS)
## Claude Agent SDK Integration
@@ -410,15 +409,15 @@ If port 37777 is in use, the worker will fail to start. Set a custom port via en
## Data Storage
The worker service stores data in the plugin data directory:
The worker service stores data in the user data directory:
```
${CLAUDE_PLUGIN_ROOT}/data/
├── claude-mem.db # SQLite database
├── worker.port # Current worker port file
~/.claude-mem/
├── claude-mem.db # SQLite database (bun:sqlite)
├── worker.pid # PID file for process tracking
├── settings.json # User settings
└── logs/
── worker-out.log # Worker stdout logs
└── worker-error.log # Worker stderr logs
── worker-YYYY-MM-DD.log # Daily rotating logs
```
## Error Handling