claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/core/framework/__init__.py

@@ -4,22 +4,9 @@ This module provides the modular framework loading system with specialized compo
 for handling different aspects of framework initialization and management.
 """
 
-from .formatters import (
-    CapabilityGenerator,
-    ContentFormatter,
-    ContextGenerator,
-)
-from .loaders import (
-    AgentLoader,
-    FileLoader,
-    InstructionLoader,
-    PackagedLoader,
-)
-from .processors import (
-    MemoryProcessor,
-    MetadataProcessor,
-    TemplateProcessor,
-)
+from .formatters import CapabilityGenerator, ContentFormatter, ContextGenerator
+from .loaders import AgentLoader, FileLoader, InstructionLoader, PackagedLoader
+from .processors import MemoryProcessor, MetadataProcessor, TemplateProcessor
 
 __all__ = [
     "AgentLoader",

claude_mpm/core/framework/formatters/content_formatter.py

@@ -100,19 +100,9 @@ class ContentFormatter:
                 instructions += framework_content["actual_memories"]
                 instructions += "\n"
 
-            # Add agent memories if available
-            if framework_content.get("agent_memories"):
-                agent_memories = framework_content["agent_memories"]
-                if agent_memories:
-                    instructions += "\n\n## Agent Memories\n\n"
-                    instructions += "**The following are accumulated memories from specialized agents:**\n\n"
-
-                    for agent_name in sorted(agent_memories.keys()):
-                        memory_content = agent_memories[agent_name]
-                        if memory_content:
-                            instructions += f"### {agent_name.replace('_', ' ').title()} Agent Memory\n\n"
-                            instructions += memory_content
-                            instructions += "\n\n"
+            # NOTE: Agent memories are now injected at agent deployment time
+            # in agent_template_builder.py, not in PM instructions.
+            # This ensures each agent gets its own memory, not all memories embedded in PM.
 
             # Add dynamic agent capabilities section
             instructions += capabilities_section

claude_mpm/core/framework/loaders/agent_loader.py

@@ -115,7 +115,11 @@ class AgentLoader:
         return agents
 
     def discover_local_json_templates(self) -> Dict[str, Dict[str, Any]]:
-        """Discover local JSON agent templates from .claude-mpm/agents/ directories.
+        """Discover local JSON agent templates.
+
+        NOTE: This method is kept for backward compatibility but is deprecated.
+        The new architecture uses SOURCE (~/.claude-mpm/cache/agents/)
+        and DEPLOYMENT (.claude/agents/) locations only.
 
         Returns:
             Dictionary mapping agent IDs to agent metadata
@@ -125,11 +129,10 @@ class AgentLoader:
         local_agents = {}
 
         # Check for local JSON templates in priority order
+        # NOTE: These directories are deprecated in the simplified architecture
         template_dirs = [
-            Path.cwd()
-            / ".claude-mpm"
-            / "agents",  # Project local agents (highest priority)
-            Path.home() / ".claude-mpm" / "agents",  # User local agents
+            Path.cwd() / ".claude-mpm" / "agents",  # Deprecated: Project local agents
+            Path.home() / ".claude-mpm" / "agents",  # Deprecated: User local agents
         ]
 
         for priority, template_dir in enumerate(template_dirs):

claude_mpm/core/framework/loaders/file_loader.py

@@ -66,6 +66,53 @@ class FileLoader:
             if "INSTRUCTIONS.md" in str(file_path):
                 self.framework_last_modified = timestamp
 
+    def _load_tier_file(
+        self,
+        filename: str,
+        current_dir: Path,
+        framework_path: Optional[Path] = None,
+        include_system: bool = False,
+    ) -> tuple[Optional[str], Optional[str]]:
+        """Load file with tier precedence: project → user → system.
+
+        Args:
+            filename: Name of file to load (e.g., "INSTRUCTIONS.md")
+            current_dir: Current working directory for project-level
+            framework_path: Path to framework installation for system-level
+            include_system: Whether to check system-level path
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        # Check project-level (highest priority)
+        project_path = current_dir / ".claude-mpm" / filename
+        if project_path.exists():
+            loaded_content = self.try_load_file(
+                project_path, f"project-specific {filename}"
+            )
+            if loaded_content:
+                self.logger.info(f"Using project-specific {filename} from .claude-mpm/")
+                return loaded_content, "project"
+
+        # Check user-level (medium priority)
+        user_path = Path.home() / ".claude-mpm" / filename
+        if user_path.exists():
+            loaded_content = self.try_load_file(user_path, f"user-specific {filename}")
+            if loaded_content:
+                self.logger.info(f"Using user-specific {filename} from ~/.claude-mpm/")
+                return loaded_content, "user"
+
+        # Check system-level (lowest priority)
+        if include_system and framework_path and framework_path != Path("__PACKAGED__"):
+            system_path = framework_path / "src" / "claude_mpm" / "agents" / filename
+            if system_path.exists():
+                loaded_content = self.try_load_file(system_path, f"system {filename}")
+                if loaded_content:
+                    self.logger.info(f"Using system {filename}")
+                    return loaded_content, "system"
+
+        return None, None
+
     def load_instructions_file(
         self, current_dir: Path
     ) -> tuple[Optional[str], Optional[str]]:
@@ -82,31 +129,7 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', or None
         """
-        # Check for project-specific INSTRUCTIONS.md first
-        project_instructions_path = current_dir / ".claude-mpm" / "INSTRUCTIONS.md"
-        if project_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                project_instructions_path, "project-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific INSTRUCTIONS.md
-        user_instructions_path = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
-        if user_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                user_instructions_path, "user-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "user"
-
-        return None, None
+        return self._load_tier_file("INSTRUCTIONS.md", current_dir)
 
     def load_workflow_file(
         self, current_dir: Path, framework_path: Path
@@ -126,44 +149,9 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific WORKFLOW.md first (highest priority)
-        project_workflow_path = current_dir / ".claude-mpm" / "WORKFLOW.md"
-        if project_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                project_workflow_path, "project-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific WORKFLOW.md (medium priority)
-        user_workflow_path = Path.home() / ".claude-mpm" / "WORKFLOW.md"
-        if user_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                user_workflow_path, "user-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system workflow (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_workflow_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "WORKFLOW.md"
-            )
-            if system_workflow_path.exists():
-                loaded_content = self.try_load_file(
-                    system_workflow_path, "system WORKFLOW.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system workflow instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "WORKFLOW.md", current_dir, framework_path, include_system=True
+        )
 
     def load_memory_file(
         self, current_dir: Path, framework_path: Path
@@ -183,41 +171,6 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific MEMORY.md first (highest priority)
-        project_memory_path = current_dir / ".claude-mpm" / "MEMORY.md"
-        if project_memory_path.exists():
-            loaded_content = self.try_load_file(
-                project_memory_path, "project-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific memory instructions from .claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific MEMORY.md (medium priority)
-        user_memory_path = Path.home() / ".claude-mpm" / "MEMORY.md"
-        if user_memory_path.exists():
-            loaded_content = self.try_load_file(
-                user_memory_path, "user-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system memory instructions (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_memory_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "MEMORY.md"
-            )
-            if system_memory_path.exists():
-                loaded_content = self.try_load_file(
-                    system_memory_path, "system MEMORY.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system memory instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "MEMORY.md", current_dir, framework_path, include_system=True
+        )

claude_mpm/core/framework/loaders/instruction_loader.py

@@ -88,30 +88,91 @@ class InstructionLoader:
                 self.packaged_loader.framework_last_modified
             )
 
+    def _extract_version(self, file_content: str) -> int:
+        """Extract version number from PM_INSTRUCTIONS_VERSION comment.
+
+        Args:
+            file_content: Content of the file to extract version from
+
+        Returns:
+            Version number as integer, or 0 if not found
+        """
+        import re
+
+        match = re.search(r"PM_INSTRUCTIONS_VERSION:\s*(\d+)", file_content)
+        if match:
+            return int(match.group(1))
+        return 0  # No version = oldest
+
     def _load_filesystem_framework_instructions(self, content: Dict[str, Any]) -> None:
         """Load framework instructions from filesystem.
 
+        Priority order:
+        1. Deployed compiled file: .claude-mpm/PM_INSTRUCTIONS_DEPLOYED.md (if version >= source)
+        2. Source file (development): src/claude_mpm/agents/PM_INSTRUCTIONS.md
+        3. Legacy file (backward compat): src/claude_mpm/agents/INSTRUCTIONS.md
+
+        Version validation ensures deployed file is never stale compared to source.
+
         Args:
             content: Dictionary to update with framework instructions
         """
-        # Try new consolidated PM_INSTRUCTIONS.md first, fall back to INSTRUCTIONS.md
+        # Define source path for version checking
         pm_instructions_path = (
             self.framework_path / "src" / "claude_mpm" / "agents" / "PM_INSTRUCTIONS.md"
         )
+
+        # PRIORITY 1: Check for compiled/deployed version in .claude-mpm/
+        # This is the merged PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md
+        deployed_path = self.current_dir / ".claude-mpm" / "PM_INSTRUCTIONS_DEPLOYED.md"
+        if deployed_path.exists():
+            # Validate version before using deployed file
+            deployed_content = deployed_path.read_text()
+            deployed_version = self._extract_version(deployed_content)
+
+            # Check source version for comparison
+            if pm_instructions_path.exists():
+                source_content = pm_instructions_path.read_text()
+                source_version = self._extract_version(source_content)
+
+                if deployed_version < source_version:
+                    self.logger.warning(
+                        f"Deployed PM instructions v{deployed_version:04d} is stale, "
+                        f"source is v{source_version:04d}. Using source instead."
+                    )
+                    # Fall through to source loading - don't return early
+                else:
+                    # Version OK, use deployed
+                    content["framework_instructions"] = deployed_content
+                    content["loaded"] = True
+                    self.logger.info(
+                        f"Loaded PM_INSTRUCTIONS_DEPLOYED.md v{deployed_version:04d} from .claude-mpm/"
+                    )
+                    return  # Stop here - deployed version is current
+            else:
+                # Source doesn't exist, use deployed even without version check
+                content["framework_instructions"] = deployed_content
+                content["loaded"] = True
+                self.logger.info("Loaded PM_INSTRUCTIONS_DEPLOYED.md from .claude-mpm/")
+                return
+
+        # PRIORITY 2: Development mode - load from source PM_INSTRUCTIONS.md
         framework_instructions_path = (
             self.framework_path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md"
         )
 
-        # Try loading new consolidated file first
+        # Try loading new consolidated file (pm_instructions_path already defined above)
         if pm_instructions_path.exists():
             loaded_content = self.file_loader.try_load_file(
-                pm_instructions_path, "consolidated PM_INSTRUCTIONS.md"
+                pm_instructions_path, "source PM_INSTRUCTIONS.md (development mode)"
             )
             if loaded_content:
                 content["framework_instructions"] = loaded_content
                 content["loaded"] = True
-                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md")
-        # Fall back to legacy file for backward compatibility
+                self.logger.warning(
+                    "Using source PM_INSTRUCTIONS.md - deployed version not found"
+                )
+        # PRIORITY 3: Fall back to legacy file for backward compatibility
         elif framework_instructions_path.exists():
             loaded_content = self.file_loader.try_load_file(
                 framework_instructions_path, "framework INSTRUCTIONS.md (legacy)"

claude_mpm/core/framework_loader.py

@@ -255,10 +255,12 @@ class FrameworkLoader:
         """Load actual memories using the MemoryManager service."""
         memories = self._memory_manager.load_memories()
 
+        # Only load PM memories (PM.md)
+        # Agent memories are loaded at deployment time in agent_template_builder.py
         if "actual_memories" in memories:
             content["actual_memories"] = memories["actual_memories"]
-        if "agent_memories" in memories:
-            content["agent_memories"] = memories["agent_memories"]
+        # NOTE: agent_memories are no longer loaded for PM instructions
+        # They are injected per-agent at deployment time
 
     # === Agent Discovery Methods ===