claude-mpm 3.1.3__py3-none-any.whl → 3.2.1__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_wrapper.sh

@@ -2,7 +2,7 @@
 # Claude Code hook wrapper for claude-mpm
 
 # Debug log (optional - comment out in production)
-# echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Wrapper called with args: $@" >> /tmp/hook-wrapper.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Wrapper called with args: $@" >> /tmp/hook-wrapper.log
 
 # Get the directory where this script is located
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
@@ -39,9 +39,14 @@ if [[ " $* " =~ " --logging DEBUG " ]] || [[ " $* " =~ " --debug " ]]; then
     export CLAUDE_MPM_LOG_LEVEL="DEBUG"
 fi
 
+# Set Socket.IO configuration for hook events
+export CLAUDE_MPM_SOCKETIO_PORT="8765"
+export CLAUDE_MPM_HOOK_DEBUG="true"
+
 # Debug log (optional)
-# echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] PYTHONPATH: $PYTHONPATH" >> /tmp/hook-wrapper.log
-# echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Running: $PYTHON_CMD $SCRIPT_DIR/hook_handler.py" >> /tmp/hook-wrapper.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] PYTHONPATH: $PYTHONPATH" >> /tmp/hook-wrapper.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Running: $PYTHON_CMD $SCRIPT_DIR/hook_handler.py" >> /tmp/hook-wrapper.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] SOCKETIO_PORT: $CLAUDE_MPM_SOCKETIO_PORT" >> /tmp/hook-wrapper.log
 
-# Run the Python hook handler
+# Run the Python hook handler (now optimized by default)
 exec "$PYTHON_CMD" "$SCRIPT_DIR/hook_handler.py" "$@"

claude_mpm/hooks/memory_integration_hook.py

@@ -0,0 +1,312 @@
+"""Memory integration hooks for automatic agent memory management.
+
+WHY: Agents need to accumulate project-specific knowledge over time. These hooks
+automatically inject agent memory before delegation and extract learnings after,
+enabling agents to become more effective through experience.
+
+DESIGN DECISION: We use explicit markers to extract structured learnings from
+agent outputs because:
+- It gives agents explicit control over what gets memorized
+- The format is clear and unambiguous
+- It's more reliable than pattern matching
+- Agents can add multiple learnings in a single response
+"""
+
+import re
+from typing import Dict, Any, List
+from claude_mpm.hooks.base_hook import PreDelegationHook, PostDelegationHook, HookContext, HookResult
+from claude_mpm.services.agent_memory_manager import AgentMemoryManager
+from claude_mpm.services.socketio_server import get_socketio_server
+from claude_mpm.core.config import Config
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryPreDelegationHook(PreDelegationHook):
+    """Inject agent memory into delegation context.
+    
+    WHY: Agents perform better when they have access to accumulated project knowledge.
+    This hook loads agent-specific memory and adds it to the delegation context,
+    allowing agents to apply learned patterns and avoid known mistakes.
+    
+    DESIGN DECISION: Memory is injected as a clearly formatted section in the context
+    to ensure agents understand it's their accumulated knowledge, not current task info.
+    """
+    
+    def __init__(self, config: Config = None):
+        """Initialize with optional config.
+        
+        Args:
+            config: Optional Config object. If not provided, will create default Config.
+        """
+        super().__init__(name="memory_pre_delegation", priority=20)
+        self.config = config or Config()
+        self.memory_manager = AgentMemoryManager(self.config)
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Add agent memory to delegation context.
+        
+        WHY: By loading memory before delegation, agents can reference their
+        accumulated knowledge when performing tasks, leading to better outcomes.
+        """
+        try:
+            # Extract and normalize agent ID from context
+            agent_name = context.data.get('agent', '')
+            if not agent_name:
+                return HookResult(success=True, data=context.data, modified=False)
+            
+            # Normalize agent ID (e.g., "Engineer Agent" -> "engineer")
+            agent_id = agent_name.lower().replace(' ', '_').replace('_agent', '').replace('agent', '').strip('_')
+            
+            if agent_id:
+                # Load agent memory
+                memory_content = self.memory_manager.load_agent_memory(agent_id)
+                
+                if memory_content and memory_content.strip():
+                    # Get existing context data
+                    delegation_context = context.data.get('context', {})
+                    if isinstance(delegation_context, str):
+                        # If context is a string, convert to dict
+                        delegation_context = {'prompt': delegation_context}
+                    
+                    # Add memory with clear formatting
+                    memory_section = f"""
+AGENT MEMORY - PROJECT-SPECIFIC KNOWLEDGE:
+{memory_content}
+
+INSTRUCTIONS: Review your memory above before proceeding. Apply learned patterns and avoid known mistakes.
+"""
+                    
+                    # Add to context
+                    delegation_context['agent_memory'] = memory_section
+                    
+                    # Update the context data
+                    updated_data = context.data.copy()
+                    updated_data['context'] = delegation_context
+                    
+                    logger.info(f"Injected memory for agent '{agent_id}'")
+                    
+                    # Emit Socket.IO event for memory injected
+                    try:
+                        socketio_server = get_socketio_server()
+                        # Calculate size of injected content
+                        injected_size = len(memory_section.encode('utf-8'))
+                        socketio_server.memory_injected(agent_id, injected_size)
+                    except Exception as ws_error:
+                        logger.debug(f"Socket.IO notification failed: {ws_error}")
+                    
+                    return HookResult(
+                        success=True,
+                        data=updated_data,
+                        modified=True,
+                        metadata={'memory_injected': True, 'agent_id': agent_id}
+                    )
+            
+            return HookResult(success=True, data=context.data, modified=False)
+                
+        except Exception as e:
+            logger.error(f"Memory injection failed: {e}")
+            # Don't fail the delegation if memory injection fails
+            return HookResult(
+                success=True,
+                data=context.data,
+                modified=False,
+                error=f"Memory injection failed: {str(e)}"
+            )
+
+
+class MemoryPostDelegationHook(PostDelegationHook):
+    """Extract learnings from delegation results using explicit markers.
+    
+    WHY: Agents produce valuable insights during task execution. This hook
+    extracts structured learnings from their outputs using explicit markers,
+    building up project-specific knowledge over time.
+    
+    DESIGN DECISION: We use explicit markers to give agents full control over
+    what gets memorized. This is more reliable than pattern matching and allows
+    multiple learnings per response. Supports multiple trigger phrases for flexibility.
+    
+    Supported formats:
+    # Add To Memory:
+    Type: pattern
+    Content: All services use dependency injection for flexibility
+    #
+    
+    # Memorize:
+    Type: guideline
+    Content: Always validate input parameters before processing
+    #
+    
+    # Remember:
+    Type: mistake
+    Content: Never hardcode configuration values
+    #
+    """
+    
+    def __init__(self, config: Config = None):
+        """Initialize with optional config.
+        
+        Args:
+            config: Optional Config object. If not provided, will create default Config.
+        """
+        super().__init__(name="memory_post_delegation", priority=80)
+        self.config = config or Config()
+        self.memory_manager = AgentMemoryManager(self.config)
+        
+        # Map of supported types to memory sections
+        self.type_mapping = {
+            'pattern': 'pattern',           # Coding Patterns Learned
+            'architecture': 'architecture', # Project Architecture
+            'guideline': 'guideline',      # Implementation Guidelines
+            'mistake': 'mistake',          # Common Mistakes to Avoid
+            'strategy': 'strategy',        # Effective Strategies
+            'integration': 'integration',  # Integration Points
+            'performance': 'performance',  # Performance Considerations
+            'context': 'context'           # Current Technical Context
+        }
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Extract and store learnings from delegation result.
+        
+        WHY: Capturing learnings immediately after task completion ensures we
+        don't lose valuable insights that agents discover during execution.
+        """
+        try:
+            # Check if auto-learning is enabled
+            if not self.config.get('memory.auto_learning', False):
+                return HookResult(success=True, data=context.data, modified=False)
+            
+            # Extract agent ID
+            agent_name = context.data.get('agent', '')
+            if not agent_name:
+                return HookResult(success=True, data=context.data, modified=False)
+            
+            # Normalize agent ID
+            agent_id = agent_name.lower().replace(' ', '_').replace('_agent', '').replace('agent', '').strip('_')
+            
+            # Check if auto-learning is enabled for this specific agent
+            agent_overrides = self.config.get('memory.agent_overrides', {})
+            agent_config = agent_overrides.get(agent_id, {})
+            if 'auto_learning' in agent_config and not agent_config['auto_learning']:
+                return HookResult(success=True, data=context.data, modified=False)
+            
+            # Extract result content
+            result = context.data.get('result', {})
+            if isinstance(result, dict):
+                result_text = result.get('content', '') or str(result)
+            else:
+                result_text = str(result)
+            
+            if agent_id and result_text:
+                # Extract learnings using patterns
+                learnings = self._extract_learnings(result_text)
+                
+                # Store each learning
+                learnings_stored = 0
+                for learning_type, items in learnings.items():
+                    for item in items:
+                        try:
+                            self.memory_manager.add_learning(agent_id, learning_type, item)
+                            learnings_stored += 1
+                        except Exception as e:
+                            logger.warning(f"Failed to store learning: {e}")
+                
+                if learnings_stored > 0:
+                    logger.info(f"Extracted {learnings_stored} learnings for agent '{agent_id}'")
+                    
+                    return HookResult(
+                        success=True,
+                        data=context.data,
+                        modified=False,
+                        metadata={
+                            'learnings_extracted': learnings_stored,
+                            'agent_id': agent_id
+                        }
+                    )
+            
+            return HookResult(success=True, data=context.data, modified=False)
+                
+        except Exception as e:
+            logger.error(f"Learning extraction failed: {e}")
+            # Don't fail the delegation result if learning extraction fails
+            return HookResult(
+                success=True,
+                data=context.data,
+                modified=False,
+                error=f"Learning extraction failed: {str(e)}"
+            )
+    
+    def _extract_learnings(self, text: str) -> Dict[str, List[str]]:
+        """Extract structured learnings from text using explicit markers.
+        
+        WHY: We limit learnings to 100 characters to keep memory entries
+        concise and actionable. Longer entries tend to be less useful as
+        quick reference points.
+        
+        DESIGN DECISION: Using explicit markers gives agents full control and makes
+        extraction reliable. We support multiple memory additions in a single response
+        and multiple trigger phrases (Add To Memory, Memorize, Remember) for flexibility.
+        
+        Args:
+            text: The text to extract learnings from
+            
+        Returns:
+            Dictionary mapping learning types to lists of extracted learnings
+        """
+        learnings = {learning_type: [] for learning_type in self.type_mapping.keys()}
+        seen_learnings = set()  # Avoid duplicates
+        
+        # Pattern to find memory blocks with multiple trigger phrases
+        # Matches: # Add To Memory: / # Memorize: / # Remember:\n...\n#
+        # Only matches complete blocks with proper closing markers
+        memory_pattern = r'#\s*(?:Add\s+To\s+Memory|Memorize|Remember):\s*\n((?:[^#](?:[^#]|#(?!\s*(?:Add\s+To\s+Memory|Memorize|Remember):))*?)?)\n\s*#\s*$'
+        matches = re.finditer(memory_pattern, text, re.MULTILINE | re.DOTALL | re.IGNORECASE)
+        
+        for match in matches:
+            block_content = match.group(1).strip()
+            logger.debug(f"Found memory block: {block_content[:50]}...")
+            
+            # Extract type and content from the block
+            type_match = re.search(r'Type:\s*(\w+)', block_content, re.IGNORECASE)
+            content_match = re.search(r'Content:\s*(.+)', block_content, re.IGNORECASE | re.DOTALL)
+            
+            if type_match and content_match:
+                learning_type = type_match.group(1).lower().strip()
+                content = content_match.group(1).strip()
+                
+                # Clean up multi-line content - take first line if multiple
+                if '\n' in content:
+                    content = content.split('\n')[0].strip()
+                
+                # Remove trailing punctuation
+                content = content.rstrip('.!?,;')
+                
+                # Validate type is supported
+                if learning_type in self.type_mapping:
+                    # Check content length (between 5 and 100 characters)
+                    if content and 5 < len(content) <= 100:
+                        # Normalize for duplicate detection
+                        normalized = content.lower()
+                        if normalized not in seen_learnings:
+                            learnings[learning_type].append(content)
+                            seen_learnings.add(normalized)
+                            logger.debug(f"Extracted learning - Type: {learning_type}, Content: {content}")
+                        else:
+                            logger.debug(f"Skipping duplicate learning: {content}")
+                    else:
+                        logger.debug(f"Skipping learning - invalid length ({len(content)}): {content}")
+                else:
+                    logger.warning(f"Unsupported learning type: {learning_type}. Supported types: {list(self.type_mapping.keys())}")
+            else:
+                logger.debug(f"Invalid memory block format - missing Type or Content")
+        
+        # Log summary of extracted learnings
+        total_learnings = sum(len(items) for items in learnings.values())
+        if total_learnings > 0:
+            logger.info(f"Extracted {total_learnings} learnings from agent response")
+            for learning_type, items in learnings.items():
+                if items:
+                    logger.debug(f"  {learning_type}: {len(items)} items")
+        
+        return learnings

claude_mpm/models/__init__.py

@@ -1,106 +1,24 @@
 """
-Claude MPM Models Package
-=========================
+Agent models package.
 
-Centralized data models for the Claude MPM system.
-
-WHY: This package centralizes all data models to:
-- Prevent circular imports
-- Reduce code duplication
-- Ensure consistent data structures
-- Make models easily discoverable
-
-DESIGN DECISION: Models are organized by domain:
-- agent_definition: Core agent behavior models
-- lifecycle: Agent lifecycle management models
-- modification: Change tracking models
-- persistence: Storage operation models
-- registry: Discovery and management models
-- common: Shared constants and enums
+WHY: This package centralizes all data models used for agent management,
+providing a single source of truth for data structures across the system.
 """
 
-# Agent definition models
 from .agent_definition import (
+    AgentDefinition,
+    AgentMetadata,
     AgentType,
     AgentSection,
-    AgentPermissions,
     AgentWorkflow,
-    AgentMetadata,
-    AgentDefinition
-)
-
-# Lifecycle models
-from .lifecycle import (
-    LifecycleOperation,
-    LifecycleState,
-    AgentLifecycleRecord,
-    LifecycleOperationResult
-)
-
-# Modification models
-from .modification import (
-    ModificationType,
-    ModificationTier,
-    AgentModification,
-    ModificationHistory
-)
-
-# Persistence models
-from .persistence import (
-    PersistenceStrategy,
-    PersistenceOperation,
-    PersistenceRecord
-)
-
-# Registry models
-from .registry import (
-    AgentTier,
-    AgentRegistryMetadata
-)
-
-# Common constants
-from .common import (
-    AGENT_FILE_EXTENSIONS,
-    AGENT_IGNORE_PATTERNS,
-    CORE_AGENT_TYPES,
-    SPECIALIZED_AGENT_TYPES,
-    ALL_AGENT_TYPES
+    AgentPermissions
 )
 
 __all__ = [
-    # Agent definition
+    'AgentDefinition',
+    'AgentMetadata',
     'AgentType',
     'AgentSection',
-    'AgentPermissions',
     'AgentWorkflow',
-    'AgentMetadata',
-    'AgentDefinition',
-    
-    # Lifecycle
-    'LifecycleOperation',
-    'LifecycleState',
-    'AgentLifecycleRecord',
-    'LifecycleOperationResult',
-    
-    # Modification
-    'ModificationType',
-    'ModificationTier',
-    'AgentModification',
-    'ModificationHistory',
-    
-    # Persistence
-    'PersistenceStrategy',
-    'PersistenceOperation',
-    'PersistenceRecord',
-    
-    # Registry
-    'AgentTier',
-    'AgentRegistryMetadata',
-    
-    # Common
-    'AGENT_FILE_EXTENSIONS',
-    'AGENT_IGNORE_PATTERNS',
-    'CORE_AGENT_TYPES',
-    'SPECIALIZED_AGENT_TYPES',
-    'ALL_AGENT_TYPES'
+    'AgentPermissions'
 ]

claude_mpm/orchestration/__init__.py

@@ -1,6 +1,6 @@
 """Orchestration components for Claude MPM (legacy)."""
 
-# Most orchestration components have been simplified and moved to core.simple_runner
+# Most orchestration components have been simplified and moved to core.claude_runner
 # This module is kept for backwards compatibility
 
 __all__ = []

claude_mpm/scripts/claude-mpm-socketio

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Wrapper script for Socket.IO server daemon management.
+#
+# This script provides a simple command-line interface for managing
+# the Socket.IO server daemon that powers the monitoring dashboard.
+#
+# Usage:
+#   claude-mpm-socketio start     - Start the server daemon
+#   claude-mpm-socketio stop      - Stop the server daemon
+#   claude-mpm-socketio restart   - Restart the server daemon
+#   claude-mpm-socketio status    - Check server status
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Path to the Python daemon script
+DAEMON_SCRIPT="${SCRIPT_DIR}/socketio_daemon.py"
+
+# Check if the daemon script exists
+if [ ! -f "$DAEMON_SCRIPT" ]; then
+    echo "Error: Socket.IO daemon script not found at $DAEMON_SCRIPT"
+    exit 1
+fi
+
+# Check if Python is available
+if ! command -v python3 &> /dev/null; then
+    echo "Error: Python 3 is required but not found"
+    exit 1
+fi
+
+# Execute the Python daemon with all arguments
+exec python3 "$DAEMON_SCRIPT" "$@"