claude-self-reflect 2.4.13 → 2.4.15

package/.claude/agents/open-source-maintainer.md

@@ -175,20 +175,76 @@ safety check -r mcp-server/requirements.txt
 # For Node: npm test
 ```
 
-#### 5. Release Creation
+#### 4.5. Create Professional Release Notes
 ```bash
+# Create release notes file
+VERSION=$(node -p "require('./package.json').version")
+cat > docs/RELEASE_NOTES_v${VERSION}.md << 'EOF'
+# Release Notes - v${VERSION}
+
+## Summary
+Brief description of what this release addresses and why it matters.
+
+## Changes
+
+### Bug Fixes
+- Fixed global npm installation failing due to Docker build context issues (#13)
+  - Modified Dockerfile.importer to embed Python dependencies directly
+  - Removed dependency on external requirements.txt file during build
+  - Ensures compatibility with both local development and global npm installations
+
+### Technical Details
+- Files modified:
+  - `Dockerfile.importer`: Embedded Python dependencies inline
+  - Removed COPY instruction for scripts that are volume-mounted at runtime
+
+### Verification
+- Docker builds tested successfully in isolation
+- Import process verified to skip already imported files
+- Both local and global npm installation paths validated
+
+## Installation
+```bash
+npm install -g claude-self-reflect@${VERSION}
+```
+
+## Contributors
+Thank you to everyone who reported issues and helped test this release:
+- @mattias012 - Reported npm global installation issue
+- @vbp1 - Confirmed Docker setup problems
+
+## Related Issues
+- Resolves #13: Global npm installation Docker build failures
+EOF
+```
+
+#### 5. Version Bump & Release Creation
+```bash
+# Update package.json version BEFORE creating tag
+# Determine version bump type based on changes:
+# - patch: bug fixes, minor updates (2.4.10 -> 2.4.11)
+# - minor: new features, non-breaking changes (2.4.10 -> 2.5.0)
+# - major: breaking changes (2.4.10 -> 3.0.0)
+npm version patch --no-git-tag-version  # Updates package.json and package-lock.json
+
+# Commit version bump
+VERSION=$(node -p "require('./package.json').version")
+git add package.json package-lock.json
+git commit -m "chore: bump version to ${VERSION} for release"
+git push origin main
+
 # Create and push tag
-git tag -a vX.Y.Z -m "Release vX.Y.Z - Brief description"
-git push origin vX.Y.Z
+git tag -a v${VERSION} -m "Release v${VERSION} - Brief description"
+git push origin v${VERSION}
 
 # Create GitHub release
-gh release create vX.Y.Z \
-  --title "vX.Y.Z - Release Title" \
-  --notes-file docs/RELEASE_NOTES_vX.Y.Z.md \
+gh release create v${VERSION} \
+  --title "v${VERSION} - Release Title" \
+  --notes-file docs/RELEASE_NOTES_v${VERSION}.md \
   --target main
 
 # Monitor the release workflow
-echo "🚀 Release created! Monitoring automated publishing..."
+echo "Release created! Monitoring automated publishing..."
 gh run list --workflow "CI/CD Pipeline" --limit 1
 gh run watch
 ```
@@ -207,7 +263,7 @@ echo "⏳ Waiting for automated npm publish..."
 # Monitor the release workflow until npm publish completes
 ```
 
-#### 7. Post-Release Verification
+#### 7. Post-Release Verification & Issue Management
 ```bash
 # Verify GitHub release
 gh release view vX.Y.Z
@@ -217,6 +273,36 @@ npm view claude-self-reflect version
 
 # Check that related PRs are closed
 gh pr list --state closed --limit 10
+
+# Handle related issues professionally
+# For each issue addressed in this release:
+ISSUE_NUMBER=13  # Example
+VERSION=$(node -p "require('./package.json').version")
+
+# Determine if issue should be closed or kept open
+# Close if: bug fixed, feature implemented, question answered
+# Keep open if: partial fix, needs more work, ongoing discussion
+
+# Professional comment template (no emojis, clear references)
+gh issue comment $ISSUE_NUMBER --body "Thank you for reporting this issue. The global npm installation problem has been addressed in release v${VERSION}.
+
+The fix involved modifying the Docker build process to embed dependencies directly:
+- Modified: Dockerfile.importer - Embedded Python dependencies to avoid file path issues
+- Verified: Docker builds work correctly without requiring scripts directory in build context
+- Tested: Import process correctly skips already imported files
+
+You can update to the latest version with:
+\`\`\`bash
+npm install -g claude-self-reflect@${VERSION}
+\`\`\`
+
+Please let us know if you encounter any issues with the new version."
+
+# Close the issue if fully resolved
+gh issue close $ISSUE_NUMBER --comment "Closing as resolved in v${VERSION}. Feel free to reopen if you encounter any related issues."
+
+# Or keep open with status update if partially resolved
+# gh issue comment $ISSUE_NUMBER --body "Partial fix implemented in v${VERSION}. Keeping this issue open to track remaining work on [specific aspect]."
 ```
 
 #### 8. Rollback Procedures

package/Dockerfile.watcher

@@ -20,12 +20,19 @@ RUN pip install --no-cache-dir \
 # Create non-root user
 RUN useradd -m -u 1000 watcher
 
+# Pre-download FastEmbed model to avoid runtime downloads
+RUN mkdir -p /home/watcher/.cache && \
+    FASTEMBED_CACHE_PATH=/home/watcher/.cache/fastembed python -c "from fastembed import TextEmbedding; import os; os.environ['FASTEMBED_CACHE_PATH']='/home/watcher/.cache/fastembed'; TextEmbedding('sentence-transformers/all-MiniLM-L6-v2')" && \
+    chown -R watcher:watcher /home/watcher/.cache
+
 # Create scripts directory and copy required files
 RUN mkdir -p /scripts
 
 # Copy all necessary scripts
 COPY scripts/import-conversations-unified.py /scripts/
 COPY scripts/import-watcher.py /scripts/
+COPY scripts/utils.py /scripts/
+COPY scripts/trigger-import.py /scripts/
 
 RUN chmod +x /scripts/*.py
 

package/README.md

@@ -203,6 +203,10 @@ Recent conversations matter more. Old ones fade. Like your brain, but reliable.
 
 Works perfectly out of the box. [Configure if you're particular](docs/memory-decay.md).
 
+## Theoretical Foundation
+
+Claude Self-Reflect addresses the "reality gap" in AI memory systems - the distance between perfect recall expectations and practical utility. Our approach aligns with the SPAR Framework (Sense, Plan, Act, Reflect) for agentic AI systems. [Learn more about our design philosophy](docs/architecture/SPAR-alignment.md).
+
 ## For the Skeptics
 
 **"Just use grep"** - Sure, enjoy your 10,000 matches for "database"  
@@ -372,4 +376,19 @@ Special thanks to our contributors and security researchers:
 - **[@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)
 
+## Windows Configuration
+
+### Recommended: Use WSL
+For the best experience on Windows, we recommend using WSL (Windows Subsystem for Linux) which provides native Linux compatibility for Docker operations.
+
+### Alternative: Native Windows
+If using Docker Desktop on native Windows, you need to adjust the CONFIG_PATH in your `.env` file to use Docker-compatible paths:
+
+```bash
+# Replace USERNAME with your Windows username
+CONFIG_PATH=/c/Users/USERNAME/.claude-self-reflect/config
+```
+
+This ensures Docker can properly mount the config directory. The setup wizard creates the directory, but Windows users need to update the path format for Docker compatibility.
+
 MIT License. Built with ❤️ for the Claude community.

package/docker-compose.yaml

@@ -7,7 +7,7 @@ services:
     image: alpine
     command: chown -R 1000:1000 /config
     volumes:
-      - ./config:/config
+      - ${CONFIG_PATH:-~/.claude-self-reflect/config}:/config
     profiles: ["watch", "mcp", "import"]
 
   # Qdrant vector database - the heart of semantic search
@@ -22,8 +22,8 @@ services:
       - QDRANT__LOG_LEVEL=INFO
       - QDRANT__SERVICE__HTTP_PORT=6333
     restart: unless-stopped
-    mem_limit: ${QDRANT_MEMORY:-1g}
-    memswap_limit: ${QDRANT_MEMORY:-1g}
+    mem_limit: ${QDRANT_MEMORY:-2g}
+    memswap_limit: ${QDRANT_MEMORY:-2g}
 
   # One-time import service (runs once then exits)
   importer:
@@ -36,7 +36,7 @@ services:
       - qdrant
     volumes:
       - ${CLAUDE_LOGS_PATH:-~/.claude/projects}:/logs:ro
-      - ./config:/config
+      - ${CONFIG_PATH:-~/.claude-self-reflect/config}:/config
       - ./scripts:/scripts:ro
     environment:
       - QDRANT_URL=http://qdrant:6333
@@ -64,8 +64,9 @@ services:
       - qdrant
     volumes:
       - ${CLAUDE_LOGS_PATH:-~/.claude/projects}:/logs:ro
-      - ./config:/config
+      - ${CONFIG_PATH:-~/.claude-self-reflect/config}:/config
       - ./scripts:/scripts:ro
+      - /tmp:/tmp
     environment:
       - QDRANT_URL=http://qdrant:6333
       - STATE_FILE=/config/imported-files.json
@@ -78,8 +79,8 @@ services:
       - PYTHONUNBUFFERED=1
     restart: unless-stopped
     profiles: ["watch"]
-    mem_limit: 2g
-    memswap_limit: 2g
+    mem_limit: 1g
+    memswap_limit: 1g
 
   # MCP server for Claude integration
   mcp-server:

package/installer/setup-wizard-docker.js

@@ -7,6 +7,7 @@ import fs from 'fs/promises';
 import fsSync from 'fs';
 import readline from 'readline';
 import path from 'path';
+import os from 'os';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -94,6 +95,40 @@ async function checkDocker() {
 async function configureEnvironment() {
   console.log('\n🔐 Configuring environment...');
   
+  // Setup config directory in user's home directory for global npm installs
+  const userConfigDir = join(os.homedir(), '.claude-self-reflect', 'config');
+  
+  try {
+    await fs.mkdir(userConfigDir, { recursive: true });
+    console.log(`📁 Using config directory: ${userConfigDir}`);
+    
+    // Migrate existing config from project directory if it exists
+    const oldConfigDir = join(projectRoot, 'config');
+    try {
+      await fs.access(oldConfigDir);
+      const files = await fs.readdir(oldConfigDir);
+      if (files.length > 0) {
+        console.log('🔄 Migrating existing config data...');
+        for (const file of files) {
+          const sourcePath = join(oldConfigDir, file);
+          const targetPath = join(userConfigDir, file);
+          try {
+            await fs.copyFile(sourcePath, targetPath);
+          } catch (err) {
+            // Ignore copy errors, file might already exist
+          }
+        }
+        console.log('✅ Config migration completed');
+      }
+    } catch {
+      // No old config directory, nothing to migrate
+    }
+  } catch (error) {
+    console.log(`❌ Could not create config directory: ${error.message}`);
+    console.log('   This may cause Docker mount issues. Please check permissions.');
+    throw error;
+  }
+  
   const envPath = join(projectRoot, '.env');
   let envContent = '';
   let hasValidApiKey = false;
@@ -153,6 +188,9 @@ async function configureEnvironment() {
   if (!envContent.includes('PREFER_LOCAL_EMBEDDINGS=')) {
     envContent += `PREFER_LOCAL_EMBEDDINGS=${localMode ? 'true' : 'false'}\n`;
   }
+  if (!envContent.includes('CONFIG_PATH=')) {
+    envContent += `CONFIG_PATH=${userConfigDir}\n`;
+  }
   
   await fs.writeFile(envPath, envContent.trim() + '\n');
   console.log('✅ Environment configured');

package/mcp-server/src/server.py

@@ -11,6 +11,7 @@ import hashlib
 import time
 
 from fastmcp import FastMCP, Context
+from .utils import normalize_project_name
 from pydantic import BaseModel, Field
 from qdrant_client import AsyncQdrantClient, models
 from qdrant_client.models import (
@@ -233,8 +234,9 @@ async def reflect_on_past(
         # Filter collections by project if not searching all
         project_collections = []  # Define at this scope for later use
         if target_project != 'all':
-            # Generate the collection name pattern for this project
-            project_hash = hashlib.md5(target_project.encode()).hexdigest()[:8]
+            # Generate the collection name pattern for this project using normalized name
+            normalized_name = normalize_project_name(target_project)
+            project_hash = hashlib.md5(normalized_name.encode()).hexdigest()[:8]
             project_collections = [
                 c for c in all_collections 
                 if c.startswith(f"conv_{project_hash}_")

package/mcp-server/src/utils.py

@@ -0,0 +1,53 @@
+"""Shared utilities for claude-self-reflect MCP server and scripts."""
+
+from pathlib import Path
+
+
+def normalize_project_name(project_path: str) -> str:
+    """
+    Normalize project name for consistent hashing across import/search.
+    
+    Handles various path formats:
+    - Claude logs format: -Users-kyle-Code-claude-self-reflect -> claude-self-reflect
+    - Regular paths: /path/to/project -> project
+    - Already normalized: project -> project
+    
+    Args:
+        project_path: Project path or name in any format
+        
+    Returns:
+        Normalized project name suitable for consistent hashing
+    """
+    if not project_path:
+        return ""
+    
+    # Remove trailing slashes
+    project_path = project_path.rstrip('/')
+    
+    # Handle Claude logs format (starts with dash)
+    if project_path.startswith('-'):
+        # For paths like -Users-kyle-Code-claude-self-reflect
+        # We want to extract the actual project name which may contain dashes
+        # Strategy: Find common parent directories and extract what comes after
+        
+        # Remove leading dash and convert back to path-like format
+        path_str = project_path[1:].replace('-', '/')
+        path_parts = Path(path_str).parts
+        
+        # Look for common project parent directories
+        project_parents = {'projects', 'code', 'Code', 'repos', 'repositories', 
+                          'dev', 'Development', 'work', 'src', 'github'}
+        
+        # Find the project name after a known parent directory
+        for i, part in enumerate(path_parts):
+            if part.lower() in project_parents and i + 1 < len(path_parts):
+                # Everything after the parent directory is the project name
+                # Join remaining parts with dash if project name has multiple components
+                remaining = path_parts[i + 1:]
+                return '-'.join(remaining)
+        
+        # Fallback: just use the last component
+        return path_parts[-1] if path_parts else project_path
+    
+    # Handle regular paths - use basename
+    return Path(project_path).name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-self-reflect",
-  "version": "2.4.13",
+  "version": "2.4.15",
   "description": "Give Claude perfect memory of all your conversations - Installation wizard for Python MCP server",
   "keywords": [
     "claude",

package/scripts/import-conversations-unified.py

@@ -14,6 +14,10 @@ from typing import List, Dict, Any
 import logging
 from pathlib import Path
 
+# Add the mcp-server/src directory to the Python path
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'mcp-server', 'src'))
+from utils import normalize_project_name
+
 from qdrant_client import QdrantClient
 from qdrant_client.models import (
     VectorParams, Distance, PointStruct,
@@ -29,7 +33,9 @@ from tenacity import (
 # Configuration
 QDRANT_URL = os.getenv("QDRANT_URL", "http://localhost:6333")
 LOGS_DIR = os.getenv("LOGS_DIR", "/logs")
-STATE_FILE = os.getenv("STATE_FILE", "/config/imported-files.json")
+# Default to project config directory for state file
+default_state_file = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "config", "imported-files.json")
+STATE_FILE = os.getenv("STATE_FILE", default_state_file)
 BATCH_SIZE = int(os.getenv("BATCH_SIZE", "10"))  # Reduced from 100 to prevent OOM
 PREFER_LOCAL_EMBEDDINGS = os.getenv("PREFER_LOCAL_EMBEDDINGS", "false").lower() == "true"
 VOYAGE_API_KEY = os.getenv("VOYAGE_KEY")
@@ -343,10 +349,11 @@ def main():
     # Import each project
     total_imported = 0
     for project_dir in project_dirs:
-        # Create collection name from project path
-        collection_name = f"conv_{hashlib.md5(project_dir.name.encode()).hexdigest()[:8]}{collection_suffix}"
+        # Create collection name from normalized project name
+        normalized_name = normalize_project_name(project_dir.name)
+        collection_name = f"conv_{hashlib.md5(normalized_name.encode()).hexdigest()[:8]}{collection_suffix}"
         
-        logger.info(f"Importing project: {project_dir.name} -> {collection_name}")
+        logger.info(f"Importing project: {project_dir.name} (normalized: {normalized_name}) -> {collection_name}")
         chunks = import_project(project_dir, collection_name, state)
         total_imported += chunks
         logger.info(f"Imported {chunks} chunks from {project_dir.name}")

package/scripts/import-watcher.py

@@ -1,33 +1,88 @@
 #!/usr/bin/env python3
-"""Simple watcher that runs import periodically."""
+"""Enhanced watcher that runs import periodically and supports manual triggers."""
 
 import time
 import subprocess
 import os
 import sys
 from datetime import datetime
+from pathlib import Path
 
 WATCH_INTERVAL = int(os.getenv('WATCH_INTERVAL', '60'))
+SIGNAL_FILE = Path("/tmp/claude-self-reflect-import-current")
+CHECK_INTERVAL = 1  # Check for signal file every second
 
-print(f"[Watcher] Starting import watcher with {WATCH_INTERVAL}s interval", flush=True)
+print(f"[Watcher] Starting enhanced import watcher with {WATCH_INTERVAL}s interval", flush=True)
+print(f"[Watcher] Monitoring signal file: {SIGNAL_FILE}", flush=True)
+
+last_import = 0
 
 while True:
-    try:
-        print(f"[Watcher] Running import at {datetime.now().isoformat()}", flush=True)
-        result = subprocess.run([
-            sys.executable, 
-            "/scripts/import-conversations-unified.py"
-        ], capture_output=True, text=True)
-        
-        if result.returncode == 0:
-            print(f"[Watcher] Import completed successfully", flush=True)
-        else:
-            print(f"[Watcher] Import failed with code {result.returncode}", flush=True)
-            if result.stderr:
-                print(f"[Watcher] Error: {result.stderr}", flush=True)
-                
-    except Exception as e:
-        print(f"[Watcher] Error: {e}", flush=True)
+    current_time = time.time()
+    
+    # Check for manual trigger signal
+    if SIGNAL_FILE.exists():
+        print(f"[Watcher] Signal detected! Running immediate import...", flush=True)
+        try:
+            # Read conversation ID if provided
+            conversation_id = None
+            try:
+                conversation_id = SIGNAL_FILE.read_text().strip()
+            except:
+                pass
+            
+            # Remove signal file to prevent re-triggering
+            SIGNAL_FILE.unlink()
+            
+            # Run import with special flag for current conversation only
+            cmd = [sys.executable, "/scripts/import-conversations-unified.py"]
+            if conversation_id:
+                cmd.extend(["--conversation-id", conversation_id])
+            else:
+                # Import only today's conversations for manual trigger
+                cmd.extend(["--days", "1"])
+            
+            # Write progress indicator
+            progress_file = Path("/tmp/claude-self-reflect-import-progress")
+            progress_file.write_text("🔄 Starting import...")
+            
+            print(f"[Watcher] Running command: {' '.join(cmd)}", flush=True)
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            
+            if result.returncode == 0:
+                print(f"[Watcher] Manual import completed successfully", flush=True)
+                # Create completion signal
+                Path("/tmp/claude-self-reflect-import-complete").touch()
+            else:
+                print(f"[Watcher] Manual import failed with code {result.returncode}", flush=True)
+                if result.stderr:
+                    print(f"[Watcher] Error: {result.stderr}", flush=True)
+            
+            last_import = current_time
+                    
+        except Exception as e:
+            print(f"[Watcher] Error during manual import: {e}", flush=True)
+    
+    # Regular scheduled import
+    elif current_time - last_import >= WATCH_INTERVAL:
+        try:
+            print(f"[Watcher] Running scheduled import at {datetime.now().isoformat()}", flush=True)
+            result = subprocess.run([
+                sys.executable, 
+                "/scripts/import-conversations-unified.py"
+            ], capture_output=True, text=True)
+            
+            if result.returncode == 0:
+                print(f"[Watcher] Scheduled import completed successfully", flush=True)
+            else:
+                print(f"[Watcher] Scheduled import failed with code {result.returncode}", flush=True)
+                if result.stderr:
+                    print(f"[Watcher] Error: {result.stderr}", flush=True)
+            
+            last_import = current_time
+                    
+        except Exception as e:
+            print(f"[Watcher] Error during scheduled import: {e}", flush=True)
     
-    print(f"[Watcher] Sleeping for {WATCH_INTERVAL} seconds...", flush=True)
-    time.sleep(WATCH_INTERVAL)
+    # Short sleep to check for signals frequently
+    time.sleep(CHECK_INTERVAL)