fix: complete better-sqlite3 to bun:sqlite migration

Must Fix:
- Remove better-sqlite3 logic from smart-install.js (5 sections)
- Update all documentation to reference bun:sqlite (7 files)

Should Fix:
- Add defensive break statement in worker-cli.ts:38

Nice to Have:
- Add port validation in ProcessManager.start() (1024-65535)
- Add one-time marker for PM2 cleanup migration
- Verify clearPortCache() wiring (already correct)

Addresses PR #248 review feedback (comment #3648517713)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs/public/architecture-evolution.mdx

@@ -151,7 +151,7 @@ if (currentVersion !== installedVersion) {
 **Cached Check Logic**:
 1. Does `node_modules` exist?
 2. Does `.install-version` match `package.json` version?
-3. Is `better-sqlite3` present?
+3. Is `better-sqlite3` present? (Legacy: now uses bun:sqlite which requires no installation)
 
 **Impact**:
 - SessionStart hook: 2-5 seconds → 10ms (99.5% faster)

docs/public/architecture/database.mdx

@@ -5,7 +5,7 @@ description: "SQLite schema, FTS5 search, and data storage"
 
 # Database Architecture
 
-Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent storage and FTS5 for full-text search.
+Claude-Mem uses SQLite 3 with the bun:sqlite native module for persistent storage and FTS5 for full-text search.
 
 ## Database Location
 
@@ -15,7 +15,7 @@ Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent st
 
 ## Database Implementation
 
-**Primary Implementation**: better-sqlite3 (native SQLite module)
+**Primary Implementation**: bun:sqlite (native SQLite module)
 - Used by: SessionStore and SessionSearch
 - Format: Synchronous API with better performance
 - **Note**: Database.ts (using bun:sqlite) is legacy code
@@ -301,8 +301,8 @@ Database schema is managed via migrations in `src/services/sqlite/migrations.ts`
 - **Indexes**: All foreign keys and frequently queried columns are indexed
 - **FTS5**: Full-text search is significantly faster than LIKE queries
 - **Triggers**: Automatic synchronization has minimal overhead
-- **Connection Pooling**: better-sqlite3 reuses connections efficiently
-- **Synchronous API**: better-sqlite3 uses synchronous API for better performance
+- **Connection Pooling**: bun:sqlite reuses connections efficiently
+- **Synchronous API**: bun:sqlite uses synchronous API for better performance
 
 ## Troubleshooting
 

docs/public/architecture/overview.mdx

@@ -22,7 +22,7 @@ Claude-Mem operates as a Claude Code plugin with five core components:
 |------------------------|-------------------------------------------|
 | **Language**           | TypeScript (ES2022, ESNext modules)       |
 | **Runtime**            | Node.js 18+                               |
-| **Database**           | SQLite 3 with better-sqlite3 driver       |
+| **Database**           | SQLite 3 with bun:sqlite driver           |
 | **Vector Store**       | ChromaDB (optional, for semantic search)  |
 | **HTTP Server**        | Express.js 4.18                           |
 | **Real-time**          | Server-Sent Events (SSE)                  |
@@ -205,7 +205,7 @@ Express.js HTTP server on port 37777 (configurable) with:
 See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.
 
 ### 3. Database Layer
-SQLite3 with better-sqlite3 driver featuring:
+SQLite3 with bun:sqlite driver featuring:
 - FTS5 virtual tables for full-text search
 - SessionStore for CRUD operations
 - SessionSearch for FTS5 queries

docs/public/hooks-architecture.mdx

@@ -85,7 +85,6 @@ Claude-Mem uses 6 lifecycle hook scripts across 5 lifecycle events, plus 1 pre-h
 2. Only runs `npm install` when necessary:
    - First-time installation
    - Version changed in package.json
-   - Critical dependency missing (better-sqlite3)
 3. Provides Windows-specific error messages
 4. Starts Bun worker service
 

plugin/scripts/smart-install.js

@@ -17,7 +17,6 @@ import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
-import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 
 // Determine the directory where THIS script is running from
@@ -41,7 +40,6 @@ const PLUGIN_ROOT = IS_RUNNING_FROM_CACHE
 const PACKAGE_JSON_PATH = join(PLUGIN_ROOT, 'package.json');
 const VERSION_MARKER_PATH = join(PLUGIN_ROOT, '.install-version');
 const NODE_MODULES_PATH = join(PLUGIN_ROOT, 'node_modules');
-const BETTER_SQLITE3_PATH = join(NODE_MODULES_PATH, 'better-sqlite3');
 
 // Colors for output
 const colors = {
@@ -126,12 +124,6 @@ function needsInstall() {
     return true;
   }
 
-  // Check if better-sqlite3 is installed
-  if (!existsSync(BETTER_SQLITE3_PATH)) {
-    log('📦 better-sqlite3 missing - reinstalling', colors.cyan);
-    return true;
-  }
-
   // Check version marker
   const currentPackageVersion = getPackageVersion();
   const currentNodeVersion = getNodeVersion();
@@ -165,101 +157,6 @@ function needsInstall() {
   return false;
 }
 
-/**
- * Verify that better-sqlite3 native module loads correctly
- * This catches ABI mismatches and corrupted builds
- */
-async function verifyNativeModules() {
-  try {
-    log('🔍 Verifying native modules...', colors.dim);
-
-    // Use createRequire() to resolve from PLUGIN_ROOT's node_modules
-    const require = createRequire(join(PLUGIN_ROOT, 'package.json'));
-    const Database = require('better-sqlite3');
-
-    // Try to create a test in-memory database
-    const db = new Database(':memory:');
-
-    // Run a simple query to ensure it works
-    const result = db.prepare('SELECT 1 + 1 as result').get();
-
-    // Clean up
-    db.close();
-
-    if (result.result !== 2) {
-      throw new Error('SQLite math check failed');
-    }
-
-    log('✓ Native modules verified', colors.dim);
-    return true;
-
-  } catch (error) {
-    if (error.code === 'ERR_DLOPEN_FAILED') {
-      log('⚠️  Native module ABI mismatch detected', colors.yellow);
-      return false;
-    }
-
-    // Other errors are unexpected - log and fail
-    log(`❌ Native module verification failed: ${error.message}`, colors.red);
-    return false;
-  }
-}
-
-function getWindowsErrorHelp(errorOutput) {
-  // Detect Python version at runtime
-  let pythonStatus = '   Python not detected or version unknown';
-  try {
-    const pythonVersion = execSync('python --version', { encoding: 'utf-8', stdio: 'pipe' }).trim();
-    const versionMatch = pythonVersion.match(/Python\s+([\d.]+)/);
-    if (versionMatch) {
-      pythonStatus = `   You have ${versionMatch[0]} installed ✓`;
-    }
-  } catch (error) {
-    // Python not available or failed to detect - use default message
-  }
-
-  const help = [
-    '',
-    '╔══════════════════════════════════════════════════════════════════════╗',
-    '║                    Windows Installation Help                        ║',
-    '╚══════════════════════════════════════════════════════════════════════╝',
-    '',
-    '📋 better-sqlite3 requires build tools to compile native modules.',
-    '',
-    '🔧 Option 1: Install Visual Studio Build Tools (Recommended)',
-    '   1. Download: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022',
-    '   2. Install "Desktop development with C++"',
-    '   3. Restart your terminal',
-    '   4. Try again',
-    '',
-    '🔧 Option 2: Install via npm (automated)',
-    '   Run as Administrator:',
-    '   npm install --global windows-build-tools',
-    '',
-    '🐍 Python Requirement:',
-    '   Python 3.6+ is required.',
-    pythonStatus,
-    '',
-  ];
-
-  // Check for specific error patterns
-  if (errorOutput.includes('MSBuild.exe')) {
-    help.push('❌ MSBuild not found - install Visual Studio Build Tools');
-  }
-  if (errorOutput.includes('MSVS')) {
-    help.push('❌ Visual Studio not detected - install Build Tools');
-  }
-  if (errorOutput.includes('permission') || errorOutput.includes('EPERM')) {
-    help.push('❌ Permission denied - try running as Administrator');
-  }
-
-  help.push('');
-  help.push('📖 Full documentation: https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md');
-  help.push('');
-
-  return help.join('\n');
-}
-
 async function runNpmInstall() {
   const isWindows = process.platform === 'win32';
 
@@ -310,11 +207,6 @@ async function runNpmInstall() {
   log('❌ Installation failed after retrying!', colors.bright);
   log('', colors.reset);
 
-  // Provide Windows-specific help
-  if (isWindows && lastError && lastError.message && lastError.message.includes('better-sqlite3')) {
-    log(getWindowsErrorHelp(lastError.message), colors.yellow);
-  }
-
   // Show generic error info with troubleshooting steps
   if (lastError) {
     if (lastError.stderr) {
@@ -360,21 +252,6 @@ async function main() {
         log('', colors.reset);
         process.exit(1);
       }
-    } else {
-      // Even if install not needed, verify native modules work
-      const nativeModulesWork = await verifyNativeModules();
-
-      if (!nativeModulesWork) {
-        log('📦 Native modules need rebuild - reinstalling', colors.cyan);
-        const installSuccess = await runNpmInstall();
-
-        if (!installSuccess) {
-          log('', colors.red);
-          log('⚠️  Native module rebuild failed', colors.yellow);
-          log('', colors.reset);
-          process.exit(1);
-        }
-      }
     }
 
     // NOTE: Worker auto-start disabled in smart-install.js

plugin/skills/troubleshoot/operations/database.md

@@ -6,7 +6,7 @@ SQLite database troubleshooting for claude-mem.
 
 Claude-mem uses SQLite3 for persistent storage:
 - **Location:** `~/.claude-mem/claude-mem.db`
-- **Library:** better-sqlite3 (synchronous, not bun:sqlite)
+- **Library:** bun:sqlite (native Bun SQLite, synchronous)
 - **Features:** FTS5 full-text search, triggers, indexes
 - **Tables:** observations, sessions, user_prompts, observations_fts, sessions_fts, prompts_fts
 

plugin/skills/troubleshoot/operations/diagnostics.md

@@ -97,7 +97,6 @@ cd ~/.claude/plugins/marketplaces/thedotmack/
 
 # Check for critical packages
 ls node_modules/@anthropic-ai/claude-agent-sdk 2>&1 | head -1
-ls node_modules/better-sqlite3 2>&1 | head -1
 ls node_modules/express 2>&1 | head -1
 ls node_modules/pm2 2>&1 | head -1
 ```

plugin/skills/troubleshoot/operations/worker.md

@@ -187,7 +187,6 @@ pm2 delete claude-mem-worker
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
    ls node_modules/@anthropic-ai/claude-agent-sdk
-   ls node_modules/better-sqlite3
    ls node_modules/express
    ls node_modules/pm2
    ```

src/cli/worker-cli.ts

@@ -35,6 +35,7 @@ async function main() {
         console.error(`Failed to restart: ${result.error}`);
         process.exit(1);
       }
+      break;
     }
 
     case 'status': {

src/services/process/ProcessManager.ts

@@ -25,6 +25,14 @@ interface PidInfo {
 
 export class ProcessManager {
   static async start(port: number): Promise<{ success: boolean; pid?: number; error?: string }> {
+    // Validate port range
+    if (isNaN(port) || port < 1024 || port > 65535) {
+      return {
+        success: false,
+        error: `Invalid port ${port}. Must be between 1024 and 65535`
+      };
+    }
+
     // Check if already running
     if (await this.isRunning()) {
       const info = this.getPidInfo();

src/shared/worker-utils.ts

@@ -1,6 +1,7 @@
 import path from "path";
 import { homedir } from "os";
 import { spawnSync } from "child_process";
+import { existsSync, writeFileSync } from "fs";
 import { logger } from "../utils/logger.js";
 import { HOOK_TIMEOUTS, getTimeout } from "./hook-constants.js";
 import { ProcessManager } from "../services/process/ProcessManager.js";
@@ -70,11 +71,17 @@ async function isWorkerHealthy(): Promise<boolean> {
  */
 async function startWorker(): Promise<boolean> {
   // Clean up legacy PM2 (one-time migration)
-  if (process.platform !== 'win32') {
+  const pm2MigratedMarker = path.join(SettingsDefaultsManager.get('CLAUDE_MEM_DATA_DIR'), '.pm2-migrated');
+
+  if (process.platform !== 'win32' && !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 - ignore
+      // PM2 not installed or process doesn't exist - still mark as migrated
+      writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
     }
   }
 

src/types/database.ts

@@ -1,6 +1,6 @@
 /**
  * TypeScript types for database query results
- * Provides type safety for better-sqlite3 query results
+ * Provides type safety for bun:sqlite query results
  */
 
 /**