diff --git a/docs/PM2-TO-BUN-MIGRATION.md b/docs/PM2-TO-BUN-MIGRATION.md new file mode 100644 index 00000000..fa38a049 --- /dev/null +++ b/docs/PM2-TO-BUN-MIGRATION.md @@ -0,0 +1,1552 @@ +# PM2 to Bun Migration: Complete Technical Documentation + +**Version**: 7.0.10+ +**Date**: December 2025 +**Migration Type**: Process Management (PM2 → Bun) + Database Driver (better-sqlite3 → bun:sqlite) + +--- + +## Table of Contents + +1. [Executive Summary](#executive-summary) +2. [Architecture Comparison](#architecture-comparison) +3. [Migration Mechanics](#migration-mechanics) +4. [User Experience Timeline](#user-experience-timeline) +5. [Platform-Specific Behavior](#platform-specific-behavior) +6. [Observable Changes](#observable-changes) +7. [File System State](#file-system-state) +8. [Edge Cases and Troubleshooting](#edge-cases-and-troubleshooting) +9. [Developer Notes](#developer-notes) + +--- + +## Executive Summary + +Claude-mem version 7.0.10 introduces two major architectural migrations: + +1. **Process Management**: PM2 → Custom Bun-based ProcessManager +2. **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.0.10+, 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**: +```bash +pm2 start