claude-self-reflect 3.2.4 → 3.3.1

package/mcp-server/src/reflection_tools.py

@@ -0,0 +1,211 @@
+"""Reflection tools for Claude Self Reflect MCP server."""
+
+import os
+import json
+import hashlib
+import logging
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timezone
+from pathlib import Path
+import uuid
+
+from fastmcp import Context
+from pydantic import Field
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import PointStruct, VectorParams, Distance
+
+logger = logging.getLogger(__name__)
+
+
+class ReflectionTools:
+    """Handles reflection storage and conversation retrieval operations."""
+    
+    def __init__(
+        self,
+        qdrant_client: AsyncQdrantClient,
+        qdrant_url: str,
+        get_embedding_manager,
+        normalize_project_name
+    ):
+        """Initialize reflection tools with dependencies."""
+        self.qdrant_client = qdrant_client
+        self.qdrant_url = qdrant_url
+        self.get_embedding_manager = get_embedding_manager
+        self.normalize_project_name = normalize_project_name
+
+    async def store_reflection(
+        self,
+        ctx: Context,
+        content: str,
+        tags: List[str] = []
+    ) -> str:
+        """Store an important insight or reflection for future reference."""
+
+        await ctx.debug(f"Storing reflection with {len(tags)} tags")
+
+        try:
+            # Determine collection name based on active model type, not prefer_local
+            embedding_manager = self.get_embedding_manager()
+            # Use actual model_type to ensure consistency
+            embedding_type = embedding_manager.model_type or ("voyage" if embedding_manager.voyage_client else "local")
+            collection_name = f"reflections_{embedding_type}"
+
+            # Ensure reflections collection exists
+            try:
+                await self.qdrant_client.get_collection(collection_name)
+                await ctx.debug(f"Using existing {collection_name} collection")
+            except Exception:
+                # Collection doesn't exist, create it
+                await ctx.debug(f"Creating {collection_name} collection")
+
+                # Get embedding dimensions for the specific type
+                embedding_dim = embedding_manager.get_vector_dimension(force_type=embedding_type)
+
+                await self.qdrant_client.create_collection(
+                    collection_name=collection_name,
+                    vectors_config=VectorParams(
+                        size=embedding_dim,
+                        distance=Distance.COSINE
+                    )
+                )
+
+            # Generate embedding with the same forced type for consistency
+            embedding = await embedding_manager.generate_embedding(content, force_type=embedding_type)
+
+            # Guard against failed embeddings
+            if not embedding:
+                await ctx.debug("Failed to generate embedding for reflection")
+                return "Failed to store reflection: embedding generation failed"
+            
+            # Create unique ID
+            reflection_id = hashlib.md5(f"{content}{datetime.now().isoformat()}".encode()).hexdigest()
+            
+            # Prepare metadata
+            metadata = {
+                "content": content,
+                "tags": tags,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "type": "reflection"
+            }
+            
+            # Store in Qdrant
+            await self.qdrant_client.upsert(
+                collection_name=collection_name,
+                points=[
+                    PointStruct(
+                        id=reflection_id,
+                        vector=embedding,
+                        payload=metadata
+                    )
+                ]
+            )
+            
+            await ctx.debug(f"Stored reflection with ID {reflection_id}")
+            
+            return f"""Reflection stored successfully.
+ID: {reflection_id}
+Tags: {', '.join(tags) if tags else 'none'}
+Timestamp: {metadata['timestamp']}"""
+            
+        except Exception as e:
+            logger.error(f"Failed to store reflection: {e}", exc_info=True)
+            return f"Failed to store reflection: {str(e)}"
+
+    async def get_full_conversation(
+        self,
+        ctx: Context,
+        conversation_id: str,
+        project: Optional[str] = None
+    ) -> str:
+        """Get the full JSONL conversation file path for a conversation ID.
+        This allows agents to read complete conversations instead of truncated excerpts."""
+        
+        await ctx.debug(f"Getting full conversation for ID: {conversation_id}, project: {project}")
+        
+        try:
+            # Base path for conversations
+            base_path = Path.home() / '.claude' / 'projects'
+            
+            # If project is specified, try to find it in that project
+            if project:
+                # Normalize project name for path matching
+                project_normalized = self.normalize_project_name(project)
+                
+                # Look for project directories that match
+                for project_dir in base_path.glob('*'):
+                    if project_normalized in project_dir.name.lower():
+                        # Look for JSONL files in this project
+                        for jsonl_file in project_dir.glob('*.jsonl'):
+                            # Check if filename matches conversation_id (with or without .jsonl)
+                            if conversation_id in jsonl_file.stem or conversation_id == jsonl_file.stem:
+                                await ctx.debug(f"Found conversation by filename in {jsonl_file}")
+                                return f"""<conversation_file>
+<conversation_id>{conversation_id}</conversation_id>
+<file_path>{str(jsonl_file)}</file_path>
+<project>{project_dir.name}</project>
+<message>Use the Read tool with this file path to read the complete conversation.</message>
+</conversation_file>"""
+            
+            # If not found in specific project or no project specified, search all
+            await ctx.debug("Searching all projects for conversation")
+            for project_dir in base_path.glob('*'):
+                for jsonl_file in project_dir.glob('*.jsonl'):
+                    # Check if filename matches conversation_id (with or without .jsonl)
+                    if conversation_id in jsonl_file.stem or conversation_id == jsonl_file.stem:
+                        await ctx.debug(f"Found conversation by filename in {jsonl_file}")
+                        return f"""<conversation_file>
+<conversation_id>{conversation_id}</conversation_id>
+<file_path>{str(jsonl_file)}</file_path>
+<project>{project_dir.name}</project>
+<message>Use the Read tool with this file path to read the complete conversation.</message>
+</conversation_file>"""
+            
+            # Not found
+            return f"""<conversation_file>
+<error>Conversation ID '{conversation_id}' not found in any project.</error>
+<suggestion>The conversation may not have been imported yet, or the ID may be incorrect.</suggestion>
+</conversation_file>"""
+            
+        except Exception as e:
+            logger.error(f"Failed to get conversation file: {e}", exc_info=True)
+            return f"""<conversation_file>
+<error>Failed to locate conversation: {str(e)}</error>
+</conversation_file>"""
+
+
+def register_reflection_tools(
+    mcp,
+    qdrant_client: AsyncQdrantClient,
+    qdrant_url: str,
+    get_embedding_manager,
+    normalize_project_name
+):
+    """Register reflection tools with the MCP server."""
+    
+    tools = ReflectionTools(
+        qdrant_client,
+        qdrant_url,
+        get_embedding_manager,
+        normalize_project_name
+    )
+    
+    @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."""
+        return await tools.store_reflection(ctx, content, tags)
+    
+    @mcp.tool()
+    async def get_full_conversation(
+        ctx: Context,
+        conversation_id: str = Field(description="The conversation ID from search results (cid)"),
+        project: Optional[str] = Field(default=None, description="Optional project name to help locate the file")
+    ) -> str:
+        """Get the full JSONL conversation file path for a conversation ID.
+        This allows agents to read complete conversations instead of truncated excerpts."""
+        return await tools.get_full_conversation(ctx, conversation_id, project)
+    
+    logger.info("Reflection tools registered successfully")

package/mcp-server/src/rich_formatting.py

@@ -0,0 +1,196 @@
+"""Rich formatting for search results with emojis and enhanced display."""
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def format_search_results_rich(
+    results: List[Dict],
+    query: str,
+    target_project: str,
+    collections_searched: int,
+    timing_info: Dict[str, float],
+    start_time: float,
+    brief: bool = False,
+    include_raw: bool = False,
+    indexing_status: Optional[Dict] = None
+) -> str:
+    """Format search results with rich formatting including emojis and performance metrics."""
+
+    # Initialize upfront summary
+    upfront_summary = ""
+
+    # Show result summary with emojis
+    if results:
+        score_info = "high" if results[0]['score'] >= 0.85 else "good" if results[0]['score'] >= 0.75 else "partial"
+        upfront_summary += f"🎯 RESULTS: {len(results)} matches ({score_info} relevance, top score: {results[0]['score']:.3f})\n"
+
+        # Show performance metrics
+        total_time = time.time() - start_time
+        indexing_info = ""
+        if indexing_status and indexing_status.get("percentage", 100) < 100.0:
+            indexing_info = f" | 📊 {indexing_status['indexed_conversations']}/{indexing_status['total_conversations']} indexed"
+        upfront_summary += f"⚡ PERFORMANCE: {int(total_time * 1000)}ms ({collections_searched} collections searched{indexing_info})\n"
+    else:
+        upfront_summary += f"❌ NO RESULTS: No conversations found matching '{query}'\n"
+
+    # Start XML format with upfront summary
+    result_text = upfront_summary + "\n<search>\n"
+
+    # Add indexing status if not fully baselined
+    if indexing_status and indexing_status.get("percentage", 100) < 95.0:
+        result_text += f'  <info status="indexing" progress="{indexing_status["percentage"]:.1f}%" backlog="{indexing_status.get("backlog_count", 0)}">\n'
+        result_text += f'    <message>📊 Indexing: {indexing_status["indexed_conversations"]}/{indexing_status["total_conversations"]} conversations ({indexing_status["percentage"]:.1f}% complete)</message>\n'
+        result_text += f"  </info>\n"
+
+    # Add high-level result summary
+    if results:
+        # Count time-based results
+        now = datetime.now(timezone.utc)
+        today_count = 0
+        yesterday_count = 0
+        week_count = 0
+
+        for result in results:
+            timestamp_str = result.get('timestamp', '')
+            if timestamp_str:
+                try:
+                    # Clean timestamp
+                    timestamp_clean = timestamp_str.replace('Z', '+00:00') if timestamp_str.endswith('Z') else timestamp_str
+                    timestamp_dt = datetime.fromisoformat(timestamp_clean)
+                    if timestamp_dt.tzinfo is None:
+                        timestamp_dt = timestamp_dt.replace(tzinfo=timezone.utc)
+
+                    days_ago = (now - timestamp_dt).days
+                    if days_ago == 0:
+                        today_count += 1
+                    elif days_ago == 1:
+                        yesterday_count += 1
+                    if days_ago <= 7:
+                        week_count += 1
+                except:
+                    pass
+
+        # Compact summary with key info
+        time_info = ""
+        if today_count > 0:
+            time_info = f"{today_count} today"
+        elif yesterday_count > 0:
+            time_info = f"{yesterday_count} yesterday"
+        elif week_count > 0:
+            time_info = f"{week_count} this week"
+        else:
+            time_info = "older results"
+
+        score_info = "high" if results[0]['score'] >= 0.85 else "good" if results[0]['score'] >= 0.75 else "partial"
+
+        result_text += f'  <summary count="{len(results)}" relevance="{score_info}" recency="{time_info}" top-score="{results[0]["score"]:.3f}">\n'
+
+        # Short preview of top result
+        top_excerpt = results[0].get('excerpt', results[0].get('content', ''))[:100].strip()
+        if '...' not in top_excerpt:
+            top_excerpt += "..."
+        result_text += f'    <preview>{top_excerpt}</preview>\n'
+        result_text += f"  </summary>\n"
+    else:
+        result_text += f"  <result-summary>\n"
+        result_text += f"    <headline>No matches found</headline>\n"
+        result_text += f"    <relevance>No conversations matched your query</relevance>\n"
+        result_text += f"  </result-summary>\n"
+
+    # Add metadata
+    result_text += f"  <meta>\n"
+    result_text += f"    <q>{query}</q>\n"
+    result_text += f"    <scope>{target_project if target_project != 'all' else 'all'}</scope>\n"
+    result_text += f"    <count>{len(results)}</count>\n"
+    if results:
+        result_text += f"    <range>{results[-1]['score']:.3f}-{results[0]['score']:.3f}</range>\n"
+
+    # Add performance metadata
+    total_time = time.time() - start_time
+    result_text += f"    <perf>\n"
+    result_text += f"      <ttl>{int(total_time * 1000)}</ttl>\n"
+    result_text += f"      <emb>{int((timing_info.get('embedding_end', 0) - timing_info.get('embedding_start', 0)) * 1000)}</emb>\n"
+    result_text += f"      <srch>{int((timing_info.get('search_all_end', 0) - timing_info.get('search_all_start', 0)) * 1000)}</srch>\n"
+    result_text += f"      <cols>{collections_searched}</cols>\n"
+    result_text += f"    </perf>\n"
+    result_text += f"  </meta>\n"
+
+    # Add individual results
+    result_text += "  <results>\n"
+    for i, result in enumerate(results):
+        result_text += f'    <r rank="{i+1}">\n'
+        result_text += f"      <s>{result['score']:.3f}</s>\n"
+        result_text += f"      <p>{result.get('project_name', 'unknown')}</p>\n"
+
+        # Calculate relative time
+        timestamp_str = result.get('timestamp', '')
+        if timestamp_str:
+            try:
+                timestamp_clean = timestamp_str.replace('Z', '+00:00') if timestamp_str.endswith('Z') else timestamp_str
+                timestamp_dt = datetime.fromisoformat(timestamp_clean)
+                if timestamp_dt.tzinfo is None:
+                    timestamp_dt = timestamp_dt.replace(tzinfo=timezone.utc)
+                now = datetime.now(timezone.utc)
+                days_ago = (now - timestamp_dt).days
+                if days_ago == 0:
+                    time_str = "today"
+                elif days_ago == 1:
+                    time_str = "yesterday"
+                else:
+                    time_str = f"{days_ago}d"
+                result_text += f"      <t>{time_str}</t>\n"
+            except:
+                result_text += f"      <t>unknown</t>\n"
+
+        # Get excerpt/content
+        excerpt = result.get('excerpt', result.get('content', ''))
+
+        if not brief and excerpt:
+            # Extract title from first line of excerpt
+            excerpt_lines = excerpt.split('\n')
+            title = excerpt_lines[0][:80] + "..." if len(excerpt_lines[0]) > 80 else excerpt_lines[0]
+            result_text += f"      <title>{title}</title>\n"
+
+            # Key finding - summarize the main point
+            key_finding = excerpt[:100] + "..." if len(excerpt) > 100 else excerpt
+            result_text += f"      <key-finding>{key_finding.strip()}</key-finding>\n"
+
+        # Always include excerpt
+        if brief:
+            brief_excerpt = excerpt[:100] + "..." if len(excerpt) > 100 else excerpt
+            result_text += f"      <excerpt>{brief_excerpt.strip()}</excerpt>\n"
+        else:
+            result_text += f"      <excerpt><![CDATA[{excerpt}]]></excerpt>\n"
+
+        # Add conversation ID if present
+        if result.get('conversation_id'):
+            result_text += f"      <cid>{result['conversation_id']}</cid>\n"
+
+        # Include raw data if requested
+        if include_raw and result.get('raw_payload'):
+            result_text += "      <raw>\n"
+            payload = result['raw_payload']
+            result_text += f"        <txt><![CDATA[{payload.get('text', '')}]]></txt>\n"
+            result_text += f"        <id>{result.get('id', '')}</id>\n"
+            result_text += "      </raw>\n"
+
+        # Add metadata fields if present
+        if result.get('files_analyzed'):
+            result_text += f"      <files>{', '.join(result['files_analyzed'][:5])}</files>\n"
+        if result.get('tools_used'):
+            result_text += f"      <tools>{', '.join(result['tools_used'][:5])}</tools>\n"
+        if result.get('concepts'):
+            result_text += f"      <concepts>{', '.join(result['concepts'][:5])}</concepts>\n"
+
+        result_text += "    </r>\n"
+
+    result_text += "  </results>\n"
+    result_text += "</search>\n"
+
+    return result_text