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

claude_mpm/services/claude_session_logger.py

@@ -0,0 +1,299 @@
+"""
+Claude Session Response Logger
+
+Simplified response logging system that uses Claude Code session IDs.
+Stores responses in docs/responses/{session-id}/ for easy access.
+
+Now with optional async logging support for improved performance.
+Configuration via .claude-mpm/configuration.yaml.
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+import logging
+
+# Import configuration manager
+from claude_mpm.core.config import Config
+
+# Try to import async logger for performance optimization
+try:
+    from claude_mpm.services.async_session_logger import (
+        get_async_logger,
+        log_response_async,
+        AsyncSessionLogger
+    )
+    ASYNC_AVAILABLE = True
+except ImportError:
+    ASYNC_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeSessionLogger:
+    """Simplified response logger for Claude Code sessions."""
+    
+    def __init__(self, base_dir: Optional[Path] = None, use_async: Optional[bool] = None, config: Optional[Config] = None):
+        """
+        Initialize the session logger.
+        
+        Args:
+            base_dir: Base directory for responses. Overrides config.
+            use_async: Use async logging if available. Overrides config.
+            config: Configuration instance to use (creates new if not provided)
+        """
+        # Load configuration
+        if config is None:
+            config = Config()
+        self.config = config
+        
+        # Get response logging configuration
+        response_config = self.config.get('response_logging', {})
+        
+        # Determine base directory
+        if base_dir is None:
+            # Check configuration first
+            base_dir = response_config.get('session_directory')
+            if not base_dir:
+                # Fall back to default response directory
+                base_dir = '.claude-mpm/responses'
+            base_dir = Path(base_dir)
+        
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Try to get session ID from environment
+        self.session_id = self._get_claude_session_id()
+        self.response_counter = {}  # Track response count per session
+        
+        # Determine if we should use async logging
+        if use_async is None:
+            # Check if response logging is enabled at all
+            if not response_config.get('enabled', True):
+                logger.info("Response logging disabled in configuration")
+                use_async = False
+            else:
+                # Check configuration for async preference
+                use_async = response_config.get('use_async', True)
+                
+                # Check environment for backward compatibility
+                if os.environ.get('CLAUDE_USE_ASYNC_LOG'):
+                    env_async = os.environ.get('CLAUDE_USE_ASYNC_LOG', 'true').lower() == 'true'
+                    logger.info(f"Using CLAUDE_USE_ASYNC_LOG environment variable (deprecated): {env_async}")
+                    use_async = env_async
+        
+        self.use_async = use_async and ASYNC_AVAILABLE
+        self._async_logger = None
+        
+        if self.use_async:
+            try:
+                self._async_logger = get_async_logger(config=config)
+                logger.info("Using async logger for improved performance")
+            except Exception as e:
+                logger.warning(f"Failed to initialize async logger, falling back to sync: {e}")
+                self.use_async = False
+        
+    def _get_claude_session_id(self) -> Optional[str]:
+        """
+        Get the Claude Code session ID from environment.
+        
+        Returns:
+            Session ID if available, None otherwise
+        """
+        # Claude Code may set various environment variables
+        # Check common patterns
+        session_id = None
+        
+        # Check for CLAUDE_SESSION_ID
+        session_id = os.environ.get('CLAUDE_SESSION_ID')
+        
+        # Check for ANTHROPIC_SESSION_ID
+        if not session_id:
+            session_id = os.environ.get('ANTHROPIC_SESSION_ID')
+        
+        # Check for generic SESSION_ID
+        if not session_id:
+            session_id = os.environ.get('SESSION_ID')
+        
+        # Generate a default based on timestamp if nothing found
+        if not session_id:
+            # Use a timestamp-based session ID as fallback
+            session_id = datetime.now().strftime('%Y%m%d_%H%M%S')
+            logger.info(f"No Claude session ID found, using generated: {session_id}")
+        else:
+            logger.info(f"Using Claude session ID: {session_id}")
+        
+        return session_id
+    
+    def _generate_filename(self, agent: Optional[str] = None) -> str:
+        """
+        Generate a flat filename with session ID, agent, and timestamp.
+        
+        Args:
+            agent: Optional agent name
+            
+        Returns:
+            Filename in format: [session_id]-[agent]-timestamp.json
+        """
+        # Get agent name, defaulting to "unknown" if not provided
+        agent_name = agent or "unknown"
+        # Sanitize agent name (replace spaces with underscores, lowercase)
+        agent_name = agent_name.replace(" ", "_").lower()
+        
+        # Generate timestamp with microseconds for uniqueness
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        
+        # Create filename: session_id-agent-timestamp.json
+        filename = f"{self.session_id}-{agent_name}-{timestamp}.json"
+        return filename
+    
+    def log_response(
+        self,
+        request_summary: str,
+        response_content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        agent: Optional[str] = None
+    ) -> Optional[Path]:
+        """
+        Log a response to the session directory.
+        
+        Args:
+            request_summary: Brief summary of the request
+            response_content: The full response content
+            metadata: Optional metadata (agent name, model, etc.)
+            agent: Optional agent name (overrides metadata)
+            
+        Returns:
+            Path to the saved response file, or None if disabled
+        """
+        # Check if logging is actually enabled
+        response_config = self.config.get('response_logging', {})
+        if not response_config.get('enabled', True):
+            logger.debug("Response logging is disabled in configuration")
+            return None
+            
+        if not self.session_id:
+            return None
+        
+        # Use async logger if available for better performance
+        if self.use_async and self._async_logger:
+            success = self._async_logger.log_response(
+                request_summary=request_summary,
+                response_content=response_content,
+                metadata=metadata,
+                agent=agent
+            )
+            if success:
+                # Return expected path for compatibility
+                # Async logger uses timestamp-based names, so we can't return exact path
+                return self.base_dir / "async_response.json"
+            return None
+        
+        # Fall back to synchronous logging
+        # Ensure base directory exists (flat structure, no subdirs)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Extract agent name from parameter or metadata
+        agent_name = agent or (metadata.get("agent") if metadata else None) or "unknown"
+        
+        # Generate filename with flat structure
+        filename = self._generate_filename(agent_name)
+        file_path = self.base_dir / filename
+        
+        # Prepare response data with standardized field names
+        response_data = {
+            "timestamp": datetime.now().isoformat(),
+            "session_id": self.session_id,
+            "request": request_summary,  # Standardized field name
+            "response": response_content,  # Already correct
+            "agent": agent or (metadata.get("agent") if metadata else None) or "unknown",  # Standardized field name
+            "metadata": metadata or {}
+        }
+        
+        # Save response
+        try:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                json.dump(response_data, f, indent=2, ensure_ascii=False)
+            
+            logger.debug(f"Logged response to {filename} for session {self.session_id}")
+            return file_path
+            
+        except Exception as e:
+            logger.error(f"Failed to log response: {e}")
+            return None
+    
+    def set_session_id(self, session_id: str) -> None:
+        """
+        Manually set the session ID.
+        
+        Args:
+            session_id: The session ID to use
+        """
+        self.session_id = session_id
+        logger.info(f"Session ID set to: {session_id}")
+    
+    def get_session_path(self) -> Optional[Path]:
+        """
+        Get the path to the responses directory.
+        
+        Note: With flat structure, returns the base directory.
+        
+        Returns:
+            Path to responses directory, or None if no session
+        """
+        if not self.session_id:
+            return None
+        return self.base_dir
+    
+    def is_enabled(self) -> bool:
+        """
+        Check if logging is enabled.
+        
+        Returns:
+            True if logging is enabled (session ID available)
+        """
+        return self.session_id is not None
+
+
+# Singleton instance for easy access
+_logger_instance = None
+
+
+def get_session_logger(config: Optional[Config] = None) -> ClaudeSessionLogger:
+    """
+    Get the singleton session logger instance.
+    
+    Args:
+        config: Optional configuration instance to use
+    
+    Returns:
+        The shared ClaudeSessionLogger instance
+    """
+    global _logger_instance
+    if _logger_instance is None:
+        _logger_instance = ClaudeSessionLogger(config=config)
+    return _logger_instance
+
+
+def log_response(
+    request_summary: str,
+    response_content: str,
+    metadata: Optional[Dict[str, Any]] = None,
+    agent: Optional[str] = None
+) -> Optional[Path]:
+    """
+    Convenience function to log a response.
+    
+    Args:
+        request_summary: Brief summary of the request
+        response_content: The full response content
+        metadata: Optional metadata
+        agent: Optional agent name
+        
+    Returns:
+        Path to the saved response file
+    """
+    logger = get_session_logger()
+    return logger.log_response(request_summary, response_content, metadata, agent)

claude_mpm/services/framework_claude_md_generator/content_assembler.py

@@ -10,8 +10,8 @@ from typing import Dict, List, Optional, Any
 from collections import OrderedDict
 import logging
 
-from claude_mpm.services.deployed_agent_discovery import DeployedAgentDiscovery
-from claude_mpm.services.agent_capabilities_generator import AgentCapabilitiesGenerator
+from claude_mpm.services.agents.registry import DeployedAgentDiscovery
+from claude_mpm.services.agents.management import AgentCapabilitiesGenerator
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/framework_claude_md_generator/section_generators/agents.py

@@ -75,15 +75,15 @@ class AgentsGenerator(BaseSectionGenerator):
 **ALL AGENT OPERATIONS FOLLOW HIERARCHICAL PRECEDENCE**
 
 #### Agent Hierarchy (Highest to Lowest Priority)
-1. **Project Agents**: `$PROJECT/.claude-pm/agents/project-specific/`
+1. **Project Agents**: `$PROJECT/.claude-mpm/agents/project-specific/`
    - Project-specific implementations and overrides
    - Highest precedence for project context
    - Custom agents tailored to project requirements
 
 2. **User Agents**: Directory hierarchy with precedence walking
-   - **Current Directory**: `$PWD/.claude-pm/agents/user-agents/` (highest user precedence)
+   - **Current Directory**: `$PWD/.claude-mpm/agents/user-agents/` (highest user precedence)
    - **Parent Directories**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
-   - **User Home**: `~/.claude-pm/agents/user-defined/` (fallback user location)
+   - **User Home**: `~/.claude-mpm/agents/user-defined/` (fallback user location)
    - User-specific customizations across projects
    - Mid-priority, can override system defaults
 
@@ -258,7 +258,7 @@ task_type = "performance_optimization"
 required_specializations = ["performance", "monitoring"]
 
 # Discover optimal agent
-all_agents = registry.listAgents()
+all_agents = registry.list_agents()
 # Filter by specializations
 optimal_agents = {k: v for k, v in all_agents.items()
                   if any(spec in v.get('specializations', [])
@@ -352,7 +352,7 @@ TEMPORAL CONTEXT: Today is [date]. Apply date awareness to data operations.
 
 **CRITICAL: Agent Registry provides dynamic agent discovery beyond core 9 agent types**
 
-#### AgentRegistry.listAgents() Method Usage
+#### AgentRegistry.list_agents() Method Usage
 
 **Comprehensive Agent Discovery API:**
 ```python
@@ -362,7 +362,7 @@ from claude_pm.core.agent_registry import AgentRegistry
 registry = AgentRegistry()
 
 # List all available agents with metadata
-agents = registry.listAgents()
+agents = registry.list_agents()
 
 # Access agent metadata
 for agent_id, metadata in agents.items():
@@ -376,15 +376,15 @@ for agent_id, metadata in agents.items():
 #### Directory Precedence Rules and Agent Discovery
 
 **Enhanced Agent Discovery Pattern (Highest to Lowest Priority):**
-1. **Project Agents**: `$PROJECT/.claude-pm/agents/project-specific/`
-2. **Current Directory User Agents**: `$PWD/.claude-pm/agents/user-agents/`
+1. **Project Agents**: `$PROJECT/.claude-mpm/agents/project-specific/`
+2. **Current Directory User Agents**: `$PWD/.claude-mpm/agents/user-agents/`
 3. **Parent Directory User Agents**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
-4. **User Home Agents**: `~/.claude-pm/agents/user-defined/`
+4. **User Home Agents**: `~/.claude-mpm/agents/user-defined/`
 5. **System Agents**: `claude_pm/agents/`
 
 **User-Agents Directory Structure:**
 ```
-$PWD/.claude-pm/agents/user-agents/
+$PWD/.claude-mpm/agents/user-agents/
 ├── specialized/
 │   ├── performance-agent.md
 │   ├── architecture-agent.md
@@ -403,7 +403,7 @@ $PWD/.claude-pm/agents/user-agents/
 registry = AgentRegistry()
 
 # Discover all agents
-all_agents = registry.listAgents()
+all_agents = registry.list_agents()
 
 # Filter by tier if needed
 project_agents = {k: v for k, v in all_agents.items() if v.get('tier') == 'project'}
@@ -420,7 +420,7 @@ system_agents = {k: v for k, v in all_agents.items() if v.get('tier') == 'system
 **Specialized Discovery Usage:**
 ```python
 # Discover agents by type (note: specialization filtering would require custom filtering)
-all_agents = registry.listAgents()
+all_agents = registry.list_agents()
 
 # Filter by specialization manually
 ui_agents = {k: v for k, v in all_agents.items() if 'ui_ux' in v.get('specializations', [])}
@@ -440,7 +440,7 @@ multi_spec = {k: v for k, v in all_agents.items()
 registry = AgentRegistry()
 
 # Get all agents (modification timestamps are included by default)
-agents_with_tracking = registry.listAgents()
+agents_with_tracking = registry.list_agents()
 
 # Filter agents modified since last orchestration manually
 recent_agents = {k: v for k, v in agents_with_tracking.items() 
@@ -464,7 +464,7 @@ cache = SharedPromptCache()
 registry = AgentRegistry(prompt_cache=cache)
 
 # Agent discovery (caching is automatic)
-cached_agents = registry.listAgents()
+cached_agents = registry.list_agents()
 
 # Cache optimization for repeated orchestration
 cache.preload_agent_prompts(agent_ids=['documentation', 'qa', 'engineer'])
@@ -486,7 +486,7 @@ def select_optimal_agent(task_type, specialization_requirements):
     registry = AgentRegistry()
     
     # Find agents matching requirements
-    all_agents = registry.listAgents()
+    all_agents = registry.list_agents()
     matching_agents = {k: v for k, v in all_agents.items() 
                        if any(spec in v.get('specializations', []) 
                              for spec in specialization_requirements)}
@@ -541,7 +541,7 @@ TEMPORAL CONTEXT: Today is [date]. Using agent registry for optimal agent select
 
 **Enhanced Orchestration with Dynamic Discovery:**
 
-1. **Dynamic Agent Selection**: Use AgentRegistry.listAgents() to select optimal agents based on task requirements and available specializations
+1. **Dynamic Agent Selection**: Use AgentRegistry.list_agents() to select optimal agents based on task requirements and available specializations
 
 2. **Precedence-Aware Delegation**: Respect directory precedence when multiple agents of same type exist
 
@@ -562,7 +562,7 @@ def orchestrate_with_registry(task_description, requirements):
     registry = AgentRegistry()
     
     # Discover optimal agents
-    all_agents = registry.listAgents()
+    all_agents = registry.list_agents()
     # Filter by requirements
     agents = {k: v for k, v in all_agents.items()
               if any(spec in v.get('specializations', [])

claude_mpm/services/framework_claude_md_generator/section_generators/claude_pm_init.py

@@ -70,15 +70,15 @@ claude-pm init --verify
 
 **Multi-Project Orchestrator Pattern:**
 
-1. **Framework Directory** (`/Users/masa/Projects/claude-multiagent-pm/.claude-pm/`)
+1. **Framework Directory** (`/Users/masa/Projects/claude-multiagent-pm/.claude-mpm/`)
    - Global user agents (shared across all projects)
    - Framework-level configuration
 
-2. **Working Directory** (`$PWD/.claude-pm/`)
+2. **Working Directory** (`$PWD/.claude-mpm/`)
    - Current session configuration
    - Working directory context
 
-3. **Project Directory** (`$PROJECT_ROOT/.claude-pm/`)
+3. **Project Directory** (`$PROJECT_ROOT/.claude-mpm/`)
    - Project-specific agents in `agents/project-specific/`
    - User agents in `agents/user-agents/` with directory precedence
    - Project-specific configuration

claude_mpm/services/framework_claude_md_generator/section_generators/core_responsibilities.py

@@ -16,7 +16,7 @@ class CoreResponsibilitiesGenerator(BaseSectionGenerator):
 1. **Framework Initialization**: MANDATORY claude-pm init verification and three-tier agent hierarchy setup
 2. **Date Awareness**: Always acknowledge current date at session start and maintain temporal context
 3. **Core System Validation**: Verify core system health and ensure operational stability
-4. **Agent Registry Integration**: Use AgentRegistry.listAgents() for dynamic agent discovery and optimal task delegation
+4. **Agent Registry Integration**: Use AgentRegistry.list_agents() for dynamic agent discovery and optimal task delegation
 5. **Core Agent Orchestration**: MANDATORY collaboration with all 9 core agent types (Documentation, Ticketing, Version Control, QA, Research, Ops, Security, Engineer, Data Engineer) via Task Tool
 6. **Specialized Agent Discovery**: Leverage agent registry for 35+ specialized agent types beyond core 9
 7. **Multi-Agent Coordination**: Coordinate agents using three-tier hierarchy via Task Tool with registry-enhanced selection

claude_mpm/services/framework_claude_md_generator/section_generators/orchestration_principles.py

@@ -22,7 +22,7 @@ class OrchestrationPrinciplesGenerator(BaseSectionGenerator):
 6. **Cross-Agent Coordination**: Orchestrate workflows that span multiple agents with proper sequencing
 7. **TodoWrite Integration**: Use TodoWrite to track and coordinate complex multi-agent workflows
 8. **Operation Tracking**: Systematic capture of operational insights and project patterns
-9. **Agent Registry Integration**: Use AgentRegistry.listAgents() for dynamic agent discovery and optimal task delegation
+9. **Agent Registry Integration**: Use AgentRegistry.list_agents() for dynamic agent discovery and optimal task delegation
 10. **Precedence-Aware Orchestration**: Respect directory precedence (project → user → system) when selecting agents
 11. **Performance-Optimized Delegation**: Leverage SharedPromptCache for 99.7% faster agent loading and orchestration
 12. **Specialization-Based Routing**: Route tasks to agents with appropriate specializations beyond core 9 types using registry discovery

claude_mpm/services/framework_claude_md_generator/section_generators/todo_task_tools.py

@@ -43,38 +43,33 @@ class TodoTaskToolsGenerator(BaseSectionGenerator):
 Task(description="[task description]", subagent_type="[agent-type]")
 ```
 
-**Valid subagent_type values (both formats accepted):**
+**Valid subagent_type values (use lowercase format for Claude Code compatibility):**
 
-**Lowercase-hyphenated format (traditional):**
+**Required lowercase format (Claude Code expects these exact values):**
 - `subagent_type="research"` - For investigation and analysis
 - `subagent_type="engineer"` - For coding and implementation
 - `subagent_type="qa"` - For testing and quality assurance
 - `subagent_type="documentation"` - For docs and guides
 - `subagent_type="security"` - For security assessments
 - `subagent_type="ops"` - For deployment and infrastructure
-- `subagent_type="version-control"` - For git and version management
-- `subagent_type="data-engineer"` - For data processing and APIs
-
-**Capitalized format (matching TodoWrite prefixes - also accepted):**
-- `subagent_type="Research"` - For investigation and analysis
-- `subagent_type="Engineer"` - For coding and implementation
-- `subagent_type="QA"` - For testing and quality assurance
-- `subagent_type="Documentation"` - For docs and guides
-- `subagent_type="Security"` - For security assessments
-- `subagent_type="Ops"` - For deployment and infrastructure
-- `subagent_type="Version Control"` - For git and version management
-- `subagent_type="Data Engineer"` - For data processing and APIs
-
-**Examples of Proper Task Tool Usage (both formats work):**
+- `subagent_type="version_control"` - For git and version management (use underscore, not hyphen)
+- `subagent_type="data_engineer"` - For data processing and APIs (use underscore, not hyphen)
+- `subagent_type="pm"` - For project management coordination
+- `subagent_type="test_integration"` - For integration testing
+
+**Note:** Claude Code's Task tool requires exact lowercase agent names. Capitalized formats like "Research" or "Engineer" will be rejected with an error.
+
+**Examples of Proper Task Tool Usage (use lowercase format only):**
 - ✅ `Task(description="Update framework documentation", subagent_type="documentation")`
 - ✅ `Task(description="Execute test suite validation", subagent_type="qa")`
-- ✅ `Task(description="Create feature branch and sync", subagent_type="version-control")`
+- ✅ `Task(description="Create feature branch and sync", subagent_type="version_control")` (use underscore)
 - ✅ `Task(description="Investigate performance patterns", subagent_type="research")`
 - ✅ `Task(description="Implement authentication system", subagent_type="engineer")`
-- ✅ `Task(description="Configure database and optimize queries", subagent_type="data-engineer")`
-- ✅ `Task(description="Analyze code patterns", subagent_type="Research")` (capitalized format)
-- ✅ `Task(description="Update API docs", subagent_type="Documentation")` (capitalized format)
-- ✅ `Task(description="Create release tags", subagent_type="Version Control")` (capitalized format)
+- ✅ `Task(description="Configure database and optimize queries", subagent_type="data_engineer")` (use underscore)
+- ✅ `Task(description="Coordinate project tasks", subagent_type="pm")`
+- ❌ `Task(description="Analyze code patterns", subagent_type="Research")` (WRONG - will be rejected)
+- ❌ `Task(description="Update API docs", subagent_type="Documentation")` (WRONG - will be rejected)
+- ❌ `Task(description="Create release tags", subagent_type="Version Control")` (WRONG - will be rejected)
 
 ### 🚨 MANDATORY: THREE SHORTCUT COMMANDS
 
@@ -103,11 +98,11 @@ Task(description="[task description]", subagent_type="[agent-type]")
 - ☐ [Data Engineer] Validate data integrity and verify API connectivity
 - ☐ [Version Control] Apply semantic version bump and create release tags
 
-# Corresponding Task Tool delegations:
+# Corresponding Task Tool delegations (use lowercase with underscores):
 Task(description="Generate changelog and analyze version impact", subagent_type="documentation")
 Task(description="Execute full test suite and quality validation", subagent_type="qa")
-Task(description="Validate data integrity and verify API connectivity", subagent_type="data-engineer")
-Task(description="Apply semantic version bump and create release tags", subagent_type="version-control")
+Task(description="Validate data integrity and verify API connectivity", subagent_type="data_engineer")
+Task(description="Apply semantic version bump and create release tags", subagent_type="version_control")
 
 # Update TodoWrite status based on agent completions
 ```

claude_mpm/services/framework_claude_md_generator/section_generators/troubleshooting.py

@@ -21,7 +21,7 @@ class TroubleshootingGenerator(BaseSectionGenerator):
 4. **Permission Issues**: Ensure proper file permissions on CLI executables
 
 ### claude-pm init and Agent Hierarchy Issues
-5. **Missing .claude-pm Directories**: Run `claude-pm init --setup`
+5. **Missing .claude-mpm Directories**: Run `claude-pm init --setup`
 6. **Agent Hierarchy Validation Errors**: Run `claude-pm init --verify` for detailed validation
 
 ### Core System Issues

claude_mpm/services/framework_claude_md_generator.py

@@ -18,6 +18,8 @@ from pathlib import Path
 from typing import Dict, Optional, Any, List, Tuple, Callable
 from dataclasses import dataclass, field
 
+from claude_mpm.core.config_paths import ConfigPaths
+
 logger = logging.getLogger(__name__)
 
 
@@ -338,7 +340,7 @@ class FrameworkClaudeMdGenerator:
         self.framework_root = self._find_framework_root()
         self.deployment_targets = {
             'framework': self.framework_root / 'INSTRUCTIONS.md' if self.framework_root else None,
-            'user': Path.home() / '.claude-pm' / 'INSTRUCTIONS.md',
+            'user': ConfigPaths.get_user_config_dir() / 'INSTRUCTIONS.md',
             'project': Path.cwd() / 'INSTRUCTIONS.md'
         }
         
@@ -353,7 +355,7 @@ class FrameworkClaudeMdGenerator:
         version_locations = [
             Path(__file__).parent.parent / 'framework' / 'VERSION',
             Path.cwd() / 'framework' / 'VERSION',
-            Path.home() / '.claude-pm' / 'VERSION'
+            ConfigPaths.get_user_config_dir() / 'VERSION'
         ]
         
         for version_file in version_locations:

claude_mpm/services/memory/__init__.py

@@ -0,0 +1,17 @@
+"""Memory services for Claude MPM.
+
+This module provides memory management services including:
+- Memory building and optimization
+- Memory routing to appropriate agents
+- Caching services for performance
+"""
+
+from .builder import MemoryBuilder
+from .router import MemoryRouter
+from .optimizer import MemoryOptimizer
+
+__all__ = [
+    "MemoryBuilder",
+    "MemoryRouter",
+    "MemoryOptimizer",
+]

claude_mpm/services/{memory_builder.py → memory/builder.py}

@@ -28,10 +28,10 @@ from pathlib import Path
 from typing import Dict, List, Optional, Any, Tuple
 from datetime import datetime
 
-from claude_mpm.core import LoggerMixin
+from claude_mpm.core.mixins import LoggerMixin
 from claude_mpm.core.config import Config
 from claude_mpm.utils.paths import PathResolver
-from claude_mpm.services.memory_router import MemoryRouter
+from claude_mpm.services.memory.router import MemoryRouter
 from claude_mpm.services.project_analyzer import ProjectAnalyzer
 
 
@@ -340,7 +340,7 @@ class MemoryBuilder(LoggerMixin):
             Dict containing update results
         """
         try:
-            from claude_mpm.services.agent_memory_manager import get_memory_manager
+            from claude_mpm.services.agents.memory import get_memory_manager
             memory_manager = get_memory_manager(self.config)
             
             result = {

claude_mpm/services/memory/cache/__init__.py

@@ -0,0 +1,14 @@
+"""Cache services for Claude MPM memory system.
+
+This module provides caching services including:
+- Simple in-memory caching with TTL support
+- Shared prompt caching for agent prompts
+"""
+
+from .simple_cache import SimpleCacheService
+from .shared_prompt_cache import SharedPromptCache
+
+__all__ = [
+    "SimpleCacheService",
+    "SharedPromptCache",
+]

claude_mpm/services/{shared_prompt_cache.py → memory/cache/shared_prompt_cache.py}

@@ -51,7 +51,7 @@ from pathlib import Path
 from threading import RLock
 from typing import Any, Dict, List, Optional, Set, Tuple, Union
 
-from ..core.base_service import BaseService, ServiceHealth, ServiceMetrics
+from claude_mpm.core.base_service import BaseService, ServiceHealth, ServiceMetrics
 
 
 @dataclass