mdb-engine 0.7.3__py3-none-any.whl → 0.7.5__py3-none-any.whl

mdb_engine/__init__.py

@@ -81,7 +81,7 @@ from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 # Utilities
 from .utils import clean_mongo_doc, clean_mongo_docs
 
-__version__ = "0.7.3"
+__version__ = "0.7.5"
 
 __all__ = [
     # Core Engine

mdb_engine/cli/main.py

@@ -15,7 +15,7 @@ from .commands.validate import validate
 
 
 @click.group()
-@click.version_option(version="0.7.3", prog_name="mdb")
+@click.version_option(version="0.7.5", prog_name="mdb")
 def cli() -> None:
     """
     MDB_ENGINE CLI - Manifest management tool.

mdb_engine/core/engine.py

@@ -910,13 +910,14 @@ class MongoDBEngine:
 
     def get_memory_service(self, slug: str) -> Any | None:
         """
-        Get Mem0 memory service for an app.
+        Get memory service for an app (returns BaseMemoryService instance).
 
         Args:
             slug: App slug
 
         Returns:
-            Mem0MemoryService instance if memory is enabled for this app, None otherwise
+            BaseMemoryService instance (currently Mem0MemoryService) if memory is enabled
+            for this app, None otherwise
 
         Example:
             ```python

mdb_engine/core/service_initialization.py

@@ -63,10 +63,10 @@ class ServiceInitializer:
         self, slug: str, memory_config: dict[str, Any] | None
     ) -> None:
         """
-        Initialize Mem0 memory service for an app.
+        Initialize memory service for an app (defaults to Mem0 implementation).
 
         Memory support is OPTIONAL - only processes if dependencies are available.
-        mem0 handles embeddings and LLM via environment variables (.env).
+        Currently uses Mem0.ai which handles embeddings and LLM via environment variables (.env).
 
         Args:
             slug: App slug
@@ -356,13 +356,14 @@ class ServiceInitializer:
 
     def get_memory_service(self, slug: str) -> Any | None:
         """
-        Get Mem0 memory service for an app.
+        Get memory service for an app (returns BaseMemoryService instance).
 
         Args:
             slug: App slug
 
         Returns:
-            Mem0MemoryService instance if memory is enabled for this app, None otherwise
+            BaseMemoryService instance (currently Mem0MemoryService) if memory is enabled
+            for this app, None otherwise
         """
         try:
             service = self._memory_services.get(slug)

mdb_engine/core/types.py

@@ -11,9 +11,9 @@ This module is part of MDB_ENGINE - MongoDB Engine.
 from typing import TYPE_CHECKING, Any, Literal, TypedDict
 
 if TYPE_CHECKING:
-    from ..memory import Mem0MemoryService
+    from ..memory import BaseMemoryService
 else:
-    Mem0MemoryService = Any
+    BaseMemoryService = Any
 
 
 # ============================================================================

mdb_engine/dependencies.py

@@ -33,7 +33,7 @@ if TYPE_CHECKING:
     from .core.engine import MongoDBEngine
     from .database.scoped_wrapper import ScopedMongoWrapper
     from .embeddings.service import EmbeddingService
-    from .memory.service import Mem0MemoryService
+    from .memory import BaseMemoryService
 
 logger = logging.getLogger(__name__)
 
@@ -121,8 +121,8 @@ async def get_embedding_service(request: Request) -> "EmbeddingService":
         raise HTTPException(503, f"Failed to initialize embedding service: {e}") from e
 
 
-async def get_memory_service(request: Request) -> Optional["Mem0MemoryService"]:
-    """Get the Mem0 memory service if configured."""
+async def get_memory_service(request: Request) -> Optional["BaseMemoryService"]:
+    """Get the memory service if configured (defaults to Mem0 implementation)."""
     engine = getattr(request.app.state, "engine", None)
     slug = getattr(request.app.state, "app_slug", None)
     if not engine or not slug:

mdb_engine/memory/README.md

@@ -2,9 +2,45 @@
 
 Mem0.ai integration for intelligent memory management in MDB_ENGINE applications. Provides semantic memory storage, retrieval, and inference capabilities with MongoDB integration.
 
+## 🎉 What's New
+
+### Extensible Architecture (Latest)
+
+**Base Class Pattern for Future Extensibility!**
+
+The memory service now uses an abstract base class pattern, enabling future memory provider implementations while maintaining backward compatibility:
+
+- **🏗️ BaseMemoryService**: Abstract base class defining the memory service interface
+- **🔌 Provider Extensibility**: Easy to add new memory providers (LangChain, custom implementations, etc.)
+- **✅ Backward Compatible**: All existing code continues to work without changes
+- **📝 Type Safety**: Better IDE support and type checking with abstract base class
+- **🎯 Consistent API**: All memory providers implement the same interface
+
+### v0.7.5 Enhancements
+
+**Memory Injection and Enhanced Delete Capabilities!**
+
+- **💉 Inject Method**: New `inject()` method for manual memory insertion without LLM inference - perfect for adding facts, preferences, or structured data directly
+- **🗑️ Enhanced Delete**: Comprehensive delete functionality with improved documentation and user experience
+- **🧠 Memory Explorer UI**: Added memory explorer interface in chit_chat example with inject and delete buttons
+
+### v0.7.4 Enhancements
+
+**Enhanced Mem0 Integration - Production Ready!**
+
+- **🔧 Hybrid Update Pattern**: Content updates via Mem0 (triggers re-embedding), metadata updates via direct MongoDB (full control, no API limitations)
+- **📊 Direct MongoDB Access**: Reliable data retrieval directly from MongoDB, bypassing Mem0 API inconsistencies
+- **🏷️ Full Metadata Support**: Update any metadata field without restrictions - not limited by Mem0's API
+- **✅ Correct Mem0 Structure**: Properly handles Mem0's MongoDB structure (`_id` as document ID, `payload` for memory data)
+- **🛡️ Robust Error Handling**: Specific exception handling with proper KeyboardInterrupt/SystemExit propagation
+- **🔍 Reliable Returns**: Always returns normalized documents fetched directly from MongoDB (guaranteed structure)
+
+> 📖 **Want to understand why we use manual MongoDB access?** See the [Mem0 Implementation Guide](../../docs/guides/MEM0_IMPLEMENTATION.md) for detailed explanations of our architectural decisions, Mem0's MongoDB structure, and things to watch out for.
+
 ## Features
 
-- **Mem0 Integration**: Wrapper around Mem0.ai for intelligent memory management
+- **Extensible Architecture**: Base class pattern allows for multiple memory provider implementations
+- **Mem0 Integration**: Default implementation using Mem0.ai for intelligent memory management
 - **MongoDB Storage**: Built-in MongoDB vector store integration
 - **Auto-Detection**: Automatically detects OpenAI or Azure OpenAI from environment variables
 - **Semantic Search**: Vector-based semantic memory search
@@ -67,7 +103,7 @@ Enable memory service in your `manifest.json`:
 ### Basic Usage
 
 ```python
-from mdb_engine.memory import Mem0MemoryService
+from mdb_engine.memory import BaseMemoryService  # Base class for type hints
 from mdb_engine.core import MongoDBEngine
 
 # Initialize engine
@@ -75,7 +111,8 @@ engine = MongoDBEngine(mongo_uri="...", db_name="...")
 await engine.initialize()
 
 # Get memory service (automatically configured from manifest)
-memory_service = engine.get_memory_service("my_app")
+# Returns BaseMemoryService instance (currently Mem0MemoryService)
+memory_service: BaseMemoryService = engine.get_memory_service("my_app")
 
 # Add memory
 memory = await memory_service.add(
@@ -140,6 +177,45 @@ memories = await memory_service.add_all(
 )
 ```
 
+### Inject Memory (Manual Insertion)
+
+Manually inject memories without LLM inference. This is useful when you want to directly add facts, preferences, or structured data without going through the inference pipeline:
+
+```python
+# Inject memory as a string
+memory = await memory_service.inject(
+    memory="The user prefers dark mode interfaces",
+    user_id="user123",
+    metadata={"source": "manual", "category": "preference"}
+)
+
+# Inject memory as a dict
+memory = await memory_service.inject(
+    memory={"memory": "Project deadline is next Friday", "category": "work"},
+    user_id="user123",
+    metadata={"source": "manual", "type": "deadline"}
+)
+
+# Returns: {"id": "...", "memory": "...", "metadata": {...}, ...}
+```
+
+**Key Differences from `add()`:**
+- **`inject()`**: Direct insertion without LLM inference (faster, no API costs)
+- **`add()`**: Uses LLM inference to extract facts from messages (slower, costs API calls)
+- **`inject()`**: Returns a single memory dict
+- **`add()`**: Returns a list of extracted memories
+
+**When to use `inject()`:**
+- Adding known facts or preferences directly
+- Importing structured data
+- When you want to avoid LLM inference costs
+- When you have pre-formatted memory content
+
+**When to use `add()`:**
+- Extracting memories from conversations
+- When you want the LLM to identify key facts
+- Processing unstructured text into memories
+
 ### Search Memories
 
 Semantic search across stored memories:
@@ -163,14 +239,17 @@ results = await memory_service.search(
 
 ### Get Memories
 
-Retrieve memories for a user:
+Retrieve memories for a user. The service automatically normalizes Mem0's MongoDB structure (`_id`, `payload`) into a consistent API format:
 
 ```python
 # Get all memories
 all_memories = await memory_service.get_all(user_id="user123")
+# Returns normalized format: [{"id": "...", "memory": "...", "metadata": {...}, ...}]
 
 # Get specific memory
 memory = await memory_service.get(memory_id="memory_123", user_id="user123")
+# Returns normalized format: {"id": "...", "memory": "...", "metadata": {...}, ...}
+# Note: memory_id can be either Mem0's _id or the normalized id field
 
 # Get memories with filters
 memories = await memory_service.get_all(
@@ -179,9 +258,16 @@ memories = await memory_service.get_all(
 )
 ```
 
+**Note**: The service handles Mem0's internal MongoDB structure (`_id` as document ID, `payload` containing memory data) automatically. All methods return normalized documents with consistent `id`, `memory`, `text`, and `metadata` fields.
+
 ### Update Memory
 
-Update existing memories in-place while preserving the original memory ID and creation timestamp:
+Update existing memories using a **hybrid approach** that combines Mem0's embedding capabilities with direct MongoDB control:
+
+**Architecture:**
+- **Content Updates**: Routed via Mem0 (triggers automatic re-embedding)
+- **Metadata Updates**: Routed via direct PyMongo (full control, no API limitations)
+- **Return Value**: Always fetched from MongoDB (guaranteed correct structure)
 
 ```python
 # Update memory content and metadata
@@ -200,14 +286,21 @@ updated = memory_service.update(
     metadata={"updated": True}
 )
 
-# Update only metadata (content unchanged)
+# Update only metadata (content unchanged) - FULLY SUPPORTED
+updated = memory_service.update(
+    memory_id="memory_123",
+    user_id="user123",
+    metadata={"category": "updated", "priority": "high"}
+)
+
+# Update only content (no metadata changes)
 updated = memory_service.update(
     memory_id="memory_123",
     user_id="user123",
-    metadata={"category": "updated"}
+    memory="Updated content only"
 )
 
-# Backward compatibility: using 'data' parameter
+# Using 'data' parameter
 updated = memory_service.update(
     memory_id="memory_123",
     user_id="user123",
@@ -217,25 +310,63 @@ updated = memory_service.update(
 ```
 
 **Key Features:**
+- **Hybrid Architecture**: Mem0 handles embeddings, MongoDB handles data persistence
+- **Full Metadata Support**: Update any metadata field (not limited by Mem0 API)
 - **Preserves Memory ID**: The original memory ID is maintained
 - **Preserves Creation Timestamp**: `created_at` is not modified
 - **Updates Timestamp**: `updated_at` is automatically set to current time
-- **Recomputes Embeddings**: If content changes, the embedding vector is automatically recomputed
-- **Metadata Merging**: New metadata is merged with existing metadata (doesn't replace)
+- **Recomputes Embeddings**: If content changes, the embedding vector is automatically recomputed via Mem0
+- **Reliable Returns**: Always returns the actual document from MongoDB (not Mem0's response format)
 - **Partial Updates**: Can update content only, metadata only, or both
+- **Security**: Validates user_id ownership before allowing updates
+- **Mem0 Structure Aware**: Correctly handles Mem0's MongoDB structure (`_id` as document ID, `payload` for memory data)
+- **Direct MongoDB Access**: Uses PyMongo for reliable data operations, ensuring consistency
+- **Normalized Responses**: All methods return consistent document structure regardless of Mem0's internal format
 
 ### Delete Memory
 
-Remove memories:
+Remove memories from storage. Both methods return `True` on success, `False` on failure:
 
 ```python
-# Delete single memory
-await memory_service.delete(memory_id="memory_123", user_id="user123")
-
-# Delete all memories for user
-await memory_service.delete_all(user_id="user123")
+# Delete single memory by ID
+success = await memory_service.delete(memory_id="memory_123", user_id="user123")
+if success:
+    print("Memory deleted successfully")
+else:
+    print("Failed to delete memory (may not exist)")
+
+# Delete all memories for a user (use with caution!)
+success = await memory_service.delete_all(user_id="user123")
+if success:
+    print("All memories deleted successfully")
+
+# Delete with error handling
+try:
+    success = await memory_service.delete(memory_id="memory_123", user_id="user123")
+    if not success:
+        logger.warning(f"Memory {memory_id} not found or already deleted")
+except Mem0MemoryServiceError as e:
+    logger.error(f"Error deleting memory: {e}")
 ```
 
+**Key Features:**
+- **User Scoping**: Both methods respect `user_id` for security
+- **Safe Deletion**: Returns `False` if memory doesn't exist (doesn't raise exception)
+- **Bulk Deletion**: `delete_all()` removes all memories for a user
+- **Idempotent**: Safe to call multiple times (returns `False` if already deleted)
+
+**When to use `delete()`:**
+- Removing a specific memory by ID
+- Cleaning up outdated or incorrect memories
+- User-initiated memory removal
+
+**When to use `delete_all()`:**
+- Resetting user memory (e.g., account deletion)
+- Clearing test data
+- Bulk cleanup operations
+
+**Note**: Deletion is permanent and cannot be undone. Consider implementing soft deletes if you need to recover deleted memories.
+
 ### Bucket Organization
 
 Organize memories into buckets for better management:
@@ -336,31 +467,100 @@ for memory in insights:
     print(f"Insights: {memory.get('insights')}")
 ```
 
+## Architecture
+
+### Base Class Pattern
+
+The memory service uses an abstract base class pattern for extensibility:
+
+```python
+from mdb_engine.memory import BaseMemoryService, MemoryServiceError
+
+# BaseMemoryService defines the interface
+# Mem0MemoryService implements it (default provider)
+# Future providers can inherit from BaseMemoryService
+```
+
+**Benefits:**
+- **Type Safety**: Use `BaseMemoryService` for type hints
+- **Extensibility**: Easy to add new providers (LangChain, custom, etc.)
+- **Consistency**: All providers implement the same interface
+- **Backward Compatible**: Existing code works without changes
+
+### Creating Custom Memory Providers
+
+To create a custom memory provider, inherit from `BaseMemoryService`:
+
+```python
+from mdb_engine.memory import BaseMemoryService, MemoryServiceError
+
+class CustomMemoryService(BaseMemoryService):
+    """Custom memory service implementation."""
+    
+    def __init__(self, mongo_uri: str, db_name: str, app_slug: str, config: dict | None = None):
+        # Initialize your custom implementation
+        pass
+    
+    def add(self, messages, user_id=None, metadata=None, **kwargs):
+        # Implement add method
+        pass
+    
+    # Implement all other abstract methods...
+    def get_all(self, user_id=None, limit=100, filters=None, **kwargs):
+        pass
+    
+    def search(self, query, user_id=None, limit=5, filters=None, **kwargs):
+        pass
+    
+    def get(self, memory_id, user_id=None, **kwargs):
+        pass
+    
+    def delete(self, memory_id, user_id=None, **kwargs):
+        pass
+    
+    def delete_all(self, user_id=None, **kwargs):
+        pass
+    
+    def update(self, memory_id, user_id=None, memory=None, metadata=None, **kwargs):
+        pass
+```
+
 ## API Reference
 
+### BaseMemoryService
+
+Abstract base class for all memory service implementations. Defines the standard interface.
+
 ### Mem0MemoryService
 
+Default implementation using Mem0.ai. Inherits from `BaseMemoryService`.
+
 #### Initialization
 
 ```python
 Mem0MemoryService(
     mongo_uri: str,
     db_name: str,
-    collection_name: str = "memories",
-    app_slug: str = None,
-    embedding_model: str = "text-embedding-3-small",
-    embedding_dimensions: int = None,
-    chat_model: str = "gpt-4",
-    temperature: float = 0.7,
-    infer: bool = True,
-    enable_graph: bool = False,
-    config: dict = None
+    app_slug: str,
+    config: dict = None  # Optional configuration
+)
+
+# Or use the factory function
+from mdb_engine.memory import get_memory_service
+
+memory_service = get_memory_service(
+    mongo_uri="...",
+    db_name="...",
+    app_slug="...",
+    config={...},
+    provider="mem0"  # Default, future providers can be specified here
 )
 ```
 
 #### Methods
 
 - `add(messages, user_id, metadata=None, bucket_id=None, bucket_type=None, store_raw_content=False, raw_content=None)` - Add single memory with optional bucket and raw content storage
+- `inject(memory, user_id, metadata=None)` - Manually inject a memory without LLM inference
 - `add_with_raw_content(messages, raw_content, user_id, bucket_id=None, bucket_type=None)` - Store both extracted facts and raw content
 - `get_buckets(user_id, bucket_type=None, limit=None)` - Get all buckets for a user
 - `get_bucket_memories(bucket_id, user_id, include_raw_content=False, limit=None)` - Get all memories in a bucket
@@ -513,15 +713,19 @@ knowledge = await memory_service.search(
 ## Error Handling
 
 ```python
-from mdb_engine.memory import Mem0MemoryServiceError
+from mdb_engine.memory import MemoryServiceError, Mem0MemoryServiceError
 
 try:
     memory = await memory_service.add(
         messages=[{"role": "user", "content": "Test"}],
         user_id="user123"
     )
-except Mem0MemoryServiceError as e:
+except MemoryServiceError as e:
+    # Base exception for all memory service errors
     print(f"Memory service error: {e}")
+except Mem0MemoryServiceError as e:
+    # Specific exception for Mem0 implementation
+    print(f"Mem0 memory service error: {e}")
 except (ValueError, TypeError, ConnectionError) as e:
     print(f"Configuration or connection error: {e}")
 ```

mdb_engine/memory/__init__.py

@@ -14,16 +14,25 @@ Key Features:
 - **Optional LLM Inference**: Can leverage LLM service for automatic memory
   extraction (set infer: false to disable)
 - **Graph Support**: Optional knowledge graph construction for entity relationships
+- **Extensible Architecture**: Base class allows for future memory provider implementations
 
 Dependencies:
     pip install mem0ai
 """
 
+# Import base classes
+from .base import BaseMemoryService, MemoryServiceError
+
 # Import service components (mem0 import is lazy within service.py)
 from .service import Mem0MemoryService, Mem0MemoryServiceError, get_memory_service
 
 __all__ = [
+    # Base classes (for extensibility)
+    "BaseMemoryService",
+    "MemoryServiceError",
+    # Mem0 implementation (default)
     "Mem0MemoryService",
     "Mem0MemoryServiceError",
+    # Factory function
     "get_memory_service",
 ]