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

alma/mcp/tools.py

@@ -5,11 +5,9 @@ Provides the tool functions that can be called via MCP protocol.
 Each tool corresponds to an ALMA operation.
 """
 
-import json
 import logging
-from typing import Dict, Any, Optional, List
 from datetime import datetime, timezone
-from dataclasses import asdict
+from typing import Any, Dict, Optional
 
 from alma import ALMA
 from alma.types import MemorySlice
@@ -32,47 +30,57 @@ def _serialize_memory_slice(memory_slice: MemorySlice) -> Dict[str, Any]:
     }
 
     for h in memory_slice.heuristics:
-        result["heuristics"].append({
-            "id": h.id,
-            "condition": h.condition,
-            "strategy": h.strategy,
-            "confidence": h.confidence,
-            "occurrence_count": h.occurrence_count,
-            "success_rate": h.success_rate,
-        })
+        result["heuristics"].append(
+            {
+                "id": h.id,
+                "condition": h.condition,
+                "strategy": h.strategy,
+                "confidence": h.confidence,
+                "occurrence_count": h.occurrence_count,
+                "success_rate": h.success_rate,
+            }
+        )
 
     for o in memory_slice.outcomes:
-        result["outcomes"].append({
-            "id": o.id,
-            "task_type": o.task_type,
-            "task_description": o.task_description,
-            "success": o.success,
-            "strategy_used": o.strategy_used,
-            "duration_ms": o.duration_ms,
-        })
+        result["outcomes"].append(
+            {
+                "id": o.id,
+                "task_type": o.task_type,
+                "task_description": o.task_description,
+                "success": o.success,
+                "strategy_used": o.strategy_used,
+                "duration_ms": o.duration_ms,
+            }
+        )
 
     for dk in memory_slice.domain_knowledge:
-        result["domain_knowledge"].append({
-            "id": dk.id,
-            "domain": dk.domain,
-            "fact": dk.fact,
-            "confidence": dk.confidence,
-        })
+        result["domain_knowledge"].append(
+            {
+                "id": dk.id,
+                "domain": dk.domain,
+                "fact": dk.fact,
+                "confidence": dk.confidence,
+            }
+        )
 
     for ap in memory_slice.anti_patterns:
-        result["anti_patterns"].append({
-            "id": ap.id,
-            "pattern": ap.pattern,
-            "why_bad": ap.why_bad,
-            "better_alternative": ap.better_alternative,
-        })
+        result["anti_patterns"].append(
+            {
+                "id": ap.id,
+                "pattern": ap.pattern,
+                "why_bad": ap.why_bad,
+                "better_alternative": ap.better_alternative,
+            }
+        )
 
     for p in memory_slice.preferences:
-        result["preferences"].append({
-            "id": p.id,
-            "category": p.category,
-            "preference": p.preference,
-        })
+        result["preferences"].append(
+            {
+                "id": p.id,
+                "category": p.category,
+                "preference": p.preference,
+            }
+        )
 
     return result
 
@@ -97,6 +105,12 @@ def alma_retrieve(
     Returns:
         Dict containing the memory slice with relevant memories
     """
+    # Input validation
+    if not task or not task.strip():
+        return {"success": False, "error": "task cannot be empty"}
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+
     try:
         memories = alma.retrieve(
             task=task,
@@ -147,6 +161,16 @@ def alma_learn(
     Returns:
         Dict with learning result
     """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+    if not task or not task.strip():
+        return {"success": False, "error": "task cannot be empty"}
+    if not outcome or not outcome.strip():
+        return {"success": False, "error": "outcome cannot be empty"}
+    if not strategy_used or not strategy_used.strip():
+        return {"success": False, "error": "strategy_used cannot be empty"}
+
     try:
         result = alma.learn(
             agent=agent,
@@ -162,7 +186,9 @@ def alma_learn(
         return {
             "success": True,
             "learned": result,
-            "message": "Outcome recorded" if result else "Learning rejected (scope violation)",
+            "message": (
+                "Outcome recorded" if result else "Learning rejected (scope violation)"
+            ),
         }
 
     except Exception as e:
@@ -193,6 +219,14 @@ def alma_add_preference(
     Returns:
         Dict with the created preference
     """
+    # Input validation
+    if not user_id or not user_id.strip():
+        return {"success": False, "error": "user_id cannot be empty"}
+    if not category or not category.strip():
+        return {"success": False, "error": "category cannot be empty"}
+    if not preference or not preference.strip():
+        return {"success": False, "error": "preference cannot be empty"}
+
     try:
         pref = alma.add_user_preference(
             user_id=user_id,
@@ -240,6 +274,14 @@ def alma_add_knowledge(
     Returns:
         Dict with the created knowledge or rejection reason
     """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+    if not domain or not domain.strip():
+        return {"success": False, "error": "domain cannot be empty"}
+    if not fact or not fact.strip():
+        return {"success": False, "error": "fact cannot be empty"}
+
     try:
         knowledge = alma.add_domain_knowledge(
             agent=agent,
@@ -372,3 +414,98 @@ def alma_health(alma: ALMA) -> Dict[str, Any]:
             "status": "unhealthy",
             "error": str(e),
         }
+
+
+async def alma_consolidate(
+    alma: ALMA,
+    agent: str,
+    memory_type: str = "heuristics",
+    similarity_threshold: float = 0.85,
+    dry_run: bool = True,
+) -> Dict[str, Any]:
+    """
+    Consolidate similar memories to reduce redundancy.
+
+    This is ALMA's implementation of Mem0's core innovation - LLM-powered
+    deduplication that merges similar memories intelligently.
+
+    Args:
+        alma: ALMA instance
+        agent: Agent whose memories to consolidate
+        memory_type: Type of memory to consolidate
+                    ("heuristics", "outcomes", "domain_knowledge", "anti_patterns")
+        similarity_threshold: Minimum cosine similarity to group (0.0 to 1.0)
+                             Higher values are more conservative (fewer merges)
+        dry_run: If True, report what would be merged without actually modifying storage
+                 Recommended for first run to preview changes
+
+    Returns:
+        Dict with consolidation results including:
+        - merged_count: Number of memories merged
+        - groups_found: Number of similar memory groups identified
+        - memories_processed: Total memories analyzed
+        - merge_details: List of merge operations (or planned operations if dry_run)
+        - errors: Any errors encountered
+    """
+    # Input validation
+    if not agent or not agent.strip():
+        return {"success": False, "error": "agent cannot be empty"}
+
+    valid_types = ["heuristics", "outcomes", "domain_knowledge", "anti_patterns"]
+    if memory_type not in valid_types:
+        return {
+            "success": False,
+            "error": f"memory_type must be one of: {', '.join(valid_types)}",
+        }
+
+    if not 0.0 <= similarity_threshold <= 1.0:
+        return {
+            "success": False,
+            "error": "similarity_threshold must be between 0.0 and 1.0",
+        }
+
+    try:
+        from alma.consolidation import ConsolidationEngine
+
+        # Create consolidation engine
+        engine = ConsolidationEngine(
+            storage=alma.storage,
+            embedder=None,  # Will use default LocalEmbedder
+            llm_client=None,  # LLM merging disabled by default
+        )
+
+        # Run consolidation
+        result = await engine.consolidate(
+            agent=agent,
+            project_id=alma.project_id,
+            memory_type=memory_type,
+            similarity_threshold=similarity_threshold,
+            use_llm=False,  # LLM disabled - uses highest confidence merge
+            dry_run=dry_run,
+        )
+
+        # Invalidate cache after consolidation (if not dry run)
+        if not dry_run and result.merged_count > 0:
+            alma.retrieval.invalidate_cache(agent=agent, project_id=alma.project_id)
+
+        return {
+            "success": result.success,
+            "dry_run": dry_run,
+            "merged_count": result.merged_count,
+            "groups_found": result.groups_found,
+            "memories_processed": result.memories_processed,
+            "merge_details": result.merge_details,
+            "errors": result.errors,
+            "message": (
+                f"{'Would merge' if dry_run else 'Merged'} {result.merged_count} memories "
+                f"from {result.groups_found} similar groups "
+                f"(processed {result.memories_processed} total)"
+            ),
+        }
+
+    except Exception as e:
+        logger.exception(f"Error in alma_consolidate: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+        }

alma/progress/__init__.py

@@ -4,13 +4,13 @@ ALMA Progress Tracking Module.
 Track work items, progress, and suggest next actions.
 """
 
+from alma.progress.tracker import ProgressTracker
 from alma.progress.types import (
-    WorkItem,
-    WorkItemStatus,
     ProgressLog,
     ProgressSummary,
+    WorkItem,
+    WorkItemStatus,
 )
-from alma.progress.tracker import ProgressTracker
 
 __all__ = [
     "WorkItem",

alma/progress/tracker.py

@@ -5,27 +5,25 @@ Manages work items and provides progress tracking functionality.
 """
 
 import logging
-import uuid
 from datetime import datetime, timezone
-from typing import Optional, List, Dict, Any, Literal
+from typing import Any, Dict, List, Literal, Optional
 
 from alma.progress.types import (
-    WorkItem,
-    WorkItemStatus,
     ProgressLog,
     ProgressSummary,
+    WorkItem,
+    WorkItemStatus,
 )
 from alma.storage.base import StorageBackend
 
-
 logger = logging.getLogger(__name__)
 
 
 SelectionStrategy = Literal[
-    "priority",         # Highest priority first
+    "priority",  # Highest priority first
     "blocked_unblock",  # Items that unblock others
-    "quick_win",        # Smallest/easiest first
-    "fifo",             # First in, first out
+    "quick_win",  # Smallest/easiest first
+    "fifo",  # First in, first out
 ]
 
 
@@ -176,12 +174,14 @@ class ProgressTracker:
         if notes:
             if "status_notes" not in item.metadata:
                 item.metadata["status_notes"] = []
-            item.metadata["status_notes"].append({
-                "from": old_status,
-                "to": status,
-                "notes": notes,
-                "timestamp": datetime.now(timezone.utc).isoformat(),
-            })
+            item.metadata["status_notes"].append(
+                {
+                    "from": old_status,
+                    "to": status,
+                    "notes": notes,
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                }
+            )
 
         logger.info(f"Status updated: {item_id} {old_status} -> {status}")
         return item
@@ -262,7 +262,8 @@ class ProgressTracker:
     ) -> List[WorkItem]:
         """Get items that can be worked on (not blocked, not done)."""
         return [
-            item for item in self._work_items.values()
+            item
+            for item in self._work_items.values()
             if item.is_actionable()
             and (agent is None or item.agent == agent or item.agent is None)
         ]
@@ -312,7 +313,8 @@ class ProgressTracker:
             unblock_counts = {}
             for item in actionable:
                 count = sum(
-                    1 for other in self._work_items.values()
+                    1
+                    for other in self._work_items.values()
                     if item.id in other.blocked_by
                 )
                 unblock_counts[item.id] = count
@@ -439,9 +441,9 @@ class ProgressTracker:
         logs = self._progress_logs
 
         if agent:
-            logs = [l for l in logs if l.agent == agent]
+            logs = [log for log in logs if log.agent == agent]
         if session_id:
-            logs = [l for l in logs if l.session_id == session_id]
+            logs = [log for log in logs if log.session_id == session_id]
 
         # Sort by created_at descending and limit
         logs.sort(key=lambda x: x.created_at, reverse=True)
@@ -530,8 +532,12 @@ class ProgressTracker:
                     "attempt_count": item.attempt_count,
                     "created_at": item.created_at.isoformat(),
                     "updated_at": item.updated_at.isoformat(),
-                    "started_at": item.started_at.isoformat() if item.started_at else None,
-                    "completed_at": item.completed_at.isoformat() if item.completed_at else None,
+                    "started_at": (
+                        item.started_at.isoformat() if item.started_at else None
+                    ),
+                    "completed_at": (
+                        item.completed_at.isoformat() if item.completed_at else None
+                    ),
                     "metadata": item.metadata,
                 }
                 for item in self._work_items.values()

alma/progress/types.py

@@ -4,19 +4,18 @@ Progress Tracking Types.
 Data models for tracking work items and progress.
 """
 
+import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Optional, List, Dict, Any, Literal
-import uuid
-
+from typing import Any, Dict, List, Literal, Optional
 
 WorkItemStatus = Literal[
-    "pending",      # Not started
+    "pending",  # Not started
     "in_progress",  # Currently being worked on
-    "blocked",      # Waiting on something
-    "review",       # Completed, awaiting review
-    "done",         # Completed and verified
-    "failed",       # Could not complete
+    "blocked",  # Waiting on something
+    "review",  # Completed, awaiting review
+    "done",  # Completed and verified
+    "failed",  # Could not complete
 ]
 
 
@@ -124,10 +123,7 @@ class WorkItem:
 
     def is_actionable(self) -> bool:
         """Check if work item can be worked on."""
-        return (
-            self.status in ("pending", "in_progress")
-            and len(self.blocked_by) == 0
-        )
+        return self.status in ("pending", "in_progress") and len(self.blocked_by) == 0
 
 
 @dataclass

alma/retrieval/__init__.py

@@ -4,29 +4,29 @@ ALMA Retrieval Engine.
 Provides semantic search, scoring, and caching for memory retrieval.
 """
 
-from alma.retrieval.engine import RetrievalEngine
-from alma.retrieval.scoring import (
-    MemoryScorer,
-    ScoringWeights,
-    ScoredItem,
-    compute_composite_score,
-)
 from alma.retrieval.cache import (
     CacheBackend,
-    RetrievalCache,
-    RedisCache,
-    NullCache,
     CacheEntry,
     CacheStats,
+    NullCache,
     PerformanceMetrics,
+    RedisCache,
+    RetrievalCache,
     create_cache,
 )
 from alma.retrieval.embeddings import (
+    AzureEmbedder,
     EmbeddingProvider,
     LocalEmbedder,
-    AzureEmbedder,
     MockEmbedder,
 )
+from alma.retrieval.engine import RetrievalEngine
+from alma.retrieval.scoring import (
+    MemoryScorer,
+    ScoredItem,
+    ScoringWeights,
+    compute_composite_score,
+)
 
 __all__ = [
     # Engine

alma/retrieval/cache.py

@@ -5,16 +5,15 @@ Multi-backend caching layer for retrieval results with TTL-based expiration.
 Supports in-memory and Redis backends with performance monitoring.
 """
 
-import time
-import json
 import hashlib
-import threading
+import json
 import logging
+import threading
+import time
 from abc import ABC, abstractmethod
-from typing import Optional, Dict, Any, List, Callable, Tuple
-from dataclasses import dataclass, field, asdict
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from contextlib import contextmanager
+from typing import Any, Callable, Dict, List, Optional
 
 from alma.types import MemorySlice
 
@@ -27,6 +26,7 @@ logger = logging.getLogger(__name__)
 @dataclass
 class CacheEntry:
     """A cached retrieval result with metadata."""
+
     result: MemorySlice
     created_at: float  # time.time() timestamp
     expires_at: float
@@ -41,6 +41,7 @@ class CacheEntry:
 @dataclass
 class CacheStats:
     """Statistics about cache performance."""
+
     hits: int = 0
     misses: int = 0
     evictions: int = 0
@@ -81,6 +82,7 @@ class CacheStats:
 @dataclass
 class PerformanceMetrics:
     """Tracks timing metrics for performance analysis."""
+
     get_times: List[float] = field(default_factory=list)
     set_times: List[float] = field(default_factory=list)
     max_samples: int = 1000
@@ -89,13 +91,13 @@ class PerformanceMetrics:
         """Record a get operation time."""
         self.get_times.append(duration_ms)
         if len(self.get_times) > self.max_samples:
-            self.get_times = self.get_times[-self.max_samples:]
+            self.get_times = self.get_times[-self.max_samples :]
 
     def record_set(self, duration_ms: float):
         """Record a set operation time."""
         self.set_times.append(duration_ms)
         if len(self.set_times) > self.max_samples:
-            self.set_times = self.set_times[-self.max_samples:]
+            self.set_times = self.set_times[-self.max_samples :]
 
     def get_percentile(self, times: List[float], percentile: float) -> float:
         """Calculate percentile from timing data."""
@@ -430,9 +432,7 @@ class RetrievalCache(CacheBackend):
         """Remove all expired entries."""
         now = time.time()
         expired = [
-            (key, entry)
-            for key, entry in self._cache.items()
-            if now > entry.expires_at
+            (key, entry) for key, entry in self._cache.items() if now > entry.expires_at
         ]
 
         for key, entry in expired:
@@ -587,13 +587,12 @@ class RedisCache(CacheBackend):
             # Test connection
             self._redis.ping()
             logger.info(f"Connected to Redis at {host}:{port}")
-        except ImportError:
+        except ImportError as err:
             raise ImportError(
-                "redis package required for RedisCache. "
-                "Install with: pip install redis"
-            )
+                "redis package required for RedisCache. Install with: pip install redis"
+            ) from err
         except Exception as e:
-            raise ConnectionError(f"Failed to connect to Redis: {e}")
+            raise ConnectionError(f"Failed to connect to Redis: {e}") from e
 
     def set_hooks(
         self,
@@ -641,9 +640,9 @@ class RedisCache(CacheBackend):
                     "confidence": h.confidence,
                     "occurrence_count": h.occurrence_count,
                     "success_count": h.success_count,
-                    "last_validated": h.last_validated.isoformat()
-                    if h.last_validated
-                    else None,
+                    "last_validated": (
+                        h.last_validated.isoformat() if h.last_validated else None
+                    ),
                     "created_at": h.created_at.isoformat() if h.created_at else None,
                 }
                 for h in result.heuristics
@@ -703,11 +702,11 @@ class RedisCache(CacheBackend):
     def _deserialize_result(self, data: bytes) -> MemorySlice:
         """Deserialize bytes to MemorySlice."""
         from alma.types import (
+            AntiPattern,
+            DomainKnowledge,
             Heuristic,
             Outcome,
             UserPreference,
-            DomainKnowledge,
-            AntiPattern,
         )
 
         obj = json.loads(data.decode("utf-8"))

alma/retrieval/embeddings.py

@@ -59,11 +59,11 @@ class LocalEmbedder(EmbeddingProvider):
                 self._model = SentenceTransformer(self.model_name)
                 self._dimension = self._model.get_sentence_embedding_dimension()
                 logger.info(f"Model loaded, dimension: {self._dimension}")
-            except ImportError:
+            except ImportError as err:
                 raise ImportError(
                     "sentence-transformers is required for local embeddings. "
                     "Install with: pip install sentence-transformers"
-                )
+                ) from err
 
     def encode(self, text: str) -> List[float]:
         """Generate embedding for text."""
@@ -134,11 +134,11 @@ class AzureEmbedder(EmbeddingProvider):
                     api_key=self.api_key,
                     api_version=self.api_version,
                 )
-            except ImportError:
+            except ImportError as err:
                 raise ImportError(
                     "openai is required for Azure embeddings. "
                     "Install with: pip install openai"
-                )
+                ) from err
         return self._client
 
     def encode(self, text: str) -> List[float]: