claude-self-reflect 7.0.0 → 7.1.9

package/mcp-server/src/reflection_tools.py

@@ -8,6 +8,7 @@ from typing import Optional, List, Dict, Any
 from datetime import datetime, timezone
 from pathlib import Path
 import uuid
+from xml.sax.saxutils import escape as xml_escape
 
 from fastmcp import Context
 from pydantic import Field
@@ -207,13 +208,108 @@ Timestamp: {metadata['timestamp']}"""
 <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>"""
 
+    async def get_session_learnings(
+        self,
+        ctx: Context,
+        session_id: str,
+        limit: int = 50
+    ) -> str:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+        """
+        from qdrant_client import models
+
+        await ctx.debug(f"Getting learnings for session: {session_id}")
+
+        try:
+            # Check runtime preference from environment
+            prefer_local = os.getenv('PREFER_LOCAL_EMBEDDINGS', 'true').lower() == 'true'
+            embedding_type = "local" if prefer_local else "voyage"
+            collection_name = f"reflections_{embedding_type}"
+
+            # Filter by session tag - matches reflections stored with session_{id} tag
+            session_filter = models.Filter(
+                must=[
+                    models.FieldCondition(
+                        key="tags",
+                        match=models.MatchAny(any=[f"session_{session_id}"])
+                    )
+                ]
+            )
+
+            results, _ = await self.qdrant_client.scroll(
+                collection_name=collection_name,
+                scroll_filter=session_filter,
+                limit=limit,
+                with_payload=True,
+            )
+
+            if not results:
+                await ctx.debug(f"No learnings found for session {session_id}")
+                return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<count>0</count>
+<message>No learnings stored yet for this session. Use store_reflection() with tags=['session_{session_id}', 'iteration_N', 'ralph_iteration'] to store iteration learnings.</message>
+</session_learnings>"""
+
+            # Format results
+            learnings = []
+            for point in results:
+                payload = point.payload or {}
+                tags = payload.get("tags", [])
+                # Extract iteration number from tags if present
+                iteration = "unknown"
+                for tag in tags:
+                    if tag.startswith("iteration_"):
+                        iteration = tag.replace("iteration_", "")
+                        break
+
+                learnings.append({
+                    "content": payload.get("content", ""),
+                    "iteration": iteration,
+                    "timestamp": payload.get("timestamp", ""),
+                    "tags": tags
+                })
+
+            # Sort by timestamp (oldest first for chronological order)
+            learnings.sort(key=lambda x: x.get("timestamp", ""))
+
+            await ctx.debug(f"Found {len(learnings)} learnings for session {session_id}")
+
+            # Format as XML for structured output (escape special chars for safety)
+            learnings_xml = "\n".join([
+                f"""<learning iteration="{xml_escape(str(l['iteration']))}">
+<timestamp>{xml_escape(str(l['timestamp']))}</timestamp>
+<content>{xml_escape(str(l['content']))}</content>
+<tags>{xml_escape(', '.join(str(t) for t in l['tags']))}</tags>
+</learning>"""
+                for l in learnings
+            ])
+
+            return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<count>{len(learnings)}</count>
+<learnings>
+{learnings_xml}
+</learnings>
+</session_learnings>"""
+
+        except Exception as e:
+            logger.error(f"Failed to get session learnings: {e}", exc_info=True)
+            return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<error>Failed to retrieve learnings: {str(e)}</error>
+</session_learnings>"""
+
 
 def register_reflection_tools(
     mcp,
@@ -249,5 +345,21 @@ def register_reflection_tools(
         """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)
-    
+
+    @mcp.tool()
+    async def get_session_learnings(
+        ctx: Context,
+        session_id: str = Field(description="Ralph session ID to get learnings from (e.g., 'ralph_20260104_224757_iter1')"),
+        limit: int = Field(default=50, description="Maximum number of learnings to return")
+    ) -> str:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+
+        Use this at the START of each Ralph iteration to see what previous
+        iterations learned. Then use store_reflection() with session tags
+        to save learnings at the END of each iteration."""
+        return await tools.get_session_learnings(ctx, session_id, limit)
+
     logger.info("Reflection tools registered successfully")

package/mcp-server/src/standalone_client.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""
+CSR Standalone Client - For use outside the MCP server context.
+
+This client provides search and store_reflection functionality
+for hooks and scripts that need to interact with CSR without
+going through the MCP protocol.
+
+Usage:
+    from mcp_server.src.standalone_client import CSRStandaloneClient
+
+    client = CSRStandaloneClient()
+    results = client.search("docker issues", limit=5)
+    client.store_reflection("Key insight here", tags=["insight"])
+"""
+
+import os
+import uuid
+import hashlib
+import logging
+from typing import List, Dict, Any, Optional
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class CSRStandaloneClient:
+    """Standalone CSR client for hooks and scripts."""
+
+    def __init__(
+        self,
+        qdrant_url: str = None,
+        qdrant_api_key: str = None,
+        prefer_local: bool = None
+    ):
+        """Initialize the standalone client.
+
+        Args:
+            qdrant_url: Qdrant server URL (default: from env or localhost:6333)
+            qdrant_api_key: Qdrant API key (default: from env)
+            prefer_local: Use local embeddings (default: from env or True)
+        """
+        self.qdrant_url = qdrant_url or os.getenv('QDRANT_URL', 'http://localhost:6333')
+        self.qdrant_api_key = qdrant_api_key or os.getenv('QDRANT_API_KEY')
+
+        if prefer_local is None:
+            self.prefer_local = os.getenv('PREFER_LOCAL_EMBEDDINGS', 'true').lower() == 'true'
+        else:
+            self.prefer_local = prefer_local
+
+        self._client = None
+        self._embedding_manager = None
+
+    def _get_client(self):
+        """Get or create Qdrant client (synchronous)."""
+        if self._client is None:
+            from qdrant_client import QdrantClient
+
+            # Parse URL for host/port
+            import urllib.parse
+            parsed = urllib.parse.urlparse(self.qdrant_url)
+            host = parsed.hostname or 'localhost'
+            port = parsed.port or 6333
+
+            self._client = QdrantClient(
+                host=host,
+                port=port,
+                api_key=self.qdrant_api_key if self.qdrant_api_key else None,
+                timeout=30
+            )
+        return self._client
+
+    def _get_embedding_manager(self):
+        """Get or create embedding manager."""
+        if self._embedding_manager is None:
+            # Try to use the project's embedding manager
+            try:
+                from .embedding_manager import EmbeddingManager
+                self._embedding_manager = EmbeddingManager()
+            except ImportError:
+                # Fallback: create minimal embedding functionality
+                self._embedding_manager = self._create_fallback_embeddings()
+        return self._embedding_manager
+
+    def _create_fallback_embeddings(self):
+        """Create fallback embedding functionality using fastembed."""
+        class FallbackEmbeddings:
+            def __init__(self):
+                self._model = None
+
+            def get_model(self):
+                if self._model is None:
+                    try:
+                        from fastembed import TextEmbedding
+                        self._model = TextEmbedding("BAAI/bge-small-en-v1.5")
+                    except ImportError:
+                        raise ImportError("fastembed not installed. Run: pip install fastembed")
+                return self._model
+
+            def embed(self, text: str) -> List[float]:
+                model = self.get_model()
+                embeddings = list(model.embed([text]))
+                return list(embeddings[0])
+
+            @property
+            def dimension(self) -> int:
+                return 384
+
+        return FallbackEmbeddings()
+
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        min_score: float = 0.3,
+        project: str = None
+    ) -> List[Dict[str, Any]]:
+        """Search for relevant conversations.
+
+        Args:
+            query: Search query
+            limit: Maximum results to return
+            min_score: Minimum similarity score
+            project: Project name filter (optional)
+
+        Returns:
+            List of search results with content and metadata
+        """
+        client = self._get_client()
+        embeddings = self._get_embedding_manager()
+
+        # Generate query embedding
+        query_vector = embeddings.embed(query)
+
+        # Find searchable collections
+        collections = client.get_collections().collections
+        searchable = [
+            c.name for c in collections
+            if self._is_searchable_collection(c.name)
+        ]
+
+        if not searchable:
+            logger.warning("No searchable collections found")
+            return []
+
+        # Filter by project if specified
+        if project and project != 'all':
+            project_norm = self._normalize_project_name(project)
+            searchable = [c for c in searchable if project_norm in c]
+
+        # Prioritize reflections collections (where Ralph state is stored)
+        reflections = [c for c in searchable if c.startswith('reflections')]
+        others = [c for c in searchable if not c.startswith('reflections')]
+        searchable = reflections + others
+
+        results = []
+        for collection_name in searchable[:8]:  # Search up to 8 collections
+            try:
+                search_results = client.search(
+                    collection_name=collection_name,
+                    query_vector=query_vector,
+                    limit=limit,
+                    score_threshold=min_score
+                )
+
+                for hit in search_results:
+                    payload = hit.payload or {}
+                    results.append({
+                        'score': hit.score,
+                        'content': payload.get('content', ''),
+                        'preview': payload.get('preview', payload.get('content', '')[:200]),
+                        'metadata': {
+                            'collection': collection_name,
+                            'conversation_id': payload.get('conversation_id', ''),
+                            'timestamp': payload.get('timestamp', ''),
+                            'project': payload.get('project', ''),
+                        }
+                    })
+            except Exception as e:
+                logger.debug(f"Error searching {collection_name}: {e}")
+                continue
+
+        # Sort by score and limit
+        results.sort(key=lambda x: x['score'], reverse=True)
+        return results[:limit]
+
+    def store_reflection(
+        self,
+        content: str,
+        tags: List[str] = None,
+        collection: str = None
+    ) -> str:
+        """Store a reflection/insight.
+
+        Args:
+            content: The reflection content
+            tags: Optional tags for categorization
+            collection: Optional custom collection name (for hooks to use separate storage)
+
+        Returns:
+            ID of stored reflection
+        """
+        tags = tags or []
+        client = self._get_client()
+        embeddings = self._get_embedding_manager()
+
+        # Determine collection name
+        # Hooks can specify a custom collection to keep their data separate
+        if collection:
+            collection_name = collection
+        else:
+            collection_name = f"reflections_{'local' if self.prefer_local else 'voyage'}"
+
+        # Ensure collection exists
+        try:
+            client.get_collection(collection_name)
+        except Exception:
+            # Create collection
+            from qdrant_client.models import VectorParams, Distance
+            client.create_collection(
+                collection_name=collection_name,
+                vectors_config=VectorParams(
+                    size=embeddings.dimension,
+                    distance=Distance.COSINE
+                )
+            )
+
+        # Generate embedding
+        vector = embeddings.embed(content)
+
+        # Generate ID
+        reflection_id = hashlib.sha256(
+            f"{content}{datetime.now().isoformat()}".encode()
+        ).hexdigest()[:16]
+
+        # Store
+        from qdrant_client.models import PointStruct
+        client.upsert(
+            collection_name=collection_name,
+            points=[
+                PointStruct(
+                    id=str(uuid.uuid4()),
+                    vector=vector,
+                    payload={
+                        "content": content,
+                        "tags": tags,
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                        "reflection_id": reflection_id,
+                        "type": "reflection"
+                    }
+                )
+            ]
+        )
+
+        logger.info(f"Stored reflection: {reflection_id}")
+        return reflection_id
+
+    def _is_searchable_collection(self, name: str) -> bool:
+        """Check if collection is searchable."""
+        return (
+            name.endswith('_local')
+            or name.endswith('_voyage')
+            or name.endswith('_384d')
+            or name.endswith('_1024d')
+            or '_cloud_' in name
+            or name.startswith('reflections')
+            or name.startswith('csr_')
+        )
+
+    def _normalize_project_name(self, name: str) -> str:
+        """Normalize project name for collection matching."""
+        import re
+        # Convert to lowercase, replace special chars
+        normalized = name.lower()
+        normalized = re.sub(r'[^a-z0-9]', '_', normalized)
+        normalized = re.sub(r'_+', '_', normalized)
+        return normalized.strip('_')
+
+    def get_session_learnings(
+        self,
+        session_id: str,
+        limit: int = 50,
+        collection: str = None
+    ) -> List[Dict[str, Any]]:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+
+        Args:
+            session_id: The session ID (e.g., "ralph_20260104_224757_iter1")
+            limit: Maximum number of reflections to return
+            collection: Optional custom collection (for hook-stored data)
+
+        Returns:
+            List of reflection payloads from this session, each containing:
+            - content: The reflection text
+            - tags: List of tags (includes iteration info)
+            - timestamp: When it was stored
+        """
+        from qdrant_client import models
+
+        client = self._get_client()
+        if collection:
+            collection_name = collection
+        else:
+            collection_name = f"reflections_{'local' if self.prefer_local else 'voyage'}"
+
+        # Filter by session tag - matches reflections stored with session_{id} tag
+        session_filter = models.Filter(
+            must=[
+                models.FieldCondition(
+                    key="tags",
+                    match=models.MatchAny(any=[f"session_{session_id}"])
+                )
+            ]
+        )
+
+        try:
+            results, _ = client.scroll(
+                collection_name=collection_name,
+                scroll_filter=session_filter,
+                limit=limit,
+                with_payload=True,
+            )
+
+            return [
+                {
+                    "content": point.payload.get("content", ""),
+                    "tags": point.payload.get("tags", []),
+                    "timestamp": point.payload.get("timestamp", ""),
+                }
+                for point in results
+            ]
+        except Exception as e:
+            logger.error(f"Error getting session learnings: {e}")
+            return []
+
+    def test_connection(self) -> bool:
+        """Test if CSR is accessible.
+
+        Returns:
+            True if connection successful
+        """
+        try:
+            client = self._get_client()
+            client.get_collections()
+            return True
+        except Exception as e:
+            logger.error(f"Connection test failed: {e}")
+            return False
+
+
+# Convenience function for quick searches
+def quick_search(query: str, limit: int = 3) -> List[Dict[str, Any]]:
+    """Quick search without creating client instance."""
+    client = CSRStandaloneClient()
+    return client.search(query, limit=limit)
+
+
+if __name__ == "__main__":
+    # Test the client
+    import sys
+
+    client = CSRStandaloneClient()
+
+    if client.test_connection():
+        print("✓ CSR connection successful")
+
+        if len(sys.argv) > 1:
+            query = " ".join(sys.argv[1:])
+            results = client.search(query, limit=3)
+            print(f"\nResults for '{query}':")
+            for i, r in enumerate(results, 1):
+                print(f"\n{i}. Score: {r['score']:.2f}")
+                print(f"   {r['preview'][:100]}...")
+    else:
+        print("✗ CSR connection failed")
+        sys.exit(1)

package/package.json

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

package/src/runtime/hooks/__init__.py

@@ -0,0 +1,21 @@
+"""Ralph memory hooks for Claude Code integration."""
+
+from .ralph_state import (
+    RalphState,
+    load_state,
+    save_state,
+    is_ralph_session,
+    get_ralph_state_path,
+    load_ralph_session_state,
+    parse_ralph_wiggum_state,
+)
+
+__all__ = [
+    'RalphState',
+    'load_state',
+    'save_state',
+    'is_ralph_session',
+    'get_ralph_state_path',
+    'load_ralph_session_state',
+    'parse_ralph_wiggum_state',
+]