feat(ProcessManager): add Bun availability check and improve PID file validation

- Implemented a method to check if Bun is available in the system PATH.
- Updated the startWithBun method to return an error if Bun is not found.
- Enhanced PID file parsing to validate required fields and their types.
- Cleaned up stale PID files if the process is no longer alive.

fix(SettingsRoutes): clear port cache after updating settings

- Added a call to clearPortCache after writing updated settings to ensure the application uses the latest configuration.

Author: thedotmack

README.md

@@ -109,7 +109,7 @@ npx mintlify dev
 - **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5
 - **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks
 - **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained
-- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & PM2 management
+- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management
 - **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search
 - **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database
 
@@ -149,7 +149,7 @@ npx mintlify dev
 
 1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
 2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)
-3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2
+3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
 4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search
 5. **mem-search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP)
 6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
@@ -263,7 +263,7 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
 - **Node.js**: 18.0.0 or higher
 - **Claude Code**: Latest version with plugin support
-- **PM2**: Process manager (bundled - no global install required)
+- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
 - **SQLite 3**: For persistent storage (bundled)
 
 ---

docs/context/SMART_INSTALL_ANALYSIS.md

@@ -34,7 +34,7 @@ isWorkerHealthy() → fetch /health endpoint
     └─ [UNHEALTHY] → startWorker()
         ↓
         ├─ [Windows] → PowerShell Start-Process (hidden window)
-        └─ [Unix] → PM2 start ecosystem.config.cjs
+        └─ [Unix] → Bun start ecosystem.config.cjs
             ↓
         Wait for health check (15 retries × 1000ms)
             ↓
@@ -116,7 +116,7 @@ spawnSync('powershell.exe', [
 **Issues:**
 1. **PowerShell Dependency:** Assumes PowerShell is available and in PATH
 2. **Command Injection Risk:** Worker script path inserted directly into command string without escaping
-3. **Process Monitoring:** Windows approach launches detached process with no PM2 monitoring - harder to debug/restart
+3. **Process Monitoring:** Windows approach launches detached process with no Bun monitoring - harder to debug/restart
 4. **Health Check Timeout:** Comment says "Windows needs longer timeouts" but timeout is same for all platforms (500ms)
 
 **Edge Cases:**
@@ -127,16 +127,16 @@ spawnSync('powershell.exe', [
 
 **Unix Implementation:**
 ```typescript
-const localPm2Base = path.join(MARKETPLACE_ROOT, 'node_modules', '.bin', 'pm2');
-const pm2Command = existsSync(localPm2Base) ? localPm2Base : 'pm2';
+const localBunBase = path.join(MARKETPLACE_ROOT, 'node_modules', '.bin', 'bun');
+const bunCommand = existsSync(localBunBase) ? localBunBase : 'bun';
 ```
 
 **Issues:**
-1. **PM2 Dependency:** Falls back to global pm2 if local not found, but doesn't verify it exists
-2. **Silent Failure:** If PM2 not installed globally, spawnSync will fail with cryptic ENOENT error
+1. **Bun Dependency:** Falls back to global bun if local not found, but doesn't verify it exists
+2. **Silent Failure:** If Bun not installed globally, spawnSync will fail with cryptic ENOENT error
 
 **Recommendation:**
-- Add pm2 existence check before spawn
+- Add bun existence check before spawn
 - Implement consistent process monitoring across platforms
 - Add path escaping for Windows command construction
 - Actually implement longer timeout for Windows if needed
@@ -414,7 +414,7 @@ if (!existsSync(join(commandsDir, 'save.md'))) {
 ### Missing Edge Case Handling ⚠️
 
 1. **curl Failure:** context-hook.ts has no error handling for curl failures
-2. **PM2 Not Installed:** worker-utils.ts assumes pm2 exists globally
+2. **Bun Not Installed:** worker-utils.ts assumes bun exists globally
 3. **PowerShell Restrictions:** worker-utils.ts doesn't check execution policy
 4. **Concurrent Worker Starts:** No locking to prevent multiple hooks from starting worker simultaneously
 5. **Port Already In Use:** No detection or recovery if worker port is taken
@@ -442,7 +442,7 @@ if (!existsSync(join(commandsDir, 'save.md'))) {
 
 ### Medium Priority 🟡
 
-4. **Verify PM2 availability** before attempting to use it
+4. **Verify Bun availability** before attempting to use it
    - Check existence before spawn
    - Provide clear error message if missing
 
@@ -494,7 +494,7 @@ if (!existsSync(join(commandsDir, 'save.md'))) {
 
 1. **Cold Start:** First run with no existing data
 2. **Corrupt Settings:** Invalid JSON in settings.json
-3. **Missing Dependencies:** No PM2, no git, no curl
+3. **Missing Dependencies:** No Bun, no git, no curl
 4. **Port Conflicts:** Worker port already in use
 5. **Rapid Hook Invocations:** Multiple hooks trying to start worker simultaneously
 6. **Permission Issues:** Read-only filesystem, restricted execution
@@ -525,7 +525,7 @@ if (!existsSync(join(commandsDir, 'save.md'))) {
 
 - Duplicate health endpoints
 - curl dependency when fetch available
-- PM2 dependency on Unix but not Windows (inconsistent monitoring)
+- Bun dependency on Unix but not Windows (inconsistent monitoring)
 - First-run detection using node_modules existence
 - Hardcoded timeout values
 

docs/context/platform-integration-guide.md

@@ -68,9 +68,9 @@ CLAUDE_MEM_PYTHON_VERSION=3.13              # Python version for chroma-mcp
 ```bash
 npm run build                 # Compile TypeScript (hooks + worker)
 npm run sync-marketplace      # Copy to ~/.claude/plugins
-npm run worker:restart        # Restart PM2 worker
+npm run worker:restart        # Restart Bun worker
 npm run worker:logs           # View worker logs
-pm2 list                      # Check worker status
+bun list                      # Check worker status
 ```
 
 ---
@@ -918,8 +918,8 @@ esbuild.build({
 npm run watch
 
 # Terminal 2: Check worker status
-pm2 list
-pm2 logs claude-mem-worker
+bun list
+bun logs claude-mem-worker
 
 # Terminal 3: Test API manually
 curl http://localhost:37777/api/health
@@ -1020,7 +1020,7 @@ describe('Worker Integration', () => {
 ### Manual Testing Checklist
 
 **Phase 1: Connection & Health**
-- [ ] Worker starts successfully (`pm2 list`)
+- [ ] Worker starts successfully (`bun list`)
 - [ ] Health endpoint responds (`curl http://localhost:37777/api/health`)
 - [ ] SSE stream connects (`curl http://localhost:37777/stream`)
 

docs/public/architecture-evolution.mdx

@@ -46,22 +46,15 @@ const ThemeProvider = ({ children }) => {
 
 **Why It Matters**: Users working in different lighting conditions can now customize the viewer for comfort.
 
-### v5.1.1: PM2 Windows Fix (November 2025)
+### v5.1.1: Worker Startup Fix (November 2025) - Now Deprecated
 
-**The Problem**: PM2 startup failed on Windows with ENOENT error
+**Note**: This section describes a historical PM2-based approach that has been replaced with Bun in later versions.
 
-**Root Cause**:
-```typescript
-// ❌ Failed on Windows - PM2 not in PATH
-execSync('pm2 start ecosystem.config.cjs');
-```
+**The Problem**: Worker startup failed on Windows with ENOENT error when using PM2
 
-**The Fix**:
-```typescript
-// ✅ Use full path to PM2 binary
-const PM2_PATH = join(PLUGIN_ROOT, 'node_modules', '.bin', 'pm2');
-execSync(`"${PM2_PATH}" start "${ECOSYSTEM_CONFIG}"`);
-```
+**Historical Solution**: Used full path to PM2 binary instead of relying on PATH
+
+**Current Approach**: The project now uses Bun for process management, which provides better cross-platform compatibility and eliminates these PATH-related issues.
 
 **Impact**: Cross-platform compatibility restored, Windows users can now use claude-mem without issues.
 
@@ -203,7 +196,7 @@ async function ensureWorkerHealthy() {
 **Key Fixes**:
 - Fixed race conditions in observation queue processing
 - Improved error handling in SDK worker
-- Better cleanup of stale PM2 processes
+- Better cleanup of stale worker processes
 - Enhanced logging for debugging
 
 ### v5.0.0: Hybrid Search Architecture (October 2025)
@@ -520,7 +513,7 @@ const response = query({
 
     **Key change from v3:**
     - ✅ Stores raw prompts for search
-    - ✅ Auto-starts PM2 worker
+    - ✅ Auto-starts worker service
   </Tab>
 
   <Tab title="PostToolUse">

docs/public/architecture/hooks.mdx

@@ -446,7 +446,7 @@ sequenceDiagram
     else Tool allowed
         SaveHook->>SaveHook: Strip privacy tags from input/response
 
-        SaveHook->>SaveHook: Ensure worker running<br/>(PM2 health check)
+        SaveHook->>SaveHook: Ensure worker running<br/>(health check)
 
         SaveHook->>Worker: POST /api/sessions/observations<br/>{ claudeSessionId, tool_name, tool_input, tool_response, cwd }<br/>(fire-and-forget, 2s timeout)
 
@@ -906,7 +906,7 @@ For developers implementing this pattern on other platforms:
 
 ### Worker Service
 - [ ] HTTP server on configurable port (default 37777)
-- [ ] PM2 or equivalent process management
+- [ ] Bun runtime for process management
 - [ ] 3 core services: SessionManager, SDKAgent, DatabaseManager
 
 ### Hook Implementation

docs/public/architecture/overview.mdx

@@ -29,7 +29,7 @@ Claude-Mem operates as a Claude Code plugin with five core components:
 | **UI Framework**       | React + TypeScript                        |
 | **AI SDK**             | @anthropic-ai/claude-agent-sdk            |
 | **Build Tool**         | esbuild (bundles TypeScript)              |
-| **Process Manager**    | PM2                                       |
+| **Process Manager**    | Bun                                       |
 | **Testing**            | Node.js built-in test runner              |
 
 ## Data Flow
@@ -70,7 +70,7 @@ User Query → mem-search Skill Invoked → HTTP API → SessionSearch Service 
                               ↓
 ┌─────────────────────────────────────────────────────────────────┐
 │ 1. Session Starts → Context Hook Fires                          │
-│    Starts PM2 worker if needed, injects context from previous   │
+│    Starts Bun worker if needed, injects context from previous   │
 │    sessions (configurable observation count)                    │
 └─────────────────────────────────────────────────────────────────┘
                               ↓
@@ -177,13 +177,13 @@ claude-mem/
 │
 ├── tests/                      # Test suite
 ├── docs/                       # Documentation
-└── ecosystem.config.cjs        # PM2 configuration
+└── ecosystem.config.cjs        # Process configuration (deprecated)
 ```
 
 ## Component Details
 
 ### 1. Plugin Hooks (6 Hooks)
-- **context-hook.js** - SessionStart: Starts PM2 worker, injects context
+- **context-hook.js** - SessionStart: Starts Bun worker, injects context
 - **user-message-hook.js** - UserMessage: Debugging hook
 - **new-hook.js** - UserPromptSubmit: Creates session, saves prompt
 - **save-hook.js** - PostToolUse: Captures tool executions
@@ -200,7 +200,7 @@ Express.js HTTP server on port 37777 (configurable) with:
 - 8 viewer UI HTTP/SSE endpoints
 - Async observation processing via Claude Agent SDK
 - Real-time updates via Server-Sent Events
-- Auto-managed by PM2 process manager
+- Auto-managed by Bun
 
 See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.
 

docs/public/architecture/search-architecture.mdx

@@ -415,7 +415,7 @@ Claude translates to appropriate API call.
 If searches fail, check worker service:
 
 ```bash
-pm2 list                    # Check status
+npm run worker:status       # Check status
 npm run worker:restart      # Restart worker
 npm run worker:logs         # View logs
 ```

docs/public/configuration.mdx

@@ -181,33 +181,9 @@ Claude-Mem supports switching between stable and beta versions via the web viewe
 
 See [Beta Features](beta-features) for details on what's available in beta.
 
-## PM2 Configuration
-
-Worker service is managed by PM2 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'
-    }
-  }]
-};
-```
-
-### PM2 Settings
+## Worker Service Management
 
-- **instances**: 1 (single instance)
-- **autorestart**: true (auto-restart on crash)
-- **watch**: false (no file watching)
-- **max_memory_restart**: 1G (restart if memory exceeds 1GB)
+Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.
 
 ## Context Injection Configuration
 
@@ -402,13 +378,7 @@ Recommended values:
 
 ### Worker Memory Limit
 
-Modify PM2 memory limit in `ecosystem.config.cjs`:
-
-```javascript
-{
-  max_memory_restart: '2G'  // Increase if needed
-}
-```
+The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (~100-200MB).
 
 ### Logging Verbosity
 

docs/public/development.mdx

@@ -650,7 +650,7 @@ rm -rf plugin/scripts/*.js plugin/scripts/*.cjs
 
 1. Kill existing process:
    ```bash
-   pm2 delete claude-mem-worker
+   npm run worker:stop
    ```
 
 2. Check port: