claude-self-reflect 2.3.7 → 2.3.9

package/README.md

@@ -4,7 +4,7 @@ Claude forgets everything. This fixes that.
 
 ## What You Get
 
-Ask Claude about past conversations. Get actual answers. Local-first with no cloud dependencies, but cloud-enhanced search available when you need it.
+Ask Claude about past conversations. Get actual answers. **100% local by default** - your conversations never leave your machine. Cloud-enhanced search available when you need it.
 
 **Before**: "I don't have access to previous conversations"  
 **After**: 
@@ -143,6 +143,21 @@ Built by developers tired of re-explaining context every conversation.
 - Python 3.10+
 - 5 minutes for setup
 
+## Upgrading from Earlier Versions
+
+**v2.3.7+ includes major improvements:**
+- **Privacy First**: Local embeddings by default - your data never leaves your machine
+- **Smarter Setup**: Handles existing installations gracefully
+- **Better Security**: Automated vulnerability scanning
+
+**To upgrade:**
+```bash
+npm update -g claude-self-reflect
+claude-self-reflect setup  # Re-run setup, it handles everything
+```
+
+The setup wizard now detects and fixes common upgrade issues automatically. Your existing conversations remain searchable.
+
 ## Advanced Setup
 
 Want to customize? See [Configuration Guide](docs/installation-guide.md).
@@ -208,4 +223,12 @@ Monitor the release at: https://github.com/ramakay/claude-self-reflect/actions
 
 Stop reading. Start installing. Your future self will thank you.
 
+## Contributors & Acknowledgments
+
+Special thanks to our contributors and security researchers:
+
+- **[@TheGordon](https://github.com/TheGordon)** - Fixed critical timestamp parsing bug for Claude conversation exports (#10)
+- **[@akamalov](https://github.com/akamalov)** - Highlighted Ubuntu WSL bug and helped educate about filesystem nuances
+- **[@kylesnowschwartz](https://github.com/kylesnowschwartz)** - Comprehensive security review leading to v2.3.3+ security improvements (#6)
+
 MIT License. Built with ❤️ for the Claude community.

package/installer/cli.js

@@ -118,10 +118,12 @@ function help() {
   console.log('\nSetup Options:');
   console.log('  --voyage-key=<key>   Provide Voyage AI API key (recommended)');
   console.log('  --local              Run in local mode without API key');
+  console.log('  --debug              Enable debug output for troubleshooting');
   
   console.log('\nExamples:');
   console.log('  claude-self-reflect setup --voyage-key=pa-1234567890');
   console.log('  claude-self-reflect setup --local');
+  console.log('  claude-self-reflect setup --debug  # For troubleshooting');
   
   console.log('\nFor more information: https://github.com/ramakay/claude-self-reflect');
 }

package/installer/setup-wizard.js

@@ -4,6 +4,7 @@ import { execSync, spawn, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import fs from 'fs/promises';
+import fsSync from 'fs';
 import readline from 'readline';
 import path from 'path';
 
@@ -37,16 +38,36 @@ function safeExec(command, args = [], options = {}) {
 const args = process.argv.slice(2);
 let voyageKey = null;
 let mcpConfigured = false;
+let debugMode = false;
 
 for (const arg of args) {
   if (arg.startsWith('--voyage-key=')) {
     voyageKey = arg.split('=')[1];
+  } else if (arg === '--debug') {
+    debugMode = true;
   }
 }
 
 // Default to local mode unless Voyage key is provided
 let localMode = !voyageKey;
 
+// WSL Detection
+function isWSL() {
+  try {
+    const osRelease = fsSync.readFileSync('/proc/version', 'utf8');
+    return osRelease.toLowerCase().includes('microsoft') || osRelease.toLowerCase().includes('wsl');
+  } catch {
+    return false;
+  }
+}
+
+// Debug logging helper
+function debugLog(...args) {
+  if (debugMode) {
+    console.log('[DEBUG]', ...args);
+  }
+}
+
 const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
 
 const rl = isInteractive ? readline.createInterface({
@@ -238,6 +259,12 @@ async function checkQdrant() {
 async function setupPythonEnvironment() {
   console.log('\n🐍 Setting up Python MCP server...');
   
+  // Detect WSL environment
+  if (isWSL()) {
+    console.log('🐧 WSL environment detected');
+    debugLog('Running on WSL, may need special handling');
+  }
+  
   const mcpPath = join(projectRoot, 'mcp-server');
   const scriptsPath = join(projectRoot, 'scripts');
   
@@ -245,47 +272,162 @@ async function setupPythonEnvironment() {
     // Check if venv already exists
     const venvPath = join(mcpPath, 'venv');
     let venvExists = false;
+    let venvHealthy = false;
+    let needsInstall = false;
+    
     try {
       await fs.access(venvPath);
       venvExists = true;
-      console.log('✅ Virtual environment already exists');
+      
+      // Check if existing venv is healthy
+      const venvPython = process.platform === 'win32'
+        ? join(venvPath, 'Scripts', 'python.exe')
+        : join(venvPath, 'bin', 'python');
+      
+      try {
+        // Try to run python --version to verify venv is functional
+        safeExec(venvPython, ['--version'], { stdio: 'pipe' });
+        
+        // Also check if MCP dependencies are installed
+        try {
+          safeExec(venvPython, ['-c', 'import fastmcp, qdrant_client'], { stdio: 'pipe' });
+          venvHealthy = true;
+          console.log('✅ Virtual environment already exists and is healthy');
+        } catch {
+          // Dependencies not installed, need to install them
+          console.log('⚠️  Virtual environment exists but missing dependencies');
+          needsInstall = true;
+          venvHealthy = true; // venv itself is healthy, just needs deps
+        }
+      } catch (healthError) {
+        console.log('⚠️  Existing virtual environment is corrupted');
+        console.log('   Removing and recreating...');
+        
+        // Remove broken venv
+        fsSync.rmSync(venvPath, { recursive: true, force: true });
+        venvExists = false;
+        venvHealthy = false;
+      }
     } catch {
       // venv doesn't exist, create it
     }
     
-    if (!venvExists) {
+    if (!venvExists || !venvHealthy) {
+      // Pre-flight checks before creating venv
+      console.log('Checking Python environment...');
+      const pythonCmd = process.env.PYTHON_PATH || 'python3';
+      
+      // Check if Python is available and get version
+      try {
+        const pythonVersion = safeExec(pythonCmd, ['--version'], { stdio: 'pipe' });
+        debugLog(`Python version: ${pythonVersion.trim()}`);
+      } catch (e) {
+        console.log('❌ Python not found');
+        console.log('📚 Fix: Install Python 3.10 or higher');
+        return false;
+      }
+      
+      // Check if venv module is available
+      debugLog('Checking if venv module is available...');
+      try {
+        const venvCheck = spawnSync(pythonCmd, ['-c', 'import venv; print("venv module OK")'], {
+          cwd: mcpPath,
+          encoding: 'utf8'
+        });
+        
+        if (venvCheck.status !== 0) {
+          debugLog(`venv module check failed: ${venvCheck.stderr}`);
+          
+          // WSL-specific guidance
+          if (isWSL()) {
+            console.log('\n⚠️  WSL-specific issue detected');
+            console.log('Common WSL fixes:');
+            console.log('1. Install python3-venv: sudo apt install python3.10-venv');
+            console.log('2. Use specific Python version: export PYTHON_PATH=python3.10');
+            console.log('3. Check WSL Python paths: which python3');
+          }
+          
+          throw new Error('venv module not available');
+        }
+        debugLog('venv module is available');
+      } catch (moduleError) {
+        console.log('❌ Python venv module not found');
+        console.log('📚 Fix: Install python3-venv package');
+        console.log('   Ubuntu/Debian: sudo apt install python3-venv');
+        console.log('   WSL Ubuntu: sudo apt install python3.10-venv');
+        console.log('   macOS: Should be included with Python');
+        return false;
+      }
+      
       // Create virtual environment
       console.log('Creating virtual environment...');
-      const pythonCmd = process.env.PYTHON_PATH || 'python3';
       try {
-        // Use spawn with proper path handling instead of shell execution
-        const { spawnSync } = require('child_process');
+        debugLog(`Running: ${pythonCmd} -m venv venv in ${mcpPath}`);
+        
         const result = spawnSync(pythonCmd, ['-m', 'venv', 'venv'], {
           cwd: mcpPath,
-          stdio: 'inherit'
+          encoding: 'utf8'
         });
-        if (result.error) throw result.error;
+        
+        if (result.error) {
+          debugLog(`spawnSync error: ${result.error.message}`);
+          throw result.error;
+        }
+        
+        if (result.status !== 0) {
+          debugLog(`venv creation failed with status ${result.status}`);
+          debugLog(`stdout: ${result.stdout}`);
+          debugLog(`stderr: ${result.stderr}`);
+          
+          // Check for common WSL issues
+          if (isWSL() && result.stderr && result.stderr.includes('ensurepip')) {
+            console.log('\n⚠️  WSL pip installation issue detected');
+            console.log('Try: sudo apt install python3-pip python3.10-distutils');
+          }
+          
+          throw new Error(`venv creation failed: ${result.stderr}`);
+        }
+        
+        console.log('✅ Virtual environment created');
+        needsInstall = true; // Mark that we need to install dependencies
       } catch (venvError) {
         console.log('⚠️  Failed to create venv with python3, trying python...');
         try {
-          const { spawnSync } = require('child_process');
           const result = spawnSync('python', ['-m', 'venv', 'venv'], {
             cwd: mcpPath,
-            stdio: 'inherit'
+            encoding: 'utf8'
           });
+          
           if (result.error) throw result.error;
-        } catch {
+          if (result.status !== 0) {
+            debugLog(`Python venv creation failed: ${result.stderr}`);
+            throw new Error(result.stderr);
+          }
+          
+          needsInstall = true; // Mark that we need to install dependencies
+        } catch (fallbackError) {
           console.log('❌ Failed to create virtual environment');
-          console.log('📚 Fix: Install python3-venv package');
+          
+          if (debugMode) {
+            console.log('\n🔍 Debug Information:');
+            console.log(`Error: ${fallbackError.message}`);
+            console.log(`Working directory: ${mcpPath}`);
+            console.log(`Python command: ${pythonCmd}`);
+          }
+          
+          console.log('\n📚 Troubleshooting:');
+          console.log('1. Check Python installation: python3 --version');
+          console.log('2. Install venv package:');
           console.log('   Ubuntu/Debian: sudo apt install python3-venv');
-          console.log('   macOS: Should be included with Python');
+          console.log('   WSL: sudo apt install python3.10-venv python3-pip');
+          console.log('3. Try with specific Python: PYTHON_PATH=python3.10 npm run setup');
+          
           return false;
         }
       }
     }
     
     // Setup paths for virtual environment
-    console.log('Setting up pip in virtual environment...');
     const venvPython = process.platform === 'win32'
       ? join(mcpPath, 'venv', 'Scripts', 'python.exe')
       : join(mcpPath, 'venv', 'bin', 'python');
@@ -293,15 +435,19 @@ async function setupPythonEnvironment() {
       ? join(mcpPath, 'venv', 'Scripts', 'pip.exe')
       : join(mcpPath, 'venv', 'bin', 'pip');
     
-    // First, try to install certifi to help with SSL issues
-    console.log('Installing certificate handler...');
-    try {
-      safeExec(venvPip, [
-        'install', '--trusted-host', 'pypi.org', '--trusted-host', 'files.pythonhosted.org', 'certifi'
-      ], { cwd: mcpPath, stdio: 'pipe' });
-    } catch {
-      // Continue even if certifi fails
-    }
+    // Only install dependencies if we just created a new venv
+    if (needsInstall) {
+      console.log('Setting up pip in virtual environment...');
+      
+      // First, try to install certifi to help with SSL issues
+      console.log('Installing certificate handler...');
+      try {
+        safeExec(venvPip, [
+          'install', '--trusted-host', 'pypi.org', '--trusted-host', 'files.pythonhosted.org', 'certifi'
+        ], { cwd: mcpPath, stdio: 'pipe' });
+      } catch {
+        // Continue even if certifi fails
+      }
     
     // Upgrade pip and install wheel first
     try {
@@ -369,9 +515,9 @@ async function setupPythonEnvironment() {
       }
     }
     
-    // Install script dependencies
-    console.log('Installing import script dependencies...');
-    try {
+      // Install script dependencies
+      console.log('Installing import script dependencies...');
+      try {
       safeExec(venvPip, [
         'install', '-r', join(scriptsPath, 'requirements.txt')
       ], { cwd: mcpPath, stdio: 'inherit' });
@@ -387,6 +533,7 @@ async function setupPythonEnvironment() {
         console.log('   You may need to install them manually later');
       }
     }
+    } // End of needsInstall block
     
     console.log('✅ Python environment setup complete');
     return true;
@@ -679,7 +826,7 @@ async function importConversations() {
   
   try {
     const pythonCmd = process.env.PYTHON_PATH || 'python3';
-    const importScript = join(projectRoot, 'scripts', 'import-conversations-voyage.py');
+    const importScript = join(projectRoot, 'scripts', 'import-conversations-unified.py');
     
     // Use the venv Python directly - platform specific
     let venvPython;
@@ -961,12 +1108,13 @@ async function showSystemDashboard() {
 async function setupWatcher() {
   console.log('\n⚙️  Setting up Continuous Import (Watcher)...');
   
-  const watcherScript = join(projectRoot, 'scripts', 'import-watcher.py');
+  // Check if Docker compose file exists
+  const dockerComposeFile = join(projectRoot, 'docker-compose.yaml');
   
-  // Check if watcher exists
+  // Check if Docker watcher is available
   try {
-    await fs.access(watcherScript);
-    console.log('✅ Watcher script found');
+    await fs.access(dockerComposeFile);
+    console.log('✅ Docker-based watcher available');
     
     // Watcher works with both local and cloud embeddings
     console.log(localMode ? '🏠 Watcher will use local embeddings' : '🌐 Watcher will use Voyage AI embeddings');
@@ -1079,15 +1227,15 @@ async function setupWatcher() {
         // Fallback to manual Python execution
         console.log('\n📝 To enable the watcher, run:');
         console.log('   cd claude-self-reflect');
-        console.log('   source mcp-server/venv/bin/activate');
-        console.log('   python scripts/import-watcher.py &');
+        console.log('   docker compose --profile watch up -d');
       }
     } else {
       console.log('\n📝 You can enable the watcher later by running:');
       console.log('   docker compose --profile watch up -d');
     }
   } catch {
-    console.log('⚠️  Watcher script not found');
+    console.log('⚠️  Docker compose not found');
+    console.log('   The watcher requires Docker to run continuously');
   }
 }
 

package/mcp-server/src/server.py

@@ -222,10 +222,14 @@ async def reflect_on_past(
                     
                     # Process results from native decay search
                     for point in results.points:
+                        # Clean timestamp for proper parsing
+                        raw_timestamp = point.payload.get('timestamp', datetime.now().isoformat())
+                        clean_timestamp = raw_timestamp.replace('Z', '+00:00') if raw_timestamp.endswith('Z') else raw_timestamp
+                        
                         all_results.append(SearchResult(
                             id=str(point.id),
                             score=point.score,  # Score already includes decay
-                            timestamp=point.payload.get('timestamp', datetime.now().isoformat()),
+                            timestamp=clean_timestamp,
                             role=point.payload.get('start_role', point.payload.get('role', 'unknown')),
                             excerpt=(point.payload.get('text', '')[:500] + '...'),
                             project_name=point.payload.get('project', collection_name.replace('conv_', '').replace('_voyage', '').replace('_local', '')),
@@ -283,10 +287,14 @@ async def reflect_on_past(
                     
                     # Convert to SearchResult format
                     for adjusted_score, point in decay_results[:limit]:
+                        # Clean timestamp for proper parsing
+                        raw_timestamp = point.payload.get('timestamp', datetime.now().isoformat())
+                        clean_timestamp = raw_timestamp.replace('Z', '+00:00') if raw_timestamp.endswith('Z') else raw_timestamp
+                        
                         all_results.append(SearchResult(
                             id=str(point.id),
                             score=adjusted_score,  # Use adjusted score
-                            timestamp=point.payload.get('timestamp', datetime.now().isoformat()),
+                            timestamp=clean_timestamp,
                             role=point.payload.get('start_role', point.payload.get('role', 'unknown')),
                             excerpt=(point.payload.get('text', '')[:500] + '...'),
                             project_name=point.payload.get('project', collection_name.replace('conv_', '').replace('_voyage', '').replace('_local', '')),
@@ -304,10 +312,14 @@ async def reflect_on_past(
                     )
                     
                     for point in results:
+                        # Clean timestamp for proper parsing
+                        raw_timestamp = point.payload.get('timestamp', datetime.now().isoformat())
+                        clean_timestamp = raw_timestamp.replace('Z', '+00:00') if raw_timestamp.endswith('Z') else raw_timestamp
+                        
                         all_results.append(SearchResult(
                             id=str(point.id),
                             score=point.score,
-                            timestamp=point.payload.get('timestamp', datetime.now().isoformat()),
+                            timestamp=clean_timestamp,
                             role=point.payload.get('start_role', point.payload.get('role', 'unknown')),
                             excerpt=(point.payload.get('text', '')[:500] + '...'),
                             project_name=point.payload.get('project', collection_name.replace('conv_', '').replace('_voyage', '').replace('_local', '')),
@@ -330,7 +342,9 @@ async def reflect_on_past(
         result_text = f"Found {len(all_results)} relevant conversation(s) for '{query}':\n\n"
         for i, result in enumerate(all_results):
             result_text += f"**Result {i+1}** (Score: {result.score:.3f})\n"
-            result_text += f"Time: {datetime.fromisoformat(result.timestamp).strftime('%Y-%m-%d %H:%M:%S')}\n"
+            # Handle timezone suffix 'Z' properly
+            timestamp_clean = result.timestamp.replace('Z', '+00:00') if result.timestamp.endswith('Z') else result.timestamp
+            result_text += f"Time: {datetime.fromisoformat(timestamp_clean).strftime('%Y-%m-%d %H:%M:%S')}\n"
             result_text += f"Project: {result.project_name}\n"
             result_text += f"Role: {result.role}\n"
             result_text += f"Excerpt: {result.excerpt}\n"
@@ -400,4 +414,4 @@ async def store_reflection(
 
 
 # Debug output
-print(f"[DEBUG] FastMCP server created with name: {mcp.name}")
+print(f"[DEBUG] FastMCP server created with name: {mcp.name}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-self-reflect",
-  "version": "2.3.7",
+  "version": "2.3.9",
   "description": "Give Claude perfect memory of all your conversations - Installation wizard for Python MCP server",
   "keywords": [
     "claude",
@@ -47,4 +47,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}