claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/config/async_logging_config.yaml

@@ -0,0 +1,145 @@
+# Async Logging Configuration
+# Optimized logging configuration for high-performance scenarios
+
+logging:
+  # Enable async logging for improved performance
+  async:
+    enabled: true
+
+    # Log format options: json, syslog, journald
+    format: json
+
+    # Maximum queue size for async writes
+    max_queue_size: 10000
+
+    # Enable compression for JSON logs (reduces disk usage)
+    compression: false
+
+    # Worker threads for async processing
+    worker_threads: 4
+
+    # Flush timeout in seconds
+    flush_timeout: 5.0
+
+  # Session logger settings
+  session:
+    # Base directory for logs
+    base_dir: ".claude-mpm/responses"
+
+    # Use timestamp-based filenames (eliminates race conditions)
+    timestamp_filenames: true
+
+    # Include microseconds in timestamps for uniqueness
+    microsecond_precision: true
+
+    # Filename format with available variables:
+    # {agent} - Agent name
+    # {timestamp} - ISO timestamp
+    # {microseconds} - Microsecond component
+    # {session} - Session ID
+    filename_format: "{agent}_{timestamp}_{microseconds}.json"
+
+  # OS-native logging options (for extreme performance)
+  syslog:
+    # Syslog address (auto-detected by default)
+    # address: /var/run/syslog  # macOS
+    # address: /dev/log         # Linux
+    # address: ["localhost", 514]  # Network
+
+    # Syslog facility
+    facility: local0
+
+    # Include structured data
+    structured_data: true
+
+  # Performance tuning
+  performance:
+    # Fire-and-forget mode (don't wait for write confirmation)
+    fire_and_forget: true
+
+    # Drop logs if queue is full (prevents blocking)
+    drop_on_full: true
+
+    # Batch writes for efficiency
+    batch_writes: true
+    batch_size: 10
+    batch_timeout_ms: 100
+
+# Hook system optimization
+hooks:
+  # Enable hook system
+  enabled: true
+
+  # Optimization settings
+  optimization:
+    # Cache hook configurations at startup
+    cache_configs: true
+
+    # Lazy load hook implementations
+    lazy_loading: true
+
+    # Use singleton pattern for hook service
+    singleton: true
+
+    # Enable async hook execution
+    async_execution: true
+
+    # Maximum workers for parallel hook execution
+    max_workers: 4
+
+  # Pre-delegation hooks
+  pre_delegation:
+    enabled: true
+
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - memory_context_hook
+      - validation_hook
+      - auth_hook
+
+  # Post-delegation hooks
+  post_delegation:
+    enabled: true
+
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - logging_hook
+      - metrics_hook
+      - cleanup_hook
+
+  # Registered hooks with lazy loading
+  registered:
+    # NOTE: The builtin hooks have been deprecated and removed
+    # These references are kept commented for historical reference
+    # memory_context_hook:
+    #   module: claude_mpm.hooks.builtin.memory_hooks
+    #   class: MemoryContextHook
+    #   priority: 10
+    #   enabled: true
+    #   params:
+    #     cache_size: 1000
+    #
+    # response_logger_hook:
+    #   module: claude_mpm.hooks.builtin.logging_hooks
+    #   class: ResponseLoggerHook
+    #   priority: 90
+    #   enabled: true
+    #   params:
+    #     async: true
+    #
+    # metrics_hook:
+    #   module: claude_mpm.hooks.builtin.metrics_hooks
+    #   class: MetricsCollectorHook
+    #   priority: 95
+    #   enabled: true
+    #   params:
+    #     buffer_size: 100
+
+# Environment variable overrides
+# These can override any setting above:
+#
+# CLAUDE_USE_ASYNC_LOG=true        # Enable async logging
+# CLAUDE_LOG_FORMAT=syslog         # Use syslog format
+# CLAUDE_LOG_SYNC=true             # Disable async (for debugging)
+# CLAUDE_HOOKS_CACHE=true          # Enable hook caching
+# CLAUDE_HOOKS_ASYNC=true          # Enable async hooks

claude_mpm/constants.py

@@ -168,6 +168,18 @@ class SkillsCommands(str, Enum):
     UPDATE = "update"
     INFO = "info"
     CONFIG = "config"
+    # GitHub deployment commands
+    DEPLOY_FROM_GITHUB = "deploy-github"
+    LIST_AVAILABLE = "list-available"
+    CHECK_DEPLOYED = "check-deployed"
+    REMOVE = "remove"
+    # Collection management commands
+    COLLECTION_LIST = "collection-list"
+    COLLECTION_ADD = "collection-add"
+    COLLECTION_REMOVE = "collection-remove"
+    COLLECTION_ENABLE = "collection-enable"
+    COLLECTION_DISABLE = "collection-disable"
+    COLLECTION_SET_DEFAULT = "collection-set-default"
 
 
 class CLIFlags(str, Enum):

claude_mpm/core/.claude-mpm/logs/hooks_20250730.log

@@ -0,0 +1,34 @@
+2025-07-30 12:40:20,992 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:20,992 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:40:33,117 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:33,117 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Edit
+2025-07-30 12:40:33,276 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:33,276 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Edit (exit code: N/A)
+2025-07-30 12:40:39,276 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:39,276 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 12:40:39,541 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:39,541 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:40:48,610 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:48,610 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 12:40:49,941 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:49,941 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:44:50,358 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: UserPromptSubmit (session: df539357)
+2025-07-30 12:44:50,358 - claude_mpm_hooks_core - INFO - hook_handler.py:244 - UserPromptSubmit: OK. Let's make the subprocess the default method
+2025-07-30 13:05:35,872 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: UserPromptSubmit (session: df539357)
+2025-07-30 13:05:35,872 - claude_mpm_hooks_core - INFO - hook_handler.py:244 - UserPromptSubmit: actually leave as is.  I want to figure out a simple test to trigger the terminal flow.  Use docs/de...
+2025-07-30 13:05:42,930 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:42,930 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Read
+2025-07-30 13:05:43,133 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:43,133 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Read (exit code: N/A)
+2025-07-30 13:05:49,996 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:49,996 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Grep
+2025-07-30 13:05:50,548 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:50,548 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Grep (exit code: N/A)
+2025-07-30 13:05:56,341 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:56,341 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Read
+2025-07-30 13:05:56,527 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:56,528 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Read (exit code: N/A)
+2025-07-30 13:06:01,890 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:06:01,890 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 13:06:08,115 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:06:08,115 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash

claude_mpm/core/api_validator.py

@@ -326,5 +326,5 @@ def validate_api_keys(config: Optional[Dict] = None, strict: bool = True) -> boo
         ValueError: If strict=True and any validation fails
     """
     validator = APIKeyValidator(config)
-    success, errors, warnings = validator.validate_all_keys(strict=strict)
+    success, _errors, _warnings = validator.validate_all_keys(strict=strict)
     return success

claude_mpm/core/claude_runner.py

@@ -42,8 +42,19 @@ class ClaudeRunner:
         launch_method: str = "exec",  # "exec" or "subprocess"
         enable_websocket: bool = False,
         websocket_port: int = 8765,
+        use_native_agents: bool = False,  # Use --agents flag instead of file deployment
     ):
-        """Initialize the Claude runner."""
+        """Initialize the Claude runner.
+
+        Args:
+            enable_tickets: Enable ticket extraction (deprecated)
+            log_level: Logging level
+            claude_args: Additional arguments for Claude CLI
+            launch_method: "exec" or "subprocess" launch mode
+            enable_websocket: Enable WebSocket server
+            websocket_port: WebSocket server port
+            use_native_agents: Use --agents CLI flag instead of .claude/agents/ deployment
+        """
         self.logger = get_logger(__name__)
 
         # Initialize configuration service
@@ -75,6 +86,7 @@ class ClaudeRunner:
             launch_method=launch_method,
             enable_websocket=enable_websocket,
             websocket_port=websocket_port,
+            use_native_agents=use_native_agents,
         )
 
         # Set configuration attributes
@@ -84,6 +96,7 @@ class ClaudeRunner:
         self.launch_method = config_data["launch_method"]
         self.enable_websocket = config_data["enable_websocket"]
         self.websocket_port = config_data["websocket_port"]
+        self.use_native_agents = config_data.get("use_native_agents", False)
         self.config = config_data["config"]
 
         # Initialize project logger using the service

claude_mpm/core/config.py

@@ -583,6 +583,14 @@ class Config:
                 "auto_save": True,  # Enable automatic session saving
                 "save_interval": 300,  # Auto-save interval in seconds (5 minutes)
             },
+            # Update checking configuration
+            "updates": {
+                "check_enabled": True,  # Enable automatic update checks
+                "check_frequency": "daily",  # Options: "always", "daily", "weekly", "never"
+                "check_claude_code": True,  # Check Claude Code version compatibility
+                "auto_upgrade": False,  # Automatically upgrade without prompting (use with caution)
+                "cache_ttl": 86400,  # Cache update check results (24 hours)
+            },
         }
 
         # Apply defaults for missing keys

claude_mpm/core/constants.py

@@ -215,7 +215,7 @@ class Defaults:
     DEFAULT_TEMPERATURE = 0.5
 
     # Logging defaults
-    DEFAULT_LOG_LEVEL = "INFO"
+    DEFAULT_LOG_LEVEL = "OFF"
     DEFAULT_LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 
     # Session defaults

claude_mpm/core/framework/processors/metadata_processor.py

@@ -127,7 +127,7 @@ class MetadataProcessor:
             True if cache is valid, False otherwise
         """
         try:
-            data, cache_time = cached_data
+            _data, cache_time = cached_data
             current_time = time.time()
 
             # Check TTL

claude_mpm/core/hook_error_memory.py

@@ -0,0 +1,381 @@
+"""Hook Error Memory System.
+
+This module provides error detection and memory for hook execution to prevent
+repeated errors and provide helpful diagnostics.
+
+WHY this is needed:
+- Hook processor can encounter transient or persistent errors
+- Repeated failing commands waste resources and clutter logs
+- Users need actionable suggestions to fix configuration issues
+- System should learn from errors and prevent repetition
+
+DESIGN DECISION: Store errors in JSON file rather than database because:
+- Simple, human-readable format
+- Easy to inspect and manually clear
+- No additional dependencies
+- Fast read/write for small datasets
+- Users can easily delete to retry failed commands
+"""
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..core.logger import get_logger
+
+
+class HookErrorMemory:
+    """Tracks and prevents repeated hook execution errors.
+
+    WHY this design:
+    - Detects common error patterns automatically
+    - Stores error history to prevent repetition
+    - Provides actionable fix suggestions
+    - Allows manual retry by clearing memory
+    - Minimal performance overhead (<1ms per check)
+    """
+
+    # Error pattern definitions with detection regexes
+    ERROR_PATTERNS = [
+        (r"no such file or directory[:\s]+(.+?)(?:\n|$)", "file_not_found"),
+        (r"command not found[:\s]+(.+?)(?:\n|$)", "command_not_found"),
+        (r"permission denied[:\s]+(.+?)(?:\n|$)", "permission_denied"),
+        (r"syntax error", "syntax_error"),
+        (r"Error:\s*\(eval\):(\d+):\s*(.+?)(?:\n|$)", "eval_error"),
+        (r"Error:\s*(.+?)(?:\n|$)", "general_error"),
+    ]
+
+    def __init__(self, memory_file: Optional[Path] = None):
+        """Initialize hook error memory.
+
+        Args:
+            memory_file: Path to memory file (default: .claude-mpm/hook_errors.json)
+        """
+        self.logger = get_logger("hook_error_memory")
+
+        # Use default location if not specified
+        if memory_file is None:
+            memory_file = Path.cwd() / ".claude-mpm" / "hook_errors.json"
+
+        self.memory_file = memory_file
+        self.errors: Dict[str, Any] = self._load_errors()
+
+    def _load_errors(self) -> Dict[str, Any]:
+        """Load previously encountered errors from disk.
+
+        Returns:
+            Dictionary of error records
+        """
+        if not self.memory_file.exists():
+            return {}
+
+        try:
+            content = self.memory_file.read_text()
+            if not content.strip():
+                return {}
+            return json.loads(content)
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Failed to parse error memory file: {e}")
+            return {}
+        except Exception as e:
+            self.logger.error(f"Error loading error memory: {e}")
+            return {}
+
+    def _save_errors(self):
+        """Persist errors to disk."""
+        try:
+            # Ensure directory exists
+            self.memory_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write with pretty formatting for human readability
+            self.memory_file.write_text(json.dumps(self.errors, indent=2))
+        except Exception as e:
+            self.logger.error(f"Failed to save error memory: {e}")
+
+    def detect_error(
+        self, output: str, stderr: str, returncode: int
+    ) -> Optional[Dict[str, str]]:
+        """Detect if output contains an error.
+
+        WHY check both stdout and stderr:
+        - Some commands write errors to stdout
+        - Some write to stderr
+        - Return code alone isn't enough (some hooks return non-zero on purpose)
+
+        Args:
+            output: Standard output from command
+            stderr: Standard error from command
+            returncode: Exit code from command
+
+        Returns:
+            Dict with error info if detected, None otherwise
+        """
+        # Combine output sources for comprehensive error detection
+        combined_output = f"{output}\n{stderr}"
+
+        # Try each pattern in order of specificity
+        for pattern, error_type in self.ERROR_PATTERNS:
+            match = re.search(pattern, combined_output, re.IGNORECASE | re.MULTILINE)
+            if match:
+                # Extract details from the match
+                details = match.group(1) if match.groups() else match.group(0)
+
+                return {
+                    "type": error_type,
+                    "pattern": pattern,
+                    "match": match.group(0).strip(),
+                    "details": details.strip() if details else "",
+                    "returncode": returncode,
+                }
+
+        # If no pattern matched but returncode is non-zero, record as generic error
+        if returncode != 0 and combined_output.strip():
+            return {
+                "type": "unknown_error",
+                "pattern": "non-zero exit code",
+                "match": f"Exit code: {returncode}",
+                "details": combined_output[:200].strip(),  # First 200 chars
+                "returncode": returncode,
+            }
+
+        return None
+
+    def record_error(self, error_info: Dict[str, str], hook_type: str):
+        """Record an error to prevent future repetition.
+
+        WHY use composite key:
+        - Same error type can occur with different details
+        - Want to track specific error instances
+        - Hook type context helps with diagnosis
+
+        Args:
+            error_info: Error information from detect_error()
+            hook_type: Type of hook that failed (e.g., "PreToolUse")
+        """
+        # Create unique key for this error
+        key = f"{error_info['type']}:{hook_type}:{error_info['details']}"
+
+        now = datetime.now(timezone.utc).isoformat()
+
+        if key in self.errors:
+            # Update existing error
+            self.errors[key]["count"] += 1
+            self.errors[key]["last_seen"] = now
+        else:
+            # Record new error
+            self.errors[key] = {
+                "type": error_info["type"],
+                "hook_type": hook_type,
+                "details": error_info["details"],
+                "match": error_info["match"],
+                "returncode": error_info.get("returncode", 1),
+                "count": 1,
+                "first_seen": now,
+                "last_seen": now,
+            }
+
+        self._save_errors()
+        self.logger.debug(
+            f"Recorded error: {error_info['type']} (count: {self.errors[key]['count']})"
+        )
+
+    def is_known_failing_hook(self, hook_type: str) -> Optional[Dict[str, Any]]:
+        """Check if a hook type is known to fail repeatedly.
+
+        WHY check for 2+ failures:
+        - Single failure could be transient
+        - 2+ failures indicate persistent issue
+        - Balance between retry attempts and error prevention
+
+        Args:
+            hook_type: Type of hook to check
+
+        Returns:
+            Error data if hook is known to fail, None otherwise
+        """
+        # Find any errors for this hook type with 2+ occurrences
+        for key, error_data in self.errors.items():
+            if error_data["hook_type"] == hook_type and error_data["count"] >= 2:
+                return error_data
+
+        return None
+
+    def should_skip_hook(self, hook_type: str, threshold: int = 2) -> bool:
+        """Determine if a hook should be skipped due to repeated failures.
+
+        Args:
+            hook_type: Type of hook to check
+            threshold: Minimum failure count to skip (default: 2)
+
+        Returns:
+            True if hook should be skipped
+        """
+        error_data = self.is_known_failing_hook(hook_type)
+        return error_data is not None and error_data["count"] >= threshold
+
+    def suggest_fix(self, error_info: Dict[str, str]) -> str:
+        """Suggest a fix for the detected error.
+
+        WHY provide suggestions:
+        - Users need actionable guidance
+        - Common errors have known solutions
+        - Reduces support burden
+        - Improves user experience
+
+        Args:
+            error_info: Error information from detect_error()
+
+        Returns:
+            Human-readable fix suggestion
+        """
+        error_type = error_info["type"]
+        details = error_info.get("details", "")
+
+        suggestions = {
+            "file_not_found": f"""File not found: {details}
+
+Possible fixes:
+1. Check if the file exists: ls -la {details}
+2. Verify the path is correct in your hook configuration
+3. If it's a script, ensure it's executable: chmod +x {details}
+4. Clear error memory to retry: rm {self.memory_file}
+""",
+            "command_not_found": f"""Command not found: {details}
+
+Possible fixes:
+1. Install the missing command
+2. Check if it's in your PATH: which {details}
+3. Update hook configuration to use absolute path
+4. Remove the hook if no longer needed
+""",
+            "permission_denied": f"""Permission denied: {details}
+
+Possible fixes:
+1. Check file permissions: ls -la {details}
+2. Make file executable: chmod +x {details}
+3. Run with appropriate privileges
+4. Check file ownership
+""",
+            "syntax_error": """Syntax error in hook configuration or script
+
+Possible fixes:
+1. Review hook configuration in .claude-mpm/config
+2. Check script syntax if using shell hooks
+3. Validate JSON configuration format
+4. Check for typos in hook definitions
+""",
+            "eval_error": f"""Error in hook execution: {details}
+
+Possible fixes:
+1. Review hook handler logs for details
+2. Check hook configuration syntax
+3. Verify all required dependencies are available
+4. Test hook handler manually: python {details}
+""",
+            "general_error": f"""Error during hook execution: {error_info.get("match", "Unknown error")}
+
+Possible fixes:
+1. Check logs for detailed error information
+2. Verify hook configuration is correct
+3. Ensure all dependencies are installed
+4. Clear error memory to retry: rm {self.memory_file}
+""",
+        }
+
+        return suggestions.get(
+            error_type, f"Unknown error type: {error_type}\n\nDetails: {details}"
+        )
+
+    def clear_errors(self, hook_type: Optional[str] = None):
+        """Clear error memory to allow retry of failed hooks.
+
+        Args:
+            hook_type: If specified, only clear errors for this hook type
+        """
+        if hook_type is None:
+            # Clear all errors
+            count = len(self.errors)
+            self.errors.clear()
+            self._save_errors()
+            self.logger.info(f"Cleared all {count} error records")
+        else:
+            # Clear errors for specific hook type
+            keys_to_remove = [
+                key
+                for key, data in self.errors.items()
+                if data["hook_type"] == hook_type
+            ]
+            for key in keys_to_remove:
+                del self.errors[key]
+            self._save_errors()
+            self.logger.info(
+                f"Cleared {len(keys_to_remove)} error records for {hook_type}"
+            )
+
+    def get_error_summary(self) -> Dict[str, Any]:
+        """Get summary of all recorded errors.
+
+        Returns:
+            Dictionary with error statistics and details
+        """
+        if not self.errors:
+            return {
+                "total_errors": 0,
+                "unique_errors": 0,
+                "errors_by_type": {},
+                "errors_by_hook": {},
+            }
+
+        errors_by_type = {}
+        errors_by_hook = {}
+
+        total_count = 0
+
+        for error_data in self.errors.values():
+            error_type = error_data["type"]
+            hook_type = error_data["hook_type"]
+            count = error_data["count"]
+
+            total_count += count
+
+            errors_by_type[error_type] = errors_by_type.get(error_type, 0) + count
+            errors_by_hook[hook_type] = errors_by_hook.get(hook_type, 0) + count
+
+        return {
+            "total_errors": total_count,
+            "unique_errors": len(self.errors),
+            "errors_by_type": errors_by_type,
+            "errors_by_hook": errors_by_hook,
+            "memory_file": str(self.memory_file),
+        }
+
+
+# Global instance
+_hook_error_memory: Optional[HookErrorMemory] = None
+
+
+def get_hook_error_memory(memory_file: Optional[Path] = None) -> HookErrorMemory:
+    """Get the global hook error memory instance.
+
+    Args:
+        memory_file: Optional custom memory file path
+
+    Returns:
+        HookErrorMemory instance
+    """
+    global _hook_error_memory
+    if _hook_error_memory is None:
+        _hook_error_memory = HookErrorMemory(memory_file)
+    return _hook_error_memory
+
+
+def clear_hook_errors(hook_type: Optional[str] = None):
+    """Convenience function to clear hook error memory.
+
+    Args:
+        hook_type: If specified, only clear errors for this hook type
+    """
+    memory = get_hook_error_memory()
+    memory.clear_errors(hook_type)