claude-mpm 5.4.96__py3-none-any.whl → 5.6.17__py3-none-any.whl

claude_mpm/commander/memory/integration.py

@@ -0,0 +1,325 @@
+"""Integration helpers for memory system with Commander.
+
+Provides high-level functions to integrate conversation memory with
+RuntimeMonitor, Chat CLI, and session resumption workflows.
+"""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from ..llm.openrouter_client import OpenRouterClient
+from ..models.project import Project, ThreadMessage
+from .compression import ContextCompressor
+from .embeddings import EmbeddingService
+from .entities import EntityExtractor
+from .search import SemanticSearch
+from .store import Conversation, ConversationMessage, ConversationStore
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryIntegration:
+    """High-level memory integration for Commander.
+
+    Provides simple API for common memory operations:
+    - Capture conversation from Project
+    - Search across all conversations
+    - Load context for session resume
+
+    Attributes:
+        store: ConversationStore for persistence
+        embeddings: EmbeddingService for vectors
+        search: SemanticSearch for queries
+        compressor: ContextCompressor for summaries
+        extractor: EntityExtractor for entity extraction
+
+    Example:
+        >>> memory = MemoryIntegration.create()
+        >>> await memory.capture_project_conversation(project)
+        >>> results = await memory.search("login bug fix", project_id="proj-xyz")
+    """
+
+    def __init__(
+        self,
+        store: ConversationStore,
+        embeddings: EmbeddingService,
+        search: SemanticSearch,
+        compressor: ContextCompressor,
+        extractor: EntityExtractor,
+    ):
+        """Initialize memory integration.
+
+        Args:
+            store: ConversationStore instance
+            embeddings: EmbeddingService instance
+            search: SemanticSearch instance
+            compressor: ContextCompressor instance
+            extractor: EntityExtractor instance
+        """
+        self.store = store
+        self.embeddings = embeddings
+        self.search = search
+        self.compressor = compressor
+        self.extractor = extractor
+
+        logger.info("MemoryIntegration initialized")
+
+    @classmethod
+    def create(
+        cls,
+        openrouter_client: Optional[OpenRouterClient] = None,
+        embedding_provider: str = "sentence-transformers",
+    ) -> "MemoryIntegration":
+        """Create MemoryIntegration with default configuration.
+
+        Args:
+            openrouter_client: Optional OpenRouterClient for summarization
+            embedding_provider: Embedding provider ("sentence-transformers" or "openai")
+
+        Returns:
+            Configured MemoryIntegration instance
+
+        Example:
+            >>> from claude_mpm.commander.llm import OpenRouterClient
+            >>> client = OpenRouterClient()
+            >>> memory = MemoryIntegration.create(openrouter_client=client)
+        """
+        store = ConversationStore()
+        embeddings = EmbeddingService(provider=embedding_provider)
+        search = SemanticSearch(store, embeddings)
+
+        # Create OpenRouter client if not provided
+        if openrouter_client is None:
+            openrouter_client = OpenRouterClient()
+
+        compressor = ContextCompressor(openrouter_client)
+        extractor = EntityExtractor()
+
+        return cls(store, embeddings, search, compressor, extractor)
+
+    async def capture_project_conversation(
+        self,
+        project: Project,
+        instance_name: str = "unknown",
+        session_id: Optional[str] = None,
+    ) -> Conversation:
+        """Capture conversation from Project thread.
+
+        Converts Project.thread (List[ThreadMessage]) into a Conversation
+        with entity extraction and optional summarization.
+
+        Args:
+            project: Project with conversation thread
+            instance_name: Instance name (e.g., "claude-code-1")
+            session_id: Optional session ID
+
+        Returns:
+            Captured and saved Conversation
+
+        Example:
+            >>> conv = await memory.capture_project_conversation(project)
+            >>> print(f"Captured conversation {conv.id} with {len(conv.messages)} messages")
+        """
+        if not project.thread:
+            logger.warning("Project %s has no conversation thread", project.id)
+            return None
+
+        # Convert ThreadMessages to ConversationMessages
+        messages = []
+        for thread_msg in project.thread:
+            conv_msg = ConversationMessage.from_thread_message(thread_msg)
+
+            # Extract entities
+            entities = self.extractor.extract(conv_msg.content)
+            conv_msg.entities = [e.to_dict() for e in entities]
+
+            messages.append(conv_msg)
+
+        # Create conversation
+        conversation = Conversation(
+            id=f"conv-{uuid.uuid4().hex[:12]}",
+            project_id=project.id,
+            instance_name=instance_name,
+            session_id=session_id or f"sess-{uuid.uuid4().hex[:8]}",
+            messages=messages,
+        )
+
+        # Auto-summarize if needed
+        if self.compressor.needs_summarization(messages):
+            conversation.summary = await self.compressor.summarize(messages)
+            logger.info("Auto-generated summary for conversation %s", conversation.id)
+
+        # Generate embedding for semantic search
+        text_for_embedding = conversation.summary or conversation.get_full_text()[:1000]
+        conversation.embedding = await self.embeddings.embed(text_for_embedding)
+
+        # Save to store
+        await self.store.save(conversation)
+
+        logger.info(
+            "Captured conversation %s (%d messages) from project %s",
+            conversation.id,
+            len(messages),
+            project.id,
+        )
+
+        return conversation
+
+    async def search_conversations(
+        self,
+        query: str,
+        project_id: Optional[str] = None,
+        limit: int = 10,
+    ) -> List:
+        """Search conversations by natural language query.
+
+        Args:
+            query: Natural language search query
+            project_id: Optional project filter
+            limit: Maximum results
+
+        Returns:
+            List of SearchResult with conversations
+
+        Example:
+            >>> results = await memory.search_conversations(
+            ...     "how did we fix the authentication bug?",
+            ...     project_id="proj-xyz",
+            ...     limit=5
+            ... )
+            >>> for result in results:
+            ...     print(f"{result.score:.2f}: {result.snippet}")
+        """
+        return await self.search.search(query, project_id=project_id, limit=limit)
+
+    async def load_context_for_session(
+        self,
+        project_id: str,
+        max_tokens: int = 4000,
+        limit_conversations: int = 10,
+    ) -> str:
+        """Load compressed context for session resumption.
+
+        Retrieves recent conversations from project and compresses them
+        into a context string suitable for LLM input.
+
+        Args:
+            project_id: Project ID to load context for
+            max_tokens: Maximum tokens for context
+            limit_conversations: Maximum conversations to consider
+
+        Returns:
+            Compressed context string
+
+        Example:
+            >>> context = await memory.load_context_for_session("proj-xyz")
+            >>> print(f"Loaded context: {len(context)} chars")
+        """
+        # Get recent conversations from project
+        conversations = await self.store.list_by_project(
+            project_id, limit=limit_conversations
+        )
+
+        if not conversations:
+            logger.info("No conversations found for project %s", project_id)
+            return ""
+
+        # Compress into context
+        context = await self.compressor.compress_for_context(
+            conversations, max_tokens=max_tokens
+        )
+
+        logger.info(
+            "Loaded context for project %s: %d conversations, %d chars",
+            project_id,
+            len(conversations),
+            len(context),
+        )
+
+        return context
+
+    async def update_conversation(
+        self,
+        conversation_id: str,
+        new_messages: List[ThreadMessage],
+    ) -> Optional[Conversation]:
+        """Update existing conversation with new messages.
+
+        Args:
+            conversation_id: Conversation to update
+            new_messages: New messages to append
+
+        Returns:
+            Updated conversation if found, None otherwise
+
+        Example:
+            >>> updated = await memory.update_conversation(
+            ...     "conv-abc123",
+            ...     [new_message1, new_message2]
+            ... )
+        """
+        # Load existing conversation
+        conversation = await self.store.load(conversation_id)
+        if not conversation:
+            logger.warning("Conversation %s not found", conversation_id)
+            return None
+
+        # Convert and append new messages
+        for thread_msg in new_messages:
+            conv_msg = ConversationMessage.from_thread_message(thread_msg)
+
+            # Extract entities
+            entities = self.extractor.extract(conv_msg.content)
+            conv_msg.entities = [e.to_dict() for e in entities]
+
+            conversation.messages.append(conv_msg)
+
+        # Update timestamp
+        conversation.updated_at = datetime.now(timezone.utc)
+
+        # Regenerate summary if needed
+        updated_summary = await self.compressor.update_summary_if_stale(
+            conversation, message_threshold=5
+        )
+        if updated_summary:
+            conversation.summary = updated_summary
+
+        # Regenerate embedding
+        text_for_embedding = conversation.summary or conversation.get_full_text()[:1000]
+        conversation.embedding = await self.embeddings.embed(text_for_embedding)
+
+        # Save
+        await self.store.save(conversation)
+
+        logger.info(
+            "Updated conversation %s (now %d messages)",
+            conversation_id,
+            len(conversation.messages),
+        )
+
+        return conversation
+
+    async def get_conversation_by_session(
+        self, session_id: str
+    ) -> Optional[Conversation]:
+        """Get conversation by session ID.
+
+        Args:
+            session_id: Session ID from ToolSession
+
+        Returns:
+            Conversation if found, None otherwise
+
+        Example:
+            >>> conv = await memory.get_conversation_by_session("sess-abc123")
+        """
+        # For now, this requires loading and checking
+        # In production, you'd add an index on session_id
+        # This is a placeholder - implement proper query in store
+        logger.warning(
+            "get_conversation_by_session requires optimization - "
+            "add session_id index to store"
+        )
+        return None

claude_mpm/commander/memory/search.py

@@ -0,0 +1,381 @@
+"""Semantic search for conversations.
+
+Provides vector-based and text-based search across all stored conversations
+with filtering by project, date range, and entity types.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+from .embeddings import EmbeddingService
+from .entities import EntityType
+from .store import Conversation, ConversationStore
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SearchResult:
+    """Search result with relevance score.
+
+    Attributes:
+        conversation: Matched conversation
+        score: Relevance score (0-1, higher is more relevant)
+        matched_entities: Entities that matched the query
+        snippet: Relevant text snippet
+
+    Example:
+        >>> result = search_results[0]
+        >>> print(f"Score: {result.score:.3f}")
+        >>> print(f"Conversation: {result.conversation.id}")
+    """
+
+    conversation: Conversation
+    score: float
+    matched_entities: List[str] = None
+    snippet: str = ""
+
+    def __post_init__(self) -> None:
+        """Initialize matched_entities if not provided."""
+        if self.matched_entities is None:
+            self.matched_entities = []
+
+
+class SemanticSearch:
+    """Semantic search across conversations.
+
+    Combines vector similarity search with text search and entity filtering
+    for comprehensive conversation retrieval.
+
+    Attributes:
+        store: ConversationStore for persistence
+        embeddings: EmbeddingService for vector generation
+
+    Example:
+        >>> search = SemanticSearch(store, embeddings)
+        >>> results = await search.search(
+        ...     "how did we fix the login bug?",
+        ...     project_id="proj-xyz",
+        ...     limit=5
+        ... )
+    """
+
+    def __init__(self, store: ConversationStore, embeddings: EmbeddingService):
+        """Initialize semantic search.
+
+        Args:
+            store: ConversationStore for conversation persistence
+            embeddings: EmbeddingService for vector generation
+        """
+        self.store = store
+        self.embeddings = embeddings
+
+        logger.info("SemanticSearch initialized (vector: %s)", store.enable_vector)
+
+    async def search(
+        self,
+        query: str,
+        project_id: Optional[str] = None,
+        limit: int = 10,
+        date_range: Optional[Tuple[datetime, datetime]] = None,
+        entity_types: Optional[List[EntityType]] = None,
+    ) -> List[SearchResult]:
+        """Search conversations semantically.
+
+        Uses vector similarity if available, falls back to text search.
+        Results are ranked by relevance score.
+
+        Args:
+            query: Natural language search query
+            project_id: Optional project ID filter
+            limit: Maximum number of results
+            date_range: Optional (start, end) datetime filter
+            entity_types: Optional list of entity types to filter by
+
+        Returns:
+            List of SearchResult ordered by relevance (highest first)
+
+        Example:
+            >>> results = await search.search(
+            ...     "login bug fix",
+            ...     project_id="proj-xyz",
+            ...     limit=5
+            ... )
+            >>> print(f"Found {len(results)} results")
+            >>> print(f"Top result: {results[0].conversation.summary}")
+        """
+        logger.debug(
+            "Searching conversations (query: %s, project: %s, limit: %d)",
+            query[:50],
+            project_id or "all",
+            limit,
+        )
+
+        if self.store.enable_vector:
+            # Use vector search
+            results = await self._vector_search(query, project_id, limit)
+        else:
+            # Fall back to text search
+            conversations = await self.store.search_by_text(query, project_id, limit)
+            results = [
+                SearchResult(conversation=conv, score=0.5) for conv in conversations
+            ]
+
+        # Apply date range filter
+        if date_range:
+            start, end = date_range
+            results = [r for r in results if start <= r.conversation.updated_at <= end]
+
+        # Apply entity type filter
+        if entity_types:
+            results = self._filter_by_entities(results, entity_types)
+
+        # Generate snippets for top results
+        for result in results[:limit]:
+            result.snippet = self._generate_snippet(result.conversation, query)
+
+        logger.info("Search returned %d results", len(results))
+        return results[:limit]
+
+    async def _vector_search(
+        self,
+        query: str,
+        project_id: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[SearchResult]:
+        """Perform vector similarity search.
+
+        Args:
+            query: Search query
+            project_id: Optional project filter
+            limit: Maximum results
+
+        Returns:
+            List of SearchResult with similarity scores
+        """
+        # Generate query embedding
+        query_embedding = await self.embeddings.embed(query)
+
+        # Get all conversations (TODO: optimize with vector DB query)
+        if project_id:
+            conversations = await self.store.list_by_project(project_id, limit=100)
+        else:
+            # For now, we'll search recent conversations across all projects
+            # In production, you'd want to implement proper vector search in SQL
+            conversations = []
+            logger.warning(
+                "Vector search without project_id not fully optimized. "
+                "Consider implementing KNN query in SQL."
+            )
+
+        # Calculate similarities
+        results = []
+        for conv in conversations:
+            if not conv.embedding:
+                # Generate embedding if missing
+                text = conv.summary or conv.get_full_text()[:1000]
+                conv.embedding = await self.embeddings.embed(text)
+                await self.store.save(conv)
+
+            # Calculate cosine similarity
+            score = self.embeddings.cosine_similarity(query_embedding, conv.embedding)
+            results.append(SearchResult(conversation=conv, score=score))
+
+        # Sort by score descending
+        results.sort(key=lambda r: r.score, reverse=True)
+
+        return results[:limit]
+
+    def _filter_by_entities(
+        self, results: List[SearchResult], entity_types: List[EntityType]
+    ) -> List[SearchResult]:
+        """Filter results by entity types.
+
+        Args:
+            results: Search results to filter
+            entity_types: Entity types to require
+
+        Returns:
+            Filtered results
+        """
+        filtered = []
+        for result in results:
+            # Check if conversation has any messages with matching entities
+            has_entity = False
+            for msg in result.conversation.messages:
+                for entity in msg.entities:
+                    if EntityType(entity["type"]) in entity_types:
+                        has_entity = True
+                        if "matched_entities" not in result.matched_entities:
+                            result.matched_entities.append(entity["value"])
+
+            if has_entity:
+                filtered.append(result)
+
+        return filtered
+
+    def _generate_snippet(self, conversation: Conversation, query: str) -> str:
+        """Generate relevant text snippet from conversation.
+
+        Args:
+            conversation: Conversation to extract snippet from
+            query: Search query for context
+
+        Returns:
+            Relevant snippet (max 200 chars)
+        """
+        # Try to find message containing query terms
+        query_terms = query.lower().split()
+
+        for msg in conversation.messages:
+            content_lower = msg.content.lower()
+            if any(term in content_lower for term in query_terms):
+                # Found relevant message, extract snippet
+                start_idx = 0
+                for term in query_terms:
+                    if term in content_lower:
+                        start_idx = content_lower.index(term)
+                        break
+
+                # Extract context around match
+                snippet_start = max(0, start_idx - 50)
+                snippet_end = min(len(msg.content), start_idx + 150)
+                snippet = msg.content[snippet_start:snippet_end]
+
+                # Add ellipsis if truncated
+                if snippet_start > 0:
+                    snippet = "..." + snippet
+                if snippet_end < len(msg.content):
+                    snippet = snippet + "..."
+
+                return snippet.strip()
+
+        # No match found, use summary or first message
+        if conversation.summary:
+            return conversation.summary[:200]
+        if conversation.messages:
+            return conversation.messages[0].content[:200] + "..."
+
+        return ""
+
+    async def find_similar(
+        self,
+        conversation_id: str,
+        limit: int = 5,
+    ) -> List[SearchResult]:
+        """Find conversations similar to a given conversation.
+
+        Args:
+            conversation_id: Reference conversation ID
+            limit: Maximum number of similar conversations
+
+        Returns:
+            List of similar conversations ordered by similarity
+
+        Example:
+            >>> similar = await search.find_similar("conv-abc123", limit=5)
+        """
+        # Load reference conversation
+        ref_conv = await self.store.load(conversation_id)
+        if not ref_conv:
+            logger.warning("Conversation %s not found", conversation_id)
+            return []
+
+        # Ensure embedding exists
+        if not ref_conv.embedding:
+            text = ref_conv.summary or ref_conv.get_full_text()[:1000]
+            ref_conv.embedding = await self.embeddings.embed(text)
+            await self.store.save(ref_conv)
+
+        # Get all conversations from same project
+        all_convs = await self.store.list_by_project(ref_conv.project_id, limit=100)
+
+        # Calculate similarities
+        results = []
+        for conv in all_convs:
+            # Skip the reference conversation itself
+            if conv.id == conversation_id:
+                continue
+
+            if not conv.embedding:
+                text = conv.summary or conv.get_full_text()[:1000]
+                conv.embedding = await self.embeddings.embed(text)
+                await self.store.save(conv)
+
+            score = self.embeddings.cosine_similarity(
+                ref_conv.embedding, conv.embedding
+            )
+            results.append(SearchResult(conversation=conv, score=score))
+
+        # Sort by similarity
+        results.sort(key=lambda r: r.score, reverse=True)
+
+        logger.info(
+            "Found %d similar conversations to %s",
+            len(results[:limit]),
+            conversation_id,
+        )
+        return results[:limit]
+
+    async def search_by_entities(
+        self,
+        entity_type: EntityType,
+        entity_value: str,
+        project_id: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[SearchResult]:
+        """Search conversations by specific entity.
+
+        Args:
+            entity_type: Type of entity to search for
+            entity_value: Entity value (e.g., "src/auth.py")
+            project_id: Optional project filter
+            limit: Maximum results
+
+        Returns:
+            List of conversations containing the entity
+
+        Example:
+            >>> results = await search.search_by_entities(
+            ...     EntityType.FILE,
+            ...     "src/auth.py",
+            ...     project_id="proj-xyz"
+            ... )
+        """
+        # Get conversations from project
+        if project_id:
+            conversations = await self.store.list_by_project(project_id, limit=100)
+        else:
+            conversations = []
+            logger.warning("Entity search without project_id requires full scan")
+
+        # Filter by entity
+        results = []
+        for conv in conversations:
+            for msg in conv.messages:
+                for entity in msg.entities:
+                    if (
+                        entity.get("type") == entity_type.value
+                        and entity.get("value") == entity_value
+                    ):
+                        results.append(
+                            SearchResult(
+                                conversation=conv,
+                                score=1.0,  # Exact match
+                                matched_entities=[entity_value],
+                            )
+                        )
+                        break
+
+            if len(results) >= limit:
+                break
+
+        logger.info(
+            "Found %d conversations with entity %s:%s",
+            len(results),
+            entity_type.value,
+            entity_value,
+        )
+        return results[:limit]