claude-mpm 3.3.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

claude_mpm/services/agent_memory_manager.py

@@ -24,13 +24,14 @@ from datetime import datetime
 import re
 import logging
 
-from claude_mpm.core import LoggerMixin
 from claude_mpm.core.config import Config
+from claude_mpm.core.mixins import LoggerMixin
 from claude_mpm.utils.paths import PathResolver
-from claude_mpm.services.websocket_server import get_websocket_server
+from claude_mpm.services.project_analyzer import ProjectAnalyzer
+# Socket.IO notifications are optional - we'll skip them if server is not available
 
 
-class AgentMemoryManager(LoggerMixin):
+class AgentMemoryManager:
     """Manages agent memory files with size limits and validation.
     
     WHY: Agents need to accumulate project-specific knowledge over time to become
@@ -60,22 +61,49 @@ class AgentMemoryManager(LoggerMixin):
         'Current Technical Context'
     ]
     
-    def __init__(self, config: Optional[Config] = None):
+    def __init__(self, config: Optional[Config] = None, working_directory: Optional[Path] = None):
         """Initialize the memory manager.
         
         Sets up the memories directory and ensures it exists with proper README.
         
         Args:
             config: Optional Config object. If not provided, will create default Config.
+            working_directory: Optional working directory. If not provided, uses project root.
         """
-        super().__init__()
+        # Initialize logger using the same pattern as LoggerMixin
+        self._logger_instance = None
+        self._logger_name = None
+        
         self.config = config or Config()
         self.project_root = PathResolver.get_project_root()
+        self.working_directory = working_directory or self.project_root
         self.memories_dir = self.project_root / ".claude-mpm" / "memories"
         self._ensure_memories_directory()
         
         # Initialize memory limits from configuration
         self._init_memory_limits()
+        
+        # Initialize project analyzer for context-aware memory creation
+        self.project_analyzer = ProjectAnalyzer(self.config, self.working_directory)
+    
+    @property
+    def logger(self):
+        """Get or create the logger instance (like LoggerMixin)."""
+        if self._logger_instance is None:
+            if self._logger_name:
+                logger_name = self._logger_name
+            else:
+                module = self.__class__.__module__
+                class_name = self.__class__.__name__
+                
+                if module and module != "__main__":
+                    logger_name = f"{module}.{class_name}"
+                else:
+                    logger_name = class_name
+                    
+            self._logger_instance = logging.getLogger(logger_name)
+            
+        return self._logger_instance
     
     def _init_memory_limits(self):
         """Initialize memory limits from configuration.
@@ -85,7 +113,7 @@ class AgentMemoryManager(LoggerMixin):
         """
         # Check if memory system is enabled
         self.memory_enabled = self.config.get('memory.enabled', True)
-        self.auto_learning = self.config.get('memory.auto_learning', False)
+        self.auto_learning = self.config.get('memory.auto_learning', True)  # Changed default to True
         
         # Load default limits from configuration
         config_limits = self.config.get('memory.limits', {})
@@ -164,15 +192,7 @@ class AgentMemoryManager(LoggerMixin):
         try:
             content = memory_file.read_text(encoding='utf-8')
             
-            # Emit WebSocket event for memory loaded
-            try:
-                ws_server = get_websocket_server()
-                file_size = len(content.encode('utf-8'))
-                # Count sections by looking for lines starting with ##
-                sections_count = sum(1 for line in content.split('\n') if line.startswith('## '))
-                ws_server.memory_loaded(agent_id, file_size, sections_count)
-            except Exception as ws_error:
-                self.logger.debug(f"WebSocket notification failed: {ws_error}")
+            # Socket.IO notifications removed - memory manager works independently
             
             return self._validate_and_repair(content, agent_id)
         except Exception as e:
@@ -241,79 +261,85 @@ class AgentMemoryManager(LoggerMixin):
         section = section_mapping.get(learning_type, 'Recent Learnings')
         success = self.update_agent_memory(agent_id, section, content)
         
-        # Emit WebSocket event for memory updated
-        if success:
-            try:
-                ws_server = get_websocket_server()
-                ws_server.memory_updated(agent_id, learning_type, content, section)
-            except Exception as ws_error:
-                self.logger.debug(f"WebSocket notification failed: {ws_error}")
+        # Socket.IO notifications removed - memory manager works independently
         
         return success
     
     def _create_default_memory(self, agent_id: str) -> str:
-        """Create default memory file for agent.
+        """Create project-specific default memory file for agent.
         
-        WHY: New agents need a starting template with essential project knowledge
-        and the correct structure for adding new learnings.
+        WHY: Instead of generic templates, agents need project-specific knowledge
+        from the start. This analyzes the current project and creates contextual
+        memories with actual project characteristics.
         
         Args:
             agent_id: The agent identifier
             
         Returns:
-            str: The default memory template content
+            str: The project-specific memory template content
         """
         # Convert agent_id to proper name, handling cases like "test_agent" -> "Test"
         agent_name = agent_id.replace('_agent', '').replace('_', ' ').title()
-        project_name = self.project_root.name
         timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
         
         # Get limits for this agent
         limits = self._get_agent_limits(agent_id)
         
-        template = f"""# {agent_name} Agent Memory - {project_name}
+        # Analyze the project for context-specific content
+        try:
+            project_characteristics = self.project_analyzer.analyze_project()
+            project_context = self.project_analyzer.get_project_context_summary()
+            important_files = self.project_analyzer.get_important_files_for_context()
+            
+            self.logger.info(f"Creating project-specific memory for {agent_id} using analyzed project context")
+        except Exception as e:
+            self.logger.warning(f"Error analyzing project for {agent_id}, falling back to basic template: {e}")
+            return self._create_basic_memory_template(agent_id)
+        
+        # Create project-specific sections
+        architecture_items = self._generate_architecture_section(project_characteristics)
+        coding_patterns = self._generate_coding_patterns_section(project_characteristics)
+        implementation_guidelines = self._generate_implementation_guidelines(project_characteristics)
+        tech_context = self._generate_technical_context(project_characteristics)
+        integration_points = self._generate_integration_points(project_characteristics)
+        
+        template = f"""# {agent_name} Agent Memory - {project_characteristics.project_name}
 
 <!-- MEMORY LIMITS: {limits['max_file_size_kb']}KB max | {limits['max_sections']} sections max | {limits['max_items_per_section']} items per section -->
 <!-- Last Updated: {timestamp} | Auto-updated by: {agent_id} -->
 
-## Project Architecture (Max: 15 items)
-- Service-oriented architecture with clear module boundaries
-- Three-tier agent hierarchy: project → user → system
-- Agent definitions use standardized JSON schema validation
+## Project Context
+{project_context}
 
-## Coding Patterns Learned (Max: 15 items)
-- Always use PathResolver for path operations, never hardcode paths
-- SubprocessRunner utility for external command execution
-- LoggerMixin provides consistent logging across all services
+## Project Architecture
+{self._format_section_items(architecture_items)}
 
-## Implementation Guidelines (Max: 15 items)
-- Check docs/STRUCTURE.md before creating new files
-- Follow existing import patterns: from claude_mpm.module import Class
-- Use existing utilities instead of reimplementing functionality
+## Coding Patterns Learned
+{self._format_section_items(coding_patterns)}
 
-## Domain-Specific Knowledge (Max: 15 items)
-<!-- Agent-specific knowledge accumulates here -->
+## Implementation Guidelines
+{self._format_section_items(implementation_guidelines)}
+
+## Domain-Specific Knowledge
+<!-- Agent-specific knowledge for {project_characteristics.project_name} domain -->
+{self._generate_domain_knowledge_starters(project_characteristics, agent_id)}
 
-## Effective Strategies (Max: 15 items)
+## Effective Strategies
 <!-- Successful approaches discovered through experience -->
 
-## Common Mistakes to Avoid (Max: 15 items)
-- Don't modify Claude Code core functionality, only extend it
-- Avoid duplicating code - check utils/ for existing implementations
-- Never hardcode file paths, use PathResolver utilities
+## Common Mistakes to Avoid
+{self._format_section_items(self._generate_common_mistakes(project_characteristics))}
 
-## Integration Points (Max: 15 items)
-<!-- Key interfaces and integration patterns -->
+## Integration Points
+{self._format_section_items(integration_points)}
 
-## Performance Considerations (Max: 15 items)
-<!-- Performance insights and optimization patterns -->
+## Performance Considerations
+{self._format_section_items(self._generate_performance_considerations(project_characteristics))}
 
-## Current Technical Context (Max: 15 items)
-- EP-0001: Technical debt reduction in progress
-- Target: 80% test coverage (current: 23.6%)
-- Integration with Claude Code 1.0.60+ native agent framework
+## Current Technical Context
+{self._format_section_items(tech_context)}
 
-## Recent Learnings (Max: 15 items)
+## Recent Learnings
 <!-- Most recent discoveries and insights -->
 """
         
@@ -321,19 +347,313 @@ class AgentMemoryManager(LoggerMixin):
         try:
             memory_file = self.memories_dir / f"{agent_id}_agent.md"
             memory_file.write_text(template, encoding='utf-8')
-            self.logger.info(f"Created default memory file for {agent_id}")
-            
-            # Emit WebSocket event for memory created
-            try:
-                ws_server = get_websocket_server()
-                ws_server.memory_created(agent_id, "default")
-            except Exception as ws_error:
-                self.logger.debug(f"WebSocket notification failed: {ws_error}")
+            self.logger.info(f"Created project-specific memory file for {agent_id}")
+            
         except Exception as e:
             self.logger.error(f"Error saving default memory for {agent_id}: {e}")
         
         return template
     
+    def _create_basic_memory_template(self, agent_id: str) -> str:
+        """Create basic memory template when project analysis fails.
+        
+        WHY: Fallback template ensures agents always get some memory structure
+        even if project analysis encounters errors.
+        
+        Args:
+            agent_id: The agent identifier
+            
+        Returns:
+            str: Basic memory template
+        """
+        agent_name = agent_id.replace('_agent', '').replace('_', ' ').title()
+        project_name = self.project_root.name
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        limits = self._get_agent_limits(agent_id)
+        
+        return f"""# {agent_name} Agent Memory - {project_name}
+
+<!-- MEMORY LIMITS: {limits['max_file_size_kb']}KB max | {limits['max_sections']} sections max | {limits['max_items_per_section']} items per section -->
+<!-- Last Updated: {timestamp} | Auto-updated by: {agent_id} -->
+
+## Project Context
+{project_name}: Software project requiring analysis
+
+## Project Architecture
+- Analyze project structure to understand architecture patterns
+
+## Coding Patterns Learned
+- Observe codebase patterns and conventions during tasks
+
+## Implementation Guidelines
+- Extract implementation guidelines from project documentation
+
+## Domain-Specific Knowledge
+<!-- Agent-specific knowledge accumulates here -->
+
+## Effective Strategies
+<!-- Successful approaches discovered through experience -->
+
+## Common Mistakes to Avoid
+- Learn from errors encountered during project work
+
+## Integration Points
+<!-- Key interfaces and integration patterns -->
+
+## Performance Considerations
+<!-- Performance insights and optimization patterns -->
+
+## Current Technical Context
+- Project analysis pending - gather context during tasks
+
+## Recent Learnings
+<!-- Most recent discoveries and insights -->
+"""
+    
+    def _generate_architecture_section(self, characteristics) -> List[str]:
+        """Generate architecture section items based on project analysis."""
+        items = []
+        
+        # Architecture type
+        items.append(f"{characteristics.architecture_type} with {characteristics.primary_language or 'mixed'} implementation")
+        
+        # Key directories structure
+        if characteristics.key_directories:
+            key_dirs = ", ".join(characteristics.key_directories[:5])
+            items.append(f"Main directories: {key_dirs}")
+        
+        # Main modules
+        if characteristics.main_modules:
+            modules = ", ".join(characteristics.main_modules[:4])
+            items.append(f"Core modules: {modules}")
+        
+        # Entry points
+        if characteristics.entry_points:
+            entries = ", ".join(characteristics.entry_points[:3])
+            items.append(f"Entry points: {entries}")
+        
+        # Frameworks affecting architecture
+        if characteristics.web_frameworks:
+            frameworks = ", ".join(characteristics.web_frameworks[:3])
+            items.append(f"Web framework stack: {frameworks}")
+        
+        return items[:8]  # Limit to prevent overwhelming
+    
+    def _generate_coding_patterns_section(self, characteristics) -> List[str]:
+        """Generate coding patterns section based on project analysis."""
+        items = []
+        
+        # Language-specific patterns
+        if characteristics.primary_language == 'python':
+            items.append("Python project: use type hints, follow PEP 8 conventions")
+            if 'django' in [fw.lower() for fw in characteristics.web_frameworks]:
+                items.append("Django patterns: models, views, templates separation")
+            elif 'flask' in [fw.lower() for fw in characteristics.web_frameworks]:
+                items.append("Flask patterns: blueprint organization, app factory pattern")
+        elif characteristics.primary_language == 'node_js':
+            items.append("Node.js project: use async/await, ES6+ features")
+            if 'express' in [fw.lower() for fw in characteristics.web_frameworks]:
+                items.append("Express patterns: middleware usage, route organization")
+        
+        # Framework-specific patterns
+        for framework in characteristics.frameworks[:3]:
+            if 'react' in framework.lower():
+                items.append("React patterns: component composition, hooks usage")
+            elif 'vue' in framework.lower():
+                items.append("Vue patterns: single file components, composition API")
+        
+        # Code conventions found
+        for convention in characteristics.code_conventions[:3]:
+            items.append(f"Project uses: {convention}")
+        
+        return items[:8]
+    
+    def _generate_implementation_guidelines(self, characteristics) -> List[str]:
+        """Generate implementation guidelines based on project analysis."""
+        items = []
+        
+        # Package manager guidance
+        if characteristics.package_manager:
+            items.append(f"Use {characteristics.package_manager} for dependency management")
+        
+        # Testing guidelines
+        if characteristics.testing_framework:
+            items.append(f"Write tests using {characteristics.testing_framework}")
+        
+        # Test patterns
+        for pattern in characteristics.test_patterns[:2]:
+            items.append(f"Follow {pattern.lower()}")
+        
+        # Build tools
+        if characteristics.build_tools:
+            tools = ", ".join(characteristics.build_tools[:2])
+            items.append(f"Use build tools: {tools}")
+        
+        # Configuration patterns
+        for config_pattern in characteristics.configuration_patterns[:2]:
+            items.append(f"Configuration: {config_pattern}")
+        
+        # Important files to reference
+        important_configs = characteristics.important_configs[:3]
+        if important_configs:
+            configs = ", ".join(important_configs)
+            items.append(f"Key config files: {configs}")
+        
+        return items[:8]
+    
+    def _generate_technical_context(self, characteristics) -> List[str]:
+        """Generate current technical context based on project analysis."""
+        items = []
+        
+        # Technology stack summary
+        tech_stack = []
+        if characteristics.primary_language:
+            tech_stack.append(characteristics.primary_language)
+        tech_stack.extend(characteristics.frameworks[:2])
+        if tech_stack:
+            items.append(f"Tech stack: {', '.join(tech_stack)}")
+        
+        # Databases in use
+        if characteristics.databases:
+            dbs = ", ".join(characteristics.databases[:3])
+            items.append(f"Data storage: {dbs}")
+        
+        # API patterns
+        if characteristics.api_patterns:
+            apis = ", ".join(characteristics.api_patterns[:2])
+            items.append(f"API patterns: {apis}")
+        
+        # Key dependencies
+        if characteristics.key_dependencies:
+            deps = ", ".join(characteristics.key_dependencies[:4])
+            items.append(f"Key dependencies: {deps}")
+        
+        # Documentation available
+        if characteristics.documentation_files:
+            docs = ", ".join(characteristics.documentation_files[:3])
+            items.append(f"Documentation: {docs}")
+        
+        return items[:8]
+    
+    def _generate_integration_points(self, characteristics) -> List[str]:
+        """Generate integration points based on project analysis."""
+        items = []
+        
+        # Database integrations
+        for db in characteristics.databases[:3]:
+            items.append(f"{db.title()} database integration")
+        
+        # Web framework integrations
+        for framework in characteristics.web_frameworks[:2]:
+            items.append(f"{framework} web framework integration")
+        
+        # API integrations
+        for api_pattern in characteristics.api_patterns[:2]:
+            items.append(f"{api_pattern} integration pattern")
+        
+        # Common integration patterns based on dependencies
+        integration_deps = [dep for dep in characteristics.key_dependencies 
+                          if any(keyword in dep.lower() for keyword in ['redis', 'rabbit', 'celery', 'kafka', 'docker'])]
+        for dep in integration_deps[:3]:
+            items.append(f"{dep} integration")
+        
+        return items[:6]
+    
+    def _generate_common_mistakes(self, characteristics) -> List[str]:
+        """Generate common mistakes based on project type and stack."""
+        items = []
+        
+        # Language-specific mistakes
+        if characteristics.primary_language == 'python':
+            items.append("Avoid circular imports - use late imports when needed")
+            items.append("Don't ignore virtual environment - always activate before work")
+        elif characteristics.primary_language == 'node_js':
+            items.append("Avoid callback hell - use async/await consistently")
+            items.append("Don't commit node_modules - ensure .gitignore is correct")
+        
+        # Framework-specific mistakes
+        if 'django' in [fw.lower() for fw in characteristics.web_frameworks]:
+            items.append("Don't skip migrations - always create and apply them")
+        elif 'flask' in [fw.lower() for fw in characteristics.web_frameworks]:
+            items.append("Avoid app context issues - use proper application factory")
+        
+        # Database-specific mistakes
+        if characteristics.databases:
+            items.append("Don't ignore database transactions in multi-step operations")
+            items.append("Avoid N+1 queries - use proper joins or prefetching")
+        
+        # Testing mistakes
+        if characteristics.testing_framework:
+            items.append("Don't skip test isolation - ensure tests can run independently")
+        
+        return items[:8]
+    
+    def _generate_performance_considerations(self, characteristics) -> List[str]:
+        """Generate performance considerations based on project stack."""
+        items = []
+        
+        # Language-specific performance
+        if characteristics.primary_language == 'python':
+            items.append("Use list comprehensions over loops where appropriate")
+            items.append("Consider caching for expensive operations")
+        elif characteristics.primary_language == 'node_js':
+            items.append("Leverage event loop - avoid blocking operations")
+            items.append("Use streams for large data processing")
+        
+        # Database performance
+        if characteristics.databases:
+            items.append("Index frequently queried columns")
+            items.append("Use connection pooling for database connections")
+        
+        # Web framework performance
+        if characteristics.web_frameworks:
+            items.append("Implement appropriate caching strategies")
+            items.append("Optimize static asset delivery")
+        
+        # Framework-specific performance
+        if 'react' in [fw.lower() for fw in characteristics.frameworks]:
+            items.append("Use React.memo for expensive component renders")
+        
+        return items[:6]
+    
+    def _generate_domain_knowledge_starters(self, characteristics, agent_id: str) -> str:
+        """Generate domain-specific knowledge starters based on project and agent type."""
+        items = []
+        
+        # Project terminology
+        if characteristics.project_terminology:
+            terms = ", ".join(characteristics.project_terminology[:4])
+            items.append(f"- Key project terms: {terms}")
+        
+        # Agent-specific starters
+        if 'research' in agent_id.lower():
+            items.append("- Focus on code analysis, pattern discovery, and architectural insights")
+            if characteristics.documentation_files:
+                items.append("- Prioritize documentation analysis for comprehensive understanding")
+        elif 'engineer' in agent_id.lower():
+            items.append("- Focus on implementation patterns, coding standards, and best practices")
+            if characteristics.testing_framework:
+                items.append(f"- Ensure test coverage using {characteristics.testing_framework}")
+        elif 'pm' in agent_id.lower() or 'manager' in agent_id.lower():
+            items.append("- Focus on project coordination, task delegation, and progress tracking")
+            items.append("- Monitor integration points and cross-component dependencies")
+        
+        return '\n'.join(items) if items else "<!-- Domain knowledge will accumulate here -->"
+    
+    def _format_section_items(self, items: List[str]) -> str:
+        """Format list of items as markdown bullet points."""
+        if not items:
+            return "<!-- Items will be added as knowledge accumulates -->"
+        
+        formatted_items = []
+        for item in items:
+            # Ensure each item starts with a dash and is properly formatted
+            if not item.startswith('- '):
+                item = f"- {item}"
+            formatted_items.append(item)
+        
+        return '\n'.join(formatted_items)
+    
     def _add_item_to_section(self, content: str, section: str, new_item: str) -> str:
         """Add item to specified section, respecting limits.
         
@@ -392,9 +712,10 @@ class AgentMemoryManager(LoggerMixin):
         ):
             insert_point += 1
         
-        # Ensure line length limit
-        if len(new_item) > self.memory_limits['max_line_length']:
-            new_item = new_item[:self.memory_limits['max_line_length'] - 3] + '...'
+        # Ensure line length limit (account for "- " prefix)
+        max_item_length = self.memory_limits['max_line_length'] - 2  # Subtract 2 for "- " prefix
+        if len(new_item) > max_item_length:
+            new_item = new_item[:max_item_length - 3] + '...'
         
         lines.insert(insert_point, f"- {new_item}")
         
@@ -437,7 +758,7 @@ class AgentMemoryManager(LoggerMixin):
         # Insert new section
         new_section = [
             '',
-            f'## {section} (Max: 15 items)',
+            f'## {section}',
             f'- {new_item}',
             ''
         ]
@@ -577,7 +898,7 @@ class AgentMemoryManager(LoggerMixin):
             for section in missing_sections:
                 section_content = [
                     '',
-                    f'## {section} (Max: 15 items)',
+                    f'## {section}',
                     '<!-- Section added by repair -->',
                     ''
                 ]
@@ -609,6 +930,413 @@ class AgentMemoryManager(LoggerMixin):
             self.logger.error(f"Error saving memory for {agent_id}: {e}")
             return False
     
+    def optimize_memory(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
+        """Optimize agent memory by consolidating/cleaning memories.
+        
+        WHY: Over time, memory files accumulate redundant or outdated information.
+        This method delegates to the memory optimizer service to clean up and
+        consolidate memories while preserving important information.
+        
+        Args:
+            agent_id: Optional specific agent ID. If None, optimizes all agents.
+            
+        Returns:
+            Dict containing optimization results and statistics
+        """
+        try:
+            from claude_mpm.services.memory_optimizer import MemoryOptimizer
+            optimizer = MemoryOptimizer(self.config)
+            
+            if agent_id:
+                result = optimizer.optimize_agent_memory(agent_id)
+                self.logger.info(f"Optimized memory for agent: {agent_id}")
+            else:
+                result = optimizer.optimize_all_memories()
+                self.logger.info("Optimized all agent memories")
+            
+            return result
+        except Exception as e:
+            self.logger.error(f"Error optimizing memory: {e}")
+            return {"success": False, "error": str(e)}
+    
+    def build_memories_from_docs(self, force_rebuild: bool = False) -> Dict[str, Any]:
+        """Build agent memories from project documentation.
+        
+        WHY: Project documentation contains valuable knowledge that should be
+        extracted and assigned to appropriate agents for better context awareness.
+        
+        Args:
+            force_rebuild: If True, rebuilds even if docs haven't changed
+            
+        Returns:
+            Dict containing build results and statistics
+        """
+        try:
+            from claude_mpm.services.memory_builder import MemoryBuilder
+            builder = MemoryBuilder(self.config)
+            
+            result = builder.build_from_documentation(force_rebuild)
+            self.logger.info("Built memories from documentation")
+            
+            return result
+        except Exception as e:
+            self.logger.error(f"Error building memories from docs: {e}")
+            return {"success": False, "error": str(e)}
+    
+    def route_memory_command(self, content: str, context: Optional[Dict] = None) -> Dict[str, Any]:
+        """Route memory command to appropriate agent via PM delegation.
+        
+        WHY: Memory commands like "remember this for next time" need to be analyzed
+        to determine which agent should store the information. This method provides
+        routing logic for PM agent delegation.
+        
+        Args:
+            content: The content to be remembered
+            context: Optional context for routing decisions
+            
+        Returns:
+            Dict containing routing decision and reasoning
+        """
+        try:
+            from claude_mpm.services.memory_router import MemoryRouter
+            router = MemoryRouter(self.config)
+            
+            routing_result = router.analyze_and_route(content, context)
+            self.logger.debug(f"Routed memory command: {routing_result['target_agent']}")
+            
+            return routing_result
+        except Exception as e:
+            self.logger.error(f"Error routing memory command: {e}")
+            return {"success": False, "error": str(e)}
+    
+    def get_memory_status(self) -> Dict[str, Any]:
+        """Get comprehensive memory system status.
+        
+        WHY: Provides detailed overview of memory system health, file sizes,
+        optimization opportunities, and agent-specific statistics for monitoring
+        and maintenance purposes.
+        
+        Returns:
+            Dict containing comprehensive memory system status
+        """
+        try:
+            status = {
+                "system_enabled": self.memory_enabled,
+                "auto_learning": self.auto_learning,
+                "memory_directory": str(self.memories_dir),
+                "total_agents": 0,
+                "total_size_kb": 0,
+                "agents": {},
+                "optimization_opportunities": [],
+                "system_health": "healthy"
+            }
+            
+            if not self.memories_dir.exists():
+                status["system_health"] = "no_memory_dir"
+                return status
+            
+            memory_files = list(self.memories_dir.glob("*_agent.md"))
+            status["total_agents"] = len(memory_files)
+            
+            total_size = 0
+            for file_path in memory_files:
+                stat = file_path.stat()
+                size_kb = stat.st_size / 1024
+                total_size += stat.st_size
+                
+                agent_id = file_path.stem.replace('_agent', '')
+                limits = self._get_agent_limits(agent_id)
+                
+                # Analyze file content
+                try:
+                    content = file_path.read_text()
+                    section_count = len([line for line in content.splitlines() if line.startswith('## ')])
+                    learning_count = len([line for line in content.splitlines() if line.strip().startswith('- ')])
+                    
+                    agent_status = {
+                        "size_kb": round(size_kb, 2),
+                        "size_limit_kb": limits['max_file_size_kb'],
+                        "size_utilization": min(100, round((size_kb / limits['max_file_size_kb']) * 100, 1)),
+                        "sections": section_count,
+                        "items": learning_count,
+                        "last_modified": datetime.fromtimestamp(stat.st_mtime).isoformat(),
+                        "auto_learning": self._get_agent_auto_learning(agent_id)
+                    }
+                    
+                    # Check for optimization opportunities
+                    if size_kb > limits['max_file_size_kb'] * 0.8:
+                        status["optimization_opportunities"].append(f"{agent_id}: High memory usage ({size_kb:.1f}KB)")
+                    
+                    if section_count > limits['max_sections'] * 0.8:
+                        status["optimization_opportunities"].append(f"{agent_id}: Many sections ({section_count})")
+                    
+                    status["agents"][agent_id] = agent_status
+                    
+                except Exception as e:
+                    status["agents"][agent_id] = {"error": str(e)}
+            
+            status["total_size_kb"] = round(total_size / 1024, 2)
+            
+            # Determine overall system health
+            if len(status["optimization_opportunities"]) > 3:
+                status["system_health"] = "needs_optimization"
+            elif status["total_size_kb"] > 100:  # More than 100KB total
+                status["system_health"] = "high_usage"
+            
+            return status
+            
+        except Exception as e:
+            self.logger.error(f"Error getting memory status: {e}")
+            return {"success": False, "error": str(e)}
+    
+    def cross_reference_memories(self, query: Optional[str] = None) -> Dict[str, Any]:
+        """Find common patterns and cross-references across agent memories.
+        
+        WHY: Different agents may have learned similar or related information.
+        Cross-referencing helps identify knowledge gaps, redundancies, and
+        opportunities for knowledge sharing between agents.
+        
+        Args:
+            query: Optional query to filter cross-references
+            
+        Returns:
+            Dict containing cross-reference analysis results
+        """
+        try:
+            cross_refs = {
+                "common_patterns": [],
+                "knowledge_gaps": [],
+                "redundancies": [],
+                "agent_correlations": {},
+                "query_matches": [] if query else None
+            }
+            
+            if not self.memories_dir.exists():
+                return cross_refs
+            
+            memory_files = list(self.memories_dir.glob("*_agent.md"))
+            agent_memories = {}
+            
+            # Load all agent memories
+            for file_path in memory_files:
+                agent_id = file_path.stem.replace('_agent', '')
+                try:
+                    content = file_path.read_text()
+                    agent_memories[agent_id] = content
+                except Exception as e:
+                    self.logger.warning(f"Error reading memory for {agent_id}: {e}")
+                    continue
+            
+            # Find common patterns across agents
+            all_lines = []
+            agent_lines = {}
+            
+            for agent_id, content in agent_memories.items():
+                lines = [line.strip() for line in content.splitlines() 
+                        if line.strip().startswith('- ')]
+                agent_lines[agent_id] = lines
+                all_lines.extend([(line, agent_id) for line in lines])
+            
+            # Look for similar content (basic similarity check)
+            line_counts = {}
+            for line, agent_id in all_lines:
+                # Normalize line for comparison
+                normalized = line.lower().replace('- ', '').strip()
+                if len(normalized) > 20:  # Only check substantial lines
+                    if normalized not in line_counts:
+                        line_counts[normalized] = []
+                    line_counts[normalized].append(agent_id)
+            
+            # Find patterns appearing in multiple agents
+            for line, agents in line_counts.items():
+                if len(set(agents)) > 1:  # Appears in multiple agents
+                    cross_refs["common_patterns"].append({
+                        "pattern": line[:100] + "..." if len(line) > 100 else line,
+                        "agents": list(set(agents)),
+                        "count": len(agents)
+                    })
+            
+            # Query-specific matches
+            if query:
+                query_lower = query.lower()
+                for agent_id, content in agent_memories.items():
+                    matches = []
+                    for line in content.splitlines():
+                        if query_lower in line.lower():
+                            matches.append(line.strip())
+                    
+                    if matches:
+                        cross_refs["query_matches"].append({
+                            "agent": agent_id,
+                            "matches": matches[:5]  # Limit to first 5 matches
+                        })
+            
+            # Calculate agent correlations (agents with similar knowledge domains)
+            for agent_a in agent_memories:
+                for agent_b in agent_memories:
+                    if agent_a < agent_b:  # Avoid duplicates
+                        common_count = len([
+                            line for line in line_counts.values()
+                            if agent_a in line and agent_b in line
+                        ])
+                        
+                        if common_count > 0:
+                            correlation_key = f"{agent_a}+{agent_b}"
+                            cross_refs["agent_correlations"][correlation_key] = common_count
+            
+            return cross_refs
+            
+        except Exception as e:
+            self.logger.error(f"Error cross-referencing memories: {e}")
+            return {"success": False, "error": str(e)}
+
+    def get_all_memories_raw(self) -> Dict[str, Any]:
+        """Get all agent memories in structured JSON format.
+        
+        WHY: This provides programmatic access to all agent memories, allowing
+        external tools, scripts, or APIs to retrieve and process the complete
+        memory state of the system.
+        
+        DESIGN DECISION: Returns structured data with metadata for each agent
+        including file stats, sections, and parsed content. This enables both
+        content access and system analysis.
+        
+        Returns:
+            Dict containing structured memory data for all agents
+        """
+        try:
+            result = {
+                "success": True,
+                "timestamp": datetime.now().isoformat(),
+                "total_agents": 0,
+                "total_size_bytes": 0,
+                "agents": {}
+            }
+            
+            # Ensure directory exists
+            if not self.memories_dir.exists():
+                return {
+                    "success": True,
+                    "timestamp": datetime.now().isoformat(),
+                    "total_agents": 0,
+                    "total_size_bytes": 0,
+                    "agents": {},
+                    "message": "No memory directory found"
+                }
+            
+            # Find all agent memory files
+            memory_files = list(self.memories_dir.glob("*_agent.md"))
+            result["total_agents"] = len(memory_files)
+            
+            # Process each agent memory file
+            for file_path in sorted(memory_files):
+                agent_id = file_path.stem.replace('_agent', '')
+                
+                try:
+                    # Get file stats
+                    stat = file_path.stat()
+                    file_size = stat.st_size
+                    result["total_size_bytes"] += file_size
+                    
+                    # Load and parse memory content
+                    memory_content = self.load_agent_memory(agent_id)
+                    
+                    if memory_content:
+                        sections = self._parse_memory_content_to_dict(memory_content)
+                        
+                        # Count total items across all sections
+                        total_items = sum(len(items) for items in sections.values())
+                        
+                        result["agents"][agent_id] = {
+                            "agent_id": agent_id,
+                            "file_path": str(file_path),
+                            "file_size_bytes": file_size,
+                            "file_size_kb": round(file_size / 1024, 2),
+                            "last_modified": datetime.fromtimestamp(stat.st_mtime).isoformat(),
+                            "sections_count": len(sections),
+                            "total_items": total_items,
+                            "auto_learning": self._get_agent_auto_learning(agent_id),
+                            "size_limits": self._get_agent_limits(agent_id),
+                            "sections": sections,
+                            "raw_content": memory_content
+                        }
+                    else:
+                        result["agents"][agent_id] = {
+                            "agent_id": agent_id,
+                            "file_path": str(file_path),
+                            "file_size_bytes": file_size,
+                            "file_size_kb": round(file_size / 1024, 2),
+                            "last_modified": datetime.fromtimestamp(stat.st_mtime).isoformat(),
+                            "error": "Could not load memory content",
+                            "sections": {},
+                            "raw_content": ""
+                        }
+                        
+                except Exception as e:
+                    self.logger.error(f"Error processing memory for agent {agent_id}: {e}")
+                    result["agents"][agent_id] = {
+                        "agent_id": agent_id,
+                        "file_path": str(file_path),
+                        "error": str(e),
+                        "sections": {},
+                        "raw_content": ""
+                    }
+            
+            result["total_size_kb"] = round(result["total_size_bytes"] / 1024, 2)
+            return result
+            
+        except Exception as e:
+            self.logger.error(f"Error getting all memories raw: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+                "timestamp": datetime.now().isoformat()
+            }
+
+    def _parse_memory_content_to_dict(self, content: str) -> Dict[str, List[str]]:
+        """Parse memory content into structured dictionary format.
+        
+        WHY: Provides consistent parsing of memory content into sections and items
+        for both display and programmatic access. This ensures the same parsing
+        logic is used across the system.
+        
+        Args:
+            content: Raw memory file content
+            
+        Returns:
+            Dict mapping section names to lists of items
+        """
+        sections = {}
+        current_section = None
+        current_items = []
+        
+        for line in content.split('\n'):
+            line = line.strip()
+            
+            # Skip empty lines and header information
+            if not line or line.startswith('#') and 'Memory Usage' in line:
+                continue
+                
+            if line.startswith('## ') and not line.startswith('## Memory Usage'):
+                # New section found
+                if current_section and current_items:
+                    sections[current_section] = current_items.copy()
+                
+                current_section = line[3:].strip()
+                current_items = []
+                
+            elif line.startswith('- ') and current_section:
+                # Item in current section
+                item = line[2:].strip()
+                if item and len(item) > 3:  # Filter out very short items
+                    current_items.append(item)
+        
+        # Add final section
+        if current_section and current_items:
+            sections[current_section] = current_items
+        
+        return sections
+
     def _ensure_memories_directory(self):
         """Ensure memories directory exists with README.
         
@@ -667,7 +1395,7 @@ Standard markdown with structured sections. Agents expect:
 
 
 # Convenience functions for external use
-def get_memory_manager(config: Optional[Config] = None) -> AgentMemoryManager:
+def get_memory_manager(config: Optional[Config] = None, working_directory: Optional[Path] = None) -> AgentMemoryManager:
     """Get a singleton instance of the memory manager.
     
     WHY: The memory manager should be shared across the application to ensure
@@ -675,10 +1403,11 @@ def get_memory_manager(config: Optional[Config] = None) -> AgentMemoryManager:
     
     Args:
         config: Optional Config object. Only used on first instantiation.
+        working_directory: Optional working directory. Only used on first instantiation.
     
     Returns:
         AgentMemoryManager: The memory manager instance
     """
     if not hasattr(get_memory_manager, '_instance'):
-        get_memory_manager._instance = AgentMemoryManager(config)
+        get_memory_manager._instance = AgentMemoryManager(config, working_directory)
     return get_memory_manager._instance