claude-mpm 3.4.27__py3-none-any.whl → 3.5.0__py3-none-any.whl

claude_mpm/agents/agent_loader.py

@@ -62,11 +62,14 @@ import time
 import yaml
 from pathlib import Path
 from typing import Optional, Dict, Any, Tuple, Union, List
+from enum import Enum
 
-from ..services.shared_prompt_cache import SharedPromptCache
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 from .base_agent_loader import prepend_base_instructions
 from ..validation.agent_validator import AgentValidator, ValidationResult
 from ..utils.paths import PathResolver
+from ..core.agent_name_normalizer import AgentNameNormalizer
+from ..core.config_paths import ConfigPaths
 
 # Temporary placeholders for missing module
 # WHY: These classes would normally come from a task_complexity module, but
@@ -89,16 +92,63 @@ class ModelType:
 logger = logging.getLogger(__name__)
 
 
+class AgentTier(Enum):
+    """Agent precedence tiers."""
+    PROJECT = "project"  # Highest precedence - project-specific agents
+    USER = "user"       # User-level agents from ~/.claude-mpm
+    SYSTEM = "system"   # Lowest precedence - framework built-in agents
+
+
+def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
+    """
+    Get directories containing agent template JSON files across all tiers.
+    
+    Returns a dictionary mapping tiers to their template directories:
+    - PROJECT: .claude-mpm/agents/templates in the current working directory
+    - USER: ~/.claude-mpm/agents/templates 
+    - SYSTEM: Built-in templates relative to this module
+    
+    WHY: We support multiple tiers to allow project-specific customization
+    while maintaining backward compatibility with system agents.
+    
+    Returns:
+        Dict mapping AgentTier to Path (or None if not available)
+    """
+    dirs = {}
+    
+    # PROJECT tier - ALWAYS check current working directory dynamically
+    # This ensures we pick up project agents even if CWD changes
+    project_dir = Path.cwd() / ConfigPaths.CONFIG_DIR / "agents" / "templates"
+    if project_dir.exists():
+        dirs[AgentTier.PROJECT] = project_dir
+        logger.debug(f"Found PROJECT agents at: {project_dir}")
+    
+    # USER tier - check user home directory
+    user_config_dir = ConfigPaths.get_user_config_dir()
+    if user_config_dir:
+        user_agents_dir = user_config_dir / "agents" / "templates"
+        if user_agents_dir.exists():
+            dirs[AgentTier.USER] = user_agents_dir
+            logger.debug(f"Found USER agents at: {user_agents_dir}")
+    
+    # SYSTEM tier - built-in templates
+    system_dir = Path(__file__).parent / "templates"
+    if system_dir.exists():
+        dirs[AgentTier.SYSTEM] = system_dir
+        logger.debug(f"Found SYSTEM agents at: {system_dir}")
+    
+    return dirs
+
+
 def _get_agent_templates_dir() -> Path:
     """
-    Get the directory containing agent template JSON files.
+    Get the primary directory containing agent template JSON files.
     
-    WHY: We use a function instead of a direct constant to ensure the path
-    is always resolved relative to this module's location, making the code
-    portable across different installation methods (pip install, development mode, etc.).
+    DEPRECATED: Use _get_agent_templates_dirs() for tier-aware loading.
+    This function is kept for backward compatibility.
     
     Returns:
-        Path: Absolute path to the templates directory
+        Path: Absolute path to the system templates directory
     """
     return Path(__file__).parent / "templates"
 
@@ -169,7 +219,8 @@ class AgentLoader:
         1. Creates validator for schema checking
         2. Gets shared cache instance for performance
         3. Initializes empty agent registry
-        4. Triggers agent discovery and loading
+        4. Discovers template directories across all tiers
+        5. Triggers agent discovery and loading
         
         METRICS OPPORTUNITIES:
         - Track initialization time
@@ -186,10 +237,17 @@ class AgentLoader:
         self.cache = SharedPromptCache.get_instance()
         self._agent_registry: Dict[str, Dict[str, Any]] = {}
         
+        # Template directories will be discovered dynamically during loading
+        self._template_dirs = {}
+        
+        # Track which tier each agent came from for debugging
+        self._agent_tiers: Dict[str, AgentTier] = {}
+        
         # METRICS: Initialize performance tracking
         # This structure collects valuable telemetry for AI agent performance
         self._metrics = {
             'agents_loaded': 0,
+            'agents_by_tier': {tier.value: 0 for tier in AgentTier},
             'validation_failures': 0,
             'cache_hits': 0,
             'cache_misses': 0,
@@ -210,54 +268,90 @@ class AgentLoader:
     
     def _load_agents(self) -> None:
         """
-        Discover and load all valid agents from the templates directory.
+        Discover and load all valid agents from all tier directories.
         
-        This method implements the agent discovery mechanism:
-        1. Scans the templates directory for JSON files
-        2. Skips the schema definition file
-        3. Loads and validates each potential agent file
-        4. Registers valid agents in the internal registry
+        This method implements the agent discovery mechanism with tier precedence:
+        1. Scans each tier directory (PROJECT → USER → SYSTEM)
+        2. Loads and validates each agent file
+        3. Registers agents with precedence (PROJECT overrides USER overrides SYSTEM)
         
-        WHY: We use a file-based discovery mechanism because:
-        - It allows easy addition of new agents without code changes
-        - Agents can be distributed as simple JSON files
-        - The system remains extensible and maintainable
+        WHY: We use tier-based discovery to allow:
+        - Project-specific agent customization
+        - User-level agent modifications
+        - Fallback to system defaults
         
         Error Handling:
         - Invalid JSON files are logged but don't stop the loading process
         - Schema validation failures are logged with details
         - The system continues to function with whatever valid agents it finds
         """
-        logger.info(f"Loading agents from {AGENT_TEMPLATES_DIR}")
+        # Dynamically discover template directories at load time
+        self._template_dirs = _get_agent_templates_dirs()
+        
+        logger.info(f"Loading agents from {len(self._template_dirs)} tier(s)")
         
-        for json_file in AGENT_TEMPLATES_DIR.glob("*.json"):
-            # Skip the schema definition file itself
-            if json_file.name == "agent_schema.json":
+        # Process tiers in REVERSE precedence order (SYSTEM first, PROJECT last)
+        # This ensures PROJECT agents override USER/SYSTEM agents
+        for tier in [AgentTier.SYSTEM, AgentTier.USER, AgentTier.PROJECT]:
+            if tier not in self._template_dirs:
                 continue
-            
-            try:
-                with open(json_file, 'r') as f:
-                    agent_data = json.load(f)
                 
-                # Validate against schema to ensure consistency
-                validation_result = self.validator.validate_agent(agent_data)
+            templates_dir = self._template_dirs[tier]
+            logger.debug(f"Loading {tier.value} agents from {templates_dir}")
+            
+            for json_file in templates_dir.glob("*.json"):
+                # Skip the schema definition file itself
+                if json_file.name == "agent_schema.json":
+                    continue
                 
-                if validation_result.is_valid:
-                    agent_id = agent_data.get("agent_id")
-                    if agent_id:
-                        self._agent_registry[agent_id] = agent_data
-                        # METRICS: Track successful agent load
-                        self._metrics['agents_loaded'] += 1
-                        logger.debug(f"Loaded agent: {agent_id}")
-                else:
-                    # Log validation errors but continue loading other agents
-                    # METRICS: Track validation failure
-                    self._metrics['validation_failures'] += 1
-                    logger.warning(f"Invalid agent in {json_file.name}: {validation_result.errors}")
+                try:
+                    with open(json_file, 'r') as f:
+                        agent_data = json.load(f)
+                    
+                    # For files without _agent suffix, use the filename as agent_id
+                    if "agent_id" not in agent_data:
+                        agent_data["agent_id"] = json_file.stem
                     
-            except Exception as e:
-                # Log loading errors but don't crash - system should be resilient
-                logger.error(f"Failed to load {json_file.name}: {e}")
+                    # Validate against schema to ensure consistency
+                    # Skip validation for now if instructions are plain text (not in expected format)
+                    if "instructions" in agent_data and isinstance(agent_data["instructions"], str) and len(agent_data["instructions"]) > 10000:
+                        # For very long instructions, skip validation but log warning
+                        logger.warning(f"Skipping validation for {json_file.name} due to long instructions")
+                        validation_result = ValidationResult(is_valid=True, warnings=["Validation skipped due to long instructions"])
+                    else:
+                        validation_result = self.validator.validate_agent(agent_data)
+                    
+                    if validation_result.is_valid:
+                        agent_id = agent_data.get("agent_id")
+                        if agent_id:
+                            # Check if this agent was already loaded from a higher-precedence tier
+                            if agent_id in self._agent_registry:
+                                existing_tier = self._agent_tiers.get(agent_id)
+                                # Only override if current tier has higher precedence
+                                if tier == AgentTier.PROJECT or \
+                                   (tier == AgentTier.USER and existing_tier == AgentTier.SYSTEM):
+                                    logger.info(f"Overriding {existing_tier.value} agent '{agent_id}' with {tier.value} version")
+                                else:
+                                    logger.debug(f"Skipping {tier.value} agent '{agent_id}' - already loaded from {existing_tier.value}")
+                                    continue
+                            
+                            # Register the agent
+                            self._agent_registry[agent_id] = agent_data
+                            self._agent_tiers[agent_id] = tier
+                            
+                            # METRICS: Track successful agent load
+                            self._metrics['agents_loaded'] += 1
+                            self._metrics['agents_by_tier'][tier.value] += 1
+                            logger.debug(f"Loaded {tier.value} agent: {agent_id}")
+                    else:
+                        # Log validation errors but continue loading other agents
+                        # METRICS: Track validation failure
+                        self._metrics['validation_failures'] += 1
+                        logger.warning(f"Invalid agent in {json_file.name}: {validation_result.errors}")
+                        
+                except Exception as e:
+                    # Log loading errors but don't crash - system should be resilient
+                    logger.error(f"Failed to load {json_file.name}: {e}")
     
     def get_agent(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """
@@ -272,7 +366,12 @@ class AgentLoader:
         WHY: Direct dictionary lookup for O(1) performance, essential for
         frequently accessed agents during runtime.
         """
-        return self._agent_registry.get(agent_id)
+        agent_data = self._agent_registry.get(agent_id)
+        if agent_data and agent_id in self._agent_tiers:
+            # Add tier information to the agent data for debugging
+            agent_data = agent_data.copy()
+            agent_data['_tier'] = self._agent_tiers[agent_id].value
+        return agent_data
     
     def list_agents(self) -> List[Dict[str, Any]]:
         """
@@ -385,6 +484,7 @@ class AgentLoader:
             - Load time analysis
             - Memory usage patterns
             - Error tracking
+            - Tier distribution
             
         This data could be:
         - Exposed via monitoring endpoints
@@ -412,6 +512,7 @@ class AgentLoader:
         return {
             'initialization_time_ms': self._metrics['initialization_time_ms'],
             'agents_loaded': self._metrics['agents_loaded'],
+            'agents_by_tier': self._metrics['agents_by_tier'].copy(),
             'validation_failures': self._metrics['validation_failures'],
             'cache_hit_rate_percent': cache_hit_rate,
             'cache_hits': self._metrics['cache_hits'],
@@ -564,7 +665,7 @@ def _get_model_config(agent_name: str, complexity_analysis: Optional[Dict[str, A
     - Dynamic vs static selection rates
     
     Args:
-        agent_name: Name of the agent requesting model selection
+        agent_name: Name of the agent requesting model selection (already normalized to agent_id format)
         complexity_analysis: Results from task complexity analysis (if available)
         
     Returns:
@@ -659,7 +760,7 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
     4. Adding metadata about model selection decisions
     
     Args:
-        agent_name: Agent ID (e.g., "research_agent", "qa_agent")
+        agent_name: Agent name in any format (e.g., "Engineer", "research_agent", "QA")
         force_reload: Force reload from source, bypassing cache
         return_model_info: If True, returns extended info tuple
         **kwargs: Additional arguments:
@@ -676,12 +777,13 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
         ValueError: If the requested agent is not found
         
     Processing Flow:
-    1. Load agent instructions (with caching)
-    2. Analyze task complexity (if enabled and task_description provided)
-    3. Determine optimal model based on complexity
-    4. Add model selection metadata to prompt
-    5. Prepend base instructions
-    6. Return appropriate format based on return_model_info
+    1. Normalize agent name to correct agent ID
+    2. Load agent instructions (with caching)
+    3. Analyze task complexity (if enabled and task_description provided)
+    4. Determine optimal model based on complexity
+    5. Add model selection metadata to prompt
+    6. Prepend base instructions
+    7. Return appropriate format based on return_model_info
     
     WHY: This comprehensive approach ensures:
     - Consistent prompt structure across all agents
@@ -689,11 +791,53 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
     - Transparency in model selection decisions
     - Flexibility for different use cases
     """
+    # Normalize the agent name to handle various formats
+    # Convert names like "Engineer", "Research", "QA" to the correct agent IDs
+    normalizer = AgentNameNormalizer()
+    loader = _get_loader()
+    
+    # First check if agent exists with exact name
+    if loader.get_agent(agent_name):
+        actual_agent_id = agent_name
+    # Then check with _agent suffix
+    elif loader.get_agent(f"{agent_name}_agent"):
+        actual_agent_id = f"{agent_name}_agent"
+    # Check if this looks like it might already be an agent ID
+    elif agent_name.endswith("_agent"):
+        actual_agent_id = agent_name
+    else:
+        # Get the normalized key (e.g., "engineer", "research", "qa")
+        # First check if the agent name is recognized by the normalizer
+        cleaned = agent_name.strip().lower().replace("-", "_")
+        
+        # Check if this is a known alias or canonical name
+        if cleaned in normalizer.ALIASES or cleaned in normalizer.CANONICAL_NAMES:
+            agent_key = normalizer.to_key(agent_name)
+            # Try both with and without _agent suffix
+            if loader.get_agent(agent_key):
+                actual_agent_id = agent_key
+            elif loader.get_agent(f"{agent_key}_agent"):
+                actual_agent_id = f"{agent_key}_agent"
+            else:
+                actual_agent_id = agent_key  # Use normalized key
+        else:
+            # Unknown agent name - check both variations
+            if loader.get_agent(cleaned):
+                actual_agent_id = cleaned
+            elif loader.get_agent(f"{cleaned}_agent"):
+                actual_agent_id = f"{cleaned}_agent"
+            else:
+                actual_agent_id = cleaned  # Use cleaned name
+    
+    # Log the normalization for debugging
+    if agent_name != actual_agent_id:
+        logger.debug(f"Normalized agent name '{agent_name}' to '{actual_agent_id}'")
+    
     # Load from JSON template via the loader
-    prompt = load_agent_prompt_from_md(agent_name, force_reload)
+    prompt = load_agent_prompt_from_md(actual_agent_id, force_reload)
     
     if prompt is None:
-        raise ValueError(f"No agent found with ID: {agent_name}")
+        raise ValueError(f"No agent found with name: {agent_name} (normalized to: {actual_agent_id})")
     
     # Analyze task complexity if task description is provided
     complexity_analysis = None
@@ -711,7 +855,8 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
         )
     
     # Get model configuration based on agent and complexity
-    selected_model, model_config = _get_model_config(agent_name, complexity_analysis)
+    # Pass the normalized agent ID to _get_model_config
+    selected_model, model_config = _get_model_config(actual_agent_id, complexity_analysis)
     
     # Add model selection metadata to prompt for transparency
     # This helps with debugging and understanding model choices
@@ -1002,6 +1147,39 @@ def clear_agent_cache(agent_name: Optional[str] = None) -> None:
         logger.error(f"Error clearing agent cache: {e}")
 
 
+def list_agents_by_tier() -> Dict[str, List[str]]:
+    """
+    List available agents organized by their tier.
+    
+    Returns:
+        Dictionary mapping tier names to lists of agent IDs available in that tier
+        
+    Example:
+        {
+            "project": ["engineer_agent", "custom_agent"],
+            "user": ["research_agent"],
+            "system": ["engineer_agent", "research_agent", "qa_agent", ...]
+        }
+    
+    This is useful for:
+    - Understanding which agents are available at each level
+    - Debugging agent precedence issues
+    - UI display of agent sources
+    """
+    loader = _get_loader()
+    result = {"project": [], "user": [], "system": []}
+    
+    # Group agents by their loaded tier
+    for agent_id, tier in loader._agent_tiers.items():
+        result[tier.value].append(agent_id)
+    
+    # Sort each list for consistent output
+    for tier in result:
+        result[tier].sort()
+    
+    return result
+
+
 def validate_agent_files() -> Dict[str, Dict[str, Any]]:
     """
     Validate all agent template files against the schema.
@@ -1064,21 +1242,69 @@ def reload_agents() -> None:
     This function completely resets the agent loader state, causing:
     1. The global loader instance to be destroyed
     2. All cached agent prompts to be invalidated
-    3. Fresh agent discovery on next access
+    3. Fresh agent discovery on next access across all tiers
     
     Use Cases:
     - Hot-reloading during development
     - Picking up new agent files without restart
     - Recovering from corrupted state
     - Testing agent loading logic
+    - Switching between projects with different agents
     
     WHY: Hot-reloading is essential for development productivity and
     allows dynamic agent updates in production without service restart.
     
     Implementation Note: We simply clear the global loader reference.
     The next call to _get_loader() will create a fresh instance that
-    re-discovers and re-validates all agents.
+    re-discovers and re-validates all agents across all tiers.
     """
     global _loader
     _loader = None
-    logger.info("Agent registry cleared, will reload on next access")
+    logger.info("Agent registry cleared, will reload on next access")
+
+
+def get_agent_tier(agent_name: str) -> Optional[str]:
+    """
+    Get the tier from which an agent was loaded.
+    
+    Args:
+        agent_name: Agent name or ID
+        
+    Returns:
+        Tier name ("project", "user", or "system") or None if not found
+        
+    This is useful for debugging and understanding which version of an
+    agent is being used when multiple versions exist across tiers.
+    """
+    loader = _get_loader()
+    
+    # Check if agent exists with exact name
+    if agent_name in loader._agent_tiers:
+        tier = loader._agent_tiers[agent_name]
+        return tier.value if tier else None
+    
+    # Try with _agent suffix
+    agent_with_suffix = f"{agent_name}_agent"
+    if agent_with_suffix in loader._agent_tiers:
+        tier = loader._agent_tiers[agent_with_suffix]
+        return tier.value if tier else None
+    
+    # Try normalizing the name
+    normalizer = AgentNameNormalizer()
+    cleaned = agent_name.strip().lower().replace("-", "_")
+    
+    if cleaned in normalizer.ALIASES or cleaned in normalizer.CANONICAL_NAMES:
+        agent_key = normalizer.to_key(agent_name)
+        # Try both with and without suffix
+        for candidate in [agent_key, f"{agent_key}_agent"]:
+            if candidate in loader._agent_tiers:
+                tier = loader._agent_tiers[candidate]
+                return tier.value if tier else None
+    
+    # Try cleaned name with and without suffix
+    for candidate in [cleaned, f"{cleaned}_agent"]:
+        if candidate in loader._agent_tiers:
+            tier = loader._agent_tiers[candidate]
+            return tier.value if tier else None
+    
+    return None

claude_mpm/agents/agent_loader_integration.py

@@ -12,11 +12,9 @@ from typing import Optional, Dict, Any
 
 from .agent_loader import (
     load_agent_prompt_from_md,
-    get_agent_prompt,
-    AGENT_MAPPINGS,
-    FRAMEWORK_AGENT_ROLES_DIR
+    get_agent_prompt
 )
-from ..services.agent_management_service import AgentManager
+from ..services import AgentManager
 from ..models.agent_definition import AgentDefinition
 
 logger = logging.getLogger(__name__)
@@ -40,8 +38,8 @@ class EnhancedAgentLoader:
             AgentDefinition or None
         """
         # Map from old naming to new naming if needed
-        md_filename = AGENT_MAPPINGS.get(agent_name, f"{agent_name}.md")
-        agent_file_name = md_filename.replace('.md', '')
+        # Since AGENT_MAPPINGS no longer exists, use direct naming
+        agent_file_name = agent_name
         
         return self.manager.read_agent(agent_file_name)
     
@@ -127,9 +125,8 @@ class EnhancedAgentLoader:
         Returns:
             True if updated, False otherwise
         """
-        # Map name
-        md_filename = AGENT_MAPPINGS.get(agent_name, f"{agent_name}.md")
-        agent_file_name = md_filename.replace('.md', '')
+        # Map name - since AGENT_MAPPINGS no longer exists, use direct naming
+        agent_file_name = agent_name
         
         result = self.manager.update_agent(agent_file_name, {}, increment_version=True)
         return result is not None

claude_mpm/agents/base_agent.json

@@ -1,5 +1,6 @@
 {
-  "version": 2,
+  "version": 3,
+  "base_version": "0.3.0",
   "agent_type": "base",
   "narrative_fields": {
     "instructions": "# Claude MPM Framework Agent\n\nYou are a specialized agent in the Claude MPM framework. Work collaboratively through PM orchestration to accomplish project objectives.\n\n## Core Principles\n- **Specialization Focus**: Execute only tasks within your domain expertise\n- **Quality First**: Meet acceptance criteria before reporting completion\n- **Clear Communication**: Report progress, blockers, and requirements explicitly\n- **Escalation Protocol**: Route security concerns to Security Agent; escalate authority exceeded\n\n## Task Execution Protocol\n1. **Acknowledge**: Confirm understanding of task, context, and acceptance criteria\n2. **Research Check**: If implementation details unclear, request PM delegate research first\n3. **Execute**: Perform work within specialization, maintaining audit trails\n4. **Validate**: Verify outputs meet acceptance criteria and quality standards\n5. **Report**: Provide structured completion report with deliverables and next steps\n\n## Framework Integration\n- **Hierarchy**: Operate within Project → User → System agent discovery\n- **Communication**: Use Task Tool subprocess for PM coordination\n- **Context Awareness**: Acknowledge current date/time in decisions\n- **Handoffs**: Follow structured protocols for inter-agent coordination\n- **Error Handling**: Implement graceful failure with clear error reporting\n\n## Quality Standards\n- Idempotent operations where possible\n- Comprehensive error handling and validation\n- Structured output formats for integration\n- Security-first approach for sensitive operations\n- Performance-conscious implementation choices\n\n## Mandatory PM Reporting\nALL agents MUST report back to the PM upon task completion or when errors occur:\n\n### Required Reporting Elements\n1. **Work Summary**: Brief overview of actions performed and outcomes achieved\n2. **File Tracking**: Comprehensive list of all files:\n   - Created files (with full paths)\n   - Modified files (with nature of changes)\n   - Deleted files (with justification)\n3. **Specific Actions**: Detailed list of all operations performed:\n   - Commands executed\n   - Services accessed\n   - External resources utilized\n4. **Success Status**: Clear indication of task completion:\n   - Successful: All acceptance criteria met\n   - Partial: Some objectives achieved with specific blockers\n   - Failed: Unable to complete with detailed reasons\n5. **Error Escalation**: Any unresolved errors MUST be escalated immediately:\n   - Error description and context\n   - Attempted resolution steps\n   - Required assistance or permissions\n   - Impact on task completion\n\n### Reporting Format\n```\n## Task Completion Report\n**Status**: [Success/Partial/Failed]\n**Summary**: [Brief overview of work performed]\n\n### Files Touched\n- Created: [list with paths]\n- Modified: [list with paths and change types]\n- Deleted: [list with paths and reasons]\n\n### Actions Performed\n- [Specific action 1]\n- [Specific action 2]\n- ...\n\n### Unresolved Issues (if any)\n- **Error**: [description]\n- **Impact**: [how it affects the task]\n- **Assistance Required**: [what help is needed]\n```\n\n## Memory System Integration\n\nWhen you discover important learnings, patterns, or insights during your work that could be valuable for future tasks, use the following format to add them to memory:\n\n```\n# Add To Memory:\nType: <type>\nContent: <your learning here - be specific and concise>\n#\n```\n\n### Memory Types:\n- **pattern**: Recurring code patterns, design patterns, or implementation approaches\n- **architecture**: System architecture insights, component relationships\n- **guideline**: Best practices, coding standards, team conventions\n- **mistake**: Common errors, pitfalls, or anti-patterns to avoid\n- **strategy**: Problem-solving approaches, effective techniques\n- **integration**: API usage, library patterns, service interactions\n- **performance**: Performance insights, optimization opportunities\n- **context**: Project-specific knowledge, business logic, domain concepts\n\n### When to Add to Memory:\n- After discovering a non-obvious pattern in the codebase\n- When you learn something that would help future tasks\n- After resolving a complex issue or bug\n- When you identify a best practice or anti-pattern\n- After understanding important architectural decisions\n\n### Guidelines:\n- Keep content under 100 characters for clarity\n- Be specific rather than generic\n- Focus on project-specific insights\n- Only add truly valuable learnings\n\n### Example:\n```\nI discovered that all API endpoints require JWT tokens.\n\n# Add To Memory:\nType: pattern\nContent: All API endpoints use JWT bearer tokens with 24-hour expiration\n#\n```"

claude_mpm/agents/base_agent_loader.py

@@ -28,7 +28,7 @@ from pathlib import Path
 from typing import Optional, Dict, Any
 from enum import Enum
 
-from ..services.shared_prompt_cache import SharedPromptCache
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 
 # Module-level logger
 logger = logging.getLogger(__name__)

claude_mpm/cli/__init__.py

@@ -22,21 +22,20 @@ from .commands import (
     list_tickets,
     show_info,
     manage_agents,
-    run_terminal_ui,
     manage_memory,
     manage_monitor
 )
+from claude_mpm.config.paths import paths
 
-# Get version from VERSION file - single source of truth
+# Get version using centralized path management
 # Try package VERSION file first (for installed packages)
 package_version_file = Path(__file__).parent.parent / "VERSION"
 if package_version_file.exists():
     __version__ = package_version_file.read_text().strip()
 else:
-    # Fall back to project root VERSION file (for development)
-    root_version_file = Path(__file__).parent.parent.parent.parent / "VERSION"
-    if root_version_file.exists():
-        __version__ = root_version_file.read_text().strip()
+    # Use centralized path management for VERSION file
+    if paths.version_file.exists():
+        __version__ = paths.version_file.read_text().strip()
     else:
         # Try to import from package as fallback
         try:
@@ -180,7 +179,6 @@ def _execute_command(command: str, args) -> int:
         CLICommands.TICKETS.value: list_tickets,
         CLICommands.INFO.value: show_info,
         CLICommands.AGENTS.value: manage_agents,
-        CLICommands.UI.value: run_terminal_ui,
         CLICommands.MEMORY.value: manage_memory,
         CLICommands.MONITOR.value: manage_monitor,
     }

claude_mpm/cli/commands/__init__.py

@@ -9,7 +9,6 @@ from .run import run_session
 from .tickets import list_tickets
 from .info import show_info
 from .agents import manage_agents
-from .ui import run_terminal_ui
 from .memory import manage_memory
 from .monitor import manage_monitor
 
@@ -18,7 +17,6 @@ __all__ = [
     'list_tickets',
     'show_info',
     'manage_agents',
-    'run_terminal_ui',
     'manage_memory',
     'manage_monitor'
 ]

claude_mpm/cli/commands/agents.py

@@ -28,7 +28,7 @@ def manage_agents(args):
     logger = get_logger("cli")
     
     try:
-        from ...services.agent_deployment import AgentDeploymentService
+        from ...services import AgentDeploymentService
         deployment_service = AgentDeploymentService()
         
         if not args.agents_command:

claude_mpm/cli/commands/memory.py

@@ -18,7 +18,7 @@ import click
 
 from ...core.logger import get_logger
 from ...core.config import Config
-from ...services.agent_memory_manager import AgentMemoryManager
+from ...services.agents.memory import AgentMemoryManager
 
 
 def manage_memory(args):

claude_mpm/cli/commands/run.py

@@ -281,6 +281,18 @@ def run_session(args):
         websocket_port=websocket_port
     )
     
+    # Ensure project agents are available if we're in a project directory
+    # This deploys system agents to .claude-mpm/agents/ for local customization
+    if not hasattr(args, 'no_native_agents') or not args.no_native_agents:
+        # Check if we're in a project directory (has .git or other markers)
+        project_markers = ['.git', 'pyproject.toml', 'package.json', 'requirements.txt']
+        cwd = Path.cwd()
+        is_project = any((cwd / marker).exists() for marker in project_markers)
+        
+        if is_project:
+            logger.debug("Detected project directory, ensuring agents are available locally")
+            runner.ensure_project_agents()
+    
     # Set browser opening flag for monitor mode
     if monitor_mode:
         runner._should_open_monitor_browser = True

claude_mpm/cli/parser.py

@@ -278,19 +278,6 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
     )
     add_common_arguments(info_parser)
     
-    # UI command
-    ui_parser = subparsers.add_parser(
-        CLICommands.UI.value,
-        help="Launch terminal UI with multiple panes"
-    )
-    add_common_arguments(ui_parser)
-    ui_parser.add_argument(
-        "--mode",
-        choices=["terminal", "curses"],
-        default="terminal",
-        help="UI mode to launch (default: terminal)"
-    )
-    
     # Agents command with subcommands
     agents_parser = subparsers.add_parser(
         CLICommands.AGENTS.value,