Historical Migration DocumentationThis document describes the PM2 to Bun migration that occurred in v7.1.0 (December 2025). If you’re installing claude-mem for the first time, this migration has already been completed and you can use the current Bun-based system documented in the main guides.This documentation is preserved for users upgrading from versions older than v7.1.0.

PM2 to Bun Migration: Complete Technical Documentation

Version: 7.1.0 Date: December 2025 Migration Type: Process Management (PM2 → Bun) + Database Driver (better-sqlite3 → bun:sqlite)

Executive Summary

Claude-mem version 7.1.0 introduces two major architectural migrations:

Process Management: PM2 → Custom Bun-based ProcessManager
Database Driver: better-sqlite3 npm package → bun:sqlite runtime module

Both migrations are automatic and transparent to end users. The first time a hook fires after updating to 7.1.0+, the system performs a one-time cleanup of legacy PM2 processes and transitions to the new architecture.

Key Benefits

Simplified Dependencies: Removes PM2 and better-sqlite3 npm packages
Improved Cross-Platform Support: Better Windows compatibility
Faster Installation: No native module compilation required
Built-in Runtime: Leverages Bun’s built-in process management and SQLite
Reduced Complexity: Custom ProcessManager is simpler than PM2 integration

Migration Impact

Data Preservation: User data, settings, and database remain unchanged
Automatic Cleanup: Old PM2 processes automatically terminated (all platforms)
No User Action Required: Migration happens automatically on first hook trigger
Backward Compatible: SQLite database format unchanged (only driver changed)

Architecture Comparison

Old System (PM2-based)

Process Management (PM2)

Component: PM2 (Process Manager 2)

Package: pm2 npm dependency
Process Name: claude-mem-worker
Management: External PM2 daemon manages lifecycle
Discovery: pm2 list, pm2 describe commands
Auto-restart: PM2 automatically restarts on crash
Logs: ~/.pm2/logs/claude-mem-worker-*.log
PID File: ~/.pm2/pids/claude-mem-worker.pid

Lifecycle Commands:

pm2 start <script>           # Start worker
pm2 stop claude-mem-worker   # Stop worker
pm2 restart claude-mem-worker # Restart worker
pm2 delete claude-mem-worker  # Remove from PM2
pm2 logs claude-mem-worker    # View logs

Pain Points:

Additional npm dependency required
PM2 daemon must be running
Potential conflicts with other PM2 processes
Windows compatibility issues
Complex configuration for simple use case

Database Driver (better-sqlite3)

Component: better-sqlite3

Package: better-sqlite3 npm package (native module)
Installation: Requires native compilation (node-gyp)
Windows: Requires Visual Studio build tools + Python
Import: import Database from 'better-sqlite3'

Installation Requirements:

Node.js development headers
C++ compiler (gcc/clang on Mac/Linux, MSVC on Windows)
Python (for node-gyp)
Windows: Visual Studio Build Tools

New System (Bun-based)

Process Management (Custom ProcessManager)

Component: Custom ProcessManager (src/services/process/ProcessManager.ts)

Package: Built-in Bun APIs (no external dependency)
Process Spawn: Bun.spawn() with detached mode
Management: Direct process control via PID file
Discovery: PID file + process existence check + HTTP health check
Auto-restart: Hook-triggered restart on failure detection
Logs: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
PID File: ~/.claude-mem/.worker.pid
Port File: ~/.claude-mem/.worker.port (new)

Lifecycle Commands:

npm run worker:start    # Start worker
npm run worker:stop     # Stop worker
npm run worker:restart  # Restart worker
npm run worker:status   # Check status
npm run worker:logs     # View logs

Core Mechanisms:

PID File Management:
- File: ~/.claude-mem/.worker.pid
- Content: Process ID (e.g., “35557”)
- Validation: Process existence via kill(pid, 0) signal
Port File Management:
- File: ~/.claude-mem/.worker.port
- Content: Two lines (port number, PID)
- Purpose: Track port binding and validate PID match
Health Checking:
- Layer 1: PID file exists?
- Layer 2: Process alive? (kill(pid, 0))
- Layer 3: HTTP health check (GET /health)
- All three must pass for “healthy” status

Advantages:

No external dependencies
Simpler codebase (direct control)
Better error handling and validation
Platform-agnostic (Bun handles platform differences)

Database Driver (bun:sqlite)

Component: bun:sqlite

Package: Built into Bun runtime (no npm package)
Installation: None required (comes with Bun ≥1.0)
Platform: Works anywhere Bun works
Import: import { Database } from 'bun:sqlite'
API: Similar to better-sqlite3 (synchronous)

Installation Requirements:

Bun ≥1.0 (automatically installed if missing)
No native compilation required
No platform-specific build tools needed

Compatibility:

SQLite database format: Unchanged
Database file: ~/.claude-mem/claude-mem.db (same location)
Query syntax: Identical (both use SQLite SQL)

Migration Mechanics

One-Time PM2 Cleanup

The migration system uses a marker-based approach to perform PM2 cleanup exactly once. Implementation: src/shared/worker-utils.ts:73-86

// Clean up legacy PM2 (one-time migration)
const pm2MigratedMarker = join(DATA_DIR, '.pm2-migrated');

if (!existsSync(pm2MigratedMarker)) {
  try {
    spawnSync('pm2', ['delete', 'claude-mem-worker'], { stdio: 'ignore' });
    // Mark migration as complete
    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
    logger.debug('SYSTEM', 'PM2 cleanup completed and marked');
  } catch {
    // PM2 not installed or process doesn't exist - still mark as migrated
    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
  }
}

Migration Trigger Points

Hook Execution

SessionStart, UserPromptSubmit, or PostToolUse hooks execute using new 7.1.0 code

Worker Status Check

ensureWorkerRunning() checks if ~/.claude-mem/.worker.pid exists (it doesn’t for first run after update)

Start Worker Decision

Worker not running → Call startWorker()

Migration Check

Check if ~/.claude-mem/.pm2-migrated exists

PM2 Cleanup

Execute pm2 delete claude-mem-worker (errors ignored), create marker file

New Worker Start

Spawn new Bun-managed worker process with PID and port files

Marker File

Location: ~/.claude-mem/.pm2-migrated Content: ISO 8601 timestamp

2025-12-13T00:18:39.673Z

Purpose:

One-time migration flag
Prevents repeated PM2 cleanup on every start
Persists across restarts and reboots

Lifecycle:

Created: First hook trigger after update to 7.1.0+ (all platforms)
Updated: Never
Deleted: Never (user could manually delete to force re-migration)

User Experience Timeline

First Session After Update

This is the critical migration moment. The process takes approximately 2-5 seconds.

Step-by-Step Execution:

Hook fires (SessionStart most common)
Worker status check: No PID file → worker not running
Migration check: No marker file → run PM2 cleanup
PM2 cleanup: pm2 delete claude-mem-worker (old worker terminated)
Marker creation: ~/.claude-mem/.pm2-migrated with timestamp
New worker start: Bun process spawned, PID/port files created
Verification: Process check + HTTP health check
Hook completes: Claude Code session starts normally

User Observable Behavior:

Slight delay on first startup (PM2 cleanup + new worker spawn)
No error messages (cleanup failures silently handled)
Worker appears running via npm run worker:status
Old PM2 worker no longer in pm2 list

Subsequent Sessions

After migration completes, every hook trigger follows the fast path:

PID file exists? YES
Process alive? YES
HTTP health check? SUCCESS
Result: Worker already running, done (~50ms)

No migration logic runs on subsequent sessions.

Platform-Specific Behavior

Platform Comparison

Feature	macOS	Linux	Windows
PM2 Cleanup	Attempted	Attempted	Attempted
Marker File	Created	Created	Created
Process Signals	POSIX (native)	POSIX (native)	Bun abstraction
Bun Support	Full	Full	Full
PID File	Yes	Yes	Yes
Port File	Yes	Yes	Yes
Health Check	HTTP	HTTP	HTTP
Migration Delay	~2-5s first time	~2-5s first time	~2-5s first time

Platform Notes

macOS
Linux
Windows

POSIX signal handling works natively
Bun fully supported
No platform-specific workarounds needed

Observable Changes

Command Changes

Old (PM2)	New (Bun)	Notes
`pm2 list`	`npm run worker:status`	Shows worker status
`pm2 start <script>`	`npm run worker:start`	Start worker
`pm2 stop claude-mem-worker`	`npm run worker:stop`	Stop worker
`pm2 restart claude-mem-worker`	`npm run worker:restart`	Restart worker
`pm2 delete claude-mem-worker`	`npm run worker:stop`	Remove worker
`pm2 logs claude-mem-worker`	`npm run worker:logs`	View logs
`pm2 describe claude-mem-worker`	`npm run worker:status`	Detailed status
`pm2 monit`	No equivalent	PM2-specific monitoring

File Location Changes

Logs:

Old: ~/.pm2/logs/claude-mem-worker-out.log
     ~/.pm2/logs/claude-mem-worker-error.log

New: ~/.claude-mem/logs/worker-YYYY-MM-DD.log

PID Files:

Old: ~/.pm2/pids/claude-mem-worker.pid

New: ~/.claude-mem/.worker.pid

Process State:

Old: PM2 daemon memory (pm2 save)

New: ~/.claude-mem/.worker.pid
     ~/.claude-mem/.worker.port
     ~/.claude-mem/.pm2-migrated (all platforms)

Database (unchanged):

Same: ~/.claude-mem/claude-mem.db

User-Visible Changes

Before Update:

$ pm2 list
┌────┬────────────────────┬─────────┬─────────┬──────────┐
│ id │ name               │ status  │ restart │ uptime   │
├────┼────────────────────┼─────────┼─────────┼──────────┤
│ 0  │ claude-mem-worker  │ online  │ 0       │ 2d 5h    │
└────┴────────────────────┴─────────┴─────────┴──────────┘

After Update:

$ pm2 list
# Empty - worker no longer managed by PM2

$ npm run worker:status
Worker is running
PID: 35557
Port: 37777
Uptime: 2h 15m

Orphaned Files

After migration, these PM2 files may remain (safe to delete):

~/.pm2/                    # Entire PM2 directory
~/.pm2/logs/               # Old logs
~/.pm2/pids/               # Old PID files
~/.pm2/pm2.log             # PM2 daemon log
~/.pm2/dump.pm2            # PM2 process dump

Cleanup (optional):

# Remove PM2 entirely (if not used for other processes)
pm2 kill
rm -rf ~/.pm2

# Or just remove claude-mem logs
rm -f ~/.pm2/logs/claude-mem-worker-*.log
rm -f ~/.pm2/pids/claude-mem-worker.pid

File System State

State Directory Structure

Before Migration (PM2 system):

~/.claude-mem/
├── claude-mem.db          # Database (unchanged)
├── chroma/                # Vector embeddings (unchanged)
├── logs/                  # Application logs (unchanged)
└── settings.json          # User settings (unchanged)

~/.pm2/
├── logs/
│   ├── claude-mem-worker-out.log
│   └── claude-mem-worker-error.log
├── pids/
│   └── claude-mem-worker.pid
└── pm2.log

After Migration (Bun system):

~/.claude-mem/
├── claude-mem.db          # Database (same file)
├── chroma/                # Vector embeddings (unchanged)
├── logs/
│   └── worker-2025-12-13.log  # New log format
├── settings.json          # User settings (unchanged)
├── .worker.pid            # NEW: Process ID
├── .worker.port           # NEW: Port + PID
└── .pm2-migrated          # NEW: Migration marker (all platforms)

~/.pm2/                    # Orphaned (safe to delete)
├── logs/                  # Old logs (no longer written)
├── pids/                  # Old PID (no longer updated)
└── pm2.log                # PM2 daemon log (not used)

Edge Cases and Troubleshooting

Scenario 1: Migration Fails (PM2 Still Running)

This is rare but can happen if PM2 has watch mode enabled or the process is manually restarted.

Symptoms:

pm2 list still shows claude-mem-worker
Port conflict errors in logs
Worker fails to start

Resolution:

# Manual cleanup
pm2 delete claude-mem-worker
pm2 save  # Persist the deletion

# Force re-migration (optional)
rm ~/.claude-mem/.pm2-migrated

# Restart worker
npm run worker:restart

Scenario 2: Stale PID File (Process Dead)

Symptoms:

npm run worker:status shows “not running”
.worker.pid file exists
Process ID doesn’t exist

Automatic Recovery: Next hook trigger detects dead process and starts a fresh worker. Manual Resolution:

rm ~/.claude-mem/.worker.pid
rm ~/.claude-mem/.worker.port
npm run worker:start

Scenario 3: Port Already in Use

Error: EADDRINUSE: address already in use Resolution:

# Check what's using the port
lsof -i :37777

# Kill the process
kill -9 <PID>

# Restart worker
npm run worker:restart

Common Error Messages

Error	Cause	Resolution
`EADDRINUSE`	Port already in use	`lsof -i :37777` then kill conflicting process
`No such process`	Stale PID file	Automatic cleanup on next hook trigger
`pm2: command not found`	PM2 not installed	None needed (error is caught and ignored)
`Invalid port X`	Port validation failed	Update `CLAUDE_MEM_WORKER_PORT` in settings

Developer Notes

Testing the Migration

# 1. Install old version (with PM2)
git checkout <pre-7.1.0-tag>
npm install && npm run build && npm run sync-marketplace

# 2. Start PM2 worker
pm2 start plugin/scripts/worker-cli.js --name claude-mem-worker

# 3. Update to new version
git checkout main
npm install && npm run build && npm run sync-marketplace

# 4. Trigger hook
node plugin/scripts/session-start-hook.js

# 5. Verify migration
pm2 list  # Should NOT show claude-mem-worker
cat ~/.claude-mem/.pm2-migrated  # Should exist
npm run worker:status  # Should show Bun worker running

Architecture Decisions

Why Custom ProcessManager Instead of PM2?

Simplicity: Direct control, no external daemon
Dependencies: Remove npm dependency
Cross-platform: Bun handles platform differences
Bundle Size: Reduce plugin package size
Control: Fine-grained error handling and validation

Why One-Time Marker Instead of Always Running PM2 Delete?

Performance: Avoid unnecessary process spawning
Idempotency: Migration runs exactly once
Debugging: Timestamp shows when migration occurred
Simplicity: Clear migration state

Why Run PM2 Cleanup on All Platforms?

Quality Migration: Clean up orphaned processes
Consistency: Same behavior across all platforms
Safety: Error handling already in place (try/catch)
No Downside: If PM2 not installed, error is caught and ignored

Summary

The migration from PM2 to Bun-based ProcessManager is a one-time, automatic, transparent transition that:

Removes external dependencies (PM2, better-sqlite3)
Simplifies architecture (direct process control)
Improves cross-platform support (especially Windows)
Preserves user data (database, settings, logs unchanged)
Requires no user action (automatic on first hook trigger)

Key Migration Moment: First hook trigger after update to 7.1.0+ Duration: ~2-5 seconds (one-time delay) Impact: Seamless transition, user-invisible Rollback: Not needed (migration is forward-only, safe) For most users, the migration will be completely transparent - they’ll see no errors, no data loss, and experience improved reliability and simpler troubleshooting going forward.

Get Started

Cursor Integration

Gemini CLI Integration

Best Practices

Configuration & Development

Architecture

PM2 to Bun Migration

PM2 to Bun Migration: Complete Technical Documentation

Executive Summary

Key Benefits

Migration Impact

Architecture Comparison

Old System (PM2-based)

New System (Bun-based)

Migration Mechanics

One-Time PM2 Cleanup

Migration Trigger Points

Marker File

User Experience Timeline

First Session After Update

Subsequent Sessions

Platform-Specific Behavior

Platform Comparison

Platform Notes

Observable Changes

Command Changes

File Location Changes

User-Visible Changes

Orphaned Files

File System State

State Directory Structure

Edge Cases and Troubleshooting

Scenario 1: Migration Fails (PM2 Still Running)

Scenario 2: Stale PID File (Process Dead)

Scenario 3: Port Already in Use

Common Error Messages

Developer Notes

Testing the Migration

Architecture Decisions

Summary

Get Started

Cursor Integration

Gemini CLI Integration

Best Practices

Configuration & Development

Architecture

Documentation Index

​PM2 to Bun Migration: Complete Technical Documentation

​Executive Summary

​Key Benefits

​Migration Impact

​Architecture Comparison

​Old System (PM2-based)

​New System (Bun-based)

​Migration Mechanics

​One-Time PM2 Cleanup

​Migration Trigger Points

​Marker File

​User Experience Timeline

​First Session After Update

​Subsequent Sessions

​Platform-Specific Behavior

​Platform Comparison

​Platform Notes

​Observable Changes

​Command Changes

​File Location Changes

​User-Visible Changes

​Orphaned Files

​File System State

​State Directory Structure

​Edge Cases and Troubleshooting

​Scenario 1: Migration Fails (PM2 Still Running)

​Scenario 2: Stale PID File (Process Dead)

​Scenario 3: Port Already in Use

​Common Error Messages

​Developer Notes

​Testing the Migration

​Architecture Decisions

​Summary

PM2 to Bun Migration: Complete Technical Documentation

Executive Summary

Key Benefits

Migration Impact

Architecture Comparison

Old System (PM2-based)

New System (Bun-based)

Migration Mechanics

One-Time PM2 Cleanup

Migration Trigger Points

Marker File

User Experience Timeline

First Session After Update

Subsequent Sessions

Platform-Specific Behavior

Platform Comparison

Platform Notes

Observable Changes

Command Changes

File Location Changes

User-Visible Changes

Orphaned Files

File System State

State Directory Structure

Edge Cases and Troubleshooting

Scenario 1: Migration Fails (PM2 Still Running)

Scenario 2: Stale PID File (Process Dead)

Scenario 3: Port Already in Use

Common Error Messages

Developer Notes

Testing the Migration

Architecture Decisions

Summary