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

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

@@ -157,9 +157,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 +172,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 +270,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 +288,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}")

claude_mpm/hooks/kuzu_response_hook.py

@@ -0,0 +1,183 @@
+"""
+Kuzu-Memory Response Learning Hook
+===================================
+
+Captures assistant responses and extracts learnings to store in kuzu-memory.
+This completes the bidirectional enrichment cycle:
+- KuzuMemoryHook enriches prompts with memories (READ)
+- KuzuResponseHook stores learnings from responses (WRITE)
+
+WHY: To automatically capture and persist important information from agent
+responses, enabling continuous learning across conversations.
+
+DESIGN DECISIONS:
+- Priority 80 to run late after main processing
+- Reuses KuzuMemoryHook's storage methods for consistency
+- Graceful degradation if kuzu-memory is not available
+- Extracts structured learnings using patterns and AI
+"""
+
+import logging
+from typing import Any, Optional
+
+from claude_mpm.hooks.base_hook import (
+    HookContext,
+    HookResult,
+    PostDelegationHook,
+)
+from claude_mpm.hooks.kuzu_memory_hook import get_kuzu_memory_hook
+
+logger = logging.getLogger(__name__)
+
+
+class KuzuResponseHook(PostDelegationHook):
+    """
+    Hook that captures agent responses and stores learnings in kuzu-memory.
+
+    This hook:
+    1. Processes agent responses after delegation completes
+    2. Extracts important learnings and information
+    3. Stores memories in kuzu-memory for future retrieval
+    4. Tags memories for better categorization
+    """
+
+    def __init__(self):
+        """Initialize the kuzu-memory response learning hook."""
+        super().__init__(name="kuzu_response_learner", priority=80)
+
+        # Reuse the kuzu-memory hook instance for storage
+        self.kuzu_hook = get_kuzu_memory_hook()
+        self.enabled = self.kuzu_hook.enabled
+
+        if not self.enabled:
+            logger.info(
+                "Kuzu-memory response hook disabled (kuzu-memory not available)"
+            )
+        else:
+            logger.info("Kuzu-memory response learning 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 result)
+        if not super().validate(context):
+            return False
+
+        # Must have result data to extract learnings from
+        result_data = context.data.get("result")
+        if not result_data:
+            return False
+
+        return True
+
+    def execute(self, context: HookContext) -> HookResult:
+        """
+        Extract and store learnings from agent responses.
+
+        Args:
+            context: Hook context containing response data
+
+        Returns:
+            HookResult with success status and metadata
+        """
+        if not self.enabled:
+            return HookResult(success=True, data=context.data, modified=False)
+
+        try:
+            # Extract response content from various possible formats
+            result_data = context.data.get("result", {})
+            response_content = self._extract_response_content(result_data)
+
+            if not response_content:
+                logger.debug("No response content found for learning extraction")
+                return HookResult(success=True, data=context.data, modified=False)
+
+            # Extract and store learnings
+            count = self.kuzu_hook.extract_and_store_learnings(response_content)
+
+            if count > 0:
+                logger.info(f"Stored {count} learnings from agent response")
+                return HookResult(
+                    success=True,
+                    data=context.data,
+                    modified=False,
+                    metadata={"learnings_stored": count, "memory_backend": "kuzu"},
+                )
+
+            return HookResult(success=True, data=context.data, modified=False)
+
+        except Exception as e:
+            logger.error(f"Error in kuzu response hook: {e}")
+            # Don't fail the operation if learning extraction fails
+            return HookResult(
+                success=True,
+                data=context.data,
+                modified=False,
+                error=f"Learning extraction failed: {e}",
+            )
+
+    def _extract_response_content(self, result_data: Any) -> Optional[str]:
+        """
+        Extract response content from various result formats.
+
+        Args:
+            result_data: Result data in various possible formats
+
+        Returns:
+            Extracted response content as string, or None
+        """
+        if not result_data:
+            return None
+
+        # Handle dict format
+        if isinstance(result_data, dict):
+            # Try common response fields
+            for field in ["content", "text", "response", "output", "message"]:
+                if field in result_data:
+                    content = result_data[field]
+                    if isinstance(content, str):
+                        return content
+                    if isinstance(content, dict):
+                        # Recursively extract from nested dict
+                        return self._extract_response_content(content)
+
+            # If dict has no recognizable fields, try converting to string
+            return str(result_data)
+
+        # Handle string format
+        if isinstance(result_data, str):
+            return result_data
+
+        # Handle list format (concatenate items)
+        if isinstance(result_data, list):
+            items = []
+            for item in result_data:
+                extracted = self._extract_response_content(item)
+                if extracted:
+                    items.append(extracted)
+            return "\n\n".join(items) if items else None
+
+        # Fallback to string conversion
+        return str(result_data) if result_data else None
+
+
+# Create a singleton instance
+_kuzu_response_hook = None
+
+
+def get_kuzu_response_hook() -> KuzuResponseHook:
+    """Get the singleton kuzu-memory response hook instance."""
+    global _kuzu_response_hook
+    if _kuzu_response_hook is None:
+        _kuzu_response_hook = KuzuResponseHook()
+    return _kuzu_response_hook

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -495,7 +495,7 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                     base_cmd = config["mcp_command"]
                     if len(base_cmd) > 0 and base_cmd[0] == config["package"]:
                         # Simple case where first command is the package name
-                        mcp_command = ["pipx", "run", config["package"]] + base_cmd[1:]
+                        mcp_command = ["pipx", "run", config["package"], *base_cmd[1:]]
                     else:
                         # Complex case - just try running the package with mcp arg
                         mcp_command = ["pipx", "run", config["package"], "mcp"]
@@ -509,7 +509,7 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                     base_cmd = config["mcp_command"]
                     if service_name == "kuzu-memory":
                         # Special case for kuzu-memory with args
-                        mcp_command = ["pipx", "run", base_cmd[0]] + base_cmd[1:]
+                        mcp_command = ["pipx", "run", base_cmd[0], *base_cmd[1:]]
                     else:
                         mcp_command = ["pipx", "run", *base_cmd]
             else:

claude_mpm/services/mcp_service_verifier.py

@@ -550,7 +550,7 @@ class MCPServiceVerifier:
 
         try:
             # Build test command - add --help to test without side effects
-            test_cmd = [command] + args[:2] if args else [command]  # Include base args
+            test_cmd = [command, *args[:2]] if args else [command]  # Include base args
             test_cmd.append("--help")
 
             result = subprocess.run(

claude_mpm/services/memory_hook_service.py

@@ -41,8 +41,8 @@ class MemoryHookService(BaseService, MemoryHookInterface):
         These hooks ensure memory is properly managed and persisted.
 
         DESIGN DECISION: We register hooks for key lifecycle events:
-        - Before Claude interaction: Load relevant memories
-        - After Claude interaction: Save new memories
+        - Before Claude interaction: Load relevant memories (kuzu-memory + legacy)
+        - After Claude interaction: Save new memories (kuzu-memory + legacy)
         - On error: Ensure memory state is preserved
         """
         if not self.hook_service:
@@ -90,11 +90,93 @@ class MemoryHookService(BaseService, MemoryHookInterface):
             if success2:
                 self.registered_hooks.append("memory_save")
 
-            self.logger.debug("Memory hooks registered successfully")
+            self.logger.debug("Legacy memory hooks registered successfully")
+
+            # Register kuzu-memory hooks if available
+            self._register_kuzu_memory_hooks()
 
         except Exception as e:
             self.logger.warning(f"Failed to register memory hooks: {e}")
 
+    def _register_kuzu_memory_hooks(self):
+        """Register kuzu-memory bidirectional enrichment hooks.
+
+        WHY: Kuzu-memory provides persistent knowledge graph storage that works
+        across conversations. This enables:
+        1. Delegation context enrichment with relevant memories (READ)
+        2. Automatic learning extraction from responses (WRITE)
+
+        DESIGN DECISION: These hooks are separate from legacy memory hooks to
+        allow independent evolution and configuration. Both systems can coexist.
+        """
+        try:
+            # Check if kuzu-memory is enabled in config
+            from claude_mpm.core.config import Config
+
+            config = Config()
+            kuzu_config = config.get("memory.kuzu", {})
+            if isinstance(kuzu_config, dict):
+                kuzu_enabled = kuzu_config.get("enabled", True)
+                enrichment_enabled = kuzu_config.get("enrichment", True)
+                learning_enabled = kuzu_config.get("learning", True)
+            else:
+                # Default to enabled if config section doesn't exist
+                kuzu_enabled = True
+                enrichment_enabled = True
+                learning_enabled = True
+
+            if not kuzu_enabled:
+                self.logger.debug("Kuzu-memory disabled in configuration")
+                return
+
+            from claude_mpm.hooks import (
+                get_kuzu_enrichment_hook,
+                get_kuzu_response_hook,
+            )
+
+            # Get kuzu-memory hooks
+            enrichment_hook = get_kuzu_enrichment_hook()
+            learning_hook = get_kuzu_response_hook()
+
+            # Register enrichment hook (PreDelegationHook) if enabled
+            if enrichment_hook.enabled and enrichment_enabled:
+                success = self.hook_service.register_hook(enrichment_hook)
+                if success:
+                    self.registered_hooks.append("kuzu_memory_enrichment")
+                    self.logger.info(
+                        "✅ Kuzu-memory enrichment enabled (prompts → memories)"
+                    )
+                else:
+                    self.logger.warning(
+                        "Failed to register kuzu-memory enrichment hook"
+                    )
+            elif not enrichment_enabled:
+                self.logger.debug("Kuzu-memory enrichment disabled in configuration")
+
+            # Register learning hook (PostDelegationHook) if enabled
+            if learning_hook.enabled and learning_enabled:
+                success = self.hook_service.register_hook(learning_hook)
+                if success:
+                    self.registered_hooks.append("kuzu_response_learner")
+                    self.logger.info(
+                        "✅ Kuzu-memory learning enabled (responses → memories)"
+                    )
+                else:
+                    self.logger.warning("Failed to register kuzu-memory learning hook")
+            elif not learning_enabled:
+                self.logger.debug("Kuzu-memory learning disabled in configuration")
+
+            # If neither hook is enabled, kuzu-memory is not available
+            if not enrichment_hook.enabled and not learning_hook.enabled:
+                self.logger.debug(
+                    "Kuzu-memory not available. Install with: pipx install kuzu-memory"
+                )
+
+        except ImportError as e:
+            self.logger.debug(f"Kuzu-memory hooks not available: {e}")
+        except Exception as e:
+            self.logger.warning(f"Failed to register kuzu-memory hooks: {e}")
+
     def _load_relevant_memories_hook(self, context):
         """Hook function to load relevant memories before Claude interaction.