claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/hooks/failure_learning/learning_extraction_hook.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""
+Learning Extraction Hook
+=========================
+
+Synthesizes learnings from failure-fix pairs and writes them to agent memory.
+
+WHY: The final step in the failure-learning cycle is extracting actionable
+learnings and persisting them to agent memory files. This hook completes the
+cycle by taking failure-fix pairs and creating formatted learning entries.
+
+DESIGN DECISION: This hook runs last (priority=89) after both failure and fix
+detection. It uses template-based synthesis for MVP (no AI) and integrates
+with AgentMemoryManager to write learnings to the appropriate memory files.
+
+Integration points:
+- Monitors for fix_detected metadata from FixDetectionHook
+- Extracts learnings using FailureTracker
+- Formats learnings as markdown
+- Writes to agent memory files via AgentMemoryManager
+"""
+
+import logging
+from typing import Any
+
+from claude_mpm.hooks.base_hook import (
+    BaseHook,
+    HookContext,
+    HookResult,
+    HookType,
+)
+from claude_mpm.services.memory.failure_tracker import get_failure_tracker
+
+logger = logging.getLogger(__name__)
+
+
+class LearningExtractionHook(BaseHook):
+    """Hook that extracts and persists learnings from failure-fix pairs.
+
+    WHY: Automatically converts failure-fix pairs into persistent learnings
+    stored in agent memory files. This completes the failure-learning cycle
+    without requiring manual intervention.
+
+    DESIGN DECISION: Priority 89 ensures this runs last in the chain:
+    1. Failure detection (85) - detects failures
+    2. Fix detection (87) - matches fixes with failures
+    3. Learning extraction (89) - creates and persists learnings
+
+    MVP uses template-based learning synthesis. Future versions could use
+    AI to analyze git diffs, code changes, and generate richer learnings.
+    """
+
+    def __init__(self):
+        """Initialize the learning extraction hook."""
+        super().__init__(
+            name="learning_extraction",
+            priority=89,  # Last in the chain, after fix detection
+        )
+        self.tracker = get_failure_tracker()
+        self._memory_manager = None
+
+    @property
+    def memory_manager(self):
+        """Lazy-load memory manager to avoid circular imports.
+
+        WHY: AgentMemoryManager may import hooks, so we lazy-load to prevent
+        circular dependency issues.
+
+        Returns:
+            AgentMemoryManager instance
+        """
+        if self._memory_manager is None:
+            try:
+                from claude_mpm.services.agents.memory.agent_memory_manager import (
+                    get_memory_manager,
+                )
+
+                self._memory_manager = get_memory_manager()
+            except ImportError as e:
+                logger.error(f"Failed to import AgentMemoryManager: {e}")
+                raise
+
+        return self._memory_manager
+
+    def execute(self, context: HookContext) -> HookResult:
+        """Execute learning extraction from failure-fix pairs.
+
+        WHY: When a fix is detected, we have everything needed to extract a
+        learning: the original failure, the fix that resolved it, and the
+        context. This method synthesizes a learning and writes it to memory.
+
+        Args:
+            context: Hook context containing fix detection metadata
+
+        Returns:
+            HookResult with extraction results
+        """
+        try:
+            # Check if this is a fix detection event
+            metadata = context.metadata or {}
+            if not metadata.get("fix_detected"):
+                # Not a fix event, skip
+                return HookResult(success=True, modified=False)
+
+            # Extract failure and fix events from metadata
+            failure_event = metadata.get("failure_event")
+            fix_event = metadata.get("fix_event")
+
+            if not failure_event or not fix_event:
+                logger.warning("Fix detected but failure/fix events not in metadata")
+                return HookResult(success=True, modified=False)
+
+            # Extract learning from failure-fix pair
+            learning = self.tracker.extract_learning(
+                fix_event=fix_event,
+                failure_event=failure_event,
+                target_agent=self._determine_target_agent(context, failure_event),
+            )
+
+            # Format learning as markdown
+            learning_markdown = learning.to_markdown()
+
+            # Write to agent memory
+            success = self._write_to_memory(
+                agent_id=learning.target_agent, learning_text=learning_markdown
+            )
+
+            if success:
+                logger.info(
+                    f"Learning extracted and saved for {learning.target_agent}: "
+                    f"{learning.category}"
+                )
+                return HookResult(
+                    success=True,
+                    modified=False,
+                    metadata={
+                        "learning_extracted": True,
+                        "target_agent": learning.target_agent,
+                        "learning_category": learning.category,
+                    },
+                )
+            logger.warning(
+                f"Failed to write learning to memory for {learning.target_agent}"
+            )
+            return HookResult(
+                success=True,  # Don't fail the hook, just log warning
+                modified=False,
+                metadata={"learning_extracted": False},
+            )
+
+        except Exception as e:
+            logger.error(f"Error in learning extraction hook: {e}", exc_info=True)
+            return HookResult(success=False, error=str(e), modified=False)
+
+    def validate(self, context: HookContext) -> bool:
+        """Validate if this hook should run for the given context.
+
+        Args:
+            context: Hook context to validate
+
+        Returns:
+            True if hook should execute
+        """
+        if not super().validate(context):
+            return False
+
+        # Run for POST_DELEGATION events (after tool execution)
+        if context.hook_type != HookType.POST_DELEGATION:
+            return False
+
+        # Must have fix detection metadata
+        metadata = context.metadata or {}
+        return metadata.get("fix_detected", False)
+
+    def _determine_target_agent(self, context: HookContext, failure_event: Any) -> str:
+        """Determine which agent should receive the learning.
+
+        WHY: Learnings should go to the agent most likely to benefit from them.
+        This method applies routing logic to determine the best target.
+
+        Args:
+            context: Hook context
+            failure_event: The failure event
+
+        Returns:
+            Agent identifier (PM, engineer, qa, etc.)
+        """
+        # Try to get agent from context first
+        agent_type = (
+            context.data.get("agent_type")
+            or context.data.get("subagent_type")
+            or context.metadata.get("agent_type")
+        )
+        if agent_type:
+            return agent_type
+
+        # Check failure event context
+        if hasattr(failure_event, "context") and failure_event.context.get(
+            "agent_type"
+        ):
+            return failure_event.context["agent_type"]
+
+        # Fall back to task-based routing
+        if hasattr(failure_event, "task_type"):
+            task_type = failure_event.task_type
+            if task_type in ("test", "lint"):
+                return "qa"
+            if task_type in ("build", "install", "script") or task_type == "git":
+                return "engineer"
+
+        # Default to PM
+        return "PM"
+
+    def _write_to_memory(self, agent_id: str, learning_text: str) -> bool:
+        """Write learning to agent memory file.
+
+        WHY: Learnings must be persisted to memory files so agents can access
+        them in future sessions. This method uses AgentMemoryManager to handle
+        the actual file operations.
+
+        Args:
+            agent_id: Agent identifier
+            learning_text: Markdown-formatted learning
+
+        Returns:
+            True if write succeeded, False otherwise
+        """
+        try:
+            # Parse learning sections from markdown
+            learning_items = self._parse_learning_markdown(learning_text)
+
+            if not learning_items:
+                logger.warning(f"No learning items parsed from: {learning_text}")
+                return False
+
+            # Add to agent memory
+            return self.memory_manager.update_agent_memory(
+                agent_id=agent_id, new_items=learning_items
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to write learning to memory for {agent_id}: {e}")
+            return False
+
+    def _parse_learning_markdown(self, learning_markdown: str) -> list:
+        """Parse learning markdown into list items for memory.
+
+        WHY: AgentMemoryManager expects a list of learning items. We need to
+        convert the markdown-formatted learning into individual list items.
+
+        Args:
+            learning_markdown: Markdown-formatted learning
+
+        Returns:
+            List of learning items
+        """
+        items = []
+
+        # Split by lines and extract bullet points
+        lines = learning_markdown.split("\n")
+
+        for line in lines:
+            line = line.strip()
+            if line.startswith("- **"):
+                # This is a learning item (e.g., "- **Problem**: ...")
+                items.append(line)
+            elif line.startswith("## "):
+                # This is a category header, skip it
+                continue
+
+        # If no items found, return the whole thing as a single item
+        if not items:
+            items = [f"- {learning_markdown.strip()}"]
+
+        return items
+
+
+def get_learning_extraction_hook() -> LearningExtractionHook:
+    """Factory function to create learning extraction hook.
+
+    WHY: Provides consistent hook creation pattern used throughout the framework.
+
+    Returns:
+        Configured LearningExtractionHook instance
+    """
+    return LearningExtractionHook()

claude_mpm/hooks/instruction_reinforcement.py

@@ -10,6 +10,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Dict, List, Optional, Tuple
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.logging_utils import get_logger
 
 logger = get_logger(__name__)
@@ -267,7 +268,7 @@ class InstructionReinforcementHook:
         if not self.violations:
             return {
                 "total_violations": 0,
-                "status": "COMPLIANT",
+                "status": OperationResult.SUCCESS,
                 "message": "No PM delegation violations detected",
             }
 
@@ -276,7 +277,11 @@ class InstructionReinforcementHook:
             vtype = v.violation_type.value
             violation_types[vtype] = violation_types.get(vtype, 0) + 1
 
-        status = "WARNING" if self.violation_count < 3 else "CRITICAL"
+        status = (
+            OperationResult.ERROR
+            if self.violation_count < 3
+            else OperationResult.FAILED
+        )
 
         return {
             "total_violations": self.violation_count,

claude_mpm/hooks/kuzu_enrichment_hook.py

@@ -0,0 +1,263 @@
+"""
+Kuzu-Memory Pre-Delegation Enrichment Hook
+==========================================
+
+Enriches agent delegation context with relevant memories from kuzu-memory
+before the agent receives the task. This is the READ side of bidirectional
+enrichment.
+
+WHY: Agents need access to relevant historical knowledge when performing tasks.
+This hook retrieves memories from kuzu-memory and injects them into the
+delegation context.
+
+DESIGN DECISIONS:
+- Priority 10 to run early, before other context modifications
+- Reuses KuzuMemoryHook's retrieval methods for consistency
+- Injects memories as a dedicated section in agent context
+- Falls back gracefully if kuzu-memory is not available
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from claude_mpm.hooks.base_hook import HookContext, HookResult, PreDelegationHook
+from claude_mpm.hooks.kuzu_memory_hook import get_kuzu_memory_hook
+
+logger = logging.getLogger(__name__)
+
+
+class KuzuEnrichmentHook(PreDelegationHook):
+    """
+    Hook that enriches agent delegation context with kuzu-memory.
+
+    This hook:
+    1. Extracts the task/prompt from delegation context
+    2. Retrieves relevant memories from kuzu-memory
+    3. Injects memories into agent context
+    4. Formats memories for optimal agent understanding
+    """
+
+    def __init__(self):
+        """Initialize the kuzu-memory enrichment hook."""
+        super().__init__(name="kuzu_memory_enrichment", priority=10)
+
+        # Reuse the kuzu-memory hook instance for retrieval
+        self.kuzu_hook = get_kuzu_memory_hook()
+        self.enabled = self.kuzu_hook.enabled
+
+        if not self.enabled:
+            logger.info(
+                "Kuzu-memory enrichment hook disabled (kuzu-memory not available)"
+            )
+        else:
+            logger.info("Kuzu-memory enrichment hook enabled")
+
+    def validate(self, context: HookContext) -> bool:
+        """
+        Validate if hook should process this context.
+
+        Args:
+            context: Hook context to validate
+
+        Returns:
+            True if hook should execute
+        """
+        if not self.enabled:
+            return False
+
+        # Check base validation (enabled, correct hook type, has agent)
+        if not super().validate(context):
+            return False
+
+        # Must have agent and context data
+        if not context.data.get("agent"):
+            return False
+
+        return True
+
+    def execute(self, context: HookContext) -> HookResult:
+        """
+        Enrich delegation context with relevant memories.
+
+        Args:
+            context: Hook context containing delegation data
+
+        Returns:
+            HookResult with enriched context
+        """
+        if not self.enabled:
+            return HookResult(success=True, data=context.data, modified=False)
+
+        try:
+            # Extract query for memory retrieval
+            query = self._extract_query_from_context(context.data)
+
+            if not query:
+                logger.debug("No query extracted from context for memory retrieval")
+                return HookResult(success=True, data=context.data, modified=False)
+
+            # Retrieve relevant memories
+            memories = self.kuzu_hook._retrieve_memories(query)
+
+            if not memories:
+                logger.debug("No relevant memories found")
+                return HookResult(success=True, data=context.data, modified=False)
+
+            # Enrich context with memories
+            enriched_data = self._enrich_delegation_context(
+                context.data, memories, context.data.get("agent", "Agent")
+            )
+
+            logger.info(
+                f"Enriched delegation context with {len(memories)} memories for {context.data.get('agent')}"
+            )
+
+            return HookResult(
+                success=True,
+                data=enriched_data,
+                modified=True,
+                metadata={
+                    "memories_added": len(memories),
+                    "memory_source": "kuzu",
+                    "agent": context.data.get("agent"),
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Error in kuzu enrichment hook: {e}")
+            # Don't fail the delegation if memory enrichment fails
+            return HookResult(
+                success=True,
+                data=context.data,
+                modified=False,
+                error=f"Memory enrichment failed: {e}",
+            )
+
+    def _extract_query_from_context(self, data: Dict[str, Any]) -> Optional[str]:
+        """
+        Extract query text for memory retrieval.
+
+        Args:
+            data: Delegation context data
+
+        Returns:
+            Query string or None
+        """
+        # Try various context fields
+        delegation_context = data.get("context", {})
+
+        # Handle string context
+        if isinstance(delegation_context, str):
+            return delegation_context
+
+        # Handle dict context
+        if isinstance(delegation_context, dict):
+            # Try common fields
+            for field in ["prompt", "task", "query", "user_request", "description"]:
+                if field in delegation_context:
+                    value = delegation_context[field]
+                    if isinstance(value, str):
+                        return value
+
+            # If no specific field, join all string values
+            text_parts = [
+                str(v) for v in delegation_context.values() if isinstance(v, str)
+            ]
+            if text_parts:
+                return " ".join(text_parts)
+
+        # Fallback: try to get task or instruction directly
+        if "task" in data and isinstance(data["task"], str):
+            return data["task"]
+
+        if "instruction" in data and isinstance(data["instruction"], str):
+            return data["instruction"]
+
+        return None
+
+    def _enrich_delegation_context(
+        self, original_data: Dict[str, Any], memories: list, agent_name: str
+    ) -> Dict[str, Any]:
+        """
+        Enrich delegation context with memories.
+
+        Args:
+            original_data: Original delegation data
+            memories: Retrieved memories
+            agent_name: Name of the agent
+
+        Returns:
+            Enriched delegation data
+        """
+        # Format memories
+        memory_section = self._format_memory_section(memories, agent_name)
+
+        # Create enriched data
+        enriched_data = original_data.copy()
+
+        # Get existing context
+        delegation_context = enriched_data.get("context", {})
+        if isinstance(delegation_context, str):
+            delegation_context = {"prompt": delegation_context}
+
+        # Add memory section
+        if isinstance(delegation_context, dict):
+            # Prepend memory section to context
+            delegation_context["kuzu_memories"] = memory_section
+
+            # If there's a main prompt/task, prepend memory note
+            for field in ["prompt", "task", "instruction"]:
+                if field in delegation_context and isinstance(
+                    delegation_context[field], str
+                ):
+                    delegation_context[field] = (
+                        f"{memory_section}\n\n{delegation_context[field]}"
+                    )
+                    break
+        else:
+            # If context is not dict, create new dict with memory
+            delegation_context = {
+                "kuzu_memories": memory_section,
+                "original_context": delegation_context,
+            }
+
+        enriched_data["context"] = delegation_context
+        enriched_data["_kuzu_enriched"] = True
+
+        return enriched_data
+
+    def _format_memory_section(self, memories: list, agent_name: str) -> str:
+        """
+        Format memories into a readable section.
+
+        Args:
+            memories: List of memory dictionaries
+            agent_name: Name of the agent
+
+        Returns:
+            Formatted memory section
+        """
+        memory_text = self.kuzu_hook._format_memories(memories)
+
+        return f"""
+=== RELEVANT KNOWLEDGE FROM KUZU MEMORY ===
+{agent_name}, you have access to these relevant memories from the knowledge graph:
+
+{memory_text}
+
+INSTRUCTIONS: Review these memories before proceeding. Apply learned patterns and avoid known mistakes.
+Use this knowledge to provide more informed and contextual responses.
+===========================================
+"""
+
+
+# Create a singleton instance
+_kuzu_enrichment_hook = None
+
+
+def get_kuzu_enrichment_hook() -> KuzuEnrichmentHook:
+    """Get the singleton kuzu-memory enrichment hook instance."""
+    global _kuzu_enrichment_hook
+    if _kuzu_enrichment_hook is None:
+        _kuzu_enrichment_hook = KuzuEnrichmentHook()
+    return _kuzu_enrichment_hook

claude_mpm/hooks/kuzu_memory_hook.py

@@ -13,8 +13,9 @@ for structured memory storage with semantic search capabilities.
 DESIGN DECISIONS:
 - Priority 10 for early execution to enrich prompts before other hooks
 - Uses subprocess to call kuzu-memory directly for maximum compatibility
-- Graceful degradation if kuzu-memory is not installed
+- Graceful degradation if kuzu-memory is not in PATH (though it's now required)
 - Automatic extraction and storage of important information
+- kuzu-memory>=1.1.5 is now a REQUIRED dependency (moved from optional in v4.8.6)
 """
 
 import json
@@ -50,7 +51,10 @@ class KuzuMemoryHook(SubmitHook):
         self.enabled = self.kuzu_memory_cmd is not None
 
         if not self.enabled:
-            logger.info("Kuzu-memory not found. Install with: pipx install kuzu-memory")
+            logger.warning(
+                "Kuzu-memory not found in PATH. As of v4.8.6, it's a required dependency. "
+                "Install with: pip install kuzu-memory>=1.1.5 or pipx install kuzu-memory"
+            )
         else:
             logger.info(f"Kuzu-memory integration enabled: {self.kuzu_memory_cmd}")
 
@@ -72,6 +76,10 @@ class KuzuMemoryHook(SubmitHook):
         1. Check pipx installation
         2. Check system PATH
         3. Return None if not found
+
+        NOTE: As of v4.8.6, kuzu-memory is a required dependency and should be
+        installed via pip. This method checks both pipx and system PATH for
+        backward compatibility.
         """
         # Check pipx installation
         pipx_path = (
@@ -157,9 +165,13 @@ class KuzuMemoryHook(SubmitHook):
             List of relevant memory dictionaries
         """
         try:
-            # Use kuzu-memory recall command
+            # Type narrowing: ensure kuzu_memory_cmd is not None before using
+            if self.kuzu_memory_cmd is None:
+                return []
+
+            # Use kuzu-memory recall command (v1.2.7+ syntax)
             result = subprocess.run(
-                [self.kuzu_memory_cmd, "recall", query, "--format", "json"],
+                [self.kuzu_memory_cmd, "memory", "recall", query, "--format", "json"],
                 capture_output=True,
                 text=True,
                 timeout=5,
@@ -168,10 +180,21 @@ class KuzuMemoryHook(SubmitHook):
             )
 
             if result.returncode == 0 and result.stdout:
-                memories = json.loads(result.stdout)
-                return memories if isinstance(memories, list) else []
-
-        except (subprocess.TimeoutExpired, json.JSONDecodeError, Exception) as e:
+                try:
+                    # Parse JSON with strict=False to handle control characters
+                    data = json.loads(result.stdout, strict=False)
+                    # v1.2.7 returns dict with 'memories' key, not array
+                    if isinstance(data, dict):
+                        memories = data.get("memories", [])
+                    else:
+                        memories = data if isinstance(data, list) else []
+                    return memories
+                except json.JSONDecodeError as e:
+                    logger.warning(f"Failed to parse kuzu-memory JSON output: {e}")
+                    logger.debug(f"Raw output: {result.stdout[:200]}")
+                    return []  # Graceful fallback
+
+        except (subprocess.TimeoutExpired, Exception) as e:
             logger.debug(f"Memory retrieval failed: {e}")
 
         return []
@@ -255,12 +278,12 @@ Note: Use the memories above to provide more informed and contextual responses.
         Returns:
             True if storage was successful
         """
-        if not self.enabled:
+        if not self.enabled or self.kuzu_memory_cmd is None:
             return False
 
         try:
-            # Use kuzu-memory remember command (synchronous)
-            cmd = [self.kuzu_memory_cmd, "remember", content]
+            # Use kuzu-memory store command (v1.2.7+ syntax)
+            cmd = [self.kuzu_memory_cmd, "memory", "store", content]
 
             # Execute store command in project directory
             result = subprocess.run(
@@ -273,8 +296,10 @@ Note: Use the memories above to provide more informed and contextual responses.
             )
 
             if result.returncode == 0:
-                logger.debug(f"Stored memory: {content[:50]}...")
+                logger.debug(f"Stored memory in kuzu: {content[:50]}...")
                 return True
+            logger.warning(f"Failed to store memory in kuzu: {result.stderr}")
+            return False
 
         except Exception as e:
             logger.error(f"Failed to store memory: {e}")