claude-self-reflect 2.4.1 → 2.4.3

package/.claude/agents/reflection-specialist.md

@@ -41,7 +41,7 @@ You are a conversation memory specialist for the Claude Self Reflect project. Yo
 Search for relevant past conversations using semantic similarity.
 
 ```javascript
-// Basic search
+// Basic search (searches current project by default)
 {
   query: "streaming importer fixes",
   limit: 5,
@@ -55,8 +55,29 @@ Search for relevant past conversations using semantic similarity.
   min_score: 0.05,  // Common threshold for relevant results
   use_decay: 1  // Apply time-based relevance (1=enable, 0=disable, -1=default)
 }
+
+// Search specific project (NEW in v2.4.3)
+{
+  query: "Docker setup",
+  project: "ShopifyMCPMockShop",  // Use actual folder name
+  limit: 5
+}
+
+// Cross-project search (NEW in v2.4.3)
+{
+  query: "error handling patterns",
+  project: "all",  // Search across all projects
+  limit: 10
+}
 ```
 
+#### Default Behavior: Project-Scoped Search (NEW in v2.4.3)
+**IMPORTANT**: Searches are now scoped to the current project by default:
+- Auto-detects current project from your working directory
+- Only returns results from that project unless you specify otherwise
+- Use `project: "all"` to explicitly search across all projects
+- Use `project: "ProjectName"` to search a specific project (use the actual folder name)
+
 ### store_reflection
 Save important insights and decisions for future retrieval.
 

package/.env.example

@@ -0,0 +1,29 @@
+# Claude Self-Reflect Environment Variables
+# Copy this file to .env and update with your values
+
+# Voyage AI API Key (optional - only needed for cloud mode)
+# Get your key at: https://www.voyageai.com/
+VOYAGE_KEY=your-voyage-api-key-here
+
+# Qdrant Configuration
+QDRANT_URL=http://localhost:6333
+
+# Embedding Configuration
+# Set to true to use local embeddings (default)
+# Set to false to use Voyage AI embeddings (requires VOYAGE_KEY)
+PREFER_LOCAL_EMBEDDINGS=true
+
+# Memory Decay Configuration (optional)
+ENABLE_MEMORY_DECAY=true
+DECAY_WEIGHT=0.3
+DECAY_SCALE_DAYS=90
+
+# Import Configuration (optional)
+BATCH_SIZE=50
+CHUNK_SIZE=10
+WATCH_INTERVAL=60
+
+# Docker Memory Limits
+# Increase if processing large conversation files
+WATCHER_MEM_LIMIT=2g
+QDRANT_MEM_LIMIT=1g

package/Dockerfile.importer

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY scripts/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy only the unified import script
+COPY scripts/import-conversations-unified.py .
+
+# Run the unified importer
+CMD ["python", "import-conversations-unified.py"]

package/Dockerfile.importer-isolated

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+RUN pip install --no-cache-dir \
+    qdrant-client \
+    sentence-transformers \
+    numpy
+
+# Copy the import script with proper permissions
+COPY scripts/import-conversations-isolated.py /app/import.py
+RUN chmod +x /app/import.py
+
+WORKDIR /app
+
+# Run the import script
+CMD ["python", "import.py"]

package/Dockerfile.mcp-server

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy the MCP server package files
+COPY mcp-server/pyproject.toml ./
+COPY mcp-server/src ./src
+
+# Install the package in development mode
+RUN pip install --no-cache-dir -e .
+
+# Create a non-root user
+RUN useradd -m -u 1000 mcpuser
+USER mcpuser
+
+# Keep the container running and wait for docker exec commands
+CMD ["tail", "-f", "/dev/null"]

package/Dockerfile.streaming-importer

@@ -0,0 +1,30 @@
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies with specific versions for stability
+# Install torch first from PyTorch index
+RUN pip install --no-cache-dir torch==2.0.1 --index-url https://download.pytorch.org/whl/cpu
+
+# Install other dependencies from default PyPI
+RUN pip install --no-cache-dir \
+    qdrant-client==1.15.0 \
+    sentence-transformers==2.2.2 \
+    numpy==1.24.3 \
+    psutil==5.9.5
+
+# Create non-root user
+RUN useradd -m -u 1000 importer
+
+# Set working directory
+WORKDIR /app
+
+# Switch to non-root user
+USER importer
+
+# Default command
+CMD ["python", "/scripts/streaming-importer.py"]

package/Dockerfile.watcher

@@ -0,0 +1,53 @@
+FROM python:3.11-slim
+
+# Install build dependencies for psutil
+RUN apt-get update && apt-get install -y \
+    gcc \
+    python3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+RUN pip install --no-cache-dir \
+    psutil==5.9.5 \
+    qdrant-client>=1.7.0 \
+    openai>=1.0.0 \
+    backoff>=2.2.0 \
+    requests>=2.31.0 \
+    tqdm>=4.66.0 \
+    voyageai>=0.2.0 \
+    fastembed>=0.4.0
+
+# Create non-root user
+RUN useradd -m -u 1000 watcher
+
+# Create scripts directory and copy required files
+RUN mkdir -p /scripts
+
+# Copy the unified import script and create a simple watcher
+COPY scripts/import-conversations-unified.py /scripts/
+
+# Create a minimal watcher script
+RUN echo '#!/usr/bin/env python3\n\
+import time\n\
+import subprocess\n\
+import os\n\
+\n\
+while True:\n\
+    try:\n\
+        print("Running import...", flush=True)\n\
+        subprocess.run(["/usr/local/bin/python", "/scripts/import-conversations-unified.py"], check=True)\n\
+        print("Import complete. Sleeping for 60 seconds...", flush=True)\n\
+    except Exception as e:\n\
+        print(f"Error: {e}", flush=True)\n\
+    time.sleep(60)\n' > /scripts/import-watcher.py
+
+RUN chmod +x /scripts/*.py
+
+# Set working directory
+WORKDIR /app
+
+# Switch to non-root user
+USER watcher
+
+# Default command
+CMD ["python", "/scripts/import-watcher.py"]

package/README.md

@@ -20,6 +20,12 @@ The reflection specialist is a specialized sub-agent that Claude automatically s
 
 Your conversations become searchable. Your decisions stay remembered. Your context persists.
 
+## Requirements
+
+- **Docker Desktop** (macOS/Windows) or **Docker Engine** (Linux)
+- **Node.js** 16+ (for the setup wizard)
+- **Claude Desktop** app
+
 ## Install
 
 ### Quick Start (Local Mode - Default)
@@ -29,11 +35,14 @@ npm install -g claude-self-reflect
 claude-self-reflect setup
 
 # That's it! The setup will:
+# ✅ Run everything in Docker (no Python issues!)
 # ✅ Configure everything automatically
 # ✅ Install the MCP in Claude Code  
 # ✅ Start monitoring for new conversations
 # ✅ Verify the reflection tools work
 # 🔒 Keep all data local - no API keys needed
+# 🚀 Import watcher runs every 60 seconds
+# ⚡ Memory decay enabled by default (90-day half-life)
 ```
 
 ### Cloud Mode (Better Search Accuracy)
@@ -114,6 +123,30 @@ Once installed, just talk naturally:
 
 The reflection specialist automatically activates. No special commands needed.
 
+## Project-Scoped Search (New in v2.4.3)
+
+Searches are now **project-aware by default**. When you ask about past conversations, Claude automatically searches within your current project:
+
+```
+# In project "ShopifyMCPMockShop"
+You: "What authentication method did we implement?"
+Claude: [Searches only ShopifyMCPMockShop conversations]
+
+# Need to search across all projects?
+You: "Search all projects for WebSocket implementations"
+Claude: [Searches across all your projects]
+
+# Search a specific project
+You: "Find Docker setup discussions in claude-self-reflect project"
+Claude: [Searches only claude-self-reflect conversations]
+```
+
+**Key behaviors:**
+- **Default**: Searches current project based on your working directory
+- **Cross-project**: Ask for "all projects" or "across projects" 
+- **Specific project**: Mention the project name explicitly
+- **Privacy**: Each project's conversations remain isolated
+
 ## Memory Decay
 
 Recent conversations matter more. Old ones fade. Like your brain, but reliable.
@@ -131,15 +164,19 @@ Built by developers tired of re-explaining context every conversation.
 ## Requirements
 
 - Claude Code or Claude Desktop
-- Python 3.10+
+- Docker Desktop (macOS/Windows) or Docker Engine (Linux)
+- Node.js 16+ (for the setup wizard only)
 - 5 minutes for setup
 
 ## Upgrading from Earlier Versions
 
-**v2.3.7+ includes major improvements:**
+**v2.4.0+ includes major improvements:**
+- **Docker-Only Setup**: No more Python environment issues!
 - **Privacy First**: Local embeddings by default - your data never leaves your machine
 - **Smarter Setup**: Handles existing installations gracefully
 - **Better Security**: Automated vulnerability scanning
+- **Real-Time Import**: Watcher checks for new conversations every 60 seconds
+- **Fixed MCP Server**: Now uses correct server implementation with local embedding support
 
 **To upgrade:**
 ```bash

package/docker-compose.yaml

@@ -0,0 +1,98 @@
+volumes:
+  qdrant_data:
+
+services:
+  # Qdrant vector database - the heart of semantic search
+  qdrant:
+    image: qdrant/qdrant:v1.15.1
+    container_name: claude-reflection-qdrant
+    ports:
+      - "${QDRANT_PORT:-6333}:6333"
+    volumes:
+      - qdrant_data:/qdrant/storage
+    environment:
+      - QDRANT__LOG_LEVEL=INFO
+      - QDRANT__SERVICE__HTTP_PORT=6333
+    restart: unless-stopped
+    mem_limit: ${QDRANT_MEMORY:-1g}
+    memswap_limit: ${QDRANT_MEMORY:-1g}
+
+  # One-time import service (runs once then exits)
+  importer:
+    build:
+      context: .
+      dockerfile: Dockerfile.importer
+    container_name: claude-reflection-importer
+    depends_on:
+      - qdrant
+    volumes:
+      - ${CLAUDE_LOGS_PATH:-~/.claude/projects}:/logs:ro
+      - ./config:/config
+      - ./scripts:/scripts:ro
+    environment:
+      - QDRANT_URL=http://qdrant:6333
+      - STATE_FILE=/config/imported-files.json
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - VOYAGE_API_KEY=${VOYAGE_API_KEY:-}
+      - VOYAGE_KEY=${VOYAGE_KEY:-}
+      - PREFER_LOCAL_EMBEDDINGS=${PREFER_LOCAL_EMBEDDINGS:-false}
+      - EMBEDDING_MODEL=${EMBEDDING_MODEL:-voyage-3}
+      - BATCH_SIZE=${BATCH_SIZE:-50}
+      - CHUNK_SIZE=${CHUNK_SIZE:-10}
+      - PYTHONUNBUFFERED=1
+    restart: "no"
+    profiles: ["import"]
+    command: python /scripts/import-conversations-unified.py
+
+  # Continuous watcher service (optional)
+  watcher:
+    build:
+      context: .
+      dockerfile: Dockerfile.watcher
+    container_name: claude-reflection-watcher
+    depends_on:
+      - qdrant
+    volumes:
+      - ${CLAUDE_LOGS_PATH:-~/.claude/projects}:/logs:ro
+      - ./config:/config
+      - ./scripts:/scripts:ro
+    environment:
+      - QDRANT_URL=http://qdrant:6333
+      - STATE_FILE=/config/imported-files.json
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - VOYAGE_API_KEY=${VOYAGE_API_KEY:-}
+      - VOYAGE_KEY=${VOYAGE_KEY:-}
+      - PREFER_LOCAL_EMBEDDINGS=${PREFER_LOCAL_EMBEDDINGS:-false}
+      - EMBEDDING_MODEL=${EMBEDDING_MODEL:-voyage-3}
+      - WATCH_INTERVAL=${WATCH_INTERVAL:-60}
+      - PYTHONUNBUFFERED=1
+    restart: unless-stopped
+    profiles: ["watch"]
+    mem_limit: 2g
+    memswap_limit: 2g
+
+  # MCP server for Claude integration
+  mcp-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.mcp-server
+    container_name: claude-reflection-mcp
+    depends_on:
+      - qdrant
+    environment:
+      - QDRANT_URL=http://qdrant:6333
+      - VOYAGE_KEY=${VOYAGE_KEY:-}
+      - PREFER_LOCAL_EMBEDDINGS=${PREFER_LOCAL_EMBEDDINGS:-true}
+      - ENABLE_MEMORY_DECAY=${ENABLE_MEMORY_DECAY:-true}
+      - DECAY_WEIGHT=${DECAY_WEIGHT:-0.3}
+      - DECAY_SCALE_DAYS=${DECAY_SCALE_DAYS:-90}
+      - PYTHONUNBUFFERED=1
+    restart: unless-stopped
+    stdin_open: true
+    tty: true
+    profiles: ["mcp"]
+
+networks:
+  default:
+    name: claude-reflection-network
+    external: false