claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/agents/memory/memory_categorization_service.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Memory Categorization Service - Categorizes learnings into appropriate sections."""
+
+from typing import List
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryCategorizationService:
+    """Service for categorizing memory learnings."""
+
+    # Category keywords for automatic categorization
+    CATEGORY_KEYWORDS = {
+        "Project Architecture": [
+            "architecture",
+            "structure",
+            "design",
+            "pattern",
+            "framework",
+            "component",
+            "module",
+            "service",
+            "interface",
+            "api",
+            "endpoint",
+            "schema",
+            "model",
+            "database",
+            "microservice",
+        ],
+        "Implementation Guidelines": [
+            "implement",
+            "code",
+            "function",
+            "method",
+            "class",
+            "algorithm",
+            "logic",
+            "process",
+            "workflow",
+            "feature",
+            "requirement",
+            "specification",
+            "standard",
+            "convention",
+            "practice",
+        ],
+        "Common Mistakes to Avoid": [
+            "mistake",
+            "error",
+            "bug",
+            "issue",
+            "problem",
+            "avoid",
+            "don't",
+            "never",
+            "warning",
+            "caution",
+            "gotcha",
+            "pitfall",
+            "trap",
+            "wrong",
+            "incorrect",
+        ],
+        "Current Technical Context": [
+            "current",
+            "status",
+            "context",
+            "environment",
+            "configuration",
+            "setup",
+            "version",
+            "dependency",
+            "tool",
+            "library",
+            "package",
+            "integration",
+            "deployment",
+            "infrastructure",
+            "state",
+        ],
+    }
+
+    def __init__(self):
+        """Initialize the categorization service."""
+
+    def categorize_learning(self, learning: str) -> str:
+        """Categorize a learning item based on its content.
+
+        WHY: Learnings are automatically organized into categories to make them
+        easier to find and review. This uses keyword matching to determine the
+        most appropriate category.
+
+        Args:
+            learning: The learning content to categorize
+
+        Returns:
+            Category name (defaults to "Current Technical Context")
+        """
+        if not learning:
+            return "Current Technical Context"
+
+        learning_lower = learning.lower()
+        category_scores = {}
+
+        # Score each category based on keyword matches
+        for category, keywords in self.CATEGORY_KEYWORDS.items():
+            score = sum(1 for keyword in keywords if keyword in learning_lower)
+            if score > 0:
+                category_scores[category] = score
+
+        # Return category with highest score, or default
+        if category_scores:
+            return max(category_scores, key=category_scores.get)
+
+        return "Current Technical Context"
+
+    def categorize_learnings_batch(self, learnings: List[str]) -> dict:
+        """Categorize multiple learnings at once.
+
+        Args:
+            learnings: List of learning items to categorize
+
+        Returns:
+            Dictionary mapping categories to lists of learnings
+        """
+        categorized = {}
+
+        for learning in learnings:
+            category = self.categorize_learning(learning)
+            if category not in categorized:
+                categorized[category] = []
+            categorized[category].append(learning)
+
+        return categorized
+
+    def merge_categorized_learnings(
+        self, existing: dict, new: dict, max_per_category: int = 15
+    ) -> dict:
+        """Merge new categorized learnings with existing ones.
+
+        Args:
+            existing: Existing categorized learnings
+            new: New categorized learnings to add
+            max_per_category: Maximum items per category
+
+        Returns:
+            Merged categorized learnings with limits applied
+        """
+        merged = existing.copy()
+
+        for category, items in new.items():
+            if category not in merged:
+                merged[category] = []
+
+            # Add new items, avoiding duplicates
+            for item in items:
+                if item not in merged[category]:
+                    merged[category].append(item)
+
+            # Apply limit (keep most recent)
+            if len(merged[category]) > max_per_category:
+                merged[category] = merged[category][-max_per_category:]
+
+        return merged

claude_mpm/services/agents/memory/memory_file_service.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Memory File Service - Handles file operations for agent memories."""
+
+from pathlib import Path
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryFileService:
+    """Service for handling memory file operations."""
+
+    def __init__(self, memories_dir: Path):
+        """Initialize the memory file service.
+
+        Args:
+            memories_dir: Directory where memory files are stored
+        """
+        self.memories_dir = memories_dir
+        self.logger = logger  # Use the module-level logger
+
+    def get_memory_file_with_migration(self, directory: Path, agent_id: str) -> Path:
+        """Get memory file path with migration support.
+
+        Migrates from old naming convention if needed.
+        Also handles hyphen to underscore conversion for agent IDs.
+
+        Args:
+            directory: Directory to check for memory file
+            agent_id: Agent identifier (may contain hyphens or underscores)
+
+        Returns:
+            Path to the memory file
+        """
+        # Normalize agent_id to use underscores (matching deployed agent names)
+        normalized_id = agent_id.replace("-", "_")
+
+        # Define possible file paths
+        new_file = directory / f"{normalized_id}_memories.md"
+        old_file = directory / f"{normalized_id}_memory.md"
+
+        # Also check for legacy hyphenated versions
+        hyphenated_file = (
+            directory / f"{agent_id}_memories.md" if "-" in agent_id else None
+        )
+
+        # Migration priority:
+        # 1. If hyphenated version exists and normalized doesn't, migrate it
+        if hyphenated_file and hyphenated_file.exists() and not new_file.exists():
+            try:
+                hyphenated_file.rename(new_file)
+                self.logger.info(
+                    f"Migrated hyphenated memory file: {hyphenated_file} -> {new_file}"
+                )
+            except Exception as e:
+                self.logger.warning(f"Could not migrate hyphenated memory file: {e}")
+                # Fall back to using the hyphenated version
+                return hyphenated_file
+
+        # 2. Migrate from old naming convention (_memory.md to _memories.md)
+        if old_file.exists() and not new_file.exists():
+            try:
+                old_file.rename(new_file)
+                self.logger.info(f"Migrated memory file: {old_file} -> {new_file}")
+            except Exception as e:
+                self.logger.warning(f"Could not migrate memory file: {e}")
+                return old_file
+
+        return new_file
+
+    def save_memory_file(self, file_path: Path, content: str) -> bool:
+        """Save content to a memory file.
+
+        Args:
+            file_path: Path to the memory file
+            content: Content to save
+
+        Returns:
+            True if saved successfully, False otherwise
+        """
+        try:
+            # Ensure directory exists
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write content
+            file_path.write_text(content)
+
+            self.logger.debug(f"Saved memory file: {file_path}")
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Failed to save memory file {file_path}: {e}")
+            return False
+
+    def ensure_memories_directory(self) -> None:
+        """Ensure the memories directory exists with README."""
+        try:
+            # Create directory if it doesn't exist
+            self.memories_dir.mkdir(parents=True, exist_ok=True)
+
+            # Create README if it doesn't exist
+            readme_path = self.memories_dir / "README.md"
+            if not readme_path.exists():
+                readme_content = """# Agent Memories Directory
+
+This directory contains memory files for various agents used in the project.
+
+## File Format
+
+Memory files follow the naming convention: `{agent_id}_memories.md`
+
+Each file contains:
+- Agent metadata (name, type, version)
+- Project-specific learnings organized by category
+- Timestamps for tracking updates
+
+## Auto-generated
+
+These files are managed automatically by the agent memory system.
+Manual edits should be done carefully to preserve the format.
+"""
+                readme_path.write_text(readme_content)
+                self.logger.debug(
+                    f"Created README in memories directory: {readme_path}"
+                )
+
+        except Exception as e:
+            self.logger.error(f"Failed to ensure memories directory: {e}")

claude_mpm/services/agents/memory/memory_format_service.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Memory Format Service - Handles memory content formatting and parsing."""
+
+import re
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryFormatService:
+    """Service for memory content formatting and parsing."""
+
+    def __init__(self):
+        """Initialize the memory format service."""
+
+    def build_simple_memory_content(self, agent_id: str, items: List[str]) -> str:
+        """Build memory content as a simple list with header and timestamp.
+
+        Args:
+            agent_id: Agent identifier for the header
+            items: List of memory items
+
+        Returns:
+            Formatted memory content string
+        """
+        # Build header
+        header = f"# {agent_id.title()} Agent Memory\n\n"
+        header += f"Last Updated: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+        header += "## Learnings\n\n"
+
+        # Build item list
+        item_lines = []
+        for item in items:
+            # Clean and format each item
+            item = item.strip()
+            if item and not item.startswith("- "):
+                item = f"- {item}"
+            if item:
+                item_lines.append(item)
+
+        # Combine
+        content = header + "\n".join(item_lines)
+        if item_lines:
+            content += "\n"
+
+        return content
+
+    def parse_memory_list(self, memory_content: str) -> List[str]:
+        """Parse memory content into a simple list.
+
+        Args:
+            memory_content: Raw memory content
+
+        Returns:
+            List of memory items (without "- " prefix)
+        """
+        items = []
+        lines = memory_content.split("\n")
+
+        for line in lines:
+            line = line.strip()
+            # Skip headers, empty lines, and metadata
+            if (
+                not line
+                or line.startswith(("#", "Last Updated:", "**"))
+                or line == "---"
+            ):
+                continue
+
+            # Extract list items
+            if line.startswith("- "):
+                item = line[2:].strip()
+                if item:
+                    items.append(item)
+            elif line and not any(
+                line.startswith(p) for p in ["#", "**", "Last Updated:", "---"]
+            ):
+                # Include non-list items that aren't headers
+                items.append(line)
+
+        return items
+
+    def parse_memory_sections(self, memory_content: str) -> Dict[str, List[str]]:
+        """Parse memory content into sections and items.
+
+        Args:
+            memory_content: Raw memory file content
+
+        Returns:
+            Dict mapping section names to lists of items
+        """
+        sections = {}
+        current_section = None
+        current_items = []
+
+        for line in memory_content.split("\n"):
+            # Check for section header (## Section Name)
+            if line.startswith("## "):
+                # Save previous section if exists
+                if current_section and current_items:
+                    sections[current_section] = current_items
+                # Start new section
+                current_section = line[3:].strip()
+                current_items = []
+            # Check for list item
+            elif line.startswith("- ") and current_section:
+                item = line[2:].strip()
+                if item:
+                    current_items.append(item)
+
+        # Save last section
+        if current_section and current_items:
+            sections[current_section] = current_items
+
+        return sections
+
+    def clean_template_placeholders(
+        self,
+        content: str,
+        preserve_structure: bool = False,
+        agent_id: str = "agent",
+    ) -> str:
+        """Clean template placeholders from memory content.
+
+        WHY: Default templates contain placeholder text that should be removed
+        when adding real memories. This method cleans those placeholders while
+        preserving any actual content.
+
+        Args:
+            content: Memory content to clean
+            preserve_structure: If True, preserve empty sections
+            agent_id: Agent ID for context
+
+        Returns:
+            Cleaned content string
+        """
+        if not content:
+            return content
+
+        # Patterns to remove
+        placeholder_patterns = [
+            r"\[Agent will add.*?\]",
+            r"\[No .* yet\]",
+            r"<!-- .* -->",
+            r"No items yet.*",
+            r"Memory items will be added.*",
+            r"\*\*Note:.*?\*\*",
+        ]
+
+        cleaned = content
+        for pattern in placeholder_patterns:
+            cleaned = re.sub(pattern, "", cleaned, flags=re.IGNORECASE | re.MULTILINE)
+
+        if not preserve_structure:
+            # Remove empty sections
+            lines = []
+            skip_empty = False
+            for line in cleaned.split("\n"):
+                if line.startswith("## "):
+                    skip_empty = True
+                    lines.append(line)
+                elif line.strip() and skip_empty:
+                    skip_empty = False
+                    lines.append(line)
+                elif not skip_empty:
+                    lines.append(line)
+
+            cleaned = "\n".join(lines)
+
+        # Clean up multiple blank lines
+        cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
+
+        return cleaned.strip()
+
+    def clean_template_placeholders_list(self, items: List[str]) -> List[str]:
+        """Clean template placeholders from a list of items.
+
+        Args:
+            items: List of items to clean
+
+        Returns:
+            Cleaned list of items
+        """
+        cleaned = []
+        for item in items:
+            # Skip placeholder items
+            if any(
+                pattern in item.lower()
+                for pattern in [
+                    "[agent will add",
+                    "[no ",
+                    "no items yet",
+                    "memory items will be added",
+                ]
+            ):
+                continue
+            cleaned.append(item)
+        return cleaned

claude_mpm/services/agents/memory/memory_limits_service.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Memory Limits Service - Manages memory size limits and configuration."""
+
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.config import Config
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryLimitsService:
+    """Service for managing memory limits and configuration."""
+
+    # Default limits
+    DEFAULT_MEMORY_LIMITS = {
+        "max_file_size_kb": 80,  # 80KB (20k tokens)
+        "max_items": 100,  # Maximum total memory items
+        "max_line_length": 120,
+    }
+
+    def __init__(self, config: Optional[Config] = None):
+        """Initialize the memory limits service.
+
+        Args:
+            config: Optional Config object for reading configuration
+        """
+        self.config = config or Config()
+        self.logger = logger  # Use the module-level logger
+        self.memory_limits = self._init_memory_limits()
+
+    def _init_memory_limits(self) -> Dict[str, Any]:
+        """Initialize memory limits from configuration.
+
+        Returns:
+            Dictionary of memory limits
+        """
+        try:
+            limits = self.DEFAULT_MEMORY_LIMITS.copy()
+
+            # Try to load from config
+            if hasattr(self.config, "agent_memory_limits"):
+                config_limits = self.config.agent_memory_limits
+                if isinstance(config_limits, dict):
+                    limits.update(config_limits)
+
+            self.logger.debug(f"Initialized memory limits: {limits}")
+            return limits
+
+        except Exception as e:
+            self.logger.warning(f"Failed to load memory limits from config: {e}")
+            return self.DEFAULT_MEMORY_LIMITS.copy()
+
+    def get_agent_limits(self, agent_id: str) -> Dict[str, Any]:
+        """Get memory limits for a specific agent.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            Dictionary of memory limits for the agent
+        """
+        # Start with default limits
+        limits = self.memory_limits.copy()
+
+        # Check for agent-specific overrides
+        try:
+            if hasattr(self.config, "agents") and agent_id in self.config.agents:
+                agent_config = self.config.agents[agent_id]
+                if "memory_limits" in agent_config:
+                    limits.update(agent_config["memory_limits"])
+        except Exception as e:
+            self.logger.debug(f"No agent-specific limits for {agent_id}: {e}")
+
+        return limits
+
+    def get_agent_auto_learning(self, agent_id: str) -> bool:
+        """Get auto-learning setting for a specific agent.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            True if auto-learning is enabled, False otherwise
+        """
+        try:
+            # Check agent-specific config
+            if hasattr(self.config, "agents") and agent_id in self.config.agents:
+                agent_config = self.config.agents[agent_id]
+                if "auto_learning" in agent_config:
+                    return agent_config["auto_learning"]
+
+            # Check global config
+            if hasattr(self.config, "agent_auto_learning"):
+                return self.config.agent_auto_learning
+
+        except Exception as e:
+            self.logger.debug(f"Error checking auto-learning for {agent_id}: {e}")
+
+        # Default to True (auto-learning enabled)
+        return True

claude_mpm/services/agents/memory/template_generator.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""
+Memory Template Generator
+========================
+
+Generates project-specific memory templates for agents based on project analysis.
+
+This module provides:
+- Project-specific memory template creation
+- Section generation based on project characteristics
+- Domain-specific knowledge starters
+- Fallback templates when project analysis fails
+"""
+
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict
+
+from claude_mpm.core.config import Config
+
+
+class MemoryTemplateGenerator:
+    """Generates project-specific memory templates for agents.
+
+    WHY: Instead of generic templates, agents need project-specific knowledge
+    from the start. This class creates simple memory templates that agents
+    can populate as they learn about the project.
+    """
+
+    REQUIRED_SECTIONS = [
+        "Project Architecture",
+        "Implementation Guidelines",
+        "Common Mistakes to Avoid",
+        "Current Technical Context",
+    ]
+
+    def __init__(self, config: Config, working_directory: Path):
+        """Initialize the template generator.
+
+        Args:
+            config: Configuration object
+            working_directory: Working directory path
+        """
+        self.config = config
+        self.working_directory = working_directory
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+
+    def create_default_memory(self, agent_id: str, limits: Dict[str, Any]) -> str:
+        """Create basic memory template for agent.
+
+        Args:
+            agent_id: The agent identifier
+            limits: Memory limits for this agent
+
+        Returns:
+            str: The basic memory template content
+        """
+        # Convert agent_id to proper name, handling cases like "test_agent" -> "Test"
+        agent_id.replace("_agent", "").replace("_", " ").title()
+        datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+        # Create a simple template that agents will populate through learning
+        return self._create_basic_memory_template(agent_id, limits)
+
+    def _create_basic_memory_template(
+        self, agent_id: str, limits: Dict[str, Any]
+    ) -> str:
+        """Create basic memory template as a simple list.
+
+        Args:
+            agent_id: The agent identifier
+            limits: Memory limits for this agent
+
+        Returns:
+            str: Basic memory template
+        """
+        timestamp = datetime.now(timezone.utc).isoformat() + "Z"
+
+        return f"""# Agent Memory: {agent_id}
+<!-- Last Updated: {timestamp} -->
+
+"""