claude-mpm 3.3.2__py3-none-any.whl → 3.4.2__py3-none-any.whl

claude_mpm/cli/commands/memory.py

@@ -10,6 +10,7 @@ with other command modules like agents.py.
 """
 
 import json
+import os
 from datetime import datetime
 from pathlib import Path
 
@@ -38,7 +39,11 @@ def manage_memory(args):
     try:
         # Load configuration for memory manager
         config = Config()
-        memory_manager = AgentMemoryManager(config)
+        # Use CLAUDE_MPM_USER_PWD if available (when called via shell script),
+        # otherwise use current working directory
+        user_pwd = os.environ.get('CLAUDE_MPM_USER_PWD', os.getcwd())
+        current_dir = Path(user_pwd)
+        memory_manager = AgentMemoryManager(config, current_dir)
         
         if not args.memory_command:
             # No subcommand - show status
@@ -49,7 +54,7 @@ def manage_memory(args):
             _show_status(memory_manager)
         
         elif args.memory_command == "view":
-            _view_memory(args, memory_manager)
+            _show_memories(args, memory_manager)
         
         elif args.memory_command == "add":
             _add_learning(args, memory_manager)
@@ -72,6 +77,15 @@ def manage_memory(args):
         elif args.memory_command == "show":
             _show_memories(args, memory_manager)
         
+        elif args.memory_command == "init":
+            _init_memory(args, memory_manager)
+        
+        else:
+            logger.error(f"Unknown memory command: {args.memory_command}")
+            print(f"Unknown memory command: {args.memory_command}")
+            print("Available commands: init, status, view, add, clean, optimize, build, cross-ref, route, show")
+            return 1
+        
     except Exception as e:
         logger.error(f"Error managing memory: {e}")
         print(f"❌ Error: {e}")
@@ -80,6 +94,71 @@ def manage_memory(args):
     return 0
 
 
+def _init_memory(args, memory_manager):
+    """
+    Initialize project-specific memories via agent delegation.
+    
+    WHY: When starting with a new project, agents need project-specific knowledge
+    beyond what automatic analysis provides. This command triggers an agent task
+    to comprehensively scan the project and create custom memories.
+    
+    Args:
+        args: Command line arguments (unused but kept for consistency)
+        memory_manager: AgentMemoryManager instance
+    """
+    logger = get_logger("cli")
+    
+    print("🚀 Initializing project-specific memories...")
+    print("=" * 80)
+    print()
+    print("This will analyze the project to:")
+    print("  1. Scan project structure and documentation")
+    print("  2. Analyze source code for patterns and conventions")
+    print("  3. Create targeted memories for each agent type")
+    print("  4. Add insights using 'claude-mpm memory add' commands")
+    print()
+    print("The analysis will cover:")
+    print("  • Project architecture and design patterns")
+    print("  • Coding conventions and standards")
+    print("  • Key modules and integration points")
+    print("  • Testing patterns and quality standards")
+    print("  • Performance considerations")
+    print("  • Domain-specific terminology")
+    print()
+    print("=" * 80)
+    print()
+    print("[Agent Task: Initialize Project-Specific Memories]")
+    print()
+    print("Please analyze this project and create custom memories for all agents.")
+    print()
+    print("Instructions:")
+    print("1. Scan the project structure, documentation, and source code")
+    print("2. Identify key patterns, conventions, and project-specific knowledge")
+    print("3. Create targeted memories for each agent type")
+    print("4. Use 'claude-mpm memory add <agent> <type> \"<content>\"' commands")
+    print()
+    print("Focus areas:")
+    print("  • Architectural patterns and design decisions")
+    print("  • Coding conventions from actual source code")
+    print("  • Key modules, APIs, and integration points")
+    print("  • Testing patterns and quality standards")
+    print("  • Performance considerations specific to this project")
+    print("  • Common pitfalls based on the codebase")
+    print("  • Domain-specific terminology and concepts")
+    print()
+    print("Example commands to use:")
+    print('  claude-mpm memory add engineer pattern "Use dependency injection with @inject"')
+    print('  claude-mpm memory add qa pattern "Test files follow test_<module>_<feature>.py"')
+    print('  claude-mpm memory add research context "Project uses microservices architecture"')
+    print()
+    print("Begin by examining the project structure and key files.")
+    print()
+    print("=" * 80)
+    print()
+    print("📝 Note: Copy the task above to execute the memory initialization process.")
+    print("    Use 'claude-mpm memory add' commands to add discovered insights.")
+    
+
 def _show_status(memory_manager):
     """
     Show comprehensive memory system status.
@@ -113,7 +192,7 @@ def _show_status(memory_manager):
         print(f"🧠 Memory System Health: {health_emoji} {system_health}")
         print(f"📁 Memory Directory: {status.get('memory_directory', 'Unknown')}")
         print(f"🔧 System Enabled: {'Yes' if status.get('system_enabled', True) else 'No'}")
-        print(f"📚 Auto Learning: {'Yes' if status.get('auto_learning', False) else 'No'}")
+        print(f"📚 Auto Learning: {'Yes' if status.get('auto_learning', True) else 'No'}")
         print(f"📊 Total Agents: {status.get('total_agents', 0)}")
         print(f"💾 Total Size: {status.get('total_size_kb', 0):.1f} KB")
         print()
@@ -143,7 +222,7 @@ def _show_status(memory_manager):
                 sections = agent_info.get("sections", 0)
                 items = agent_info.get("items", 0)
                 last_modified = agent_info.get("last_modified", "Unknown")
-                auto_learning = agent_info.get("auto_learning", False)
+                auto_learning = agent_info.get("auto_learning", True)
                 
                 # Format last modified time
                 try:
@@ -474,24 +553,48 @@ def _show_memories(args, memory_manager):
     WHY: Users need to see agent memories in a readable format to understand
     what agents have learned and identify common patterns across agents.
     
+    DESIGN DECISION: Added --raw flag to output structured JSON data for
+    programmatic processing, enabling external tools and scripts to access
+    all agent memories in a structured format.
+    
     Args:
-        args: Command arguments with optional agent_id and format
+        args: Command arguments with optional agent_id, format, and raw flag
         memory_manager: AgentMemoryManager instance
     """
-    print("🧠 Agent Memories Display")
-    print("-" * 80)
-    
     agent_id = getattr(args, 'agent_id', None)
-    format_type = getattr(args, 'format', 'summary')
+    format_type = getattr(args, 'format', 'detailed')
+    raw_output = getattr(args, 'raw', False)
     
     try:
-        if agent_id:
-            _show_single_agent_memory(agent_id, format_type, memory_manager)
+        if raw_output:
+            # Output structured JSON data
+            if agent_id:
+                # Get single agent memory in raw format
+                _output_single_agent_raw(agent_id, memory_manager)
+            else:
+                # Get all agent memories in raw format
+                _output_all_memories_raw(memory_manager)
         else:
-            _show_all_agent_memories(format_type, memory_manager)
+            # Normal user-friendly display
+            print("🧠 Agent Memories Display")
+            print("-" * 80)
             
+            if agent_id:
+                _show_single_agent_memory(agent_id, format_type, memory_manager)
+            else:
+                _show_all_agent_memories(format_type, memory_manager)
+                
     except Exception as e:
-        print(f"❌ Error showing memories: {e}")
+        if raw_output:
+            # Output error in JSON format for consistency
+            error_output = {
+                "success": False,
+                "error": str(e),
+                "timestamp": datetime.now().isoformat()
+            }
+            print(json.dumps(error_output, indent=2))
+        else:
+            print(f"❌ Error showing memories: {e}")
 
 
 def _show_single_agent_memory(agent_id, format_type, memory_manager):
@@ -779,4 +882,79 @@ def _display_bulk_optimization_results(result):
                 print(f"   {agent_id}: {reduction}% reduction{status}")
             else:
                 error = agent_result.get("error", "Unknown error")
-                print(f"   {agent_id}: ❌ {error}")
+                print(f"   {agent_id}: ❌ {error}")
+
+
+def _output_all_memories_raw(memory_manager):
+    """
+    Output all agent memories in raw JSON format.
+    
+    WHY: Provides programmatic access to all agent memories for external tools,
+    scripts, or APIs that need to process or analyze the complete memory state.
+    
+    Args:
+        memory_manager: AgentMemoryManager instance
+    """
+    try:
+        raw_data = memory_manager.get_all_memories_raw()
+        print(json.dumps(raw_data, indent=2, ensure_ascii=False))
+    except Exception as e:
+        error_output = {
+            "success": False,
+            "error": f"Failed to retrieve all memories: {str(e)}",
+            "timestamp": datetime.now().isoformat()
+        }
+        print(json.dumps(error_output, indent=2))
+
+
+def _output_single_agent_raw(agent_id, memory_manager):
+    """
+    Output single agent memory in raw JSON format.
+    
+    WHY: Provides programmatic access to a specific agent's memory for
+    targeted analysis or processing by external tools.
+    
+    Args:
+        agent_id: ID of the agent to retrieve memory for
+        memory_manager: AgentMemoryManager instance
+    """
+    try:
+        # Get all memories and extract the specific agent
+        all_memories = memory_manager.get_all_memories_raw()
+        
+        if not all_memories.get("success", False):
+            error_output = {
+                "success": False,
+                "error": all_memories.get("error", "Failed to retrieve memories"),
+                "timestamp": datetime.now().isoformat()
+            }
+            print(json.dumps(error_output, indent=2))
+            return
+        
+        agents = all_memories.get("agents", {})
+        if agent_id not in agents:
+            error_output = {
+                "success": False,
+                "error": f"No memory found for agent: {agent_id}",
+                "available_agents": list(agents.keys()),
+                "timestamp": datetime.now().isoformat()
+            }
+            print(json.dumps(error_output, indent=2))
+            return
+        
+        # Return single agent data with metadata
+        single_agent_output = {
+            "success": True,
+            "timestamp": all_memories["timestamp"],
+            "agent": agents[agent_id]
+        }
+        
+        print(json.dumps(single_agent_output, indent=2, ensure_ascii=False))
+        
+    except Exception as e:
+        error_output = {
+            "success": False,
+            "error": f"Failed to retrieve memory for agent {agent_id}: {str(e)}",
+            "timestamp": datetime.now().isoformat()
+        }
+        print(json.dumps(error_output, indent=2))

claude_mpm/cli/parser.py

@@ -366,6 +366,12 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         metavar="SUBCOMMAND"
     )
     
+    # Init command
+    init_parser = memory_subparsers.add_parser(
+        MemoryCommands.INIT.value,
+        help="Initialize project-specific memories via PM agent"
+    )
+    
     # Status command
     status_parser = memory_subparsers.add_parser(
         MemoryCommands.STATUS.value,
@@ -379,7 +385,8 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
     )
     view_parser.add_argument(
         "agent_id",
-        help="Agent ID to view memory for"
+        nargs="?",
+        help="Agent ID to view memory for (optional - shows all agents if not provided)"
     )
     
     # Add command
@@ -468,6 +475,11 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         default="summary",
         help="Display format: summary (default), detailed, or full"
     )
+    show_parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Output raw memory content in JSON format for programmatic processing"
+    )
     
     return parser
 

claude_mpm/constants.py

@@ -58,6 +58,7 @@ class AgentCommands(str, Enum):
 
 class MemoryCommands(str, Enum):
     """Memory subcommand constants."""
+    INIT = "init"
     STATUS = "status"
     VIEW = "view"
     ADD = "add"

claude_mpm/core/claude_runner.py

@@ -13,10 +13,14 @@ import uuid
 try:
     from claude_mpm.services.agent_deployment import AgentDeploymentService
     from claude_mpm.services.ticket_manager import TicketManager
+    from claude_mpm.services.hook_service import HookService
+    from claude_mpm.core.config import Config
     from claude_mpm.core.logger import get_logger, get_project_logger, ProjectLogger
 except ImportError:
     from claude_mpm.services.agent_deployment import AgentDeploymentService
     from claude_mpm.services.ticket_manager import TicketManager
+    from claude_mpm.services.hook_service import HookService
+    from claude_mpm.core.config import Config
     from claude_mpm.core.logger import get_logger, get_project_logger, ProjectLogger
 
 
@@ -76,6 +80,11 @@ class ClaudeRunner:
                 self.ticket_manager = None
                 self.enable_tickets = False
         
+        # Initialize hook service and register memory hooks
+        self.config = Config()
+        self.hook_service = HookService(self.config)
+        self._register_memory_hooks()
+        
         # Load system instructions
         self.system_instructions = self._load_system_instructions()
         
@@ -741,6 +750,58 @@ class ClaudeRunner:
             except Exception as e:
                 self.logger.debug(f"Failed to log session event: {e}")
     
+    def _register_memory_hooks(self):
+        """Register memory integration hooks with the hook service.
+        
+        WHY: This activates the memory system by registering hooks that automatically
+        inject agent memory before delegation and extract learnings after delegation.
+        This is the critical connection point between the memory system and the CLI.
+        
+        DESIGN DECISION: We register hooks here instead of in __init__ to ensure
+        all services are initialized first. Hooks are only registered if the memory
+        system is enabled in configuration.
+        """
+        try:
+            # Only register if memory system is enabled
+            if not self.config.get('memory.enabled', True):
+                self.logger.debug("Memory system disabled - skipping hook registration")
+                return
+            
+            # Import hook classes (lazy import to avoid circular dependencies)
+            from claude_mpm.hooks.memory_integration_hook import (
+                MemoryPreDelegationHook,
+                MemoryPostDelegationHook
+            )
+            
+            # Register pre-delegation hook for memory injection
+            pre_hook = MemoryPreDelegationHook(self.config)
+            success = self.hook_service.register_hook(pre_hook)
+            if success:
+                self.logger.info(f"✅ Registered memory pre-delegation hook (priority: {pre_hook.priority})")
+            else:
+                self.logger.warning("❌ Failed to register memory pre-delegation hook")
+            
+            # Register post-delegation hook if auto-learning is enabled
+            if self.config.get('memory.auto_learning', True):  # Default to True now
+                post_hook = MemoryPostDelegationHook(self.config)
+                success = self.hook_service.register_hook(post_hook)
+                if success:
+                    self.logger.info(f"✅ Registered memory post-delegation hook (priority: {post_hook.priority})")
+                else:
+                    self.logger.warning("❌ Failed to register memory post-delegation hook")
+            else:
+                self.logger.info("ℹ️  Auto-learning disabled - skipping post-delegation hook")
+            
+            # Log summary of registered hooks
+            hooks = self.hook_service.list_hooks()
+            pre_count = len(hooks.get('pre_delegation', []))
+            post_count = len(hooks.get('post_delegation', []))
+            self.logger.info(f"📋 Hook Service initialized: {pre_count} pre-delegation, {post_count} post-delegation hooks")
+            
+        except Exception as e:
+            self.logger.error(f"❌ Failed to register memory hooks: {e}")
+            # Don't fail the entire initialization - memory system is optional
+    
     def _launch_subprocess_interactive(self, cmd: list, env: dict):
         """Launch Claude as a subprocess with PTY for interactive mode."""
         import pty

claude_mpm/core/config.py

@@ -166,9 +166,38 @@ class Config:
             # Health monitoring
             "enable_health_monitoring": True,
             "health_check_interval": 30,
+            "health_history_size": 100,
+            "health_aggregation_window": 300,
             # Metrics
             "enable_metrics": True,
             "metrics_interval": 60,
+            # Advanced health monitoring thresholds
+            "health_thresholds": {
+                "cpu_percent": 80.0,
+                "memory_mb": 500,
+                "file_descriptors": 1000,
+                "max_clients": 1000,
+                "max_error_rate": 0.1,
+                "network_timeout": 2.0
+            },
+            # Automatic recovery configuration
+            "recovery": {
+                "enabled": True,
+                "check_interval": 60,
+                "max_recovery_attempts": 5,
+                "recovery_timeout": 30,
+                "circuit_breaker": {
+                    "failure_threshold": 5,
+                    "timeout_seconds": 300,
+                    "success_threshold": 3
+                },
+                "strategy": {
+                    "warning_threshold": 2,
+                    "critical_threshold": 1,
+                    "failure_window_seconds": 300,
+                    "min_recovery_interval": 60
+                }
+            },
             # Service management
             "graceful_shutdown_timeout": 30,
             "startup_timeout": 60,
@@ -231,7 +260,7 @@ class Config:
             # Agent Memory System configuration
             "memory": {
                 "enabled": True,                    # Master switch for memory system
-                "auto_learning": False,             # Automatic learning extraction
+                "auto_learning": True,              # Automatic learning extraction (changed default to True)
                 "limits": {
                     "default_size_kb": 8,           # Default file size limit
                     "max_sections": 10,             # Maximum sections per file
@@ -247,6 +276,47 @@ class Config:
                         "auto_learning": True       # Enable auto learning
                     }
                 }
+            },
+            # Socket.IO server health and recovery configuration
+            "socketio_server": {
+                "host": "localhost",
+                "port": 8765,
+                "enable_health_monitoring": True,
+                "enable_recovery": True,
+                "health_monitoring": {
+                    "check_interval": 30,
+                    "history_size": 100,
+                    "aggregation_window": 300,
+                    "thresholds": {
+                        "cpu_percent": 80.0,
+                        "memory_mb": 500,
+                        "file_descriptors": 1000,
+                        "max_clients": 1000,
+                        "max_error_rate": 0.1
+                    }
+                },
+                "recovery": {
+                    "enabled": True,
+                    "max_attempts": 5,
+                    "timeout": 30,
+                    "circuit_breaker": {
+                        "failure_threshold": 5,
+                        "timeout_seconds": 300,
+                        "success_threshold": 3
+                    },
+                    "strategy": {
+                        "warning_threshold": 2,
+                        "critical_threshold": 1,
+                        "failure_window_seconds": 300,
+                        "min_recovery_interval": 60
+                    },
+                    "actions": {
+                        "log_warning": True,
+                        "clear_connections": True,
+                        "restart_service": True,
+                        "emergency_stop": True
+                    }
+                }
             }
         }
 
@@ -254,6 +324,9 @@ class Config:
         for key, default_value in defaults.items():
             if key not in self._config:
                 self._config[key] = default_value
+        
+        # Validate health and recovery configuration
+        self._validate_health_recovery_config()
 
     def get(self, key: str, default: Any = None) -> Any:
         """Get configuration value."""
@@ -349,6 +422,93 @@ class Config:
         """Check if configuration contains a key."""
         return self.get(key) is not None
 
+    def _validate_health_recovery_config(self) -> None:
+        """Validate health monitoring and recovery configuration."""
+        try:
+            # Validate health thresholds
+            thresholds = self.get('health_thresholds', {})
+            if thresholds.get('cpu_percent', 0) < 0 or thresholds.get('cpu_percent', 0) > 100:
+                logger.warning("CPU threshold should be between 0-100, using default 80")
+                self.set('health_thresholds.cpu_percent', 80.0)
+            
+            if thresholds.get('memory_mb', 0) <= 0:
+                logger.warning("Memory threshold should be positive, using default 500MB")
+                self.set('health_thresholds.memory_mb', 500)
+            
+            if thresholds.get('max_error_rate', 0) < 0 or thresholds.get('max_error_rate', 0) > 1:
+                logger.warning("Error rate threshold should be between 0-1, using default 0.1")
+                self.set('health_thresholds.max_error_rate', 0.1)
+            
+            # Validate recovery configuration
+            recovery_config = self.get('recovery', {})
+            if recovery_config.get('max_recovery_attempts', 0) <= 0:
+                logger.warning("Max recovery attempts should be positive, using default 5")
+                self.set('recovery.max_recovery_attempts', 5)
+            
+            # Validate circuit breaker configuration
+            cb_config = recovery_config.get('circuit_breaker', {})
+            if cb_config.get('failure_threshold', 0) <= 0:
+                logger.warning("Circuit breaker failure threshold should be positive, using default 5")
+                self.set('recovery.circuit_breaker.failure_threshold', 5)
+            
+            if cb_config.get('timeout_seconds', 0) <= 0:
+                logger.warning("Circuit breaker timeout should be positive, using default 300")
+                self.set('recovery.circuit_breaker.timeout_seconds', 300)
+            
+        except Exception as e:
+            logger.error(f"Error validating health/recovery configuration: {e}")
+    
+    def get_health_monitoring_config(self) -> Dict[str, Any]:
+        """Get health monitoring configuration with defaults."""
+        base_config = {
+            'enabled': self.get('enable_health_monitoring', True),
+            'check_interval': self.get('health_check_interval', 30),
+            'history_size': self.get('health_history_size', 100),
+            'aggregation_window': self.get('health_aggregation_window', 300),
+            'thresholds': self.get('health_thresholds', {
+                'cpu_percent': 80.0,
+                'memory_mb': 500,
+                'file_descriptors': 1000,
+                'max_clients': 1000,
+                'max_error_rate': 0.1,
+                'network_timeout': 2.0
+            })
+        }
+        
+        # Merge with socketio-specific config if available
+        socketio_config = self.get('socketio_server.health_monitoring', {})
+        if socketio_config:
+            base_config.update(socketio_config)
+        
+        return base_config
+    
+    def get_recovery_config(self) -> Dict[str, Any]:
+        """Get recovery configuration with defaults."""
+        base_config = self.get('recovery', {
+            'enabled': True,
+            'check_interval': 60,
+            'max_recovery_attempts': 5,
+            'recovery_timeout': 30,
+            'circuit_breaker': {
+                'failure_threshold': 5,
+                'timeout_seconds': 300,
+                'success_threshold': 3
+            },
+            'strategy': {
+                'warning_threshold': 2,
+                'critical_threshold': 1,
+                'failure_window_seconds': 300,
+                'min_recovery_interval': 60
+            }
+        })
+        
+        # Merge with socketio-specific config if available
+        socketio_config = self.get('socketio_server.recovery', {})
+        if socketio_config:
+            base_config = self._config_mgr.merge_configs(base_config, socketio_config)
+        
+        return base_config
+
     def __repr__(self) -> str:
         """String representation of configuration."""
         return f"<Config({len(self._config)} keys)>"