claude-self-reflect 2.4.5 → 2.4.7

package/README.md

@@ -123,21 +123,27 @@ Once installed, just talk naturally:
 
 The reflection specialist automatically activates. No special commands needed.
 
-## Performance & Usage Guide (v2.4.5)
+## Performance & Usage Guide
 
-### 🚀 10-40x Faster Performance
-Search response times improved from 28.9s-2min down to **200-350ms** through optimizations:
-- Compressed XML response format (40% smaller)
-- Optimized excerpts (350 chars for context, 100 chars in brief mode)
-- Smart defaults (5 results to avoid missing relevant conversations)
+### 🚀 Lightning Fast Search
+Optimized to deliver results in **200-350ms** (10-40x faster than v2.4.4)
 
 ### 🎯 Recommended Usage: Through Reflection-Specialist Agent
 
 **Why use the agent instead of direct MCP tools?**
-- Rich formatted responses with analysis and insights
-- Proper handling of specialized search tools
-- Better user experience with streaming feedback
-- Automatic cross-project search suggestions
+- **Preserves your main conversation context** - Search results don't clutter your working memory
+- **Rich formatted responses** - Clean markdown instead of raw XML in your conversation
+- **Better user experience** - Real-time streaming feedback and progress indicators
+- **Proper tool counting** - Shows actual tool usage instead of "0 tool uses"
+- **Automatic cross-project search** - Agent suggests searching across projects when relevant
+- **Specialized search tools** - Access to quick_search, search_summary, and pagination
+
+**Context Preservation Benefit:**
+When you use the reflection-specialist agent, all the search results and processing happen in an isolated context. This means:
+- Your main conversation stays clean and focused
+- No XML dumps or raw data in your chat history
+- Multiple searches won't exhaust your context window
+- You get just the insights, not the implementation details
 
 **Example:**
 ```
@@ -147,61 +153,40 @@ You: "What Docker issues did we solve?"
   ⎿ Searching 57 collections...
   ⎿ Found 5 relevant conversations
   ⎿ Done (1 tool use · 12k tokens · 2.3s)
+[Returns clean, formatted insights without cluttering your context]
 ```
 
 ### ⚡ Performance Baselines
 
-| Method | Search Time | Total Time | Best For |
-|--------|------------|------------|----------|
-| Direct MCP | 200-350ms | 200-350ms | Programmatic use, integrations |
-| Via Agent | 200-350ms | 2-3s | Interactive use, rich analysis |
+| Method | Search Time | Total Time | Context Impact | Best For |
+|--------|------------|------------|----------------|----------|
+| Direct MCP | 200-350ms | 200-350ms | Uses main context | Programmatic use, when context space matters |
+| Via Agent | 200-350ms | 24-30s* | Isolated context | Interactive use, exploration, multiple searches |
 
-**Note**: The specialized tools (`quick_search`, `search_summary`, `get_more_results`) only work through the reflection-specialist agent due to MCP protocol limitations.
-
-## Project-Scoped Search (New in v2.4.3)
+*Note: The 24-30s includes context preservation overhead, which keeps your main conversation clean
 
-**⚠️ Breaking Change**: Searches now default to current project only. Previously searched all projects.
+**Note**: The specialized tools (`quick_search`, `search_summary`, `get_more_results`) only work through the reflection-specialist agent due to MCP protocol limitations.
 
-Conversations are now **project-aware by default**. When you ask about past conversations, Claude automatically searches within your current project directory, keeping results focused and relevant.
+## Key Features
 
-### How It Works
+### 🎯 Project-Scoped Search
+Searches are **project-aware by default** (v2.4.3+). Claude automatically searches within your current project:
 
 ```
-# Example: Working in ~/projects/ShopifyMCPMockShop
-You: "What authentication method did we implement?"
-Claude: [Searches ONLY ShopifyMCPMockShop conversations]
-        "Found 3 conversations about JWT authentication..."
+# In ~/projects/MyApp
+You: "What authentication method did we use?"
+Claude: [Searches ONLY MyApp conversations]
 
-# To search everywhere (like pre-v2.4.3 behavior)
+# To search everywhere
 You: "Search all projects for WebSocket implementations"
 Claude: [Searches across ALL your projects]
-        "Found implementations in 5 projects: ..."
-
-# To search a specific project
-You: "Find Docker setup in claude-self-reflect project"
-Claude: [Searches only claude-self-reflect conversations]
 ```
 
-### Key Behaviors
-
-| Search Type | How to Trigger | Example |
+| Search Scope | How to Trigger | Example |
 |------------|----------------|---------|
-| **Current Project** (default) | Just ask normally | "What did we discuss about caching?" |
-| **All Projects** | Say "all projects" or "across projects" | "Search all projects for error handling" |
-| **Specific Project** | Mention the project name | "Find auth code in MyApp project" |
-
-### Why This Change?
-
-- **Focused Results**: No more sifting through unrelated conversations
-- **Better Performance**: Single-project search is ~100ms faster
-- **Natural Workflow**: Results match your current working context
-- **Privacy**: Work and personal projects stay isolated
-
-### Upgrading from Earlier Versions?
-
-Your existing conversations remain searchable. The only change is that searches now default to your current project. To get the old behavior, simply ask to "search all projects".
-
-See [Project-Scoped Search Guide](docs/project-scoped-search.md) for detailed examples and advanced usage.
+| Current Project (default) | Just ask normally | "What did we discuss about caching?" |
+| All Projects | Say "all projects" | "Search all projects for error handling" |
+| Specific Project | Name the project | "Find auth code in MyApp project" |
 
 ## Memory Decay
 
@@ -272,10 +257,14 @@ Both embedding options work well. Local mode uses FastEmbed for privacy and offl
 - [GitHub Issues](https://github.com/ramakay/claude-self-reflect/issues)
 - [Discussions](https://github.com/ramakay/claude-self-reflect/discussions)
 
-## Latest Updates
+## What's New
+
+### Recent Updates
+- **v2.4.5** - 10-40x performance boost, context preservation
+- **v2.4.3** - Project-scoped search (breaking change) 
+- **v2.3.7** - Local embeddings by default for privacy
 
-- 📢 [v2.4.x Announcement](https://github.com/ramakay/claude-self-reflect/discussions/19) - Major improvements including Docker setup and project-scoped search
-- 💬 [Project-Scoped Search Feedback](https://github.com/ramakay/claude-self-reflect/discussions/17) - Share your experience with the breaking change
+📚 [Full Release History](docs/release-history.md) | 💬 [Discussions](https://github.com/ramakay/claude-self-reflect/discussions)
 
 ## Contributing
 

package/installer/setup-wizard-docker.js

@@ -262,7 +262,10 @@ async function configureClaude() {
   
   // Create a script that runs the MCP server in Docker
   const scriptContent = `#!/bin/bash
-docker exec -i claude-reflection-mcp python -m src.server_v2
+# Run the MCP server in the Docker container with stdin attached
+# Using python -u for unbuffered output
+# Using the main module which properly supports local embeddings
+docker exec -i claude-reflection-mcp python -u -m src
 `;
   
   await fs.writeFile(mcpScript, scriptContent, { mode: 0o755 });

package/mcp-server/run-mcp-docker.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 # Run the MCP server in the Docker container with stdin attached
 # Using python -u for unbuffered output
-# Using server.py which supports local embeddings (not server_v2.py)
+# Using the main module which properly supports local embeddings
 docker exec -i claude-reflection-mcp python -u -m src

package/package.json

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

package/mcp-server/src/server_v2.py

@@ -1,254 +0,0 @@
-"""Claude Reflect MCP Server with Native Qdrant Memory Decay (v2.0.0)."""
-
-import os
-from pathlib import Path
-from typing import Any, Optional, List, Dict, Union
-from datetime import datetime
-import json
-
-from fastmcp import FastMCP, Context
-from pydantic import BaseModel, Field
-from qdrant_client import AsyncQdrantClient, models
-from qdrant_client.models import (
-    PointStruct, VectorParams, Distance
-)
-try:
-    from qdrant_client.models import (
-        Query, Formula, Expression, MultExpression,
-        ExpDecayExpression, DecayParamsExpression,
-        SearchRequest, NamedQuery
-    )
-    NATIVE_DECAY_AVAILABLE = True
-except ImportError:
-    # Fallback for older qdrant-client versions
-    NATIVE_DECAY_AVAILABLE = False
-    Query = Formula = Expression = MultExpression = None
-    ExpDecayExpression = DecayParamsExpression = None
-    SearchRequest = NamedQuery = None
-import voyageai
-from dotenv import load_dotenv
-
-# Load environment variables
-env_path = Path(__file__).parent.parent.parent / '.env'
-load_dotenv(env_path)
-
-# Configuration
-QDRANT_URL = os.getenv('QDRANT_URL', 'http://localhost:6333')
-VOYAGE_API_KEY = os.getenv('VOYAGE_KEY') or os.getenv('VOYAGE_KEY-2')
-ENABLE_MEMORY_DECAY = os.getenv('ENABLE_MEMORY_DECAY', 'false').lower() == 'true'
-DECAY_WEIGHT = float(os.getenv('DECAY_WEIGHT', '0.3'))
-DECAY_SCALE_DAYS = float(os.getenv('DECAY_SCALE_DAYS', '90'))
-
-# Initialize Voyage AI client
-voyage_client = voyageai.Client(api_key=VOYAGE_API_KEY) if VOYAGE_API_KEY else None
-
-# Debug environment loading (disabled for production)
-# print(f"[DEBUG] Qdrant Native Decay Server v2.0.0")
-# print(f"[DEBUG] ENABLE_MEMORY_DECAY: {ENABLE_MEMORY_DECAY}")
-# print(f"[DEBUG] DECAY_WEIGHT: {DECAY_WEIGHT}")
-# print(f"[DEBUG] DECAY_SCALE_DAYS: {DECAY_SCALE_DAYS}")
-
-
-class SearchResult(BaseModel):
-    """A single search result."""
-    id: str
-    score: float
-    timestamp: str
-    role: str
-    excerpt: str
-    project_name: str
-    conversation_id: Optional[str] = None
-    collection_name: str
-
-
-# Initialize FastMCP instance
-mcp = FastMCP(
-    name="claude-reflect",
-    instructions="Search past conversations and store reflections with time-based memory decay (v2.0.0 - Native Qdrant)"
-)
-
-# Create Qdrant client
-qdrant_client = AsyncQdrantClient(url=QDRANT_URL)
-    
-async def get_voyage_collections() -> List[str]:
-    """Get all Voyage collections."""
-    collections = await qdrant_client.get_collections()
-    return [c.name for c in collections.collections if c.name.endswith('_voyage')]
-
-async def generate_embedding(text: str) -> List[float]:
-    """Generate embedding using Voyage AI."""
-    if not voyage_client:
-        raise ValueError("Voyage AI API key not configured")
-    
-    result = voyage_client.embed(
-        texts=[text],
-        model="voyage-3-large",
-        input_type="query"
-    )
-    return result.embeddings[0]
-    
-# Register tools
-@mcp.tool()
-async def reflect_on_past(
-    ctx: Context,
-    query: str = Field(description="The search query to find semantically similar conversations"),
-    limit: int = Field(default=5, description="Maximum number of results to return"),
-    min_score: float = Field(default=0.3, description="Minimum similarity score (0-1)"),
-    use_decay: Union[int, str] = Field(default=-1, description="Apply time-based decay: 1=enable, 0=disable, -1=use environment default (accepts int or str)")
-) -> str:
-    """Search for relevant past conversations using semantic search with optional time decay."""
-    
-    # Normalize use_decay to integer
-    if isinstance(use_decay, str):
-        try:
-            use_decay = int(use_decay)
-        except ValueError:
-            raise ValueError("use_decay must be '1', '0', or '-1'")
-    
-    # Parse decay parameter using integer approach
-    should_use_decay = (
-        True if use_decay == 1
-        else False if use_decay == 0
-        else ENABLE_MEMORY_DECAY  # -1 or any other value
-    )
-    
-    await ctx.debug(f"Searching for: {query}")
-    await ctx.debug(f"Decay enabled: {should_use_decay}")
-    await ctx.debug(f"Using Qdrant Native Decay (v2.0.0)")
-    
-    try:
-        # Generate embedding
-        query_embedding = await generate_embedding(query)
-        
-        # Get all Voyage collections
-        voyage_collections = await get_voyage_collections()
-        if not voyage_collections:
-            return "No conversation collections found. Please import conversations first."
-        
-        await ctx.debug(f"Searching across {len(voyage_collections)} collections")
-        
-        all_results = []
-        
-        # Search each collection with native Qdrant decay
-        for collection_name in voyage_collections:
-            try:
-                if should_use_decay and NATIVE_DECAY_AVAILABLE:
-                    # Build the query with native Qdrant decay formula
-                    query_obj = Query(
-                        nearest=query_embedding,
-                        formula=Formula(
-                            sum=[
-                                # Original similarity score
-                                Expression(variable="score"),
-                                # Decay boost term
-                                Expression(
-                                    mult=MultExpression(
-                                        mult=[
-                                            # Decay weight
-                                            Expression(constant=DECAY_WEIGHT),
-                                            # Exponential decay function
-                                            Expression(
-                                                exp_decay=DecayParamsExpression(
-                                                    # Use timestamp field for decay
-                                                    x=Expression(datetime_key="timestamp"),
-                                                    # Decay from current time (server-side)
-                                                    target=Expression(datetime="now"),
-                                                    # Scale in milliseconds
-                                                    scale=DECAY_SCALE_DAYS * 24 * 60 * 60 * 1000,
-                                                    # Standard exponential decay midpoint
-                                                    midpoint=0.5
-                                                )
-                                            )
-                                        ]
-                                    )
-                                )
-                            ]
-                        )
-                    )
-                    
-                    # Execute query with native decay
-                    results = await qdrant_client.query_points(
-                        collection_name=collection_name,
-                        query=query_obj,
-                        limit=limit,
-                        score_threshold=min_score,
-                        with_payload=True
-                    )
-                    
-                    await ctx.debug(f"Native decay search in {collection_name} returned {len(results.points)} results")
-                else:
-                    # Standard search without decay
-                    results = await qdrant_client.search(
-                        collection_name=collection_name,
-                        query_vector=query_embedding,
-                        limit=limit,
-                        score_threshold=min_score,
-                        with_payload=True
-                    )
-                    results = models.QueryResponse(points=results)
-                
-                # Process results
-                for point in results.points:
-                    all_results.append(SearchResult(
-                        id=str(point.id),
-                        score=point.score,
-                        timestamp=point.payload.get('timestamp', datetime.now().isoformat()),
-                        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', '')),
-                        conversation_id=point.payload.get('conversation_id'),
-                        collection_name=collection_name
-                    ))
-            
-            except Exception as e:
-                await ctx.debug(f"Error searching {collection_name}: {str(e)}")
-                continue
-        
-        # Sort by score and limit
-        all_results.sort(key=lambda x: x.score, reverse=True)
-        all_results = all_results[:limit]
-        
-        if not all_results:
-            return f"No conversations found matching '{query}'. Try different keywords or check if conversations have been imported."
-        
-        # Format results
-        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"
-            result_text += f"Project: {result.project_name}\n"
-            result_text += f"Role: {result.role}\n"
-            result_text += f"Excerpt: {result.excerpt}\n"
-            result_text += "---\n\n"
-        
-        return result_text
-        
-    except Exception as e:
-        await ctx.error(f"Search failed: {str(e)}")
-        return f"Failed to search conversations: {str(e)}"
-
-@mcp.tool()
-async def store_reflection(
-    ctx: Context,
-    content: str = Field(description="The insight or reflection to store"),
-    tags: List[str] = Field(default=[], description="Tags to categorize this reflection")
-) -> str:
-    """Store an important insight or reflection for future reference."""
-    
-    try:
-        # TODO: Implement actual storage in a dedicated reflections collection
-        # For now, just acknowledge the storage
-        tags_str = ', '.join(tags) if tags else 'none'
-        return f"Reflection stored successfully with tags: {tags_str}"
-        
-    except Exception as e:
-        await ctx.error(f"Store failed: {str(e)}") 
-        return f"Failed to store reflection: {str(e)}"
-
-
-# Debug output (disabled for production)
-# print(f"[DEBUG] FastMCP server v2.0.0 created with native Qdrant decay")
-
-# Run the server when executed as main module
-if __name__ == "__main__":
-    mcp.run(transport="stdio", show_banner=False)