Problem Statement

Since v7.1.0, claude-mem migrated from PM2 to Bun for cross-platform support. However, all troubleshooting documentation still contains PM2-based instructions that no longer work with the current implementation.

Current State Analysis (v7.1.14)

✅ Code Implementation (Correct):

• All hook scripts use #!/usr/bin/env bun shebang
• Worker management uses startWithBun() method
• PID-based process management (~/.claude-mem/worker.pid)
• PM2 cleanup logic implemented (.pm2-migrated marker)

❌ Documentation (Outdated):

All troubleshooting operation files reference PM2 extensively:

1. skills/troubleshoot/operations/worker.md (308 lines)

   • 100% PM2-centric commands
   • Examples: pm2 list, pm2 logs, pm2 restart, pm2 start ecosystem.config.cjs

2. skills/troubleshoot/operations/diagnostics.md (219 lines)

   • PM2-based diagnostic procedures
   • Example workflow uses pm2 jlist, pm2 start ecosystem.config.cjs

3. skills/troubleshoot/operations/automated-fixes.md (152 lines)

   • All automated fix scripts use pm2 commands
   • Example: pm2 delete claude-mem-worker && npm install && pm2 start ecosystem.config.cjs

4. skills/troubleshoot/operations/common-issues.md (233 lines)

   • Common issue resolutions rely on PM2
   • Example: pm2 jlist | grep claude-mem-worker

User Impact

When users run /troubleshoot or consult troubleshooting docs:

1. They receive PM2-based instructions
2. Running pm2 commands fails (worker not managed by PM2)
3. Users attempt to install PM2 unnecessarily
4. Confusion and ineffective problem-solving

Proposed Solution

Update all troubleshooting documentation to reflect Bun-based implementation:

Current (PM2 - doesn't work):

pm2 status | grep claude-mem-worker
pm2 restart claude-mem-worker
pm2 logs claude-mem-worker --lines 50 --nostream

Should be (Bun - actual implementation):

# Check worker status
curl -s http://127.0.0.1:37777/health

# Check worker process
cat ~/.claude-mem/worker.pid

# View logs
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -50

# Restart worker
# Worker restarts automatically on Claude Code restart
# Or kill process: kill -TERM $(cat ~/.claude-mem/worker.pid | jq -r '.pid')

Files Requiring Updates

• skills/troubleshoot/operations/worker.md
• skills/troubleshoot/operations/diagnostics.md
• skills/troubleshoot/operations/automated-fixes.md
• skills/troubleshoot/operations/common-issues.md

Additional Context

• Version analyzed: v7.1.14
• Database library correctly documented as bun:sqlite in database.md:9
• Migration completed in code but not in user-facing documentation
• This affects the /troubleshoot skill which users rely on for problem resolution

Evidence

All hook scripts confirm Bun usage:

• scripts/cleanup-hook.js:1 → #!/usr/bin/env bun
• scripts/context-hook.js:1 → #!/usr/bin/env bun
• scripts/new-hook.js:1 → #!/usr/bin/env bun
• scripts/save-hook.js:1 → #!/usr/bin/env bun
• scripts/summary-hook.js:1 → #!/usr/bin/env bun
• scripts/user-message-hook.js:1 → #!/usr/bin/env bun

Worker management uses Bun spawn:

spawn(bunPath, [workerScript], {
  detached: true,
  env: { ...process.env, CLAUDE_MEM_WORKER_PORT: String(port) },
  // ...
})