alma-memory 0.5.0__tar.gz → 0.5.1__tar.gz

{alma_memory-0.5.0 → alma_memory-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alma-memory
-Version: 0.5.0
+Version: 0.5.1
 Summary: Agent Learning Memory Architecture - Persistent memory for AI agents
 Author-email: RBKunnela <aiagentsprompt@gmail.com>
 License: MIT
@@ -41,6 +41,10 @@ Requires-Dist: pinecone>=3.0.0; extra == "pinecone"
 Provides-Extra: mcp
 Requires-Dist: pydantic>=2.0.0; extra == "mcp"
 Requires-Dist: aiohttp>=3.9.0; extra == "mcp"
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "observability"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -52,7 +56,7 @@ Requires-Dist: black>=24.0.0; extra == "dev"
 Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
 Requires-Dist: numpy>=1.24.0; extra == "dev"
 Provides-Extra: all
-Requires-Dist: alma-memory[azure,chroma,dev,local,mcp,pinecone,postgres,qdrant]; extra == "all"
+Requires-Dist: alma-memory[azure,chroma,dev,local,mcp,observability,pinecone,postgres,qdrant]; extra == "all"
 
 # ALMA - Agent Learning Memory Architecture
 
@@ -79,7 +83,7 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 | **Event System** | Webhooks + in-process callbacks | None | React to memory changes in real-time |
 | **TypeScript SDK** | Full-featured client library | None | First-class JavaScript/TypeScript support |
 | **Vector DB Support** | 6 backends (PostgreSQL, Qdrant, Pinecone, Chroma, SQLite, Azure) | Limited | Deploy anywhere |
-| **Graph Memory** | Pluggable backends (Neo4j, In-memory) | Limited | Entity relationship tracking |
+| **Graph Memory** | Pluggable backends (Neo4j, Memgraph, Kuzu, In-memory) | Limited | Entity relationship tracking |
 | **Harness Pattern** | Decouples agent from domain memory | None | Reusable agent architecture |
 | **MCP Integration** | Native stdio/HTTP server | None | Direct Claude Code integration |
 | **Domain Memory Factory** | 6 pre-built schemas | None | Instant setup for any domain |
@@ -111,9 +115,16 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 - **Graph Database Abstraction** (`alma/graph/`)
   - Pluggable `GraphBackend` interface
   - Neo4j backend for production
+  - Memgraph backend for high-performance in-memory graphs
+  - Kuzu backend for embedded graph storage (no server required)
   - In-memory backend for testing
   - Factory function `create_graph_backend()` for easy setup
 
+- **Testing Module** (`alma/testing/`)
+  - `MockStorage` - In-memory storage backend for isolated testing
+  - `MockEmbedder` - Deterministic fake embedding provider
+  - Factory functions for creating test data with sensible defaults
+
 ### Phase 1: Core Features
 
 - **Memory Consolidation Engine** (`alma/consolidation/`)
@@ -434,14 +445,23 @@ Capture entity relationships for complex reasoning:
 ```python
 from alma.graph import create_graph_backend, BackendGraphStore, EntityExtractor
 
-# Create graph backend (Neo4j for production, memory for testing)
+# Create graph backend - multiple options available:
+
+# Neo4j (production, hosted)
 backend = create_graph_backend(
     "neo4j",
     uri="neo4j+s://xxx.databases.neo4j.io",
     username="neo4j",
     password="your-password"
 )
-# Or for testing:
+
+# Memgraph (high-performance, in-memory)
+# backend = create_graph_backend("memgraph", uri="bolt://localhost:7687")
+
+# Kuzu (embedded, no server required)
+# backend = create_graph_backend("kuzu", database_path="./my_graph_db")
+
+# In-memory (testing)
 # backend = create_graph_backend("memory")
 
 # Create store with backend
@@ -693,9 +713,12 @@ print(f"Recommendation: {signal.recommendation}")
 |  +---------------+  +------------------+  +---------------+             |
 +-------------------------------------------------------------------------+
 |  GRAPH LAYER                                                            |
-|  +---------------+  +------------------+                                |
-|  |    Neo4j      |  |   In-Memory      |                                |
-|  +---------------+  +------------------+                                |
+|  +---------------+  +------------------+  +---------------+             |
+|  |    Neo4j      |  |    Memgraph      |  |     Kuzu      |             |
+|  +---------------+  +------------------+  +---------------+             |
+|  +---------------+                                                      |
+|  |   In-Memory   |                                                      |
+|  +---------------+                                                      |
 +-------------------------------------------------------------------------+
 |  INTEGRATION LAYER                                                      |
 |  +-------------------------------------------------------------------+  |
@@ -819,6 +842,7 @@ chroma:
 | Pinecone Backend | Serverless vector DB | Done |
 | Chroma Backend | Lightweight vector DB | Done |
 | Graph Abstraction | Pluggable graph backends | Done |
+| Testing Module | Mocks and factories for testing | Done |
 
 ---
 
@@ -850,6 +874,16 @@ docker run -p 6333:6333 qdrant/qdrant
 - Ensure `embedding_dim` in config matches your embedding provider
 - Local: 384, Azure text-embedding-3-small: 1536
 
+**Memgraph connection refused**
+```bash
+# Start Memgraph with Docker
+docker run -p 7687:7687 memgraph/memgraph-mage
+```
+
+**Kuzu database locked**
+- Ensure only one process accesses the database at a time
+- Use `read_only=True` for concurrent read access
+
 ### Debug Logging
 
 ```python

{alma_memory-0.5.0 → alma_memory-0.5.1}/README.md

@@ -23,7 +23,7 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 | **Event System** | Webhooks + in-process callbacks | None | React to memory changes in real-time |
 | **TypeScript SDK** | Full-featured client library | None | First-class JavaScript/TypeScript support |
 | **Vector DB Support** | 6 backends (PostgreSQL, Qdrant, Pinecone, Chroma, SQLite, Azure) | Limited | Deploy anywhere |
-| **Graph Memory** | Pluggable backends (Neo4j, In-memory) | Limited | Entity relationship tracking |
+| **Graph Memory** | Pluggable backends (Neo4j, Memgraph, Kuzu, In-memory) | Limited | Entity relationship tracking |
 | **Harness Pattern** | Decouples agent from domain memory | None | Reusable agent architecture |
 | **MCP Integration** | Native stdio/HTTP server | None | Direct Claude Code integration |
 | **Domain Memory Factory** | 6 pre-built schemas | None | Instant setup for any domain |
@@ -55,9 +55,16 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 - **Graph Database Abstraction** (`alma/graph/`)
   - Pluggable `GraphBackend` interface
   - Neo4j backend for production
+  - Memgraph backend for high-performance in-memory graphs
+  - Kuzu backend for embedded graph storage (no server required)
   - In-memory backend for testing
   - Factory function `create_graph_backend()` for easy setup
 
+- **Testing Module** (`alma/testing/`)
+  - `MockStorage` - In-memory storage backend for isolated testing
+  - `MockEmbedder` - Deterministic fake embedding provider
+  - Factory functions for creating test data with sensible defaults
+
 ### Phase 1: Core Features
 
 - **Memory Consolidation Engine** (`alma/consolidation/`)
@@ -378,14 +385,23 @@ Capture entity relationships for complex reasoning:
 ```python
 from alma.graph import create_graph_backend, BackendGraphStore, EntityExtractor
 
-# Create graph backend (Neo4j for production, memory for testing)
+# Create graph backend - multiple options available:
+
+# Neo4j (production, hosted)
 backend = create_graph_backend(
     "neo4j",
     uri="neo4j+s://xxx.databases.neo4j.io",
     username="neo4j",
     password="your-password"
 )
-# Or for testing:
+
+# Memgraph (high-performance, in-memory)
+# backend = create_graph_backend("memgraph", uri="bolt://localhost:7687")
+
+# Kuzu (embedded, no server required)
+# backend = create_graph_backend("kuzu", database_path="./my_graph_db")
+
+# In-memory (testing)
 # backend = create_graph_backend("memory")
 
 # Create store with backend
@@ -637,9 +653,12 @@ print(f"Recommendation: {signal.recommendation}")
 |  +---------------+  +------------------+  +---------------+             |
 +-------------------------------------------------------------------------+
 |  GRAPH LAYER                                                            |
-|  +---------------+  +------------------+                                |
-|  |    Neo4j      |  |   In-Memory      |                                |
-|  +---------------+  +------------------+                                |
+|  +---------------+  +------------------+  +---------------+             |
+|  |    Neo4j      |  |    Memgraph      |  |     Kuzu      |             |
+|  +---------------+  +------------------+  +---------------+             |
+|  +---------------+                                                      |
+|  |   In-Memory   |                                                      |
+|  +---------------+                                                      |
 +-------------------------------------------------------------------------+
 |  INTEGRATION LAYER                                                      |
 |  +-------------------------------------------------------------------+  |
@@ -763,6 +782,7 @@ chroma:
 | Pinecone Backend | Serverless vector DB | Done |
 | Chroma Backend | Lightweight vector DB | Done |
 | Graph Abstraction | Pluggable graph backends | Done |
+| Testing Module | Mocks and factories for testing | Done |
 
 ---
 
@@ -794,6 +814,16 @@ docker run -p 6333:6333 qdrant/qdrant
 - Ensure `embedding_dim` in config matches your embedding provider
 - Local: 384, Azure text-embedding-3-small: 1536
 
+**Memgraph connection refused**
+```bash
+# Start Memgraph with Docker
+docker run -p 7687:7687 memgraph/memgraph-mage
+```
+
+**Kuzu database locked**
+- Ensure only one process accesses the database at a time
+- Use `read_only=True` for concurrent read access
+
 ### Debug Logging
 
 ```python

{alma_memory-0.5.0 → alma_memory-0.5.1}/alma/__init__.py

@@ -12,9 +12,24 @@ The Harness Pattern:
 
 This makes any tool-using agent appear to "learn" by injecting relevant
 memory slices before each run and updating memory after.
+
+Testing Support:
+    For testing ALMA integrations, use the `alma.testing` module:
+
+        from alma.testing import MockStorage, create_test_heuristic
+
+        def test_my_integration():
+            storage = MockStorage()
+            heuristic = create_test_heuristic(agent="test-agent")
+            storage.save_heuristic(heuristic)
+
+    Available utilities:
+    - MockStorage: In-memory storage backend
+    - MockEmbedder: Deterministic fake embeddings
+    - create_test_heuristic(), create_test_outcome(), etc.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 
 # Core
 # Confidence Engine (Phase 12)
@@ -92,6 +107,16 @@ from alma.initializer import (
     SessionInitializer,
 )
 
+# Observability (Phase 20)
+from alma.observability import (
+    ALMAMetrics,
+    configure_observability,
+    get_logger,
+    get_metrics,
+    get_tracer,
+    trace_method,
+)
+
 # Progress Tracking (Phase 10)
 from alma.progress import (
     ProgressLog,
@@ -191,4 +216,11 @@ __all__ = [
     "EmbeddingError",
     "RetrievalError",
     "ExtractionError",
+    # Observability
+    "configure_observability",
+    "get_tracer",
+    "get_logger",
+    "get_metrics",
+    "ALMAMetrics",
+    "trace_method",
 ]

{alma_memory-0.5.0 → alma_memory-0.5.1}/alma/core.py

@@ -1,22 +1,38 @@
 """
 ALMA Core - Main interface for the Agent Learning Memory Architecture.
+
+API Return Type Conventions:
+- Create operations: Return created object or raise exception
+- Update operations: Return updated object or raise exception
+- Delete operations: Return bool (success) or int (count), raise on failure
+- Query operations: Return list (empty if none) or object
+
+All scope violations raise ScopeViolationError for consistent error handling.
 """
 
 import logging
+import time
 from typing import Any, Dict, Optional
 
 from alma.config.loader import ConfigLoader
+from alma.exceptions import ScopeViolationError
 from alma.learning.protocols import LearningProtocol
+from alma.observability.logging import get_logger
+from alma.observability.metrics import get_metrics
+from alma.observability.tracing import SpanKind, get_tracer, trace_method
 from alma.retrieval.engine import RetrievalEngine
 from alma.storage.base import StorageBackend
 from alma.types import (
     DomainKnowledge,
     MemoryScope,
     MemorySlice,
+    Outcome,
     UserPreference,
 )
 
 logger = logging.getLogger(__name__)
+structured_logger = get_logger(__name__)
+tracer = get_tracer(__name__)
 
 
 class ALMA:
@@ -124,6 +140,7 @@ class ALMA:
 
             return FileBasedStorage.from_config(config)
 
+    @trace_method(name="ALMA.retrieve", kind=SpanKind.INTERNAL)
     def retrieve(
         self,
         task: str,
@@ -143,11 +160,19 @@ class ALMA:
         Returns:
             MemorySlice with relevant memories for context injection
         """
+        start_time = time.time()
+        metrics = get_metrics()
+
         # Validate agent has a defined scope
         if agent not in self.scopes:
             logger.warning(f"Agent '{agent}' has no defined scope, using defaults")
+            structured_logger.warning(
+                "Agent has no defined scope, using defaults",
+                agent=agent,
+                project_id=self.project_id,
+            )
 
-        return self.retrieval.retrieve(
+        result = self.retrieval.retrieve(
             query=task,
             agent=agent,
             project_id=self.project_id,
@@ -156,6 +181,30 @@ class ALMA:
             scope=self.scopes.get(agent),
         )
 
+        # Record metrics
+        duration_ms = (time.time() - start_time) * 1000
+        cache_hit = result.retrieval_time_ms < 10  # Approximate cache hit detection
+        metrics.record_retrieve_latency(
+            duration_ms=duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            cache_hit=cache_hit,
+            items_returned=result.total_items,
+        )
+
+        structured_logger.info(
+            "Memory retrieval completed",
+            agent=agent,
+            project_id=self.project_id,
+            task_preview=task[:50] if task else "",
+            items_returned=result.total_items,
+            duration_ms=duration_ms,
+            cache_hit=cache_hit,
+        )
+
+        return result
+
+    @trace_method(name="ALMA.learn", kind=SpanKind.INTERNAL)
     def learn(
         self,
         agent: str,
@@ -166,7 +215,7 @@ class ALMA:
         duration_ms: Optional[int] = None,
         error_message: Optional[str] = None,
         feedback: Optional[str] = None,
-    ) -> bool:
+    ) -> Outcome:
         """
         Learn from a task outcome.
 
@@ -184,9 +233,15 @@ class ALMA:
             feedback: User feedback if provided
 
         Returns:
-            True if learning was accepted, False if rejected (scope violation)
+            The created Outcome record
+
+        Raises:
+            ScopeViolationError: If learning is outside agent's scope
         """
-        result = self.learning.learn(
+        start_time = time.time()
+        metrics = get_metrics()
+
+        outcome_record = self.learning.learn(
             agent=agent,
             project_id=self.project_id,
             task=task,
@@ -199,10 +254,28 @@ class ALMA:
         )
 
         # Invalidate cache for this agent/project after learning
-        if result:
-            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+        self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
-        return result
+        # Record metrics
+        learn_duration_ms = (time.time() - start_time) * 1000
+        metrics.record_learn_operation(
+            duration_ms=learn_duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            memory_type="outcome",
+            success=True,
+        )
+
+        structured_logger.info(
+            "Learning operation completed",
+            agent=agent,
+            project_id=self.project_id,
+            task_type=task_type,
+            outcome=outcome,
+            duration_ms=learn_duration_ms,
+        )
+
+        return outcome_record
 
     def add_user_preference(
         self,
@@ -241,7 +314,7 @@ class ALMA:
         domain: str,
         fact: str,
         source: str = "user_stated",
-    ) -> Optional[DomainKnowledge]:
+    ) -> DomainKnowledge:
         """
         Add domain knowledge within agent's scope.
 
@@ -252,13 +325,17 @@ class ALMA:
             source: How this was learned
 
         Returns:
-            The created DomainKnowledge or None if scope violation
+            The created DomainKnowledge
+
+        Raises:
+            ScopeViolationError: If agent is not allowed to learn in this domain
         """
         # Check scope
         scope = self.scopes.get(agent)
         if scope and not scope.is_allowed(domain):
-            logger.warning(f"Agent '{agent}' not allowed to learn in domain '{domain}'")
-            return None
+            raise ScopeViolationError(
+                f"Agent '{agent}' is not allowed to learn in domain '{domain}'"
+            )
 
         result = self.learning.add_domain_knowledge(
             agent=agent,
@@ -269,11 +346,11 @@ class ALMA:
         )
 
         # Invalidate cache for this agent/project after adding knowledge
-        if result:
-            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+        self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
         return result
 
+    @trace_method(name="ALMA.forget", kind=SpanKind.INTERNAL)
     def forget(
         self,
         agent: Optional[str] = None,
@@ -283,7 +360,8 @@ class ALMA:
         """
         Prune stale or low-confidence memories.
 
-        Invalidates cache after pruning to ensure fresh retrieval results.
+        This is a delete operation that invalidates cache after pruning
+        to ensure fresh retrieval results.
 
         Args:
             agent: Specific agent to prune, or None for all
@@ -291,8 +369,14 @@ class ALMA:
             below_confidence: Remove heuristics below this confidence
 
         Returns:
-            Number of items pruned
+            Number of items pruned (0 if nothing was pruned)
+
+        Raises:
+            StorageError: If the delete operation fails
         """
+        start_time = time.time()
+        metrics = get_metrics()
+
         count = self.learning.forget(
             project_id=self.project_id,
             agent=agent,
@@ -304,17 +388,41 @@ class ALMA:
         if count > 0:
             self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
+        # Record metrics
+        duration_ms = (time.time() - start_time) * 1000
+        metrics.record_forget_operation(
+            duration_ms=duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            items_removed=count,
+        )
+
+        structured_logger.info(
+            "Forget operation completed",
+            agent=agent or "all",
+            project_id=self.project_id,
+            items_removed=count,
+            older_than_days=older_than_days,
+            below_confidence=below_confidence,
+            duration_ms=duration_ms,
+        )
+
         return count
 
     def get_stats(self, agent: Optional[str] = None) -> Dict[str, Any]:
         """
         Get memory statistics.
 
+        This is a query operation that returns statistics about stored memories.
+
         Args:
             agent: Specific agent or None for all
 
         Returns:
-            Dict with counts and metadata
+            Dict with counts and metadata (always returns a dict, may be empty)
+
+        Raises:
+            StorageError: If the query operation fails
         """
         return self.storage.get_stats(
             project_id=self.project_id,

{alma_memory-0.5.0 → alma_memory-0.5.1}/alma/extraction/auto_learner.py

@@ -208,16 +208,17 @@ class AutoLearner:
                     preference=fact.content,
                     source="auto_extraction",
                 )
-                return pref.id if pref else None
+                return pref.id
 
         elif fact.fact_type == FactType.DOMAIN_KNOWLEDGE:
+            # add_domain_knowledge now raises ScopeViolationError instead of returning None
             knowledge = self.alma.add_domain_knowledge(
                 agent=agent,
                 domain=fact.domain or "general",
                 fact=fact.content,
                 source="auto_extraction",
             )
-            return knowledge.id if knowledge else None
+            return knowledge.id
 
         elif fact.fact_type == FactType.OUTCOME:
             # Outcomes need success/failure info we don't have
@@ -228,7 +229,7 @@ class AutoLearner:
                 fact=fact.content,
                 source="auto_extraction",
             )
-            return knowledge.id if knowledge else None
+            return knowledge.id
 
         return None
 

{alma_memory-0.5.0 → alma_memory-0.5.1}/alma/graph/__init__.py

@@ -48,7 +48,7 @@ def create_graph_backend(backend: str = "neo4j", **config) -> GraphBackend:
     Factory function to create a graph backend.
 
     Args:
-        backend: Backend type ("neo4j" or "memory")
+        backend: Backend type ("neo4j", "memgraph", "kuzu", or "memory")
         **config: Backend-specific configuration options
 
     Returns:
@@ -66,6 +66,23 @@ def create_graph_backend(backend: str = "neo4j", **config) -> GraphBackend:
             password="password"
         )
 
+        # Create Memgraph backend
+        backend = create_graph_backend(
+            backend="memgraph",
+            uri="bolt://localhost:7687",
+            username="",
+            password=""
+        )
+
+        # Create Kuzu embedded backend (persistent)
+        backend = create_graph_backend(
+            backend="kuzu",
+            database_path="./my_graph_db"
+        )
+
+        # Create Kuzu embedded backend (in-memory)
+        backend = create_graph_backend(backend="kuzu")
+
         # Create in-memory backend for testing
         backend = create_graph_backend(backend="memory")
     """
@@ -73,6 +90,14 @@ def create_graph_backend(backend: str = "neo4j", **config) -> GraphBackend:
         from alma.graph.backends.neo4j import Neo4jBackend
 
         return Neo4jBackend(**config)
+    elif backend == "memgraph":
+        from alma.graph.backends.memgraph import MemgraphBackend
+
+        return MemgraphBackend(**config)
+    elif backend == "kuzu":
+        from alma.graph.backends.kuzu import KuzuBackend
+
+        return KuzuBackend(**config)
     elif backend == "memory":
         from alma.graph.backends.memory import InMemoryBackend
 

alma_memory-0.5.1/alma/graph/backends/__init__.py

@@ -0,0 +1,32 @@
+"""
+ALMA Graph Memory Backends.
+
+This package contains implementations of the GraphBackend interface
+for various graph database systems.
+
+Available backends:
+- neo4j: Neo4j graph database backend
+- memgraph: Memgraph graph database backend (Neo4j Bolt protocol compatible)
+- kuzu: Kuzu embedded graph database backend (no server required)
+- memory: In-memory backend for testing and development
+"""
+
+from alma.graph.backends.memgraph import MemgraphBackend
+from alma.graph.backends.memory import InMemoryBackend
+from alma.graph.backends.neo4j import Neo4jBackend
+
+# Kuzu is an optional dependency
+try:
+    from alma.graph.backends.kuzu import KuzuBackend
+
+    _KUZU_AVAILABLE = True
+except ImportError:
+    KuzuBackend = None  # type: ignore
+    _KUZU_AVAILABLE = False
+
+__all__ = [
+    "Neo4jBackend",
+    "MemgraphBackend",
+    "KuzuBackend",
+    "InMemoryBackend",
+]