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

alma/retrieval/engine.py

@@ -4,14 +4,14 @@ ALMA Retrieval Engine.
 Handles semantic search and memory retrieval with scoring and caching.
 """
 
-import time
 import logging
-from typing import Optional, List, Dict, Any
+import time
+from typing import Any, Dict, List, Optional
 
-from alma.types import MemorySlice, MemoryScope
+from alma.retrieval.cache import NullCache, RetrievalCache
+from alma.retrieval.scoring import MemoryScorer, ScoredItem, ScoringWeights
 from alma.storage.base import StorageBackend
-from alma.retrieval.scoring import MemoryScorer, ScoringWeights, ScoredItem
-from alma.retrieval.cache import RetrievalCache, NullCache
+from alma.types import MemoryScope, MemorySlice
 
 logger = logging.getLogger(__name__)
 
@@ -81,18 +81,24 @@ class RetrievalEngine:
         top_k: int = 5,
         scope: Optional[MemoryScope] = None,
         bypass_cache: bool = False,
+        include_shared: bool = True,
     ) -> MemorySlice:
         """
         Retrieve relevant memories for a task.
 
+        Supports multi-agent memory sharing: if a scope is provided with
+        inherit_from agents, memories from those agents will also be included.
+        Shared memories have their origin tracked in the metadata['shared_from'] field.
+
         Args:
             query: Task description to find relevant memories for
             agent: Agent requesting memories
             project_id: Project context
             user_id: Optional user for preference retrieval
             top_k: Max items per memory type
-            scope: Agent's learning scope for filtering
+            scope: Agent's learning scope for filtering (enables multi-agent sharing)
             bypass_cache: Skip cache lookup/storage
+            include_shared: If True and scope has inherit_from, include shared memories
 
         Returns:
             MemorySlice with relevant memories, scored and ranked
@@ -110,36 +116,79 @@ class RetrievalEngine:
         # Generate embedding for query
         query_embedding = self._get_embedding(query)
 
-        # Retrieve raw items from storage (with vector search)
-        raw_heuristics = self.storage.get_heuristics(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,  # Get extra for scoring/filtering
-            min_confidence=0.0,  # Let scorer handle filtering
-        )
-
-        raw_outcomes = self.storage.get_outcomes(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-            success_only=False,
-        )
+        # Determine which agents to query based on scope
+        agents_to_query = [agent]
+        if include_shared and scope and scope.inherit_from:
+            agents_to_query = scope.get_readable_agents()
+            logger.debug(
+                f"Multi-agent retrieval for {agent}: querying {agents_to_query}"
+            )
 
-        raw_domain_knowledge = self.storage.get_domain_knowledge(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-        )
+        # Retrieve raw items from storage (with vector search)
+        if len(agents_to_query) > 1:
+            # Use multi-agent query methods
+            raw_heuristics = self.storage.get_heuristics_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                min_confidence=0.0,
+            )
+            raw_outcomes = self.storage.get_outcomes_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                success_only=False,
+            )
+            raw_domain_knowledge = self.storage.get_domain_knowledge_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
+            raw_anti_patterns = self.storage.get_anti_patterns_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
 
-        raw_anti_patterns = self.storage.get_anti_patterns(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-        )
+            # Mark shared memories with origin tracking
+            raw_heuristics = self._mark_shared_memories(raw_heuristics, agent)
+            raw_outcomes = self._mark_shared_memories(raw_outcomes, agent)
+            raw_domain_knowledge = self._mark_shared_memories(
+                raw_domain_knowledge, agent
+            )
+            raw_anti_patterns = self._mark_shared_memories(raw_anti_patterns, agent)
+        else:
+            # Single agent query (original behavior)
+            raw_heuristics = self.storage.get_heuristics(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                min_confidence=0.0,
+            )
+            raw_outcomes = self.storage.get_outcomes(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                success_only=False,
+            )
+            raw_domain_knowledge = self.storage.get_domain_knowledge(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
+            raw_anti_patterns = self.storage.get_anti_patterns(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
 
         # Score and rank each type
         scored_heuristics = self.scorer.score_heuristics(raw_heuristics)
@@ -182,6 +231,31 @@ class RetrievalEngine:
 
         return result
 
+    def _mark_shared_memories(
+        self,
+        memories: List[Any],
+        requesting_agent: str,
+    ) -> List[Any]:
+        """
+        Mark memories that came from other agents with their origin.
+
+        Adds 'shared_from' to metadata for memories not owned by requesting_agent.
+        This maintains write isolation - only the owning agent can modify their memories.
+
+        Args:
+            memories: List of memory objects (Heuristic, Outcome, etc.)
+            requesting_agent: The agent that requested the memories
+
+        Returns:
+            Same memories with shared_from metadata added where applicable
+        """
+        for memory in memories:
+            if hasattr(memory, "agent") and memory.agent != requesting_agent:
+                if not hasattr(memory, "metadata") or memory.metadata is None:
+                    memory.metadata = {}
+                memory.metadata["shared_from"] = memory.agent
+        return memories
+
     def _extract_top_k(
         self,
         scored_items: List[ScoredItem],
@@ -217,12 +291,15 @@ class RetrievalEngine:
         """Initialize the embedding model based on provider config."""
         if self.embedding_provider == "azure":
             from alma.retrieval.embeddings import AzureEmbedder
+
             return AzureEmbedder()
         elif self.embedding_provider == "mock":
             from alma.retrieval.embeddings import MockEmbedder
+
             return MockEmbedder()
         else:
             from alma.retrieval.embeddings import LocalEmbedder
+
             return LocalEmbedder()
 
     def invalidate_cache(
@@ -280,7 +357,9 @@ class RetrievalEngine:
         self.scorer.weights = ScoringWeights(
             similarity=similarity if similarity is not None else current.similarity,
             recency=recency if recency is not None else current.recency,
-            success_rate=success_rate if success_rate is not None else current.success_rate,
+            success_rate=(
+                success_rate if success_rate is not None else current.success_rate
+            ),
             confidence=confidence if confidence is not None else current.confidence,
         )
         # Clear cache since scoring changed

alma/retrieval/scoring.py

@@ -5,11 +5,11 @@ Combines semantic similarity, recency, and success rate for optimal retrieval.
 """
 
 import math
-from datetime import datetime, timezone
-from typing import List, Dict, Any, Optional, TypeVar, Callable
 from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, List, Optional
 
-from alma.types import Heuristic, Outcome, DomainKnowledge, AntiPattern
+from alma.types import AntiPattern, DomainKnowledge, Heuristic, Outcome
 
 
 @dataclass
@@ -19,10 +19,11 @@ class ScoringWeights:
 
     All weights should sum to 1.0 for normalized scores.
     """
-    similarity: float = 0.4      # Semantic relevance to query
-    recency: float = 0.3         # How recently the memory was validated/used
-    success_rate: float = 0.2    # Historical success rate
-    confidence: float = 0.1      # Stored confidence score
+
+    similarity: float = 0.4  # Semantic relevance to query
+    recency: float = 0.3  # How recently the memory was validated/used
+    success_rate: float = 0.2  # Historical success rate
+    confidence: float = 0.1  # Stored confidence score
 
     def __post_init__(self):
         """Validate weights sum to approximately 1.0."""
@@ -38,6 +39,7 @@ class ScoringWeights:
 @dataclass
 class ScoredItem:
     """A memory item with its computed score."""
+
     item: Any
     score: float
     similarity_score: float
@@ -93,26 +95,28 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(heuristics)
         scored = []
 
-        for h, sim in zip(heuristics, similarities):
+        for h, sim in zip(heuristics, similarities, strict=False):
             recency = self._compute_recency_score(h.last_validated)
             success = h.success_rate
             confidence = h.confidence
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=h,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=h,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -140,7 +144,7 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(outcomes)
         scored = []
 
-        for o, sim in zip(outcomes, similarities):
+        for o, sim in zip(outcomes, similarities, strict=False):
             recency = self._compute_recency_score(o.timestamp)
             # Success gets full score, failure gets partial (still useful to learn from)
             success = 1.0 if o.success else 0.3
@@ -148,20 +152,22 @@ class MemoryScorer:
             confidence = 1.0
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=o,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=o,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -186,27 +192,29 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(knowledge)
         scored = []
 
-        for dk, sim in zip(knowledge, similarities):
+        for dk, sim in zip(knowledge, similarities, strict=False):
             recency = self._compute_recency_score(dk.last_verified)
             # Knowledge doesn't have success rate, use 1.0
             success = 1.0
             confidence = dk.confidence
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=dk,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=dk,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -233,7 +241,7 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(anti_patterns)
         scored = []
 
-        for ap, sim in zip(anti_patterns, similarities):
+        for ap, sim in zip(anti_patterns, similarities, strict=False):
             recency = self._compute_recency_score(ap.last_seen)
             # More occurrences = more important to avoid
             # Normalize occurrence count (cap at 10 for scoring)
@@ -241,20 +249,22 @@ class MemoryScorer:
             confidence = 1.0
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=ap,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=ap,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -327,8 +337,8 @@ def compute_composite_score(
     recency_score = math.pow(0.5, recency_days / recency_half_life)
 
     return (
-        weights.similarity * similarity +
-        weights.recency * recency_score +
-        weights.success_rate * success_rate +
-        weights.confidence * confidence
+        weights.similarity * similarity
+        + weights.recency * recency_score
+        + weights.success_rate * success_rate
+        + weights.confidence * confidence
     )

alma/session/__init__.py

@@ -4,12 +4,12 @@ ALMA Session Management Module.
 Handles session continuity, handoffs, and quick context reload.
 """
 
+from alma.session.manager import SessionManager
 from alma.session.types import (
-    SessionHandoff,
     SessionContext,
+    SessionHandoff,
     SessionOutcome,
 )
-from alma.session.manager import SessionManager
 
 __all__ = [
     "SessionHandoff",

alma/session/manager.py

@@ -4,14 +4,14 @@ Session Manager.
 Manages session continuity, handoffs, and quick context reload.
 """
 
-from datetime import datetime, timezone
-from typing import Optional, List, Dict, Any, Callable
-import uuid
 import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
 
 from alma.session.types import (
-    SessionHandoff,
     SessionContext,
+    SessionHandoff,
     SessionOutcome,
 )
 
@@ -281,7 +281,7 @@ class SessionManager:
 
         # Trim to max
         if len(self._handoffs[agent]) > self.max_handoffs:
-            self._handoffs[agent] = self._handoffs[agent][-self.max_handoffs:]
+            self._handoffs[agent] = self._handoffs[agent][-self.max_handoffs :]
 
         # TODO: Persist to storage backend when integrated
 

alma/session/types.py

@@ -4,11 +4,10 @@ Session Management Types.
 Data models for session continuity and handoffs.
 """
 
+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
 
 SessionOutcome = Literal["success", "failure", "interrupted", "unknown"]
 
@@ -276,7 +275,9 @@ class SessionContext:
             if "branch" in self.codebase_state:
                 lines.append(f"Branch: {self.codebase_state['branch']}")
             if "uncommitted" in self.codebase_state:
-                lines.append(f"Uncommitted Changes: {self.codebase_state['uncommitted']}")
+                lines.append(
+                    f"Uncommitted Changes: {self.codebase_state['uncommitted']}"
+                )
 
         # Rules
         if self.rules_of_engagement:

alma/storage/__init__.py

@@ -7,14 +7,55 @@ from alma.storage.sqlite_local import SQLiteStorage
 # Azure Cosmos DB is optional - requires azure-cosmos package
 try:
     from alma.storage.azure_cosmos import AzureCosmosStorage
+
     _HAS_AZURE = True
 except ImportError:
     AzureCosmosStorage = None  # type: ignore
     _HAS_AZURE = False
 
+# PostgreSQL is optional - requires psycopg package
+try:
+    from alma.storage.postgresql import PostgreSQLStorage
+
+    _HAS_POSTGRES = True
+except ImportError:
+    PostgreSQLStorage = None  # type: ignore
+    _HAS_POSTGRES = False
+
+# Qdrant is optional - requires qdrant-client package
+try:
+    from alma.storage.qdrant import QdrantStorage
+
+    _HAS_QDRANT = True
+except ImportError:
+    QdrantStorage = None  # type: ignore
+    _HAS_QDRANT = False
+
+# ChromaDB is optional - requires chromadb package
+try:
+    from alma.storage.chroma import ChromaStorage
+
+    _HAS_CHROMA = True
+except ImportError:
+    ChromaStorage = None  # type: ignore
+    _HAS_CHROMA = False
+
+# Pinecone is optional - requires pinecone-client package
+try:
+    from alma.storage.pinecone import PineconeStorage
+
+    _HAS_PINECONE = True
+except ImportError:
+    PineconeStorage = None  # type: ignore
+    _HAS_PINECONE = False
+
 __all__ = [
     "StorageBackend",
     "FileBasedStorage",
     "SQLiteStorage",
     "AzureCosmosStorage",
+    "PostgreSQLStorage",
+    "QdrantStorage",
+    "ChromaStorage",
+    "PineconeStorage",
 ]