mcal-ai-autogen 0.2.0__py3-none-any.whl

mcal_ai_autogen-0.2.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: mcal-ai-autogen
+Version: 0.2.0
+Summary: Microsoft AutoGen integration for MCAL - Goal-aware memory for multi-agent systems
+Author: MCAL Team
+License: MIT
+Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
+Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai/tree/main/packages/mcal-autogen
+Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai
+Keywords: mcal,autogen,memory,llm,agents,goal-aware,multi-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcal-ai>=0.1.0
+Provides-Extra: autogen
+Requires-Dist: autogen-core>=0.4.0; extra == "autogen"
+Requires-Dist: autogen-agentchat>=0.4.0; extra == "autogen"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: mcal-autogen[autogen,dev]; extra == "all"
+Dynamic: license-file
+
+# mcal-autogen
+
+Microsoft AutoGen integration for MCAL (Multi-turn Conversation Abstraction Layer), bringing goal-aware memory to AutoGen agents.
+
+## Installation
+
+```bash
+pip install mcal-autogen
+
+# With AutoGen dependencies
+pip install mcal-autogen[autogen]
+```
+
+## Quick Start
+
+```python
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from mcal import MCAL
+from mcal_autogen import MCALMemory
+
+# Initialize MCAL with your project goal
+mcal = MCAL(goal="Help users build data pipelines")
+
+# Create MCAL-backed memory
+memory = MCALMemory(mcal, user_id="user_123")
+
+# Create an agent with MCAL memory
+model_client = OpenAIChatCompletionClient(model="gpt-4")
+agent = AssistantAgent(
+    name="data_engineer",
+    model_client=model_client,
+    memory=[memory],
+    system_message="You are a helpful data engineering assistant.",
+)
+
+# Use the agent - MCAL automatically tracks context and decisions
+result = await agent.run(task="How should I set up my ETL pipeline?")
+```
+
+## Features
+
+### Goal-Aware Memory
+
+MCAL's unique value is understanding your project's goals and maintaining context across conversations:
+
+```python
+# Initialize with a clear goal
+mcal = MCAL(goal="Build a real-time fraud detection system")
+memory = MCALMemory(mcal)
+
+# Add relevant context
+from autogen_core.memory import MemoryContent
+await memory.add(MemoryContent(
+    content="We decided to use Kafka for streaming",
+    mime_type="text/plain",
+    metadata={"category": "architecture", "decision": True}
+))
+
+# Query returns goal-relevant results
+results = await memory.query("What messaging system should I use?")
+# Returns Kafka decision with goal-relevance scoring
+```
+
+### Decision Tracking
+
+Track architectural and project decisions automatically:
+
+```python
+memory = MCALMemory(
+    mcal,
+    enable_goal_tracking=True,  # Extract goals from content
+    include_decisions=True,      # Include decisions in search
+)
+
+# Decisions are automatically tracked
+await memory.add(MemoryContent(
+    content="After evaluating options, we chose PostgreSQL for its JSON support",
+    mime_type="text/plain"
+))
+
+# Query finds relevant decisions
+results = await memory.query("database selection")
+```
+
+### User Isolation
+
+Support multi-tenant scenarios with user isolation:
+
+```python
+# Create separate memories for different users
+user1_memory = MCALMemory(mcal, user_id="alice")
+user2_memory = MCALMemory(mcal, user_id="bob")
+
+# Each user has isolated memory
+await user1_memory.add(MemoryContent(content="Alice prefers Python"))
+await user2_memory.add(MemoryContent(content="Bob prefers Rust"))
+
+# Queries only return user-specific results
+results = await user1_memory.query("language preference")
+# Only returns Alice's preference
+```
+
+### TTL Support
+
+Configure time-to-live for memory entries:
+
+```python
+memory = MCALMemory(mcal, default_ttl_minutes=60)  # 1 hour default
+
+# Or per-entry TTL via metadata
+await memory.add(MemoryContent(
+    content="Temporary context",
+    mime_type="text/plain",
+    metadata={"ttl_minutes": 15}  # 15 minute TTL
+))
+```
+
+## Integration with AutoGen Features
+
+### With AssistantAgent
+
+```python
+from autogen_agentchat.agents import AssistantAgent
+
+agent = AssistantAgent(
+    name="assistant",
+    model_client=model_client,
+    memory=[memory],  # MCAL memory integrates seamlessly
+)
+```
+
+### With Teams
+
+```python
+from autogen_agentchat.teams import RoundRobinGroupChat
+
+# Share MCAL memory across team members
+shared_memory = MCALMemory(mcal, user_id="team_alpha")
+
+coder = AssistantAgent("coder", model_client=model_client, memory=[shared_memory])
+reviewer = AssistantAgent("reviewer", model_client=model_client, memory=[shared_memory])
+
+team = RoundRobinGroupChat([coder, reviewer])
+```
+
+### Context Window Management
+
+MCAL automatically manages context relevance:
+
+```python
+memory = MCALMemory(
+    mcal,
+    max_results=10,           # Limit results per query
+    score_threshold=0.5,      # Minimum relevance score
+)
+
+# update_context adds relevant memories to the agent's context
+result = await memory.update_context(model_context)
+```
+
+## API Reference
+
+### MCALMemory
+
+```python
+class MCALMemory(Memory):
+    def __init__(
+        self,
+        mcal: MCAL,
+        user_id: str = "default",
+        name: str = "mcal_memory",
+        max_results: int = 10,
+        score_threshold: float = 0.0,
+        default_ttl_minutes: Optional[float] = None,
+        enable_goal_tracking: bool = True,
+        include_decisions: bool = True,
+    ):
+        """
+        Initialize MCAL-backed memory for AutoGen.
+        
+        Args:
+            mcal: Initialized MCAL instance
+            user_id: User identifier for memory isolation
+            name: Memory instance name
+            max_results: Maximum results to return from queries
+            score_threshold: Minimum relevance score (0-1)
+            default_ttl_minutes: Default TTL in minutes
+            enable_goal_tracking: Extract goals from content
+            include_decisions: Include decisions in search results
+        """
+```
+
+### Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `add(content)` | Add content to memory |
+| `query(query)` | Search for relevant memories |
+| `update_context(model_context)` | Update agent context with memories |
+| `clear()` | Clear all memory entries |
+| `close()` | Cleanup resources |
+
+## Requirements
+
+- Python >= 3.10
+- mcal >= 0.1.0
+- autogen-core >= 0.4.0 (optional)
+- autogen-agentchat >= 0.4.0 (optional)
+
+## License
+
+MIT License

mcal_ai_autogen-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcal_ai_autogen-0.2.0.dist-info/licenses/LICENSE,sha256=zdp5kxDzb-kYvBiEZ_h1Hi96z-o6e5oXoXFx2IIefCs,1062
+mcal_autogen/__init__.py,sha256=kz9Y4F2Ji_FQAPGChDyQKo8I78plamx059yb30Zk0AY,187
+mcal_autogen/_compat.py,sha256=8U8sj3F6hvfBnKjSpyjCZEDHnzpxc3J9tHx93LPfwbU,1868
+mcal_autogen/memory.py,sha256=7su6wQ7-5rdxAhFSufw8at5c5mBEpOpKeeiVvN7R_SE,16959
+mcal_ai_autogen-0.2.0.dist-info/METADATA,sha256=7Y4QEm70NSr05p7XDQJlLI_QSaw1md9vOHCYt9QHgoA,6944
+mcal_ai_autogen-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mcal_ai_autogen-0.2.0.dist-info/top_level.txt,sha256=VEv2d_KPDVrYHd9_NIyrcdqusUwOA63aJIMUF0gqvQw,13
+mcal_ai_autogen-0.2.0.dist-info/RECORD,,

mcal_ai_autogen-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcal_ai_autogen-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcal_ai_autogen-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcal_autogen

mcal_autogen/__init__.py

@@ -0,0 +1,10 @@
+"""
+MCAL AutoGen Integration
+
+Goal-aware memory for Microsoft AutoGen multi-agent systems.
+"""
+
+from mcal_autogen.memory import MCALMemory
+
+__version__ = "0.1.0"
+__all__ = ["MCALMemory"]

mcal_autogen/_compat.py

@@ -0,0 +1,67 @@
+"""
+Compatibility layer for AutoGen imports.
+
+Provides graceful handling when autogen packages are not installed.
+"""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+# Check if AutoGen is available
+AUTOGEN_AVAILABLE = False
+AUTOGEN_CORE_AVAILABLE = False
+
+try:
+    from autogen_core import CancellationToken
+    from autogen_core.memory import (
+        Memory,
+        MemoryContent,
+        MemoryQueryResult,
+        UpdateContextResult,
+        MemoryMimeType,
+    )
+    from autogen_core.model_context import ChatCompletionContext
+    from autogen_core.models import SystemMessage
+    AUTOGEN_CORE_AVAILABLE = True
+    AUTOGEN_AVAILABLE = True
+except ImportError:
+    # Define minimal stubs for type checking
+    Memory = object  # type: ignore
+    MemoryContent = Any  # type: ignore
+    MemoryQueryResult = Any  # type: ignore
+    UpdateContextResult = Any  # type: ignore
+    MemoryMimeType = Any  # type: ignore
+    CancellationToken = Any  # type: ignore
+    ChatCompletionContext = Any  # type: ignore
+    SystemMessage = Any  # type: ignore
+
+
+def check_autogen() -> None:
+    """Raise ImportError if AutoGen is not available."""
+    if not AUTOGEN_AVAILABLE:
+        raise ImportError(
+            "AutoGen packages not found. Install with: pip install mcal-autogen[autogen]"
+        )
+
+
+def check_autogen_core() -> None:
+    """Raise ImportError if autogen-core is not available."""
+    if not AUTOGEN_CORE_AVAILABLE:
+        raise ImportError(
+            "autogen-core not found. Install with: pip install autogen-core>=0.4.0"
+        )
+
+
+__all__ = [
+    "AUTOGEN_AVAILABLE",
+    "AUTOGEN_CORE_AVAILABLE",
+    "check_autogen",
+    "check_autogen_core",
+    "Memory",
+    "MemoryContent",
+    "MemoryQueryResult",
+    "UpdateContextResult",
+    "MemoryMimeType",
+    "CancellationToken",
+    "ChatCompletionContext",
+    "SystemMessage",
+]

mcal_autogen/memory.py

@@ -0,0 +1,493 @@
+"""
+MCAL Memory Backend for Microsoft AutoGen
+
+Implements AutoGen's Memory interface with goal-aware memory capabilities.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from mcal_autogen._compat import (
+    AUTOGEN_CORE_AVAILABLE,
+    check_autogen_core,
+    Memory,
+    MemoryContent,
+    MemoryQueryResult,
+    UpdateContextResult,
+    MemoryMimeType,
+    CancellationToken,
+    ChatCompletionContext,
+    SystemMessage,
+)
+
+if TYPE_CHECKING:
+    from mcal import MCAL
+
+
+class MCALMemory(Memory if AUTOGEN_CORE_AVAILABLE else object):
+    """
+    MCAL memory backend for Microsoft AutoGen.
+    
+    This class implements AutoGen's Memory interface, providing
+    goal-aware memory with context preservation for multi-agent systems.
+    
+    Key Features:
+    - Goal-aware search that prioritizes project-relevant memories
+    - Decision tracking for architectural choices
+    - User isolation for multi-tenant scenarios
+    - TTL support with automatic expiration
+    - Thread-safe operations
+    
+    Usage:
+        from mcal import MCAL
+        from mcal_autogen import MCALMemory
+        from autogen_agentchat.agents import AssistantAgent
+        
+        mcal = MCAL(goal="Build fraud detection system")
+        memory = MCALMemory(mcal, user_id="user_123")
+        
+        agent = AssistantAgent(
+            name="analyst",
+            model_client=model_client,
+            memory=[memory],
+        )
+        
+    Args:
+        mcal: Initialized MCAL instance
+        user_id: User identifier for memory isolation
+        name: Memory instance name (default: "mcal_memory")
+        max_results: Maximum results to return from queries (default: 10)
+        score_threshold: Minimum relevance score 0-1 (default: 0.0)
+        default_ttl_minutes: Default TTL in minutes (None = no expiration)
+        enable_goal_tracking: Whether to extract goals from content
+        include_decisions: Whether to include decisions in search results
+    """
+    
+    def __init__(
+        self,
+        mcal: "MCAL",
+        user_id: str = "default",
+        name: str = "mcal_memory",
+        max_results: int = 10,
+        score_threshold: float = 0.0,
+        default_ttl_minutes: Optional[float] = None,
+        enable_goal_tracking: bool = True,
+        include_decisions: bool = True,
+    ):
+        check_autogen_core()
+        
+        self._mcal = mcal
+        self._user_id = user_id
+        self._name = name
+        self._max_results = max_results
+        self._score_threshold = score_threshold
+        self._default_ttl_minutes = default_ttl_minutes
+        self._enable_goal_tracking = enable_goal_tracking
+        self._include_decisions = include_decisions
+        
+        # Thread safety
+        self._lock = threading.RLock()
+        
+        # In-memory storage for MemoryContent items
+        # Maps content_id -> MemoryContent
+        self._items: Dict[str, MemoryContent] = {}
+        self._created_at: Dict[str, datetime] = {}
+        self._expires_at: Dict[str, Optional[float]] = {}  # Unix timestamp
+        
+        # Counter for generating unique IDs
+        self._id_counter = 0
+    
+    @property
+    def name(self) -> str:
+        """Get the memory instance identifier."""
+        return self._name
+    
+    @property
+    def user_id(self) -> str:
+        """Get the user identifier."""
+        return self._user_id
+    
+    @property
+    def mcal(self) -> "MCAL":
+        """Get the underlying MCAL instance."""
+        return self._mcal
+    
+    def _generate_id(self) -> str:
+        """Generate a unique content ID."""
+        with self._lock:
+            self._id_counter += 1
+            return f"mem_{self._user_id}_{self._id_counter}_{int(time.time() * 1000)}"
+    
+    def _is_expired(self, content_id: str) -> bool:
+        """Check if a memory entry has expired."""
+        expires = self._expires_at.get(content_id)
+        if expires is None:
+            return False
+        return time.time() > expires
+    
+    def _cleanup_expired(self) -> int:
+        """Remove expired entries. Returns count of removed items."""
+        removed = 0
+        with self._lock:
+            expired_ids = [
+                cid for cid in list(self._items.keys())
+                if self._is_expired(cid)
+            ]
+            for cid in expired_ids:
+                del self._items[cid]
+                self._created_at.pop(cid, None)
+                self._expires_at.pop(cid, None)
+                removed += 1
+        return removed
+    
+    def _extract_text(self, content: MemoryContent | str) -> str:
+        """Extract searchable text from content."""
+        if isinstance(content, str):
+            return content
+        
+        if hasattr(content, 'content'):
+            val = content.content
+            if isinstance(val, str):
+                return val
+            elif isinstance(val, dict):
+                # Try common keys
+                for key in ['text', 'content', 'message', 'data']:
+                    if key in val:
+                        return str(val[key])
+                # Fallback to JSON-like string
+                import json
+                try:
+                    return json.dumps(val)
+                except (TypeError, ValueError):
+                    return str(val)
+            elif isinstance(val, bytes):
+                try:
+                    return val.decode('utf-8')
+                except UnicodeDecodeError:
+                    return str(val)
+            else:
+                return str(val)
+        
+        return str(content)
+    
+    async def add(
+        self,
+        content: MemoryContent,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> None:
+        """
+        Add new content to memory.
+        
+        Args:
+            content: Memory content to store
+            cancellation_token: Optional token to cancel operation
+        """
+        # Check cancellation
+        if cancellation_token and hasattr(cancellation_token, 'cancelled'):
+            if getattr(cancellation_token, 'cancelled', False):
+                return
+        
+        content_id = self._generate_id()
+        now = datetime.now(timezone.utc)
+        
+        # Calculate expiration
+        expires_at: Optional[float] = None
+        ttl_minutes = self._default_ttl_minutes
+        
+        # Check for TTL in metadata
+        if content.metadata and 'ttl_minutes' in content.metadata:
+            ttl_minutes = content.metadata['ttl_minutes']
+        
+        if ttl_minutes is not None:
+            expires_at = time.time() + (ttl_minutes * 60)
+        
+        # Store the content
+        with self._lock:
+            self._items[content_id] = content
+            self._created_at[content_id] = now
+            self._expires_at[content_id] = expires_at
+        
+        # Also store in MCAL for goal-aware search
+        text = self._extract_text(content)
+        if text:
+            metadata = dict(content.metadata) if content.metadata else {}
+            metadata['content_id'] = content_id
+            metadata['user_id'] = self._user_id
+            metadata['source'] = 'autogen_memory'
+            
+            # Add to MCAL using add_memory or similar method
+            try:
+                # Try different MCAL methods
+                if hasattr(self._mcal, 'add_memory'):
+                    self._mcal.add_memory(
+                        text=text,
+                        metadata=metadata,
+                        user_id=self._user_id,
+                    )
+                elif hasattr(self._mcal, 'store'):
+                    self._mcal.store(
+                        content=text,
+                        metadata=metadata,
+                    )
+                elif hasattr(self._mcal, 'add'):
+                    self._mcal.add(text, metadata=metadata)
+            except Exception:
+                # Silently continue if MCAL storage fails
+                # The in-memory storage still works
+                pass
+    
+    async def query(
+        self,
+        query: str | MemoryContent,
+        cancellation_token: Optional[CancellationToken] = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        """
+        Query memory for relevant content.
+        
+        Uses MCAL's goal-aware search to find the most relevant memories
+        based on the current project goal and query.
+        
+        Args:
+            query: Query string or MemoryContent
+            cancellation_token: Optional token to cancel operation
+            **kwargs: Additional query parameters
+        
+        Returns:
+            MemoryQueryResult containing matching memories
+        """
+        # Check cancellation
+        if cancellation_token and hasattr(cancellation_token, 'cancelled'):
+            if getattr(cancellation_token, 'cancelled', False):
+                return MemoryQueryResult(results=[])
+        
+        # Cleanup expired entries
+        self._cleanup_expired()
+        
+        query_text = self._extract_text(query)
+        if not query_text:
+            return MemoryQueryResult(results=[])
+        
+        # Get search parameters
+        max_results = kwargs.get('max_results', self._max_results)
+        score_threshold = kwargs.get('score_threshold', self._score_threshold)
+        
+        results: List[MemoryContent] = []
+        
+        # Try MCAL search first for goal-aware results
+        try:
+            mcal_results = []
+            if hasattr(self._mcal, 'search'):
+                mcal_results = self._mcal.search(
+                    query=query_text,
+                    user_id=self._user_id,
+                    top_k=max_results,
+                    include_decisions=self._include_decisions,
+                )
+            elif hasattr(self._mcal, 'query'):
+                mcal_results = self._mcal.query(
+                    query_text,
+                    top_k=max_results,
+                )
+            
+            # Convert MCAL results to MemoryContent
+            for item in mcal_results[:max_results]:
+                score = 0.0
+                text = ""
+                metadata: Dict[str, Any] = {}
+                
+                if isinstance(item, dict):
+                    text = item.get('content', item.get('text', str(item)))
+                    score = item.get('score', item.get('relevance', 0.0))
+                    metadata = item.get('metadata', {})
+                elif hasattr(item, 'content'):
+                    text = str(item.content)
+                    score = getattr(item, 'score', 0.0)
+                    metadata = getattr(item, 'metadata', {})
+                else:
+                    text = str(item)
+                
+                # Apply score threshold
+                if score >= score_threshold:
+                    metadata['score'] = score
+                    results.append(MemoryContent(
+                        content=text,
+                        mime_type=MemoryMimeType.TEXT,
+                        metadata=metadata,
+                    ))
+        except Exception:
+            # Fallback to in-memory search if MCAL fails
+            pass
+        
+        # If no MCAL results, fall back to simple in-memory search
+        if not results:
+            query_lower = query_text.lower()
+            with self._lock:
+                for content_id, content in self._items.items():
+                    if self._is_expired(content_id):
+                        continue
+                    
+                    text = self._extract_text(content)
+                    # Simple text matching
+                    if query_lower in text.lower():
+                        metadata = dict(content.metadata) if content.metadata else {}
+                        metadata['score'] = 0.5  # Default score for text match
+                        results.append(MemoryContent(
+                            content=text,
+                            mime_type=content.mime_type,
+                            metadata=metadata,
+                        ))
+                        
+                        if len(results) >= max_results:
+                            break
+        
+        return MemoryQueryResult(results=results[:max_results])
+    
+    async def update_context(
+        self,
+        model_context: ChatCompletionContext,
+    ) -> UpdateContextResult:
+        """
+        Update the model context with relevant memories.
+        
+        This method retrieves the conversation history, uses the last
+        message as a query to find relevant memories, and adds them
+        to the context as a system message.
+        
+        Args:
+            model_context: The model context to update
+        
+        Returns:
+            UpdateContextResult containing memories added to context
+        """
+        # Get messages from context
+        messages = await model_context.get_messages()
+        if not messages:
+            return UpdateContextResult(memories=MemoryQueryResult(results=[]))
+        
+        # Use the last message as query
+        last_message = messages[-1]
+        query_text = (
+            last_message.content
+            if isinstance(last_message.content, str)
+            else str(last_message)
+        )
+        
+        # Query memory
+        query_results = await self.query(query_text)
+        
+        # Add relevant memories to context
+        if query_results.results:
+            memory_strings = [
+                f"{i}. {self._extract_text(memory)}"
+                for i, memory in enumerate(query_results.results, 1)
+            ]
+            memory_context = (
+                "\nRelevant context from memory:\n" + 
+                "\n".join(memory_strings)
+            )
+            
+            # Add as system message
+            await model_context.add_message(
+                SystemMessage(content=memory_context)
+            )
+        
+        return UpdateContextResult(memories=query_results)
+    
+    async def clear(self) -> None:
+        """Clear all memory entries for this user."""
+        with self._lock:
+            # Filter to only clear this user's entries
+            user_prefix = f"mem_{self._user_id}_"
+            to_remove = [
+                cid for cid in self._items.keys()
+                if cid.startswith(user_prefix) or self._user_id == "default"
+            ]
+            
+            for cid in to_remove:
+                self._items.pop(cid, None)
+                self._created_at.pop(cid, None)
+                self._expires_at.pop(cid, None)
+        
+        # Also clear from MCAL if possible
+        try:
+            if hasattr(self._mcal, 'clear_user'):
+                self._mcal.clear_user(self._user_id)
+            elif hasattr(self._mcal, 'reset'):
+                # Only reset if default user (affects all)
+                if self._user_id == "default":
+                    self._mcal.reset()
+        except Exception:
+            pass
+    
+    async def close(self) -> None:
+        """Clean up resources."""
+        # Clear in-memory data
+        with self._lock:
+            self._items.clear()
+            self._created_at.clear()
+            self._expires_at.clear()
+    
+    # -------------------------------------------------------------------------
+    # Additional helper methods
+    # -------------------------------------------------------------------------
+    
+    def get_item_count(self) -> int:
+        """Get the number of non-expired items in memory."""
+        self._cleanup_expired()
+        with self._lock:
+            return len(self._items)
+    
+    def get_all_items(self) -> List[MemoryContent]:
+        """Get all non-expired items (for debugging)."""
+        self._cleanup_expired()
+        with self._lock:
+            return list(self._items.values())
+    
+    async def add_text(
+        self,
+        text: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Convenience method to add plain text to memory.
+        
+        Args:
+            text: Text content to add
+            metadata: Optional metadata
+        """
+        content = MemoryContent(
+            content=text,
+            mime_type=MemoryMimeType.TEXT,
+            metadata=metadata,
+        )
+        await self.add(content)
+    
+    async def query_text(
+        self,
+        query: str,
+        max_results: Optional[int] = None,
+    ) -> List[str]:
+        """
+        Convenience method to query and return plain text results.
+        
+        Args:
+            query: Search query
+            max_results: Optional max results override
+        
+        Returns:
+            List of text strings from matching memories
+        """
+        kwargs = {}
+        if max_results is not None:
+            kwargs['max_results'] = max_results
+        
+        results = await self.query(query, **kwargs)
+        return [self._extract_text(r) for r in results.results]
+
+
+__all__ = ["MCALMemory"]