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

claude_mpm/services/memory/indexed_memory.py

@@ -23,7 +23,7 @@ import re
 import time
 from collections import Counter, defaultdict
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional, Set, Tuple
 
 from ...core.cache import get_file_cache
@@ -213,7 +213,7 @@ class InvertedIndex:
             "doc_freqs": dict(self.doc_freqs),
             "doc_count": self.doc_count,
         }
-        with open(path, "wb") as f:
+        with path.open("wb") as f:
             pickle.dump(data, f)
 
     def load(self, path: Path):
@@ -221,7 +221,7 @@ class InvertedIndex:
         if not path.exists():
             return
 
-        with open(path, "rb") as f:
+        with path.open("rb") as f:
             data = pickle.load(f)
 
         self.index = defaultdict(set, {k: set(v) for k, v in data["index"].items()})
@@ -388,7 +388,7 @@ class IndexedMemoryService:
             agent_id=agent_id,
             content=content,
             category=category,
-            timestamp=datetime.now(),
+            timestamp=datetime.now(timezone.utc),
             tags=tags or [],
             metadata=metadata or {},
         )
@@ -510,7 +510,7 @@ class IndexedMemoryService:
         start_time = time.time()
 
         # Calculate time range
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         if hours:
             min_time = now - timedelta(hours=hours)
         elif days:
@@ -563,7 +563,7 @@ class IndexedMemoryService:
 
     def _generate_id(self, agent_id: str, content: str) -> str:
         """Generate unique ID for memory entry."""
-        timestamp = datetime.now().isoformat()
+        timestamp = datetime.now(timezone.utc).isoformat()
         hash_input = f"{agent_id}:{content[:100]}:{timestamp}"
         return hashlib.md5(hash_input.encode()).hexdigest()[:12]
 
@@ -573,7 +573,7 @@ class IndexedMemoryService:
         self.text_index.save(self.data_dir / "text_index.pkl")
 
         # Save other indexes
-        with open(self.data_dir / "indexes.pkl", "wb") as f:
+        with Path(self.data_dir / "indexes.pkl").open("wb") as f:
             pickle.dump(
                 {
                     "memories": self.memories,
@@ -597,7 +597,7 @@ class IndexedMemoryService:
         # Load other indexes
         indexes_path = self.data_dir / "indexes.pkl"
         if indexes_path.exists():
-            with open(indexes_path, "rb") as f:
+            with indexes_path.open("rb") as f:
                 data = pickle.load(f)
 
             self.memories = data.get("memories", {})

claude_mpm/services/memory/optimizer.py

@@ -22,9 +22,8 @@ rather than aggressively removing content. Better to keep potentially useful
 information than lose important insights.
 """
 
-import os
 import re
-from datetime import datetime
+from datetime import datetime, timezone
 from difflib import SequenceMatcher
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -79,7 +78,7 @@ class MemoryOptimizer(LoggerMixin):
         self.config = config or Config()
         self.project_root = get_path_manager().get_project_root()
         # Use current working directory by default, not project root
-        self.working_directory = working_directory or Path(os.getcwd())
+        self.working_directory = working_directory or Path(Path.cwd())
         self.memories_dir = self.working_directory / ".claude-mpm" / "memories"
 
     def optimize_agent_memory(self, agent_id: str) -> Dict[str, Any]:
@@ -164,7 +163,7 @@ class MemoryOptimizer(LoggerMixin):
                     else 0
                 ),
                 "backup_created": str(backup_path),
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 **optimization_stats,
             }
 
@@ -230,7 +229,7 @@ class MemoryOptimizer(LoggerMixin):
 
             return {
                 "success": True,
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 "agents": results,
                 "summary": {
                     **total_stats,
@@ -545,7 +544,7 @@ class MemoryOptimizer(LoggerMixin):
 
         # Update timestamp
         content = "\n".join(content_lines)
-        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
         return re.sub(
             r"<!-- Last Updated: .+ \| Auto-updated by: .+ -->",
             f"<!-- Last Updated: {timestamp} | Auto-updated by: optimizer -->",
@@ -561,7 +560,7 @@ class MemoryOptimizer(LoggerMixin):
         Returns:
             Path to backup file
         """
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
         backup_name = f"{memory_file.stem}_backup_{timestamp}{memory_file.suffix}"
         backup_path = memory_file.parent / backup_name
 
@@ -619,7 +618,7 @@ class MemoryOptimizer(LoggerMixin):
                     )
 
                 # Check for similar items
-                consolidated, consolidated_count = self._consolidate_similar_items(
+                _consolidated, consolidated_count = self._consolidate_similar_items(
                     unique_points
                 )
                 if consolidated_count > 0:
@@ -647,7 +646,7 @@ class MemoryOptimizer(LoggerMixin):
 
         return {
             "success": True,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "agents_analyzed": len(agents_analysis),
             "agents": agents_analysis,
         }

claude_mpm/services/memory/router.py

@@ -21,7 +21,7 @@ users understand why content was assigned to specific agents.
 """
 
 import re
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Tuple
 
 from claude_mpm.core.config import Config
@@ -622,7 +622,7 @@ class MemoryRouter(LoggerMixin):
                 "confidence": confidence,
                 "reasoning": reasoning,
                 "agent_scores": agent_scores,
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 "content_length": len(content),
             }
 
@@ -639,7 +639,7 @@ class MemoryRouter(LoggerMixin):
                 "confidence": 0.1,
                 "reasoning": f"Error during analysis, defaulting to {self.DEFAULT_AGENT}",
                 "error": str(e),
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 "content_length": len(content) if content else 0,
             }
 

claude_mpm/services/memory_hook_service.py

@@ -11,6 +11,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.interfaces import MemoryHookInterface
 
 
@@ -41,8 +42,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 +91,169 @@ 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()
+
+            # Register failure-learning hooks
+            self._register_failure_learning_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 _register_failure_learning_hooks(self):
+        """Register failure-learning hooks for automatic learning extraction.
+
+        WHY: When tasks fail and agents fix them, we want to automatically capture
+        this as a learning. The failure-learning system provides:
+        1. Failure detection from tool outputs (errors, exceptions, test failures)
+        2. Fix detection when same task type succeeds after failure
+        3. Learning extraction and persistence to agent memory files
+
+        DESIGN DECISION: These hooks work as a chain with specific priorities:
+        - FailureDetectionHook (priority=85): Detects failures after tool execution
+        - FixDetectionHook (priority=87): Matches fixes with failures
+        - LearningExtractionHook (priority=89): Extracts and persists learnings
+
+        The system is enabled by default but can be disabled via configuration.
+        """
+        try:
+            # Check if failure-learning is enabled in config
+            from claude_mpm.core.config import Config
+
+            config = Config()
+            failure_learning_config = config.get("memory.failure_learning", {})
+
+            if isinstance(failure_learning_config, dict):
+                enabled = failure_learning_config.get("enabled", True)
+            else:
+                # Default to enabled if config section doesn't exist
+                enabled = True
+
+            if not enabled:
+                self.logger.debug("Failure-learning disabled in configuration")
+                return
+
+            # Import failure-learning hooks
+            from claude_mpm.hooks.failure_learning import (
+                get_failure_detection_hook,
+                get_fix_detection_hook,
+                get_learning_extraction_hook,
+            )
+
+            # Get hook instances
+            failure_hook = get_failure_detection_hook()
+            fix_hook = get_fix_detection_hook()
+            learning_hook = get_learning_extraction_hook()
+
+            # Register hooks in priority order
+            success1 = self.hook_service.register_hook(failure_hook)
+            success2 = self.hook_service.register_hook(fix_hook)
+            success3 = self.hook_service.register_hook(learning_hook)
+
+            if success1:
+                self.registered_hooks.append("failure_detection")
+                self.logger.debug("✅ Failure detection enabled")
+
+            if success2:
+                self.registered_hooks.append("fix_detection")
+                self.logger.debug("✅ Fix detection enabled")
+
+            if success3:
+                self.registered_hooks.append("learning_extraction")
+                self.logger.debug("✅ Learning extraction enabled")
+
+            if success1 and success2 and success3:
+                self.logger.info(
+                    "✅ Failure-learning system enabled "
+                    "(failures → fixes → learnings → memory)"
+                )
+
+        except ImportError as e:
+            self.logger.debug(f"Failure-learning hooks not available: {e}")
+        except Exception as e:
+            self.logger.warning(f"Failed to register failure-learning hooks: {e}")
+
     def _load_relevant_memories_hook(self, context):
         """Hook function to load relevant memories before Claude interaction.
 
@@ -305,5 +464,7 @@ class MemoryHookService(BaseService, MemoryHookInterface):
             "hook_service_available": self.hook_service is not None,
             "memory_enabled": self.is_memory_enabled(),
             "total_hooks": len(self.registered_hooks),
-            "status": "active" if self.registered_hooks else "inactive",
+            "status": (
+                ServiceState.RUNNING if self.registered_hooks else ServiceState.IDLE
+            ),
         }

claude_mpm/services/model/__init__.py

@@ -0,0 +1,147 @@
+"""
+Model Services Package for Claude MPM Framework
+================================================
+
+WHY: Provides hybrid local/cloud content processing with intelligent routing
+and automatic fallback. Enables privacy-preserving local model execution via
+Ollama with cloud fallback to Claude for reliability.
+
+ARCHITECTURE:
+- Interfaces: Core contracts for model providers and routing (IModelProvider, IModelRouter)
+- Base Provider: Common functionality for all providers (BaseModelProvider)
+- Providers: Ollama (local) and Claude (cloud) implementations
+- Router: Intelligent routing with fallback logic (ModelRouter)
+- Configuration: Centralized config management (model_config.py)
+
+USAGE:
+
+    Basic Usage with Auto-Routing:
+    ```python
+    from claude_mpm.services.model import ModelRouter
+    from claude_mpm.services.core.interfaces.model import ModelCapability
+
+    # Create router with default config (auto mode)
+    router = ModelRouter()
+    await router.initialize()
+
+    # Analyze content (tries Ollama first, falls back to Claude)
+    response = await router.analyze_content(
+        content="Your article text here...",
+        task=ModelCapability.SEO_ANALYSIS
+    )
+
+    if response.success:
+        print(f"Analysis by {response.provider}:")
+        print(response.result)
+    ```
+
+    Direct Provider Usage:
+    ```python
+    from claude_mpm.services.model import OllamaProvider
+
+    # Use Ollama directly
+    provider = OllamaProvider(config={
+        "host": "http://localhost:11434"
+    })
+
+    if await provider.is_available():
+        response = await provider.analyze_content(
+            content="Text to analyze",
+            task=ModelCapability.READABILITY
+        )
+    ```
+
+    Configuration-Based Setup:
+    ```python
+    from claude_mpm.config.model_config import ModelConfigManager
+    from claude_mpm.services.model import ModelRouter
+
+    # Load config from file
+    config = ModelConfigManager.load_config(".claude/configuration.yaml")
+    router_config = ModelConfigManager.get_router_config(config)
+
+    # Create router with loaded config
+    router = ModelRouter(config=router_config)
+    await router.initialize()
+    ```
+
+PROVIDER STRATEGIES:
+- AUTO: Try Ollama first, fallback to Claude (default)
+- OLLAMA: Local-only, fail if unavailable (privacy mode)
+- CLAUDE: Cloud-only, always use Claude
+- PRIVACY: Like OLLAMA with privacy-focused messages
+
+RECOMMENDED MODELS (Ollama):
+- SEO Analysis: llama3.3:70b - Comprehensive SEO insights
+- Readability: gemma2:9b - Fast, accurate readability scoring
+- Grammar: qwen3:14b - Specialized grammar checking
+- Summarization: mistral:7b - Concise, effective summaries
+- Keyword Extraction: seoassistant - SEO-specialized model
+
+CONFIGURATION:
+See claude_mpm.config.model_config for detailed configuration options.
+
+Example configuration.yaml:
+```yaml
+content_agent:
+  model_provider: auto
+
+  ollama:
+    enabled: true
+    host: http://localhost:11434
+    fallback_to_cloud: true
+    models:
+      seo_analysis: llama3.3:70b
+      readability: gemma2:9b
+
+  claude:
+    enabled: true
+    model: claude-3-5-sonnet-20241022
+```
+
+PHASE 1 STATUS (Current):
+✅ Core interfaces and contracts defined
+✅ Base provider with common functionality
+✅ Ollama provider with direct API integration
+✅ Claude provider (Phase 1: mock responses)
+✅ Router with intelligent fallback logic
+✅ Configuration management with validation
+⏳ Claude API integration (Phase 2)
+⏳ Content agent integration (Phase 2)
+"""
+
+# Re-export interfaces for convenience
+from claude_mpm.services.core.interfaces.model import (
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+from claude_mpm.services.model.base_provider import BaseModelProvider
+from claude_mpm.services.model.claude_provider import ClaudeProvider
+from claude_mpm.services.model.model_router import ModelRouter, RoutingStrategy
+from claude_mpm.services.model.ollama_provider import OllamaProvider
+
+__all__ = [  # noqa: RUF022 - Semantic grouping preferred over alphabetical
+    # Base classes
+    "BaseModelProvider",
+    # Providers
+    "ClaudeProvider",
+    "OllamaProvider",
+    # Router
+    "ModelRouter",
+    "RoutingStrategy",
+    # Interfaces
+    "IModelProvider",
+    "IModelRouter",
+    # Data types
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
+]
+
+# Version and metadata
+__version__ = "1.0.0"
+__phase__ = "1"
+__status__ = "Core Infrastructure Complete"