claude-mpm 3.3.2__py3-none-any.whl → 3.4.2__py3-none-any.whl

claude_mpm/services/agent_memory_manager.py

@@ -23,14 +23,16 @@ from typing import Dict, List, Optional, Any
 from datetime import datetime
 import re
 import logging
+import os
 
-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.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 +62,50 @@ 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 current working directory.
         """
-        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.memories_dir = self.project_root / ".claude-mpm" / "memories"
+        # Use current working directory by default, not project root
+        self.working_directory = working_directory or Path(os.getcwd())
+        self.memories_dir = self.working_directory / ".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 +115,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', {})
@@ -238,68 +268,80 @@ class AgentMemoryManager(LoggerMixin):
         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)}
 
-## Effective Strategies (Max: 15 items)
+## Domain-Specific Knowledge
+<!-- Agent-specific knowledge for {project_characteristics.project_name} domain -->
+{self._generate_domain_knowledge_starters(project_characteristics, agent_id)}
+
+## 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 -->
 """
         
@@ -307,14 +349,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}")
+            self.logger.info(f"Created project-specific memory file for {agent_id}")
             
-            # Socket.IO notifications removed - memory manager works independently
         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.
         
@@ -373,9 +714,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}")
         
@@ -418,7 +760,7 @@ class AgentMemoryManager(LoggerMixin):
         # Insert new section
         new_section = [
             '',
-            f'## {section} (Max: 15 items)',
+            f'## {section}',
             f'- {new_item}',
             ''
         ]
@@ -558,7 +900,7 @@ class AgentMemoryManager(LoggerMixin):
             for section in missing_sections:
                 section_content = [
                     '',
-                    f'## {section} (Max: 15 items)',
+                    f'## {section}',
                     '<!-- Section added by repair -->',
                     ''
                 ]
@@ -605,7 +947,7 @@ class AgentMemoryManager(LoggerMixin):
         """
         try:
             from claude_mpm.services.memory_optimizer import MemoryOptimizer
-            optimizer = MemoryOptimizer(self.config)
+            optimizer = MemoryOptimizer(self.config, self.working_directory)
             
             if agent_id:
                 result = optimizer.optimize_agent_memory(agent_id)
@@ -633,7 +975,7 @@ class AgentMemoryManager(LoggerMixin):
         """
         try:
             from claude_mpm.services.memory_builder import MemoryBuilder
-            builder = MemoryBuilder(self.config)
+            builder = MemoryBuilder(self.config, self.working_directory)
             
             result = builder.build_from_documentation(force_rebuild)
             self.logger.info("Built memories from documentation")
@@ -850,6 +1192,153 @@ class AgentMemoryManager(LoggerMixin):
             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.
         
@@ -908,7 +1397,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
@@ -916,10 +1405,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