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

claude_mpm/services/{agent_lifecycle_manager.py → agents/deployment/agent_lifecycle_manager.py}

@@ -33,23 +33,24 @@ from enum import Enum
 from pathlib import Path
 from typing import Dict, List, Optional, Set, Any, Tuple, Union
 
-from claude_mpm.services.shared_prompt_cache import SharedPromptCache
-from claude_mpm.services.agent_registry import AgentRegistry, AgentMetadata
-from claude_mpm.services.agent_modification_tracker import (
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
+from claude_mpm.services.agents.registry import AgentRegistry, AgentMetadata
+from claude_mpm.services.agents.registry.modification_tracker import (
     AgentModificationTracker, 
     AgentModification, 
     ModificationType, 
     ModificationTier
 )
-from claude_mpm.services.agent_persistence_service import (
+from claude_mpm.services.agents.memory import (
     AgentPersistenceService,
     PersistenceStrategy,
     PersistenceRecord,
     PersistenceOperation
 )
-from claude_mpm.services.agent_management_service import AgentManager
+from claude_mpm.services.agents.management import AgentManager
 from claude_mpm.models.agent_definition import AgentDefinition, AgentType
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.config_paths import ConfigPaths
 from claude_mpm.utils.path_operations import path_ops
 from claude_mpm.utils.config_manager import ConfigurationManager
 
@@ -275,7 +276,7 @@ class AgentLifecycleManager(BaseService):
     async def _load_agent_records(self) -> None:
         """Load existing agent lifecycle records."""
         try:
-            records_file = Path.home() / '.claude-pm' / 'agent_tracking' / 'lifecycle_records.json'
+            records_file = ConfigPaths.get_tracking_dir() / 'lifecycle_records.json'
             if path_ops.validate_exists(records_file):
                 data = self.config_mgr.load_json(records_file)
                 
@@ -294,7 +295,7 @@ class AgentLifecycleManager(BaseService):
     async def _save_agent_records(self) -> None:
         """Save agent lifecycle records to disk."""
         try:
-            records_file = Path.home() / '.claude-pm' / 'agent_tracking' / 'lifecycle_records.json'
+            records_file = ConfigPaths.get_tracking_dir() / 'lifecycle_records.json'
             path_ops.ensure_dir(records_file.parent)
             
             data = {}
@@ -788,9 +789,9 @@ class AgentLifecycleManager(BaseService):
     async def _determine_agent_file_path(self, agent_name: str, tier: ModificationTier) -> Path:
         """Determine appropriate file path for agent."""
         if tier == ModificationTier.USER:
-            base_path = Path.home() / '.claude-pm' / 'agents'
+            base_path = ConfigPaths.get_user_agents_dir()
         elif tier == ModificationTier.PROJECT:
-            base_path = Path.cwd() / '.claude-pm' / 'agents'
+            base_path = ConfigPaths.get_project_agents_dir()
         else:  # SYSTEM
             base_path = Path.cwd() / 'claude_pm' / 'agents'
         
@@ -804,7 +805,7 @@ class AgentLifecycleManager(BaseService):
             if not path_ops.validate_exists(source_path):
                 return None
             
-            backup_dir = Path.home() / '.claude-pm' / 'agent_tracking' / 'backups'
+            backup_dir = ConfigPaths.get_tracking_dir() / 'backups'
             path_ops.ensure_dir(backup_dir)
             
             timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')

claude_mpm/services/agents/loading/__init__.py

@@ -0,0 +1,11 @@
+"""Agent loading and profile management services."""
+
+from .framework_agent_loader import FrameworkAgentLoader
+from .agent_profile_loader import AgentProfileLoader
+from .base_agent_manager import BaseAgentManager
+
+__all__ = [
+    "FrameworkAgentLoader",
+    "AgentProfileLoader",
+    "BaseAgentManager",
+]

claude_mpm/services/{agent_profile_loader.py → agents/loading/agent_profile_loader.py}

@@ -34,8 +34,9 @@ import yaml
 
 from claude_mpm.core.base_service import BaseService
 from claude_mpm.core.config import Config
-from claude_mpm.services.shared_prompt_cache import SharedPromptCache
-from claude_mpm.services.agent_registry import AgentRegistry
+from claude_mpm.core.config_paths import ConfigPaths
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
+from claude_mpm.services.agents.registry import AgentRegistry
 from claude_mpm.utils.path_operations import path_ops
 
 
@@ -47,10 +48,10 @@ logger = logging.getLogger(__name__)
 # ============================================================================
 
 class ProfileTier(Enum):
-    """Agent profile hierarchy tiers."""
-    SYSTEM = "system"
-    USER = "user" 
-    PROJECT = "project"
+    """Agent profile hierarchy tiers with precedence order."""
+    PROJECT = "project"  # Highest precedence - project-specific agents
+    USER = "user"       # Medium precedence - user-level agents
+    SYSTEM = "system"   # Lowest precedence - framework/built-in agents
 
 
 class ProfileStatus(Enum):
@@ -117,7 +118,7 @@ class AgentProfileLoader(BaseService):
         # Tier paths configuration
         self.tier_paths = {
             ProfileTier.PROJECT: self.working_directory / 'agents',
-            ProfileTier.USER: self.user_home / '.claude-pm' / 'agents',
+            ProfileTier.USER: ConfigPaths.get_user_agents_dir(),
             ProfileTier.SYSTEM: Path(__file__).parent.parent / 'agents' / 'templates'
         }
         
@@ -133,7 +134,7 @@ class AgentProfileLoader(BaseService):
         self.agent_registry: Optional[AgentRegistry] = None
         
         # Improved prompts storage
-        self.improved_prompts_path = self.user_home / '.claude-pm' / 'improved_prompts'
+        self.improved_prompts_path = ConfigPaths.get_user_config_dir() / 'improved_prompts'
         self.improved_prompts_path.mkdir(parents=True, exist_ok=True)
         
         # Performance tracking

claude_mpm/services/{base_agent_manager.py → agents/loading/base_agent_manager.py}

@@ -14,8 +14,8 @@ from datetime import datetime
 from dataclasses import dataclass, field
 from enum import Enum
 
-from .shared_prompt_cache import SharedPromptCache
-from ..agents.base_agent_loader import clear_base_agent_cache
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
+from claude_mpm.agents.base_agent_loader import clear_base_agent_cache
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/{framework_agent_loader.py → agents/loading/framework_agent_loader.py}

@@ -2,10 +2,14 @@
 Framework Agent Loader Service
 
 Implements agent profile loading logic based on directory hierarchy:
-1. Framework .claude-pm (next to agents/INSTRUCTIONS.md or CLAUDE.md): system, trained, user agents
-2. Project .claude-pm (in project root): project agents
+1. Project .claude-mpm (in project root): project agents - HIGHEST PRECEDENCE
+2. User .claude-mpm (~/.claude-mpm): user agents - MEDIUM PRECEDENCE  
+3. Framework/System agents: built-in agents - LOWEST PRECEDENCE
 
-Loading precedence: Project → Framework (user → trained → system)
+Loading precedence: Project → User → System
+
+This service integrates with the main agent_loader.py to provide
+markdown-based agent profiles alongside JSON-based templates.
 """
 
 import os
@@ -14,38 +18,56 @@ from pathlib import Path
 from typing import Dict, Optional, Any
 import logging
 
+from claude_mpm.core.config_paths import ConfigPaths
+from claude_mpm.agents.agent_loader import AgentTier, get_agent_tier, list_agents_by_tier
+
 logger = logging.getLogger(__name__)
 
 class FrameworkAgentLoader:
-    """Loads agent profiles from framework and project .claude-pm directories"""
+    """Loads agent profiles from project, user, and system directories with proper precedence"""
     
     def __init__(self):
-        self.framework_agents_dir = None
         self.project_agents_dir = None
+        self.user_agents_dir = None
+        self.system_agents_dir = None
         self._profile_cache = {}
+        self._tier_mapping = {
+            AgentTier.PROJECT: 'project',
+            AgentTier.USER: 'user',
+            AgentTier.SYSTEM: 'system'
+        }
         
     def initialize(self, framework_claude_md_path: Optional[str] = None):
         """
-        Initialize loader with framework and project directory detection
+        Initialize loader with project, user, and system directory detection
         
         Args:
             framework_claude_md_path: Optional explicit path to agents/INSTRUCTIONS.md or CLAUDE.md
         """
-        # Find framework .claude-pm directory (next to framework/CLAUDE.md)
+        # Find project .claude-mpm directory (highest precedence)
+        project_dir = self._find_project_directory()
+        if project_dir:
+            self.project_agents_dir = project_dir / ConfigPaths.CONFIG_DIR / "agents"
+            logger.info(f"Project agents directory: {self.project_agents_dir}")
+        
+        # Find user .claude-mpm directory (medium precedence)
+        user_config_dir = ConfigPaths.get_user_config_dir()
+        if user_config_dir:
+            self.user_agents_dir = user_config_dir / "agents"
+            if self.user_agents_dir.exists():
+                logger.info(f"User agents directory: {self.user_agents_dir}")
+            else:
+                self.user_agents_dir = None
+        
+        # Find system/framework agents directory (lowest precedence)
         if framework_claude_md_path:
             framework_dir = Path(framework_claude_md_path).parent.parent
         else:
             framework_dir = self._find_framework_directory()
             
         if framework_dir:
-            self.framework_agents_dir = framework_dir / ".claude-pm" / "agents"
-            logger.info(f"Framework agents directory: {self.framework_agents_dir}")
-        
-        # Find project .claude-pm directory
-        project_dir = self._find_project_directory()
-        if project_dir:
-            self.project_agents_dir = project_dir / ".claude-pm" / "agents"
-            logger.info(f"Project agents directory: {self.project_agents_dir}")
+            self.system_agents_dir = framework_dir / ConfigPaths.CONFIG_DIR / "agents"
+            logger.info(f"System agents directory: {self.system_agents_dir}")
     
     def _find_framework_directory(self) -> Optional[Path]:
         """Find directory containing agents/INSTRUCTIONS.md (or legacy CLAUDE.md)"""
@@ -75,12 +97,12 @@ class FrameworkAgentLoader:
         return None
     
     def _find_project_directory(self) -> Optional[Path]:
-        """Find project directory containing .claude-pm"""
+        """Find project directory containing .claude-mpm"""
         current = Path.cwd()
         
-        # Check current directory and parents for .claude-pm
+        # Check current directory and parents for .claude-mpm
         for path in [current] + list(current.parents):
-            claude_pm_dir = path / ".claude-pm"
+            claude_pm_dir = path / ConfigPaths.CONFIG_DIR
             if claude_pm_dir.exists():
                 return path
                 
@@ -88,7 +110,10 @@ class FrameworkAgentLoader:
     
     def load_agent_profile(self, agent_type: str) -> Optional[Dict[str, Any]]:
         """
-        Load agent profile with precedence: Project → Framework (user → trained → system)
+        Load agent profile with precedence: Project → User → System
+        
+        This method now properly integrates with the main agent_loader.py
+        tier system for consistent precedence handling.
         
         Args:
             agent_type: Agent type (Engineer, Documenter, QA, etc.)
@@ -102,31 +127,57 @@ class FrameworkAgentLoader:
             return self._profile_cache[cache_key]
         
         profile = None
+        loaded_tier = None
         
         # 1. Try project agents first (highest precedence)
         if self.project_agents_dir:
+            # Check both 'project' subdirectory and direct directory
             profile = self._load_profile_from_directory(
                 self.project_agents_dir / "project", agent_type
             )
+            if not profile:
+                profile = self._load_profile_from_directory(
+                    self.project_agents_dir, agent_type
+                )
+            if profile:
+                loaded_tier = AgentTier.PROJECT
         
-        # 2. Try framework agents (user → trained → system)
-        if not profile and self.framework_agents_dir:
-            # Framework user agents
+        # 2. Try user agents (medium precedence)
+        if not profile and self.user_agents_dir:
+            # Check both 'user' subdirectory and direct directory
             profile = self._load_profile_from_directory(
-                self.framework_agents_dir / "user", agent_type
+                self.user_agents_dir / "user", agent_type
             )
-            
-            # Framework trained agents
             if not profile:
                 profile = self._load_profile_from_directory(
-                    self.framework_agents_dir / "trained", agent_type
+                    self.user_agents_dir, agent_type
+                )
+            if profile:
+                loaded_tier = AgentTier.USER
+        
+        # 3. Try system agents (lowest precedence)
+        if not profile and self.system_agents_dir:
+            # Check subdirectories in order: trained → system
+            for subdir in ["trained", "system"]:
+                profile = self._load_profile_from_directory(
+                    self.system_agents_dir / subdir, agent_type
                 )
+                if profile:
+                    loaded_tier = AgentTier.SYSTEM
+                    break
             
-            # Framework system agents (fallback)
+            # Also check root system directory
             if not profile:
                 profile = self._load_profile_from_directory(
-                    self.framework_agents_dir / "system", agent_type
+                    self.system_agents_dir, agent_type
                 )
+                if profile:
+                    loaded_tier = AgentTier.SYSTEM
+        
+        # Add tier information to profile
+        if profile and loaded_tier:
+            profile['_tier'] = loaded_tier.value
+            logger.debug(f"Loaded {agent_type} profile from {loaded_tier.value} tier")
         
         # Cache result
         if profile:
@@ -270,23 +321,48 @@ class FrameworkAgentLoader:
         """Get list of available agents by tier"""
         agents = {
             'project': [],
-            'framework_user': [],
-            'framework_trained': [],
-            'framework_system': []
+            'user': [],
+            'system': []
         }
         
         # Project agents
         if self.project_agents_dir:
-            project_dir = self.project_agents_dir / "project"
-            if project_dir.exists():
-                agents['project'] = [f.stem for f in project_dir.glob("*.md")]
+            # Check both project subdirectory and root
+            for search_dir in [self.project_agents_dir / "project", self.project_agents_dir]:
+                if search_dir.exists():
+                    md_files = [f.stem for f in search_dir.glob("*.md")]
+                    agents['project'].extend([f for f in md_files if f not in agents['project']])
+        
+        # User agents
+        if self.user_agents_dir:
+            # Check both user subdirectory and root
+            for search_dir in [self.user_agents_dir / "user", self.user_agents_dir]:
+                if search_dir.exists():
+                    md_files = [f.stem for f in search_dir.glob("*.md")]
+                    agents['user'].extend([f for f in md_files if f not in agents['user']])
         
-        # Framework agents
-        if self.framework_agents_dir:
-            for tier in ['user', 'trained', 'system']:
-                tier_dir = self.framework_agents_dir / tier
-                if tier_dir.exists():
-                    agents[f'framework_{tier}'] = [f.stem for f in tier_dir.glob("*.md")]
+        # System agents
+        if self.system_agents_dir:
+            # Check subdirectories and root
+            for subdir in ["trained", "system", ""]:
+                search_dir = self.system_agents_dir / subdir if subdir else self.system_agents_dir
+                if search_dir.exists():
+                    md_files = [f.stem for f in search_dir.glob("*.md")]
+                    agents['system'].extend([f for f in md_files if f not in agents['system']])
+        
+        # Also integrate with main agent_loader to get JSON-based agents
+        try:
+            json_agents = list_agents_by_tier()
+            for tier, agent_list in json_agents.items():
+                if tier in agents:
+                    # Merge lists, avoiding duplicates
+                    for agent in agent_list:
+                        # Remove _agent suffix for consistency
+                        agent_name = agent.replace('_agent', '')
+                        if agent_name not in agents[tier]:
+                            agents[tier].append(agent_name)
+        except Exception as e:
+            logger.debug(f"Could not integrate with agent_loader: {e}")
         
         return agents
     

claude_mpm/services/agents/management/__init__.py

@@ -0,0 +1,9 @@
+"""High-level agent management services."""
+
+from .agent_management_service import AgentManager
+from .agent_capabilities_generator import AgentCapabilitiesGenerator
+
+__all__ = [
+    "AgentManager",
+    "AgentCapabilitiesGenerator",
+]

claude_mpm/services/{agent_management_service.py → agents/management/agent_management_service.py}

@@ -21,13 +21,14 @@ from datetime import datetime
 import frontmatter
 import mistune
 
-from ..models.agent_definition import (
+from claude_mpm.models.agent_definition import (
     AgentDefinition, AgentMetadata, AgentType, 
     AgentSection, AgentWorkflow, AgentPermissions
 )
-from .agent_versioning import AgentVersionManager
-from .shared_prompt_cache import SharedPromptCache
-from ..utils.paths import PathResolver
+from ..deployment.agent_versioning import AgentVersionManager
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
+from claude_mpm.utils.paths import PathResolver
+from claude_mpm.core.config_paths import ConfigPaths
 
 logger = logging.getLogger(__name__)
 
@@ -56,7 +57,7 @@ class AgentManager:
             
         if project_dir is None:
             project_root = PathResolver.get_project_root()
-            self.project_dir = project_root / ".claude-pm" / "agents" / "project-specific"
+            self.project_dir = project_root / ConfigPaths.CONFIG_DIR / "agents" / "project-specific"
         else:
             self.project_dir = project_dir
         self.version_manager = AgentVersionManager()

claude_mpm/services/agents/memory/__init__.py

@@ -0,0 +1,21 @@
+"""Agent memory and persistence services."""
+
+from .agent_memory_manager import (
+    AgentMemoryManager,
+    get_memory_manager,
+)
+from .agent_persistence_service import (
+    AgentPersistenceService,
+    PersistenceStrategy,
+    PersistenceOperation,
+    PersistenceRecord,
+)
+
+__all__ = [
+    "AgentMemoryManager",
+    "get_memory_manager",
+    "AgentPersistenceService",
+    "PersistenceStrategy",
+    "PersistenceOperation",
+    "PersistenceRecord",
+]

claude_mpm/services/{agent_memory_manager.py → agents/memory/agent_memory_manager.py}

@@ -946,7 +946,7 @@ class AgentMemoryManager:
             Dict containing optimization results and statistics
         """
         try:
-            from claude_mpm.services.memory_optimizer import MemoryOptimizer
+            from claude_mpm.services.memory.optimizer import MemoryOptimizer
             optimizer = MemoryOptimizer(self.config, self.working_directory)
             
             if agent_id:
@@ -974,7 +974,7 @@ class AgentMemoryManager:
             Dict containing build results and statistics
         """
         try:
-            from claude_mpm.services.memory_builder import MemoryBuilder
+            from claude_mpm.services.memory.builder import MemoryBuilder
             builder = MemoryBuilder(self.config, self.working_directory)
             
             result = builder.build_from_documentation(force_rebuild)
@@ -1000,7 +1000,7 @@ class AgentMemoryManager:
             Dict containing routing decision and reasoning
         """
         try:
-            from claude_mpm.services.memory_router import MemoryRouter
+            from claude_mpm.services.memory.router import MemoryRouter
             router = MemoryRouter(self.config)
             
             routing_result = router.analyze_and_route(content, context)

claude_mpm/services/agents/registry/__init__.py

@@ -0,0 +1,29 @@
+"""Agent registry services for discovery and tracking."""
+
+from .agent_registry import (
+    AgentRegistry,
+    AgentMetadata,
+    AgentTier,
+    AgentType,
+)
+from .deployed_agent_discovery import DeployedAgentDiscovery
+from .modification_tracker import (
+    AgentModificationTracker,
+    ModificationType,
+    ModificationTier,
+    AgentModification,
+    ModificationHistory,
+)
+
+__all__ = [
+    "AgentRegistry",
+    "AgentMetadata",
+    "AgentTier",
+    "AgentType",
+    "DeployedAgentDiscovery",
+    "AgentModificationTracker",
+    "ModificationType",
+    "ModificationTier",
+    "AgentModification",
+    "ModificationHistory",
+]