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

mcal_ai_langgraph-0.2.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: mcal-ai-langgraph
+Version: 0.2.0
+Summary: LangGraph integration for MCAL - Goal-aware memory for AI agents
+Author: MCAL Team
+License: MIT
+Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
+Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai/blob/main/docs/integrations/langgraph.md
+Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai.git
+Project-URL: Issues, https://github.com/Shivakoreddi/mcal-ai/issues
+Keywords: mcal,langgraph,memory,agents,llm,goal-aware,langchain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcal-ai>=0.1.0
+Requires-Dist: langgraph>=0.0.40
+Requires-Dist: langchain-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# mcal-langgraph
+
+LangGraph integration for [MCAL](https://github.com/Shivakoreddi/mcla-research) - Goal-aware memory for AI agents.
+
+## Installation
+
+```bash
+pip install mcal-langgraph
+```
+
+This will automatically install `mcal` and `langgraph` as dependencies.
+
+## Quick Start
+
+```python
+from mcal import MCAL
+from mcal_langgraph import MCALStore
+
+# Initialize MCAL with a goal
+mcal = MCAL(goal="Build a fraud detection system")
+
+# Create LangGraph-compatible store
+store = MCALStore(mcal)
+
+# Use with LangGraph
+from langgraph.prebuilt import create_react_agent
+
+agent = create_react_agent(
+    model=your_model,
+    tools=your_tools,
+    store=store  # Goal-aware memory!
+)
+```
+
+## Features
+
+### MCALStore (BaseStore)
+
+Drop-in replacement for LangGraph's built-in stores with **goal-aware** memory:
+
+```python
+from mcal_langgraph import MCALStore
+
+store = MCALStore(mcal)
+
+# Store memories
+await store.aput(
+    namespace=("user_123", "memories"),
+    key="decision_1",
+    value={"text": "Decided to use PostgreSQL for ACID compliance"}
+)
+
+# Goal-aware search - returns memories relevant to current goals
+results = await store.asearch(
+    namespace_prefix=("user_123",),
+    query="database choice"
+)
+
+# Results include goal context and decisions
+for item in results:
+    print(item.value["goals"])      # Related goals
+    print(item.value["decisions"])  # Related decisions
+```
+
+### MCALMemory
+
+Memory nodes for custom LangGraph workflows:
+
+```python
+from mcal_langgraph import MCALMemory
+
+memory = MCALMemory(llm_provider="anthropic")
+
+# Add as nodes in your graph
+graph.add_node("update_memory", memory.update_node())
+graph.add_node("get_context", memory.context_node())
+```
+
+### MCALCheckpointer
+
+State persistence for LangGraph graphs:
+
+```python
+from mcal_langgraph import MCALCheckpointer
+
+checkpointer = MCALCheckpointer(mcal)
+graph = builder.compile(checkpointer=checkpointer)
+```
+
+## Why mcal-langgraph?
+
+| Feature | LangGraph InMemoryStore | **MCALStore** |
+|---------|------------------------|---------------|
+| BaseStore interface | ✅ | ✅ |
+| Namespace organization | ✅ | ✅ |
+| **Goal-aware search** | ❌ | ✅ |
+| **Decision tracking** | ❌ | ✅ |
+| **Intent preservation** | ❌ | ✅ |
+
+## Migrating from mcal[langgraph]
+
+If you were using the old extras-based installation:
+
+```python
+# Old way (deprecated)
+from mcal.integrations.langgraph import MCALStore
+
+# New way (recommended)
+from mcal_langgraph import MCALStore
+```
+
+The old import path still works but will show a deprecation warning.
+
+## License
+
+MIT

mcal_ai_langgraph-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcal_ai_langgraph-0.2.0.dist-info/licenses/LICENSE,sha256=zdp5kxDzb-kYvBiEZ_h1Hi96z-o6e5oXoXFx2IIefCs,1062
+mcal_langgraph/__init__.py,sha256=YfCMV6GcPo8zITC9y6BfdkIcpT3U4oZNG7-rsFUZYrg,1022
+mcal_langgraph/_compat.py,sha256=_KO7SX8g4ahMVHoHDqpuBFO-dpgOVA1JUlc2daw9Ph0,1644
+mcal_langgraph/checkpointer.py,sha256=y9ChSXu71J9FWnwpnHRhdpuR-7FNQoSGrKtA7fn5x5U,1687
+mcal_langgraph/memory.py,sha256=POgMIoVXuZA8KAM-o2ZR6bIx9k4ct4T6WwBU4QRFkGU,6047
+mcal_langgraph/py.typed,sha256=2X_1X_HUbFbPMsgG85pQ4WTxzXDtgoxEZEPV1nHY9nw,40
+mcal_langgraph/store.py,sha256=8XgYI2Y2oFL54vooRRM633FtU04cbHIWYHGQG9fC1cY,19608
+mcal_ai_langgraph-0.2.0.dist-info/METADATA,sha256=aZTOXcAYtbQ__0MjFY1DN-GlUUhJsMQuNnez8Lj5kbw,3871
+mcal_ai_langgraph-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mcal_ai_langgraph-0.2.0.dist-info/top_level.txt,sha256=msXK9BlyqOeRq-IPIzT2O9j7bwlx1fe9z_cb5rYszUU,15
+mcal_ai_langgraph-0.2.0.dist-info/RECORD,,

mcal_ai_langgraph-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_langgraph-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_langgraph-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcal_langgraph

mcal_langgraph/__init__.py

@@ -0,0 +1,39 @@
+"""
+mcal-langgraph: LangGraph integration for MCAL
+
+Provides goal-aware memory for LangGraph agent workflows:
+- MCALStore: BaseStore implementation with goal-aware search
+- MCALMemory: Memory nodes for LangGraph workflows  
+- MCALCheckpointer: State persistence for graphs
+
+Installation:
+    pip install mcal-langgraph
+
+Usage:
+    from mcal import MCAL
+    from mcal_langgraph import MCALStore
+    
+    mcal = MCAL(goal="Build fraud detection system")
+    store = MCALStore(mcal)
+    
+    # Use with LangGraph
+    from langgraph.prebuilt import create_react_agent
+    agent = create_react_agent(model, tools, store=store)
+"""
+
+from mcal_langgraph.store import MCALStore
+from mcal_langgraph.memory import MCALMemory, MCALMemoryConfig
+from mcal_langgraph.checkpointer import MCALCheckpointer
+from mcal_langgraph._compat import LANGGRAPH_AVAILABLE
+
+# Version
+__version__ = "0.1.0"
+
+__all__ = [
+    "MCALStore",
+    "MCALMemory",
+    "MCALMemoryConfig",
+    "MCALCheckpointer",
+    "LANGGRAPH_AVAILABLE",
+    "__version__",
+]

mcal_langgraph/_compat.py

@@ -0,0 +1,71 @@
+"""
+Compatibility layer for LangGraph imports.
+
+Handles graceful degradation when langgraph is not installed.
+"""
+
+from __future__ import annotations
+from typing import Any
+
+# Check for LangGraph availability
+try:
+    from langgraph.graph import StateGraph
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+    from langgraph.store.base import (
+        BaseStore,
+        Item,
+        SearchItem,
+        GetOp,
+        PutOp,
+        SearchOp,
+        ListNamespacesOp,
+        NamespacePath,
+    )
+    from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
+    
+    LANGGRAPH_AVAILABLE = True
+except ImportError:
+    LANGGRAPH_AVAILABLE = False
+    StateGraph = None
+    BaseCheckpointSaver = object
+    BaseStore = object
+    Item = None
+    SearchItem = None
+    GetOp = None
+    PutOp = None
+    SearchOp = None
+    ListNamespacesOp = None
+    NamespacePath = None
+    BaseMessage = Any
+    HumanMessage = Any
+    AIMessage = Any
+
+
+def check_langgraph():
+    """Raise helpful error if LangGraph not installed."""
+    if not LANGGRAPH_AVAILABLE:
+        raise ImportError(
+            "mcal-langgraph requires langgraph package.\n"
+            "Install with: pip install mcal-langgraph\n"
+            "Or manually: pip install langgraph langchain-core"
+        )
+
+
+# Export everything needed by other modules
+__all__ = [
+    "LANGGRAPH_AVAILABLE",
+    "check_langgraph",
+    "StateGraph",
+    "BaseCheckpointSaver",
+    "BaseStore",
+    "Item",
+    "SearchItem",
+    "GetOp",
+    "PutOp",
+    "SearchOp",
+    "ListNamespacesOp",
+    "NamespacePath",
+    "BaseMessage",
+    "HumanMessage",
+    "AIMessage",
+]

mcal_langgraph/checkpointer.py

@@ -0,0 +1,53 @@
+"""
+MCALCheckpointer: State persistence for LangGraph graphs.
+
+Stores graph state alongside MCAL memory for unified persistence.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from mcal_langgraph._compat import (
+    check_langgraph,
+    LANGGRAPH_AVAILABLE,
+    BaseCheckpointSaver,
+)
+
+
+class MCALCheckpointer(BaseCheckpointSaver if LANGGRAPH_AVAILABLE else object):
+    """
+    MCAL-based checkpointer for LangGraph state persistence.
+    
+    Stores graph state alongside MCAL memory for unified persistence.
+    
+    Usage:
+        from mcal_langgraph import MCALCheckpointer
+        
+        checkpointer = MCALCheckpointer(storage_path="~/.mcal")
+        graph = StateGraph(...).compile(checkpointer=checkpointer)
+    """
+    
+    def __init__(self, storage_path: Optional[str] = None):
+        check_langgraph()
+        if LANGGRAPH_AVAILABLE:
+            super().__init__()
+        self.storage_path = storage_path
+        self._checkpoints: Dict[str, Any] = {}
+    
+    def get(self, config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Get checkpoint by config."""
+        thread_id = config.get("configurable", {}).get("thread_id", "default")
+        return self._checkpoints.get(thread_id)
+    
+    def put(self, config: Dict[str, Any], checkpoint: Dict[str, Any]) -> None:
+        """Save checkpoint."""
+        thread_id = config.get("configurable", {}).get("thread_id", "default")
+        self._checkpoints[thread_id] = checkpoint
+    
+    def list(self, config: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """List all checkpoints."""
+        return list(self._checkpoints.values())
+
+
+__all__ = ["MCALCheckpointer"]

mcal_langgraph/memory.py

@@ -0,0 +1,189 @@
+"""
+MCALMemory: Memory nodes for LangGraph workflows.
+
+Provides goal-aware memory that preserves reasoning context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Sequence, TYPE_CHECKING
+
+from mcal_langgraph._compat import check_langgraph, BaseMessage
+from mcal_langgraph.store import MCALStore
+
+if TYPE_CHECKING:
+    from mcal import MCAL
+
+
+@dataclass
+class MCALMemoryConfig:
+    """Configuration for MCAL memory in LangGraph."""
+    llm_provider: str = "anthropic"
+    embedding_provider: str = "openai"
+    storage_path: Optional[str] = None
+    user_id: str = "default"
+    include_goals: bool = True
+    include_decisions: bool = True
+    max_context_tokens: int = 4000
+
+
+class MCALMemory:
+    """
+    MCAL Memory component for LangGraph workflows.
+    
+    Provides goal-aware memory that preserves reasoning context
+    across agent interactions.
+    
+    Usage:
+        from mcal_langgraph import MCALMemory
+        from langgraph.graph import StateGraph
+        
+        memory = MCALMemory(llm_provider="anthropic")
+        
+        # Add as a node in your graph
+        graph = StateGraph(...)
+        graph.add_node("update_memory", memory.update_node())
+        graph.add_node("get_context", memory.context_node())
+    """
+    
+    def __init__(
+        self,
+        llm_provider: str = "anthropic",
+        embedding_provider: str = "openai",
+        storage_path: Optional[str] = None,
+        user_id: str = "default",
+        **mcal_kwargs
+    ):
+        check_langgraph()
+        
+        # Import MCAL here to avoid circular imports
+        from mcal import MCAL
+        
+        self.user_id = user_id
+        self._mcal = MCAL(
+            llm_provider=llm_provider,
+            storage_path=storage_path,
+            **mcal_kwargs
+        )
+    
+    @property
+    def mcal(self) -> "MCAL":
+        """Get the underlying MCAL instance."""
+        return self._mcal
+    
+    def as_store(self) -> MCALStore:
+        """Get a LangGraph BaseStore backed by this memory."""
+        return MCALStore(self._mcal)
+    
+    def _convert_messages(self, messages: Sequence[BaseMessage]) -> List[Dict[str, str]]:
+        """Convert LangChain messages to MCAL format."""
+        result = []
+        for msg in messages:
+            if hasattr(msg, 'type'):
+                if msg.type == "human":
+                    result.append({"role": "user", "content": str(msg.content)})
+                elif msg.type == "ai":
+                    result.append({"role": "assistant", "content": str(msg.content)})
+                else:
+                    result.append({"role": "user", "content": str(msg.content)})
+            else:
+                result.append({"role": "user", "content": str(msg.content)})
+        return result
+    
+    async def add(self, messages: Sequence[BaseMessage]) -> Dict[str, Any]:
+        """
+        Add messages to MCAL memory.
+        
+        Args:
+            messages: LangChain message sequence
+            
+        Returns:
+            Extraction result with goals and decisions
+        """
+        mcal_messages = self._convert_messages(messages)
+        result = await self._mcal.add(mcal_messages, user_id=self.user_id)
+        return {
+            "goals": result.unified_graph.get_active_goals() if result.unified_graph else [],
+            "decisions": result.unified_graph.get_all_decisions_with_detail() if result.unified_graph else [],
+            "node_count": result.unified_graph.node_count if result.unified_graph else 0,
+        }
+    
+    async def get_context(self, query: str, max_tokens: int = 4000) -> str:
+        """
+        Get goal-aware context for a query.
+        
+        Args:
+            query: The current query/task
+            max_tokens: Maximum context tokens
+            
+        Returns:
+            Formatted context string
+        """
+        return await self._mcal.get_context(
+            query=query,
+            user_id=self.user_id,
+            max_tokens=max_tokens
+        )
+    
+    async def search(self, query: str, top_k: int = 10) -> List[Dict[str, Any]]:
+        """
+        Search memory for relevant information.
+        
+        Args:
+            query: Search query
+            top_k: Number of results
+            
+        Returns:
+            List of search results
+        """
+        results = await self._mcal.search(query, user_id=self.user_id, top_k=top_k)
+        return results.results if results else []
+    
+    def update_node(self) -> Callable:
+        """
+        Create a LangGraph node that updates memory.
+        
+        Usage:
+            graph.add_node("update_memory", memory.update_node())
+        
+        Returns:
+            Async function suitable for add_node()
+        """
+        async def _update_memory(state: Dict[str, Any]) -> Dict[str, Any]:
+            messages = state.get("messages", [])
+            if messages:
+                result = await self.add(messages)
+                return {
+                    "memory_updated": True,
+                    "active_goals": result.get("goals", []),
+                    "decisions": result.get("decisions", []),
+                }
+            return {"memory_updated": False}
+        
+        return _update_memory
+    
+    def context_node(self, query_key: str = "query") -> Callable:
+        """
+        Create a LangGraph node that retrieves context.
+        
+        Usage:
+            graph.add_node("get_context", memory.context_node())
+        
+        Args:
+            query_key: State key containing the query
+            
+        Returns:
+            Async function suitable for add_node()
+        """
+        async def _get_context(state: Dict[str, Any]) -> Dict[str, Any]:
+            query = state.get(query_key, "")
+            if query:
+                context = await self.get_context(query)
+                return {"memory_context": context}
+            return {"memory_context": ""}
+        
+        return _get_context
+
+
+__all__ = ["MCALMemory", "MCALMemoryConfig"]

mcal_langgraph/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 typed package

mcal_langgraph/store.py

@@ -0,0 +1,564 @@
+"""
+MCALStore: LangGraph BaseStore implementation with goal-aware search.
+
+This is the main integration point for LangGraph users.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from datetime import datetime, timezone, timedelta
+from typing import Any, Dict, Iterable, List, Literal, Tuple, TYPE_CHECKING
+
+from mcal_langgraph._compat import (
+    LANGGRAPH_AVAILABLE,
+    check_langgraph,
+    BaseStore,
+    Item,
+    SearchItem,
+    GetOp,
+    PutOp,
+    SearchOp,
+    ListNamespacesOp,
+    NamespacePath,
+)
+
+if TYPE_CHECKING:
+    from mcal import MCAL
+
+# Type aliases
+Op = Any
+Result = Any
+
+
+def _run_sync(coro):
+    """
+    Run async coroutine synchronously, handling existing event loops.
+    
+    Works in Lambda, Jupyter, FastAPI, and other async environments.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop - safe to use asyncio.run()
+        return asyncio.run(coro)
+    else:
+        # Loop already running - run in thread pool
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(asyncio.run, coro)
+            return future.result()
+
+
+class MCALStore(BaseStore if LANGGRAPH_AVAILABLE else object):
+    """
+    LangGraph-compatible store backed by MCAL.
+    
+    Implements LangGraph's BaseStore interface, providing MCAL's
+    goal-aware memory capabilities through the standard LangGraph API.
+    
+    Key Advantages over generic stores:
+    - Goal-aware search (MCAL's unique value)
+    - Decision tracking in search results
+    - Intent preservation across conversations
+    
+    Usage:
+        from mcal import MCAL
+        from mcal_langgraph import MCALStore
+        
+        mcal = MCAL(goal="Build fraud detection system")
+        store = MCALStore(mcal)
+        
+        # Use with LangGraph
+        from langgraph.prebuilt import create_react_agent
+        agent = create_react_agent(model, tools, store=store)
+        
+        # Or use directly
+        await store.aput(("user_123",), "mem1", {"text": "Use PostgreSQL"})
+        results = await store.asearch(("user_123",), query="database choice")
+    """
+    
+    def __init__(self, mcal: "MCAL"):
+        """
+        Initialize MCALStore.
+        
+        Args:
+            mcal: Initialized MCAL instance
+        """
+        check_langgraph()
+        self._mcal = mcal
+        self._lock = threading.RLock()  # Thread safety for writes
+        
+        # In-memory storage for items
+        self._items: Dict[Tuple[str, ...], Dict[str, Dict[str, Any]]] = {}
+        self._created_at: Dict[Tuple[str, ...], Dict[str, datetime]] = {}
+        self._updated_at: Dict[Tuple[str, ...], Dict[str, datetime]] = {}
+        
+        # TTL support (Issue #057)
+        self._ttl: Dict[Tuple[str, ...], Dict[str, float]] = {}  # TTL in minutes
+        self._expires_at: Dict[Tuple[str, ...], Dict[str, datetime]] = {}  # Expiration times
+    
+    @property
+    def mcal(self) -> "MCAL":
+        """Get the underlying MCAL instance."""
+        return self._mcal
+    
+    # ========== TTL Support (Issue #057) ==========
+    
+    def _is_expired(self, namespace: Tuple[str, ...], key: str) -> bool:
+        """Check if an item has expired based on TTL."""
+        if namespace not in self._expires_at:
+            return False
+        if key not in self._expires_at.get(namespace, {}):
+            return False
+        
+        expires_at = self._expires_at[namespace][key]
+        return datetime.now(timezone.utc) > expires_at
+    
+    def _refresh_ttl(self, namespace: Tuple[str, ...], key: str) -> None:
+        """Refresh TTL by updating expiration time."""
+        if namespace in self._ttl and key in self._ttl.get(namespace, {}):
+            ttl_minutes = self._ttl[namespace][key]
+            self._expires_at[namespace][key] = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    
+    def _cleanup_ttl(self, namespace: Tuple[str, ...], key: str) -> None:
+        """Clean up TTL tracking for a deleted item."""
+        if namespace in self._ttl and key in self._ttl.get(namespace, {}):
+            del self._ttl[namespace][key]
+        if namespace in self._expires_at and key in self._expires_at.get(namespace, {}):
+            del self._expires_at[namespace][key]
+    
+    # ========== Abstract Methods (Required by BaseStore) ==========
+    
+    def batch(self, ops: Iterable[Op]) -> List[Result]:
+        """Execute multiple operations synchronously in a single batch."""
+        return _run_sync(self.abatch(ops))
+    
+    async def abatch(self, ops: Iterable[Op]) -> List[Result]:
+        """Execute multiple operations asynchronously in a single batch."""
+        results = []
+        for op in ops:
+            if isinstance(op, GetOp):
+                result = await self.aget(op.namespace, op.key)
+                results.append(result)
+            elif isinstance(op, PutOp):
+                await self.aput(op.namespace, op.key, op.value)
+                results.append(None)
+            elif isinstance(op, SearchOp):
+                result = await self.asearch(
+                    op.namespace_prefix,
+                    query=op.query,
+                    filter=op.filter,
+                    limit=op.limit,
+                    offset=op.offset,
+                )
+                results.append(result)
+            elif isinstance(op, ListNamespacesOp):
+                prefix = None
+                suffix = None
+                if op.match_conditions:
+                    for cond in op.match_conditions:
+                        if cond.match_type == "prefix":
+                            prefix = cond.path
+                        elif cond.match_type == "suffix":
+                            suffix = cond.path
+                result = await self.alist_namespaces(
+                    prefix=prefix,
+                    suffix=suffix,
+                    max_depth=op.max_depth,
+                    limit=op.limit,
+                    offset=op.offset,
+                )
+                results.append(result)
+            else:
+                results.append(None)
+        return results
+    
+    # ========== Get Operations ==========
+    
+    def get(
+        self,
+        namespace: Tuple[str, ...],
+        key: str,
+        *,
+        refresh_ttl: bool | None = None,
+    ) -> Item | None:
+        """Retrieve a single item synchronously."""
+        return _run_sync(self.aget(namespace, key, refresh_ttl=refresh_ttl))
+    
+    async def aget(
+        self,
+        namespace: Tuple[str, ...],
+        key: str,
+        *,
+        refresh_ttl: bool | None = None,
+    ) -> Item | None:
+        """
+        Retrieve a single item asynchronously.
+        
+        Args:
+            namespace: The namespace tuple for the item
+            key: The unique key within the namespace
+            refresh_ttl: If True, refresh the TTL on access. Default: True for items with TTL.
+        
+        Returns:
+            Item if found and not expired, None otherwise
+        """
+        if namespace not in self._items:
+            return None
+        if key not in self._items[namespace]:
+            return None
+        
+        # Check TTL expiration (lazy expiration)
+        if self._is_expired(namespace, key):
+            # Item has expired - delete it
+            with self._lock:
+                if namespace in self._items and key in self._items[namespace]:
+                    del self._items[namespace][key]
+                    self._cleanup_ttl(namespace, key)
+            return None
+        
+        # Refresh TTL on access if requested (default: True for items with TTL)
+        if refresh_ttl is not False:
+            with self._lock:
+                self._refresh_ttl(namespace, key)
+        
+        value = self._items[namespace][key]
+        created = self._created_at.get(namespace, {}).get(key, datetime.now(timezone.utc))
+        updated = self._updated_at.get(namespace, {}).get(key, datetime.now(timezone.utc))
+        
+        return Item(
+            namespace=namespace,
+            key=key,
+            value=value,
+            created_at=created,
+            updated_at=updated,
+        )
+    
+    # ========== Put Operations ==========
+    
+    def put(
+        self,
+        namespace: Tuple[str, ...],
+        key: str,
+        value: Dict[str, Any],
+        index: Literal[False] | List[str] | None = None,
+        *,
+        ttl: float | None = None,
+    ) -> None:
+        """Store or update an item synchronously."""
+        _run_sync(self.aput(namespace, key, value, index, ttl=ttl))
+    
+    async def aput(
+        self,
+        namespace: Tuple[str, ...],
+        key: str,
+        value: Dict[str, Any],
+        index: Literal[False] | List[str] | None = None,
+        *,
+        ttl: float | None = None,
+    ) -> None:
+        """
+        Store or update an item asynchronously.
+        
+        Args:
+            namespace: The namespace tuple for the item
+            key: The unique key within the namespace
+            value: The value to store (must be a dict)
+            index: Fields to index for search. False to skip indexing.
+            ttl: Time-to-live in minutes. None for no expiration.
+        """
+        now = datetime.now(timezone.utc)
+        
+        # Thread-safe write
+        with self._lock:
+            if namespace not in self._items:
+                self._items[namespace] = {}
+                self._created_at[namespace] = {}
+                self._updated_at[namespace] = {}
+            
+            if key not in self._items[namespace]:
+                self._created_at[namespace][key] = now
+            
+            self._items[namespace][key] = value
+            self._updated_at[namespace][key] = now
+            
+            # Store TTL if provided (Issue #057)
+            if ttl is not None:
+                if namespace not in self._ttl:
+                    self._ttl[namespace] = {}
+                    self._expires_at[namespace] = {}
+                self._ttl[namespace][key] = ttl
+                self._expires_at[namespace][key] = now + timedelta(minutes=ttl)
+        
+        # Process through MCAL for goal-aware retrieval (outside lock)
+        user_id = namespace[0] if namespace else "default"
+        text = value.get("text", value.get("content", json.dumps(value)))
+        
+        if text and index is not False:
+            try:
+                await self._mcal.add(
+                    messages=[{"role": "user", "content": text}],
+                    user_id=user_id,
+                    metadata={"key": key, "namespace": "/".join(namespace)},
+                )
+            except Exception:
+                pass  # Don't fail if MCAL processing fails
+    
+    # ========== Delete Operations ==========
+    
+    def delete(self, namespace: Tuple[str, ...], key: str) -> None:
+        """Delete an item synchronously."""
+        _run_sync(self.adelete(namespace, key))
+    
+    async def adelete(self, namespace: Tuple[str, ...], key: str) -> None:
+        """Delete an item asynchronously."""
+        with self._lock:
+            if namespace in self._items and key in self._items[namespace]:
+                del self._items[namespace][key]
+                if namespace in self._created_at and key in self._created_at[namespace]:
+                    del self._created_at[namespace][key]
+                if namespace in self._updated_at and key in self._updated_at[namespace]:
+                    del self._updated_at[namespace][key]
+                # Clean up TTL tracking
+                self._cleanup_ttl(namespace, key)
+    
+    # ========== Search Operations ==========
+    
+    def search(
+        self,
+        namespace_prefix: Tuple[str, ...],
+        /,
+        *,
+        query: str | None = None,
+        filter: Dict[str, Any] | None = None,
+        limit: int = 10,
+        offset: int = 0,
+        refresh_ttl: bool | None = None,
+    ) -> List[SearchItem]:
+        """Search for items synchronously."""
+        return _run_sync(
+            self.asearch(
+                namespace_prefix,
+                query=query,
+                filter=filter,
+                limit=limit,
+                offset=offset,
+                refresh_ttl=refresh_ttl,
+            )
+        )
+    
+    async def asearch(
+        self,
+        namespace_prefix: Tuple[str, ...],
+        /,
+        *,
+        query: str | None = None,
+        filter: Dict[str, Any] | None = None,
+        limit: int = 10,
+        offset: int = 0,
+        refresh_ttl: bool | None = None,
+    ) -> List[SearchItem]:
+        """
+        Search for items asynchronously.
+        
+        MCAL Enhancement: Uses goal-aware retrieval when query is provided,
+        enriching results with goals and decisions.
+        """
+        results = []
+        
+        # If query provided, use MCAL's goal-aware search
+        if query:
+            user_id = namespace_prefix[0] if namespace_prefix else "default"
+            try:
+                mcal_results = await self._mcal.search(
+                    query=query,
+                    user_id=user_id,
+                    top_k=limit,
+                )
+                
+                for i, result in enumerate(mcal_results.results if mcal_results else []):
+                    if i < offset:
+                        continue
+                    if len(results) >= limit:
+                        break
+                    
+                    now = datetime.now(timezone.utc)
+                    results.append(SearchItem(
+                        namespace=namespace_prefix,
+                        key=f"mcal_{i}",
+                        value={
+                            "text": result.get("content", result.get("memory", "")),
+                            "goals": result.get("goals", []),
+                            "decisions": result.get("decisions", []),
+                            "score": result.get("score", 0.0),
+                            "metadata": result.get("metadata", {}),
+                        },
+                        created_at=now,
+                        updated_at=now,
+                        score=result.get("score", 0.0),
+                    ))
+            except Exception:
+                pass
+        
+        # Also search in-memory items
+        for ns, items in list(self._items.items()):
+            if not self._namespace_matches_prefix(ns, namespace_prefix):
+                continue
+            
+            for key, value in list(items.items()):
+                # Skip expired items (lazy expiration)
+                if self._is_expired(ns, key):
+                    with self._lock:
+                        if ns in self._items and key in self._items[ns]:
+                            del self._items[ns][key]
+                            self._cleanup_ttl(ns, key)
+                    continue
+                
+                if filter and not self._matches_filter(value, filter):
+                    continue
+                
+                if query and not self._text_matches_query(value, query):
+                    continue
+                
+                # Refresh TTL on search access if requested
+                if refresh_ttl is not False:
+                    with self._lock:
+                        self._refresh_ttl(ns, key)
+                
+                created = self._created_at.get(ns, {}).get(key, datetime.now(timezone.utc))
+                updated = self._updated_at.get(ns, {}).get(key, datetime.now(timezone.utc))
+                
+                results.append(SearchItem(
+                    namespace=ns,
+                    key=key,
+                    value=value,
+                    created_at=created,
+                    updated_at=updated,
+                    score=1.0 if query else None,
+                ))
+        
+        return results[offset:offset + limit]
+    
+    # ========== List Namespaces ==========
+    
+    def list_namespaces(
+        self,
+        *,
+        prefix: NamespacePath | None = None,
+        suffix: NamespacePath | None = None,
+        max_depth: int | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Tuple[str, ...]]:
+        """List namespaces synchronously."""
+        return _run_sync(
+            self.alist_namespaces(
+                prefix=prefix,
+                suffix=suffix,
+                max_depth=max_depth,
+                limit=limit,
+                offset=offset,
+            )
+        )
+    
+    async def alist_namespaces(
+        self,
+        *,
+        prefix: NamespacePath | None = None,
+        suffix: NamespacePath | None = None,
+        max_depth: int | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Tuple[str, ...]]:
+        """List namespaces asynchronously."""
+        namespaces = set()
+        
+        for ns in self._items.keys():
+            if prefix and not self._namespace_matches_prefix(ns, prefix):
+                continue
+            
+            if suffix and not self._namespace_matches_suffix(ns, suffix):
+                continue
+            
+            if max_depth and len(ns) > max_depth:
+                ns = ns[:max_depth]
+            
+            namespaces.add(ns)
+        
+        sorted_ns = sorted(namespaces)
+        return sorted_ns[offset:offset + limit]
+    
+    # ========== Helper Methods ==========
+    
+    def _namespace_matches_prefix(
+        self,
+        namespace: Tuple[str, ...],
+        prefix: Tuple[str, ...],
+    ) -> bool:
+        """Check if namespace starts with prefix."""
+        if not prefix:
+            return True
+        if len(namespace) < len(prefix):
+            return False
+        return namespace[:len(prefix)] == prefix
+    
+    def _namespace_matches_suffix(
+        self,
+        namespace: Tuple[str, ...],
+        suffix: Tuple[str, ...],
+    ) -> bool:
+        """Check if namespace ends with suffix."""
+        if not suffix:
+            return True
+        if len(namespace) < len(suffix):
+            return False
+        return namespace[-len(suffix):] == suffix
+    
+    def _matches_filter(
+        self,
+        value: Dict[str, Any],
+        filter: Dict[str, Any],
+    ) -> bool:
+        """Check if value matches filter criteria."""
+        for key, expected in filter.items():
+            if key not in value:
+                return False
+            actual = value[key]
+            
+            if isinstance(expected, dict):
+                for op, val in expected.items():
+                    if op == "$eq" and actual != val:
+                        return False
+                    elif op == "$ne" and actual == val:
+                        return False
+                    elif op == "$gt" and not (actual > val):
+                        return False
+                    elif op == "$gte" and not (actual >= val):
+                        return False
+                    elif op == "$lt" and not (actual < val):
+                        return False
+                    elif op == "$lte" and not (actual <= val):
+                        return False
+            else:
+                if actual != expected:
+                    return False
+        return True
+    
+    def _text_matches_query(
+        self,
+        value: Dict[str, Any],
+        query: str,
+    ) -> bool:
+        """Simple text matching for query."""
+        query_lower = query.lower()
+        for field in ["text", "content", "memory", "description"]:
+            if field in value:
+                if query_lower in str(value[field]).lower():
+                    return True
+        return False
+
+
+__all__ = ["MCALStore"]