claude-mpm 4.7.5__py3-none-any.whl → 4.7.7__py3-none-any.whl

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.
 

claude_mpm/utils/agent_dependency_loader.py

@@ -14,7 +14,7 @@ import logging
 import subprocess
 import sys
 import time
-from typing import Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 from packaging.requirements import InvalidRequirement, Requirement
 
@@ -72,7 +72,7 @@ class AgentDependencyLoader:
         Returns:
             Dictionary mapping agent IDs to their file paths
         """
-        deployed_agents = {}
+        deployed_agents: Dict[str, Path] = {}
         claude_agents_dir = Path.cwd() / ".claude" / "agents"
 
         if not claude_agents_dir.exists():
@@ -409,7 +409,7 @@ class AgentDependencyLoader:
         Returns:
             Analysis results including missing and satisfied dependencies
         """
-        results = {
+        results: Dict[str, Any] = {
             "agents": {},
             "summary": {
                 "total_agents": len(self.deployed_agents),
@@ -422,7 +422,7 @@ class AgentDependencyLoader:
         }
 
         for agent_id, deps in self.agent_dependencies.items():
-            agent_result = {
+            agent_result: Dict[str, Dict[str, List[str]]] = {
                 "python": {"satisfied": [], "missing": [], "outdated": []},
                 "system": {"satisfied": [], "missing": []},
             }
@@ -476,8 +476,8 @@ class AgentDependencyLoader:
         """
         import sys
 
-        compatible = []
-        incompatible = []
+        compatible: List[str] = []
+        incompatible: List[str] = []
 
         for dep in dependencies:
             try:
@@ -593,20 +593,37 @@ class AgentDependencyLoader:
             try:
                 cmd = [sys.executable, "-m", "pip", "install"]
 
-                # Check for PEP 668 managed environment
+                # Check environment and add appropriate flags
+                import os
                 import sysconfig
 
-                stdlib_path = sysconfig.get_path("stdlib")
-                marker_file = Path(stdlib_path) / "EXTERNALLY-MANAGED"
-                parent_marker = marker_file.parent.parent / "EXTERNALLY-MANAGED"
+                # Check if in virtualenv
+                in_virtualenv = (
+                    (hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix)
+                    or (hasattr(sys, "real_prefix"))
+                    or (os.environ.get("VIRTUAL_ENV") is not None)
+                )
 
-                if marker_file.exists() or parent_marker.exists():
-                    logger.warning(
-                        "PEP 668 managed environment detected. "
-                        "Installing with --break-system-packages --user flags. "
-                        "Consider using a virtual environment instead."
-                    )
-                    cmd.extend(["--break-system-packages", "--user"])
+                if in_virtualenv:
+                    # In virtualenv - no special flags needed
+                    logger.debug("Installing in virtualenv (no special flags)")
+                else:
+                    # Check for PEP 668 managed environment
+                    stdlib_path = sysconfig.get_path("stdlib")
+                    marker_file = Path(stdlib_path) / "EXTERNALLY-MANAGED"
+                    parent_marker = marker_file.parent.parent / "EXTERNALLY-MANAGED"
+
+                    if marker_file.exists() or parent_marker.exists():
+                        logger.warning(
+                            "PEP 668 managed environment detected. "
+                            "Installing with --break-system-packages flag. "
+                            "Consider using a virtual environment instead."
+                        )
+                        cmd.append("--break-system-packages")
+                    else:
+                        # Normal system Python - use --user
+                        cmd.append("--user")
+                        logger.debug("Installing with --user flag")
 
                 cmd.extend(compatible)
 
@@ -946,13 +963,16 @@ class AgentDependencyLoader:
 
 def check_deployed_agent_dependencies(
     auto_install: bool = False, verbose: bool = False
-) -> None:
+) -> int:
     """
     Check dependencies for currently deployed agents.
 
     Args:
         auto_install: If True, automatically install missing Python dependencies
         verbose: If True, enable verbose logging
+
+    Returns:
+        Status code: 0 if all dependencies satisfied, 1 if missing dependencies
     """
     if verbose:
         logging.getLogger().setLevel(logging.DEBUG)

claude_mpm/utils/robust_installer.py

@@ -9,6 +9,7 @@ DESIGN DECISION: We implement exponential backoff for retries and provide
 multiple installation strategies (pip, conda, source) to maximize success rate.
 """
 
+import os
 import re
 import subprocess
 import sys
@@ -80,6 +81,7 @@ class RobustPackageInstaller:
         self.use_cache = use_cache
         self.attempts: List[InstallAttempt] = []
         self.success_cache: Dict[str, bool] = {}
+        self.in_virtualenv = self._check_virtualenv()
         self.is_pep668_managed = self._check_pep668_managed()
         self.pep668_warning_shown = False
 
@@ -201,6 +203,35 @@ class RobustPackageInstaller:
         except Exception as e:
             return False, f"Unexpected error: {e!s}"
 
+    def _check_virtualenv(self) -> bool:
+        """
+        Check if running inside a virtual environment.
+
+        WHY: Virtual environments are already isolated and don't need
+        --user or --break-system-packages flags. In fact, using --user
+        in a virtualenv causes errors.
+
+        Returns:
+            True if in a virtualenv, False otherwise
+        """
+        # Multiple ways to detect virtualenv
+        return (
+            (
+                # venv creates sys.base_prefix
+                hasattr(sys, "base_prefix")
+                and sys.base_prefix != sys.prefix
+            )
+            or (
+                # virtualenv creates sys.real_prefix
+                hasattr(sys, "real_prefix")
+            )
+            or (
+                # VIRTUAL_ENV environment variable
+                os.environ.get("VIRTUAL_ENV")
+                is not None
+            )
+        )
+
     def _check_pep668_managed(self) -> bool:
         """
         Check if Python environment is PEP 668 externally managed.
@@ -211,6 +242,11 @@ class RobustPackageInstaller:
         Returns:
             True if PEP 668 managed, False otherwise
         """
+        # If in virtualenv, PEP 668 doesn't apply
+        if self.in_virtualenv:
+            logger.debug("Running in virtualenv, PEP 668 restrictions don't apply")
+            return False
+
         # Check for EXTERNALLY-MANAGED marker file
         stdlib_path = sysconfig.get_path("stdlib")
         marker_file = Path(stdlib_path) / "EXTERNALLY-MANAGED"
@@ -240,7 +276,7 @@ class RobustPackageInstaller:
                 "Your Python installation is marked as externally managed (PEP 668).\n"
                 "This typically means you're using a system Python managed by Homebrew, apt, etc.\n"
                 "\n"
-                "Installing packages with --break-system-packages --user flags...\n"
+                "Installing packages with --break-system-packages flag...\n"
                 "\n"
                 "RECOMMENDED: Use a virtual environment instead:\n"
                 "  python -m venv .venv\n"
@@ -255,8 +291,10 @@ class RobustPackageInstaller:
         """
         Build the installation command for a given strategy.
 
-        WHY: PEP 668 support added to handle externally managed Python
-        environments by adding appropriate flags when needed.
+        WHY: Proper environment detection ensures we use the right pip flags:
+        - Virtualenv: No special flags needed (already isolated)
+        - PEP 668 system: Use --break-system-packages only
+        - Normal system: Use --user for user-local install
 
         Args:
             package_spec: Package specification
@@ -267,14 +305,19 @@ class RobustPackageInstaller:
         """
         base_cmd = [sys.executable, "-m", "pip", "install"]
 
-        # Add PEP 668 bypass flags if needed
-        if self.is_pep668_managed:
+        # Determine appropriate flags based on environment
+        if self.in_virtualenv:
+            # In virtualenv - no special flags needed
+            logger.debug("Installing in virtualenv (no special flags)")
+        elif self.is_pep668_managed:
+            # System Python with PEP 668 - use --break-system-packages only
             self._show_pep668_warning()
-            # Add flags to bypass PEP 668 restrictions
-            base_cmd.extend(["--break-system-packages", "--user"])
-            logger.debug(
-                "Added --break-system-packages --user flags for PEP 668 environment"
-            )
+            base_cmd.append("--break-system-packages")
+            logger.debug("Added --break-system-packages flag for PEP 668 environment")
+        else:
+            # Normal system Python - use --user for user-local install
+            base_cmd.append("--user")
+            logger.debug("Added --user flag for user-local installation")
 
         # Add cache control
         if not self.use_cache:
@@ -612,11 +655,16 @@ class RobustPackageInstaller:
         try:
             cmd = [sys.executable, "-m", "pip", "install"]
 
-            # Add PEP 668 bypass flags if needed
-            if self.is_pep668_managed:
+            # Add appropriate flags based on environment
+            if self.in_virtualenv:
+                logger.debug("Batch install in virtualenv (no special flags)")
+            elif self.is_pep668_managed:
                 self._show_pep668_warning()
-                cmd.extend(["--break-system-packages", "--user"])
-                logger.debug("Added PEP 668 flags for batch installation")
+                cmd.append("--break-system-packages")
+                logger.debug("Added --break-system-packages for batch installation")
+            else:
+                cmd.append("--user")
+                logger.debug("Added --user flag for batch installation")
 
             cmd.extend(packages)
 
@@ -654,12 +702,18 @@ class RobustPackageInstaller:
         lines.append("INSTALLATION REPORT")
         lines.append("=" * 60)
 
-        # Add PEP 668 status
-        if self.is_pep668_managed:
-            lines.append("")
+        # Add environment status
+        lines.append("")
+        if self.in_virtualenv:
+            lines.append("✓ Environment: Virtual Environment (isolated)")
+            lines.append("  No special pip flags needed")
+        elif self.is_pep668_managed:
             lines.append("⚠️  PEP 668 Managed Environment: YES")
-            lines.append("   Installations used --break-system-packages --user flags")
+            lines.append("   Installations used --break-system-packages flag")
             lines.append("   Consider using a virtual environment for better isolation")
+        else:
+            lines.append("Environment: System Python")
+            lines.append("   Installations used --user flag for user-local install")
 
         # Summary
         total_attempts = len(self.attempts)
@@ -672,7 +726,7 @@ class RobustPackageInstaller:
         lines.append("")
 
         # Details by package
-        packages = {}
+        packages: Dict[str, List[InstallAttempt]] = {}
         for attempt in self.attempts:
             if attempt.package not in packages:
                 packages[attempt.package] = []

{claude_mpm-4.7.5.dist-info → claude_mpm-4.7.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.7.5
+Version: 4.7.7
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team