claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/commander/memory/example_usage.py

@@ -0,0 +1,290 @@
+"""Example usage of Commander memory system.
+
+Demonstrates:
+1. Capturing conversations from Project
+2. Searching conversations semantically
+3. Loading context for session resumption
+4. Entity extraction and filtering
+"""
+
+import asyncio
+
+from ..models.project import Project, ProjectState, ThreadMessage
+from .entities import EntityType
+from .integration import MemoryIntegration
+
+
+async def example_basic_usage():
+    """Example 1: Basic conversation capture and search."""
+    print("\n=== Example 1: Basic Usage ===\n")
+
+    # Initialize memory integration
+    memory = MemoryIntegration.create()
+
+    # Create sample project with conversation
+    project = Project(
+        id="proj-example-123",
+        path="/Users/masa/Projects/example-app",
+        name="example-app",
+        state=ProjectState.IDLE,
+    )
+
+    # Add sample conversation to project
+    project.thread = [
+        ThreadMessage(
+            id="msg-1",
+            role="user",
+            content="Fix the login authentication bug in src/auth.py",
+        ),
+        ThreadMessage(
+            id="msg-2",
+            role="assistant",
+            content="I'll investigate the authentication bug. Let me read the auth.py file.",
+        ),
+        ThreadMessage(
+            id="msg-3",
+            role="assistant",
+            content="Found the issue in UserService.authenticate() - the token validation was missing expiry check. Fixed it.",
+        ),
+        ThreadMessage(
+            id="msg-4",
+            role="user",
+            content="Great! Can you also add tests for this fix?",
+        ),
+        ThreadMessage(
+            id="msg-5",
+            role="assistant",
+            content="Added test_token_expiry_validation() in tests/test_auth.py. All tests passing.",
+        ),
+    ]
+
+    # Capture conversation
+    conversation = await memory.capture_project_conversation(
+        project, instance_name="claude-code-1", session_id="sess-abc123"
+    )
+
+    print(f"✅ Captured conversation: {conversation.id}")
+    print(f"   Messages: {len(conversation.messages)}")
+    print(f"   Summary: {conversation.summary}")
+    print(
+        f"   Entities extracted: {len([e for msg in conversation.messages for e in msg.entities])}"
+    )
+
+    # Search conversations
+    print("\n🔍 Searching for 'authentication bug'...")
+    results = await memory.search_conversations(
+        "authentication bug fix", project_id=project.id, limit=3
+    )
+
+    for i, result in enumerate(results, 1):
+        print(f"\n{i}. Score: {result.score:.3f}")
+        print(f"   Conversation: {result.conversation.id}")
+        print(f"   Snippet: {result.snippet[:100]}...")
+
+
+async def example_entity_search():
+    """Example 2: Entity-based search and filtering."""
+    print("\n=== Example 2: Entity Search ===\n")
+
+    memory = MemoryIntegration.create()
+
+    # Create project with file references
+    project = Project(
+        id="proj-example-456",
+        path="/Users/masa/Projects/example-app",
+        name="example-app",
+    )
+
+    project.thread = [
+        ThreadMessage(
+            id="msg-1",
+            role="user",
+            content="Update the UserService class in src/services/user_service.py",
+        ),
+        ThreadMessage(
+            id="msg-2",
+            role="assistant",
+            content="I'll update UserService.create_user() to include email validation. Also updating tests/test_user_service.py.",
+        ),
+    ]
+
+    # Capture
+    conversation = await memory.capture_project_conversation(
+        project, instance_name="claude-code-2"
+    )
+
+    # Extract entities
+    entities = []
+    for msg in conversation.messages:
+        entities.extend(msg.entities)
+
+    # Filter by type
+    files = memory.extractor.get_unique_values(
+        [memory.extractor.Entity.from_dict(e) for e in entities], EntityType.FILE
+    )
+    print(f"📁 Files mentioned: {files}")
+
+    classes = memory.extractor.get_unique_values(
+        [memory.extractor.Entity.from_dict(e) for e in entities], EntityType.CLASS
+    )
+    print(f"🏗️  Classes mentioned: {classes}")
+
+    # Search by entity
+    print("\n🔍 Finding conversations that mention 'src/services/user_service.py'...")
+    results = await memory.search.search_by_entities(
+        EntityType.FILE,
+        "src/services/user_service.py",
+        project_id=project.id,
+    )
+
+    print(f"Found {len(results)} conversations mentioning this file")
+
+
+async def example_context_loading():
+    """Example 3: Load context for session resumption."""
+    print("\n=== Example 3: Context Loading for Session Resumption ===\n")
+
+    memory = MemoryIntegration.create()
+
+    # Create multiple conversations (simulating historical work)
+    project = Project(
+        id="proj-example-789",
+        path="/Users/masa/Projects/example-app",
+        name="example-app",
+    )
+
+    # Conversation 1: Week ago
+    project.thread = [
+        ThreadMessage(
+            id="msg-1",
+            role="user",
+            content="Implement user registration with email verification",
+        ),
+        ThreadMessage(
+            id="msg-2",
+            role="assistant",
+            content="Implemented registration in src/auth.py with email service integration",
+        ),
+    ]
+    await memory.capture_project_conversation(project, instance_name="claude-code-1")
+
+    # Conversation 2: Yesterday
+    project.thread = [
+        ThreadMessage(
+            id="msg-3",
+            role="user",
+            content="Fix the email verification bug - tokens not expiring",
+        ),
+        ThreadMessage(
+            id="msg-4",
+            role="assistant",
+            content="Fixed token expiry check in src/auth.py and added tests",
+        ),
+    ]
+    await memory.capture_project_conversation(project, instance_name="claude-code-1")
+
+    # Load context for resumption
+    print("📖 Loading context for session resumption...")
+    context = await memory.load_context_for_session(
+        project.id, max_tokens=4000, limit_conversations=10
+    )
+
+    print(f"✅ Loaded context ({len(context)} chars):\n")
+    print(context[:500] + "...\n")
+
+    print(
+        "This context would be injected into the new session to provide historical awareness."
+    )
+
+
+async def example_similarity_search():
+    """Example 4: Find similar conversations."""
+    print("\n=== Example 4: Similarity Search ===\n")
+
+    memory = MemoryIntegration.create()
+
+    # Create project with multiple conversations
+    project = Project(
+        id="proj-example-999",
+        path="/Users/masa/Projects/example-app",
+        name="example-app",
+    )
+
+    # Reference conversation
+    project.thread = [
+        ThreadMessage(
+            id="msg-1",
+            role="user",
+            content="Fix the authentication bug in login flow",
+        ),
+        ThreadMessage(
+            id="msg-2",
+            role="assistant",
+            content="Fixed token validation in src/auth.py",
+        ),
+    ]
+    ref_conv = await memory.capture_project_conversation(project)
+
+    # Similar conversation
+    project.thread = [
+        ThreadMessage(
+            id="msg-3",
+            role="user",
+            content="Update the login authentication to use OAuth",
+        ),
+        ThreadMessage(
+            id="msg-4",
+            role="assistant",
+            content="Implemented OAuth in src/auth.py",
+        ),
+    ]
+    await memory.capture_project_conversation(project)
+
+    # Different conversation
+    project.thread = [
+        ThreadMessage(
+            id="msg-5",
+            role="user",
+            content="Add dark mode toggle to the UI",
+        ),
+        ThreadMessage(
+            id="msg-6",
+            role="assistant",
+            content="Added dark mode CSS in styles/theme.css",
+        ),
+    ]
+    await memory.capture_project_conversation(project)
+
+    # Find similar
+    print(f"🔍 Finding conversations similar to: {ref_conv.id}")
+    similar = await memory.search.find_similar(ref_conv.id, limit=3)
+
+    for i, result in enumerate(similar, 1):
+        print(f"\n{i}. Similarity: {result.score:.3f}")
+        print(f"   Conversation: {result.conversation.id}")
+        print(f"   Summary: {result.conversation.summary}")
+
+
+async def main():
+    """Run all examples."""
+    print("\n" + "=" * 60)
+    print("Commander Memory System - Example Usage")
+    print("=" * 60)
+
+    # Run examples
+    await example_basic_usage()
+    await example_entity_search()
+    await example_context_loading()
+    await example_similarity_search()
+
+    print("\n" + "=" * 60)
+    print("✅ All examples completed!")
+    print("=" * 60 + "\n")
+
+    print("📚 For more information, see:")
+    print("   - src/claude_mpm/commander/memory/README.md")
+    print("   - API documentation in each module")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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