Update troubleshooting docs from PM2 to Bun (v7.1.0+)

[Copilot]

Since v7.1.0, claude-mem uses Bun for cross-platform worker management. All troubleshooting documentation still referenced PM2 commands that no longer work.

Changes

Updated 4 troubleshooting operation files:

• worker.md: PM2 commands → npm scripts and PID file operations

  • pm2 status → npm run worker:status
  • pm2 logs → tail ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
  • pm2 restart → npm run worker:restart

• diagnostics.md: PM2 health checks → PID file + health endpoint workflow

  • Diagnostic script checks ~/.claude-mem/worker.pid instead of pm2 jlist
  • Added Bun availability checks

• automated-fixes.md: PM2 fix sequences → npm script equivalents

  • All automated fixes now use npm run worker:{start|stop|restart}

• common-issues.md: PM2 resolution steps → Bun-based troubleshooting

  • Port conflicts, worker crashes, database issues

Settings format

Old nested schema (auto-migrated but no longer documented):

{"env": {"CLAUDE_MEM_WORKER_PORT": "37778"}}

Current flat schema:

{"CLAUDE_MEM_WORKER_PORT": "37778"}

All examples updated to match SettingsDefaultsManager.loadFromFile() implementation.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📚 Documentation outdated: Troubleshoot guides still reference PM2 instead of Bun (v7.1.0+)</issue_title>
<issue_description>## 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) },
  // ...
})

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes 📚 Documentation outdated: Troubleshoot guides still reference PM2 instead of Bun (v7.1.0+) #299

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.