alma-memory 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

alma/learning/heuristic_extractor.py

@@ -4,15 +4,15 @@ ALMA Heuristic Extraction.
 Analyzes outcomes to identify patterns and create heuristics.
 """
 
-import uuid
 import logging
-from datetime import datetime, timezone
-from typing import Optional, List, Dict, Any, Tuple
-from dataclasses import dataclass, field
+import uuid
 from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
 
-from alma.types import Heuristic, Outcome, MemoryScope
 from alma.storage.base import StorageBackend
+from alma.types import Heuristic, MemoryScope, Outcome
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +20,7 @@ logger = logging.getLogger(__name__)
 @dataclass
 class PatternCandidate:
     """A potential pattern for heuristic creation."""
+
     task_type: str
     strategy: str
     occurrence_count: int
@@ -56,6 +57,7 @@ class PatternCandidate:
 @dataclass
 class ExtractionResult:
     """Result of heuristic extraction."""
+
     heuristics_created: int = 0
     heuristics_updated: int = 0
     patterns_analyzed: int = 0
@@ -137,7 +139,7 @@ class HeuristicExtractor:
         # Group outcomes by agent and task type
         grouped = self._group_outcomes(outcomes)
 
-        for (ag, task_type), type_outcomes in grouped.items():
+        for (ag, _task_type), type_outcomes in grouped.items():
             # Find patterns within this group
             patterns = self._identify_patterns(type_outcomes)
             result.patterns_analyzed += len(patterns)
@@ -204,14 +206,16 @@ class HeuristicExtractor:
         patterns = []
         for strategy, group_outcomes in strategy_groups.items():
             success_count = sum(1 for o in group_outcomes if o.success)
-            patterns.append(PatternCandidate(
-                task_type=group_outcomes[0].task_type,
-                strategy=strategy,
-                occurrence_count=len(group_outcomes),
-                success_count=success_count,
-                failure_count=len(group_outcomes) - success_count,
-                outcomes=group_outcomes,
-            ))
+            patterns.append(
+                PatternCandidate(
+                    task_type=group_outcomes[0].task_type,
+                    strategy=strategy,
+                    occurrence_count=len(group_outcomes),
+                    success_count=success_count,
+                    failure_count=len(group_outcomes) - success_count,
+                    outcomes=group_outcomes,
+                )
+            )
 
         return patterns
 
@@ -291,8 +295,9 @@ class HeuristicExtractor:
         )
 
         for h in heuristics:
-            if (task_type in h.condition and
-                    self._strategies_similar(h.strategy, strategy)):
+            if task_type in h.condition and self._strategies_similar(
+                h.strategy, strategy
+            ):
                 return h
 
         return None
@@ -305,13 +310,9 @@ class HeuristicExtractor:
         """Update an existing heuristic with new data."""
         # Merge counts
         heuristic.occurrence_count = max(
-            heuristic.occurrence_count,
-            pattern.occurrence_count
-        )
-        heuristic.success_count = max(
-            heuristic.success_count,
-            pattern.success_count
+            heuristic.occurrence_count, pattern.occurrence_count
         )
+        heuristic.success_count = max(heuristic.success_count, pattern.success_count)
 
         # Update confidence
         heuristic.confidence = pattern.confidence
@@ -344,8 +345,23 @@ class HeuristicExtractor:
         """Normalize strategy text for comparison."""
         # Remove common stop words and normalize
         stop_words = {
-            "the", "a", "an", "and", "or", "but", "in", "on", "at",
-            "to", "for", "of", "with", "by", "then", "first", "next",
+            "the",
+            "a",
+            "an",
+            "and",
+            "or",
+            "but",
+            "in",
+            "on",
+            "at",
+            "to",
+            "for",
+            "of",
+            "with",
+            "by",
+            "then",
+            "first",
+            "next",
         }
 
         words = strategy.lower().replace(",", " ").replace(".", " ").split()

alma/learning/protocols.py

@@ -4,20 +4,23 @@ ALMA Learning Protocols.
 Defines how agents learn from outcomes while respecting scope constraints.
 """
 
-import uuid
 import logging
-from datetime import datetime, timezone, timedelta
-from typing import Optional, Dict, Any
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Dict, Optional
 
+from alma.storage.base import StorageBackend
 from alma.types import (
+    AntiPattern,
+    DomainKnowledge,
     Heuristic,
+    MemoryScope,
     Outcome,
     UserPreference,
-    DomainKnowledge,
-    AntiPattern,
-    MemoryScope,
 )
-from alma.storage.base import StorageBackend
+
+if TYPE_CHECKING:
+    from alma.retrieval.embeddings import EmbeddingProvider
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +39,8 @@ class LearningProtocol:
         self,
         storage: StorageBackend,
         scopes: Dict[str, MemoryScope],
+        embedder: Optional["EmbeddingProvider"] = None,
+        similarity_threshold: float = 0.75,
     ):
         """
         Initialize learning protocol.
@@ -43,9 +48,13 @@ class LearningProtocol:
         Args:
             storage: Storage backend for persistence
             scopes: Dict of agent_name -> MemoryScope
+            embedder: Optional embedding provider for semantic similarity
+            similarity_threshold: Cosine similarity threshold for strategy matching (default 0.75)
         """
         self.storage = storage
         self.scopes = scopes
+        self.embedder = embedder
+        self.similarity_threshold = similarity_threshold
 
     def learn(
         self,
@@ -100,7 +109,9 @@ class LearningProtocol:
 
         # Save outcome
         self.storage.save_outcome(outcome_record)
-        logger.info(f"Recorded outcome for {agent}: {'success' if outcome else 'failure'}")
+        logger.info(
+            f"Recorded outcome for {agent}: {'success' if outcome else 'failure'}"
+        )
 
         # Check if we should create/update a heuristic
         self._maybe_create_heuristic(
@@ -153,7 +164,8 @@ class LearningProtocol:
 
         # Filter to same strategy
         same_strategy = [
-            o for o in similar_outcomes
+            o
+            for o in similar_outcomes
             if self._strategies_similar(o.strategy_used, strategy)
         ]
 
@@ -200,9 +212,11 @@ class LearningProtocol:
 
         # Filter to failures with similar error
         similar = [
-            o for o in similar_failures
-            if not o.success and o.error_message and
-            self._errors_similar(o.error_message, error)
+            o
+            for o in similar_failures
+            if not o.success
+            and o.error_message
+            and self._errors_similar(o.error_message, error)
         ]
 
         if len(similar) >= 2:  # At least 2 similar failures
@@ -311,13 +325,47 @@ class LearningProtocol:
         return "general"
 
     def _strategies_similar(self, s1: str, s2: str) -> bool:
-        """Check if two strategies are similar enough to count together."""
-        # Simple word overlap check - could be improved with embeddings
+        """
+        Check if two strategies are similar enough to count together.
+
+        Uses embedding-based cosine similarity when an embedder is available,
+        otherwise falls back to simple word overlap.
+        """
+        if self.embedder is not None:
+            return self._strategies_similar_embedding(s1, s2)
+        return self._strategies_similar_word_overlap(s1, s2)
+
+    def _strategies_similar_embedding(self, s1: str, s2: str) -> bool:
+        """Check strategy similarity using embedding cosine similarity."""
+        try:
+            emb1 = self.embedder.encode(s1)
+            emb2 = self.embedder.encode(s2)
+            similarity = self._cosine_similarity(emb1, emb2)
+            return similarity >= self.similarity_threshold
+        except Exception as e:
+            logger.warning(
+                f"Embedding similarity failed, falling back to word overlap: {e}"
+            )
+            return self._strategies_similar_word_overlap(s1, s2)
+
+    def _strategies_similar_word_overlap(self, s1: str, s2: str) -> bool:
+        """Check strategy similarity using simple word overlap."""
         words1 = set(s1.lower().split())
         words2 = set(s2.lower().split())
         overlap = len(words1 & words2)
         return overlap >= min(3, len(words1) // 2)
 
+    def _cosine_similarity(self, v1: list, v2: list) -> float:
+        """Compute cosine similarity between two vectors."""
+        import math
+
+        dot_product = sum(a * b for a, b in zip(v1, v2, strict=False))
+        norm1 = math.sqrt(sum(a * a for a in v1))
+        norm2 = math.sqrt(sum(b * b for b in v2))
+        if norm1 == 0 or norm2 == 0:
+            return 0.0
+        return dot_product / (norm1 * norm2)
+
     def _errors_similar(self, e1: str, e2: str) -> bool:
         """Check if two errors are similar."""
         # Simple substring check

alma/learning/validation.py

@@ -5,9 +5,9 @@ Enforces scope constraints and validates learning requests.
 """
 
 import logging
-from typing import Optional, List, Dict, Any, Set
 from dataclasses import dataclass, field
 from enum import Enum
+from typing import Any, Dict, List, Optional, Set
 
 from alma.types import MemoryScope
 
@@ -16,6 +16,7 @@ logger = logging.getLogger(__name__)
 
 class ValidationResult(Enum):
     """Result of a validation check."""
+
     ALLOWED = "allowed"
     DENIED_OUT_OF_SCOPE = "denied_out_of_scope"
     DENIED_FORBIDDEN = "denied_forbidden"
@@ -26,6 +27,7 @@ class ValidationResult(Enum):
 @dataclass
 class ValidationReport:
     """Detailed report of a validation check."""
+
     result: ValidationResult
     agent: str
     domain: str
@@ -36,7 +38,10 @@ class ValidationReport:
     @property
     def is_allowed(self) -> bool:
         """Check if the validation passed."""
-        return self.result in (ValidationResult.ALLOWED, ValidationResult.WARNING_NO_SCOPE)
+        return self.result in (
+            ValidationResult.ALLOWED,
+            ValidationResult.WARNING_NO_SCOPE,
+        )
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary."""

alma/mcp/__init__.py

@@ -24,13 +24,13 @@ Integration with Claude Code (.mcp.json):
 
 from alma.mcp.server import ALMAMCPServer
 from alma.mcp.tools import (
-    alma_retrieve,
-    alma_learn,
-    alma_add_preference,
     alma_add_knowledge,
+    alma_add_preference,
     alma_forget,
-    alma_stats,
     alma_health,
+    alma_learn,
+    alma_retrieve,
+    alma_stats,
 )
 
 __all__ = [

alma/mcp/__main__.py

@@ -78,7 +78,8 @@ Examples:
     )
 
     parser.add_argument(
-        "--verbose", "-v",
+        "--verbose",
+        "-v",
         action="store_true",
         help="Enable verbose logging",
     )

alma/mcp/resources.py

@@ -6,10 +6,9 @@ Resources represent configuration and metadata about the ALMA instance.
 """
 
 import logging
-from typing import Dict, Any, List
+from typing import Any, Dict, List
 
 from alma import ALMA
-from alma.types import MemoryScope
 
 logger = logging.getLogger(__name__)
 
@@ -70,20 +69,22 @@ def get_agents_resource(alma: ALMA) -> Dict[str, Any]:
         except Exception:
             stats = {}
 
-        agents.append({
-            "name": name,
-            "scope": {
-                "can_learn": scope.can_learn,
-                "cannot_learn": scope.cannot_learn,
-                "min_occurrences_for_heuristic": scope.min_occurrences_for_heuristic,
-            },
-            "stats": {
-                "heuristics_count": stats.get("heuristics_count", 0),
-                "outcomes_count": stats.get("outcomes_count", 0),
-                "domain_knowledge_count": stats.get("domain_knowledge_count", 0),
-                "anti_patterns_count": stats.get("anti_patterns_count", 0),
-            },
-        })
+        agents.append(
+            {
+                "name": name,
+                "scope": {
+                    "can_learn": scope.can_learn,
+                    "cannot_learn": scope.cannot_learn,
+                    "min_occurrences_for_heuristic": scope.min_occurrences_for_heuristic,
+                },
+                "stats": {
+                    "heuristics_count": stats.get("heuristics_count", 0),
+                    "outcomes_count": stats.get("outcomes_count", 0),
+                    "domain_knowledge_count": stats.get("domain_knowledge_count", 0),
+                    "anti_patterns_count": stats.get("anti_patterns_count", 0),
+                },
+            }
+        )
 
     return {
         "uri": "alma://agents",

alma/mcp/server.py

@@ -9,23 +9,23 @@ import asyncio
 import json
 import logging
 import sys
-from typing import Dict, Any, Optional, List, Callable
-from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
 
 from alma import ALMA
+from alma.mcp.resources import (
+    get_agents_resource,
+    get_config_resource,
+    list_resources,
+)
 from alma.mcp.tools import (
-    alma_retrieve,
-    alma_learn,
-    alma_add_preference,
     alma_add_knowledge,
+    alma_add_preference,
+    alma_consolidate,
     alma_forget,
-    alma_stats,
     alma_health,
-)
-from alma.mcp.resources import (
-    get_config_resource,
-    get_agents_resource,
-    list_resources,
+    alma_learn,
+    alma_retrieve,
+    alma_stats,
 )
 
 logger = logging.getLogger(__name__)
@@ -235,6 +235,41 @@ class ALMAMCPServer:
                     "properties": {},
                 },
             },
+            {
+                "name": "alma_consolidate",
+                "description": "Consolidate similar memories to reduce redundancy. Merges near-duplicate memories based on semantic similarity. Use dry_run=true first to preview what would be merged.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "agent": {
+                            "type": "string",
+                            "description": "Agent whose memories to consolidate",
+                        },
+                        "memory_type": {
+                            "type": "string",
+                            "enum": [
+                                "heuristics",
+                                "outcomes",
+                                "domain_knowledge",
+                                "anti_patterns",
+                            ],
+                            "description": "Type of memory to consolidate (default: heuristics)",
+                            "default": "heuristics",
+                        },
+                        "similarity_threshold": {
+                            "type": "number",
+                            "description": "Minimum cosine similarity to group memories (0.0-1.0, default: 0.85). Higher values are more conservative.",
+                            "default": 0.85,
+                        },
+                        "dry_run": {
+                            "type": "boolean",
+                            "description": "If true, preview what would be merged without modifying storage (default: true)",
+                            "default": True,
+                        },
+                    },
+                    "required": ["agent"],
+                },
+            },
         ]
 
     async def handle_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
@@ -281,17 +316,20 @@ class ALMAMCPServer:
         params: Dict[str, Any],
     ) -> Dict[str, Any]:
         """Handle initialize request."""
-        return self._success_response(request_id, {
-            "protocolVersion": "2024-11-05",
-            "serverInfo": {
-                "name": self.server_name,
-                "version": self.server_version,
-            },
-            "capabilities": {
-                "tools": {},
-                "resources": {},
+        return self._success_response(
+            request_id,
+            {
+                "protocolVersion": "2024-11-05",
+                "serverInfo": {
+                    "name": self.server_name,
+                    "version": self.server_version,
+                },
+                "capabilities": {
+                    "tools": {},
+                    "resources": {},
+                },
             },
-        })
+        )
 
     def _handle_tools_list(self, request_id: Optional[int]) -> Dict[str, Any]:
         """Handle tools/list request."""
@@ -351,6 +389,13 @@ class ALMAMCPServer:
                 agent=arguments.get("agent"),
             ),
             "alma_health": lambda: alma_health(self.alma),
+            "alma_consolidate": lambda: alma_consolidate(
+                self.alma,
+                agent=arguments.get("agent", ""),
+                memory_type=arguments.get("memory_type", "heuristics"),
+                similarity_threshold=arguments.get("similarity_threshold", 0.85),
+                dry_run=arguments.get("dry_run", True),
+            ),
         }
 
         if tool_name not in tool_handlers:
@@ -362,14 +407,21 @@ class ALMAMCPServer:
 
         result = tool_handlers[tool_name]()
 
-        return self._success_response(request_id, {
-            "content": [
-                {
-                    "type": "text",
-                    "text": json.dumps(result, indent=2),
-                }
-            ],
-        })
+        # Handle async functions (like alma_consolidate)
+        if asyncio.iscoroutine(result):
+            result = await result
+
+        return self._success_response(
+            request_id,
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps(result, indent=2),
+                    }
+                ],
+            },
+        )
 
     def _handle_resources_list(
         self,
@@ -397,15 +449,18 @@ class ALMAMCPServer:
                 f"Unknown resource: {uri}",
             )
 
-        return self._success_response(request_id, {
-            "contents": [
-                {
-                    "uri": resource["uri"],
-                    "mimeType": resource["mimeType"],
-                    "text": json.dumps(resource["content"], indent=2),
-                }
-            ],
-        })
+        return self._success_response(
+            request_id,
+            {
+                "contents": [
+                    {
+                        "uri": resource["uri"],
+                        "mimeType": resource["mimeType"],
+                        "text": json.dumps(resource["content"], indent=2),
+                    }
+                ],
+            },
+        )
 
     def _success_response(
         self,
@@ -437,15 +492,16 @@ class ALMAMCPServer:
 
     async def run_stdio(self):
         """Run the server in stdio mode for Claude Code integration."""
-        logger.info(f"Starting ALMA MCP Server (stdio mode)")
+        logger.info("Starting ALMA MCP Server (stdio mode)")
 
         reader = asyncio.StreamReader()
         protocol = asyncio.StreamReaderProtocol(reader)
-        await asyncio.get_event_loop().connect_read_pipe(
-            lambda: protocol, sys.stdin
-        )
+        await asyncio.get_event_loop().connect_read_pipe(lambda: protocol, sys.stdin)
 
-        writer_transport, writer_protocol = await asyncio.get_event_loop().connect_write_pipe(
+        (
+            writer_transport,
+            writer_protocol,
+        ) = await asyncio.get_event_loop().connect_write_pipe(
             asyncio.streams.FlowControlMixin, sys.stdout
         )
         writer = asyncio.StreamWriter(
@@ -497,7 +553,9 @@ class ALMAMCPServer:
         try:
             from aiohttp import web
         except ImportError:
-            logger.error("aiohttp required for HTTP mode. Install with: pip install aiohttp")
+            logger.error(
+                "aiohttp required for HTTP mode. Install with: pip install aiohttp"
+            )
             return
 
         async def handle_post(request: web.Request) -> web.Response: