claude-mpm 3.3.2__tar.gz → 3.4.2__tar.gz

{claude_mpm-3.3.2 → claude_mpm-3.4.2}/MANIFEST.in

@@ -8,6 +8,7 @@ include requirements.txt
 include requirements-dev.txt
 
 # Include version file
+include VERSION
 include src/claude_mpm/_version.py
 
 # Include all agent templates and instructions

{claude_mpm-3.3.2 → claude_mpm-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.3.2
+Version: 3.4.2
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -57,6 +57,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 ## Features
 
 - 🤖 **Multi-Agent System**: Automatically delegates tasks to specialized agents (PM, Research, Engineer, QA, Documentation, Security, Ops, Data Engineer)
+- 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 📁 **Multi-Project Support**: Per-session working directories
@@ -108,6 +109,26 @@ The PM agent automatically delegates work to specialized agents:
 - Switch between projects with per-session directories
 - View session history and activity
 
+### Agent Memory System
+Agents learn and improve over time with persistent memory:
+- **Project-Specific Knowledge**: Automatically analyzes your codebase to understand patterns
+- **Continuous Learning**: Agents remember insights across sessions
+- **Memory Management**: Initialize, optimize, and manage agent memories
+- **Quick Initialization**: Use `/mpm memory init` to scan project and create memories
+
+```bash
+# Initialize project-specific memories
+claude-mpm memory init
+
+# View memory status
+claude-mpm memory status
+
+# Add specific learning
+claude-mpm memory add engineer pattern "Always use async/await for I/O"
+```
+
+See [docs/MEMORY.md](docs/MEMORY.md) for comprehensive memory system documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing:
 - Live agent activity and delegations
@@ -121,23 +142,26 @@ See [docs/monitoring.md](docs/monitoring.md) for full monitoring guide.
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
+- **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
 - **[Monitoring Dashboard](docs/monitoring.md)** - Real-time monitoring features
 - **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
 - **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation
 - **[Developer Guide](docs/developer/)** - Architecture and API reference
 
-## Recent Updates (v3.3.1)
+## Recent Updates (v3.4.0)
 
-### Session Working Directories
-- Each session can now have its own working directory
-- Git operations use the session's directory automatically
-- Switch projects seamlessly without changing terminal directory
+### Agent Memory System
+- **Project-Specific Memory Generation**: Automatic analysis of project characteristics
+- **Memory Initialization Command**: New `/mpm memory init` for quick project onboarding
+- **Enhanced Documentation Processing**: Dynamic file discovery based on project type
+- **Improved Memory Templates**: Clean section headers with programmatic limit enforcement
 
-### Monitoring Improvements
-- Fixed git diff viewer for cross-project files
-- Auto-sync working directory from session data
-- Improved error handling and display
+### Project Organization
+- **Deep Clean**: Comprehensive project structure cleanup for publishing readiness
+- **Documentation Archives**: Historical reports organized in docs/archive/
+- **Test Organization**: All tests properly relocated to /tests/ directory
+- **Enhanced .gitignore**: Prevents temporary and debug file commits
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

{claude_mpm-3.3.2 → claude_mpm-3.4.2}/README.md

@@ -7,6 +7,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 ## Features
 
 - 🤖 **Multi-Agent System**: Automatically delegates tasks to specialized agents (PM, Research, Engineer, QA, Documentation, Security, Ops, Data Engineer)
+- 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 📁 **Multi-Project Support**: Per-session working directories
@@ -58,6 +59,26 @@ The PM agent automatically delegates work to specialized agents:
 - Switch between projects with per-session directories
 - View session history and activity
 
+### Agent Memory System
+Agents learn and improve over time with persistent memory:
+- **Project-Specific Knowledge**: Automatically analyzes your codebase to understand patterns
+- **Continuous Learning**: Agents remember insights across sessions
+- **Memory Management**: Initialize, optimize, and manage agent memories
+- **Quick Initialization**: Use `/mpm memory init` to scan project and create memories
+
+```bash
+# Initialize project-specific memories
+claude-mpm memory init
+
+# View memory status
+claude-mpm memory status
+
+# Add specific learning
+claude-mpm memory add engineer pattern "Always use async/await for I/O"
+```
+
+See [docs/MEMORY.md](docs/MEMORY.md) for comprehensive memory system documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing:
 - Live agent activity and delegations
@@ -71,23 +92,26 @@ See [docs/monitoring.md](docs/monitoring.md) for full monitoring guide.
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
+- **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
 - **[Monitoring Dashboard](docs/monitoring.md)** - Real-time monitoring features
 - **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
 - **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation
 - **[Developer Guide](docs/developer/)** - Architecture and API reference
 
-## Recent Updates (v3.3.1)
+## Recent Updates (v3.4.0)
 
-### Session Working Directories
-- Each session can now have its own working directory
-- Git operations use the session's directory automatically
-- Switch projects seamlessly without changing terminal directory
+### Agent Memory System
+- **Project-Specific Memory Generation**: Automatic analysis of project characteristics
+- **Memory Initialization Command**: New `/mpm memory init` for quick project onboarding
+- **Enhanced Documentation Processing**: Dynamic file discovery based on project type
+- **Improved Memory Templates**: Clean section headers with programmatic limit enforcement
 
-### Monitoring Improvements
-- Fixed git diff viewer for cross-project files
-- Auto-sync working directory from session data
-- Improved error handling and display
+### Project Organization
+- **Deep Clean**: Comprehensive project structure cleanup for publishing readiness
+- **Documentation Archives**: Historical reports organized in docs/archive/
+- **Test Organization**: All tests properly relocated to /tests/ directory
+- **Enhanced .gitignore**: Prevents temporary and debug file commits
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

claude_mpm-3.4.2/VERSION

@@ -0,0 +1 @@
+3.4.2

{claude_mpm-3.3.2 → claude_mpm-3.4.2}/src/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-3.3.2 → claude_mpm-3.4.2}/src/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-3.3.2 → claude_mpm-3.4.2}/src/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-3.3.2 → claude_mpm-3.4.2}/src/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