crewai-substrate-memory 0.1.1__tar.gz

crewai_substrate_memory-0.1.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: crewai-substrate-memory
+Version: 0.1.1
+Summary: SUBSTRATE persistent memory provider for CrewAI -- causal memory, emotion, and identity for your AI crews.
+Project-URL: Homepage, https://garmolabs.com/substrate.html
+Project-URL: Documentation, https://github.com/PKaldone/substrate-mcp
+Project-URL: Repository, https://github.com/PKaldone/substrate-mcp
+Project-URL: Issues, https://garmolabs.com/substrate.html
+Author-email: Garmo Labs <hello@garmolabs.com>
+License-Expression: MIT
+Keywords: ai,causal-memory,crewai,emotional-state,garmo-labs,mcp,memory,substrate
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: crewai>=0.80
+Requires-Dist: httpx>=0.25
+Description-Content-Type: text/markdown
+
+# crewai-substrate-memory
+
+SUBSTRATE persistent memory provider for [CrewAI](https://crewai.com). Gives your AI crew causal memory, emotional context, and cryptographic identity continuity through the [SUBSTRATE](https://garmolabs.com/substrate.html) MCP server.
+
+## What SUBSTRATE adds to CrewAI
+
+- **Causal memory** -- episodes linked by cause-effect rules, not just vector similarity
+- **Emotional context** -- valence, arousal, dominance, certainty (no other provider has this)
+- **Identity continuity** -- cryptographically signed proof-of-existence chain across sessions
+- **Trust architecture** -- consistency ratings and verification status for every memory
+- **Hybrid search** -- semantic + keyword retrieval across the entity's full knowledge store
+
+## Installation
+
+```bash
+pip install crewai-substrate-memory
+```
+
+## Quick start
+
+```python
+import os
+from crewai import Agent, Task, Crew
+from crewai_substrate import SubstrateMemoryProvider
+
+# 1. Create the SUBSTRATE memory provider
+memory = SubstrateMemoryProvider(
+    api_key=os.environ["SUBSTRATE_API_KEY"],
+)
+
+# 2. Define your agents
+researcher = Agent(
+    role="Researcher",
+    goal="Find relevant information on a topic",
+    backstory="Expert researcher with deep analytical skills",
+)
+
+writer = Agent(
+    role="Writer",
+    goal="Write clear, compelling content",
+    backstory="Professional writer who crafts engaging narratives",
+)
+
+# 3. Define tasks
+research_task = Task(
+    description="Research the latest developments in causal AI",
+    agent=researcher,
+    expected_output="A summary of key developments",
+)
+
+writing_task = Task(
+    description="Write a brief article based on the research",
+    agent=writer,
+    expected_output="A 500-word article",
+)
+
+# 4. Create the crew with SUBSTRATE memory
+crew = Crew(
+    agents=[researcher, writer],
+    tasks=[research_task, writing_task],
+    memory=True,
+    memory_config={"provider": memory},
+    verbose=True,
+)
+
+result = crew.kickoff()
+print(result)
+```
+
+## SUBSTRATE-exclusive features
+
+### Emotional context
+
+```python
+# Get the entity's emotional state (UASV -- Unified Affective State Vector)
+emotion = memory.get_emotional_context()
+print(emotion)
+# {"valence": 0.7, "arousal": 0.4, "dominance": 0.6, "certainty": 0.8}
+```
+
+### Entity state (identity + trust)
+
+```python
+# Verify cryptographic identity and get trust scores
+state = memory.get_entity_state()
+print(state["identity"])  # Continuity chain verification
+print(state["trust"])     # Trust scores and consistency ratings
+```
+
+### Memory statistics
+
+```python
+stats = memory.get_memory_stats()
+print(stats)
+# {"episode_count": 142, "rule_count": 37, "avg_probability": 0.82, ...}
+```
+
+## Configuration
+
+| Parameter   | Default                                              | Description                    |
+|-------------|------------------------------------------------------|--------------------------------|
+| `api_key`   | `$SUBSTRATE_API_KEY`                                 | Your SUBSTRATE API key         |
+| `base_url`  | `https://substrate.garmolabs.com/mcp-server/mcp`    | MCP server endpoint            |
+| `timeout`   | `30.0`                                               | HTTP request timeout (seconds) |
+
+## API key
+
+Get your API key at [garmolabs.com](https://garmolabs.com). The free tier includes `memory_search` and `get_emotion_state`. Upgrade to Pro for `hybrid_search` and `get_trust_state`.
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.
+
+Built by [Garmo Labs](https://garmolabs.com).

crewai_substrate_memory-0.1.1/README.md

@@ -0,0 +1,114 @@
+# crewai-substrate-memory
+
+SUBSTRATE persistent memory provider for [CrewAI](https://crewai.com). Gives your AI crew causal memory, emotional context, and cryptographic identity continuity through the [SUBSTRATE](https://garmolabs.com/substrate.html) MCP server.
+
+## What SUBSTRATE adds to CrewAI
+
+- **Causal memory** -- episodes linked by cause-effect rules, not just vector similarity
+- **Emotional context** -- valence, arousal, dominance, certainty (no other provider has this)
+- **Identity continuity** -- cryptographically signed proof-of-existence chain across sessions
+- **Trust architecture** -- consistency ratings and verification status for every memory
+- **Hybrid search** -- semantic + keyword retrieval across the entity's full knowledge store
+
+## Installation
+
+```bash
+pip install crewai-substrate-memory
+```
+
+## Quick start
+
+```python
+import os
+from crewai import Agent, Task, Crew
+from crewai_substrate import SubstrateMemoryProvider
+
+# 1. Create the SUBSTRATE memory provider
+memory = SubstrateMemoryProvider(
+    api_key=os.environ["SUBSTRATE_API_KEY"],
+)
+
+# 2. Define your agents
+researcher = Agent(
+    role="Researcher",
+    goal="Find relevant information on a topic",
+    backstory="Expert researcher with deep analytical skills",
+)
+
+writer = Agent(
+    role="Writer",
+    goal="Write clear, compelling content",
+    backstory="Professional writer who crafts engaging narratives",
+)
+
+# 3. Define tasks
+research_task = Task(
+    description="Research the latest developments in causal AI",
+    agent=researcher,
+    expected_output="A summary of key developments",
+)
+
+writing_task = Task(
+    description="Write a brief article based on the research",
+    agent=writer,
+    expected_output="A 500-word article",
+)
+
+# 4. Create the crew with SUBSTRATE memory
+crew = Crew(
+    agents=[researcher, writer],
+    tasks=[research_task, writing_task],
+    memory=True,
+    memory_config={"provider": memory},
+    verbose=True,
+)
+
+result = crew.kickoff()
+print(result)
+```
+
+## SUBSTRATE-exclusive features
+
+### Emotional context
+
+```python
+# Get the entity's emotional state (UASV -- Unified Affective State Vector)
+emotion = memory.get_emotional_context()
+print(emotion)
+# {"valence": 0.7, "arousal": 0.4, "dominance": 0.6, "certainty": 0.8}
+```
+
+### Entity state (identity + trust)
+
+```python
+# Verify cryptographic identity and get trust scores
+state = memory.get_entity_state()
+print(state["identity"])  # Continuity chain verification
+print(state["trust"])     # Trust scores and consistency ratings
+```
+
+### Memory statistics
+
+```python
+stats = memory.get_memory_stats()
+print(stats)
+# {"episode_count": 142, "rule_count": 37, "avg_probability": 0.82, ...}
+```
+
+## Configuration
+
+| Parameter   | Default                                              | Description                    |
+|-------------|------------------------------------------------------|--------------------------------|
+| `api_key`   | `$SUBSTRATE_API_KEY`                                 | Your SUBSTRATE API key         |
+| `base_url`  | `https://substrate.garmolabs.com/mcp-server/mcp`    | MCP server endpoint            |
+| `timeout`   | `30.0`                                               | HTTP request timeout (seconds) |
+
+## API key
+
+Get your API key at [garmolabs.com](https://garmolabs.com). The free tier includes `memory_search` and `get_emotion_state`. Upgrade to Pro for `hybrid_search` and `get_trust_state`.
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.
+
+Built by [Garmo Labs](https://garmolabs.com).

crewai_substrate_memory-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-substrate-memory"
+version = "0.1.1"
+description = "SUBSTRATE persistent memory provider for CrewAI -- causal memory, emotion, and identity for your AI crews."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Garmo Labs", email = "hello@garmolabs.com" },
+]
+keywords = [
+    "crewai",
+    "substrate",
+    "memory",
+    "ai",
+    "mcp",
+    "causal-memory",
+    "emotional-state",
+    "garmo-labs",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "crewai>=0.80",
+    "httpx>=0.25",
+]
+
+[project.urls]
+Homepage = "https://garmolabs.com/substrate.html"
+Documentation = "https://github.com/PKaldone/substrate-mcp"
+Repository = "https://github.com/PKaldone/substrate-mcp"
+Issues = "https://garmolabs.com/substrate.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_substrate"]

crewai_substrate_memory-0.1.1/src/crewai_substrate/__init__.py

@@ -0,0 +1,10 @@
+"""
+crewai-substrate-memory -- SUBSTRATE persistent memory for CrewAI.
+
+Gives your AI crew causal memory, emotional context, and cryptographic
+identity continuity through the SUBSTRATE MCP server.
+"""
+from crewai_substrate.memory import SubstrateMemoryProvider
+
+__all__ = ["SubstrateMemoryProvider"]
+__version__ = "0.1.0"

crewai_substrate_memory-0.1.1/src/crewai_substrate/client.py

@@ -0,0 +1,159 @@
+"""
+Synchronous HTTP client for the SUBSTRATE MCP server (JSON-RPC over HTTP).
+
+The SUBSTRATE MCP endpoint accepts standard JSON-RPC 2.0 requests with
+Bearer token authentication. This client wraps that transport into a
+clean Python interface for use by the memory provider.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("crewai_substrate.client")
+
+_DEFAULT_BASE_URL = "https://substrate.garmolabs.com/mcp-server/mcp"
+_DEFAULT_TIMEOUT = 30.0
+_JSONRPC_VERSION = "2.0"
+
+
+class SubstrateClientError(Exception):
+    """Raised when a SUBSTRATE MCP request fails."""
+
+    def __init__(self, message: str, code: int = -1) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class SubstrateClientConfig:
+    """Immutable configuration for the SUBSTRATE MCP client."""
+
+    api_key: str
+    base_url: str = _DEFAULT_BASE_URL
+    timeout: float = _DEFAULT_TIMEOUT
+
+
+class SubstrateClient:
+    """
+    Synchronous JSON-RPC client for the SUBSTRATE MCP server.
+
+    All tool calls go through ``call_tool`` which handles the JSON-RPC
+    envelope, authentication, error handling, and response unwrapping.
+    """
+
+    def __init__(self, config: SubstrateClientConfig) -> None:
+        if not config.api_key:
+            raise ValueError("api_key is required -- set SUBSTRATE_API_KEY")
+        self._config = config
+        self._request_id = 0
+        self._http = httpx.Client(
+            base_url="",  # We use full URL in requests
+            timeout=config.timeout,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {config.api_key}",
+            },
+        )
+        self._session_id: str | None = None
+
+    # -- Public API --------------------------------------------------------
+
+    def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> Any:
+        """
+        Call a SUBSTRATE MCP tool by name and return the result content.
+
+        Raises ``SubstrateClientError`` on JSON-RPC errors or HTTP failures.
+        """
+        self._request_id += 1
+        payload = {
+            "jsonrpc": _JSONRPC_VERSION,
+            "id": self._request_id,
+            "method": "tools/call",
+            "params": {
+                "name": name,
+                "arguments": arguments or {},
+            },
+        }
+        return self._send(payload)
+
+    def initialize(self) -> dict[str, Any]:
+        """Perform the MCP initialize handshake."""
+        self._request_id += 1
+        payload = {
+            "jsonrpc": _JSONRPC_VERSION,
+            "id": self._request_id,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {
+                    "name": "crewai-substrate-memory",
+                    "version": "0.1.0",
+                },
+            },
+        }
+        return self._send(payload)
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._http.close()
+
+    # -- Internal ----------------------------------------------------------
+
+    def _send(self, payload: dict[str, Any]) -> Any:
+        """Send a JSON-RPC request and return the unwrapped result."""
+        headers: dict[str, str] = {}
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+
+        try:
+            response = self._http.post(
+                self._config.base_url,
+                json=payload,
+                headers=headers,
+            )
+        except httpx.HTTPError as exc:
+            raise SubstrateClientError(f"HTTP request failed: {exc}") from exc
+
+        # Capture session ID from response
+        session_id = response.headers.get("Mcp-Session-Id")
+        if session_id:
+            self._session_id = session_id
+
+        if response.status_code == 401:
+            raise SubstrateClientError("Authentication failed -- check your SUBSTRATE_API_KEY", code=-32000)
+
+        if response.status_code == 429:
+            raise SubstrateClientError("Rate limit exceeded -- slow down or upgrade your plan", code=-32029)
+
+        if response.status_code not in (200, 202):
+            raise SubstrateClientError(
+                f"Unexpected HTTP {response.status_code}: {response.text[:200]}",
+                code=response.status_code,
+            )
+
+        try:
+            body = response.json()
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise SubstrateClientError(f"Invalid JSON response: {exc}") from exc
+
+        # Handle JSON-RPC error
+        if "error" in body:
+            err = body["error"]
+            raise SubstrateClientError(
+                err.get("message", "Unknown error"),
+                code=err.get("code", -1),
+            )
+
+        return body.get("result", {})
+
+    def __enter__(self) -> SubstrateClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

crewai_substrate_memory-0.1.1/src/crewai_substrate/memory.py

@@ -0,0 +1,287 @@
+"""
+SUBSTRATE Memory Provider for CrewAI.
+
+Replaces CrewAI's default memory with SUBSTRATE's causal memory engine,
+giving your crew persistent memory, emotional context, and identity
+continuity across sessions.
+
+This provider implements CrewAI's external memory interface and adds
+SUBSTRATE-exclusive capabilities (emotion, trust, identity verification)
+that no other memory provider offers.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from crewai_substrate.client import (
+    SubstrateClient,
+    SubstrateClientConfig,
+    SubstrateClientError,
+)
+
+logger = logging.getLogger("crewai_substrate.memory")
+
+
+def _extract_text(result: Any) -> str:
+    """
+    Extract text content from a SUBSTRATE MCP tool result.
+
+    The MCP tools/call response wraps content in a ``content`` list of
+    typed blocks. This helper pulls out all text blocks and joins them.
+    """
+    if isinstance(result, str):
+        return result
+    if isinstance(result, dict):
+        content = result.get("content", [])
+        if isinstance(content, list):
+            parts = [
+                block.get("text", "")
+                for block in content
+                if isinstance(block, dict) and block.get("type") == "text"
+            ]
+            return "\n".join(parts)
+        # Fallback: return the dict as JSON
+        return json.dumps(result, indent=2)
+    return str(result)
+
+
+def _parse_json_safe(text: str) -> dict[str, Any]:
+    """Parse JSON from text, returning an empty dict on failure."""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+
+@dataclass(frozen=True)
+class SubstrateMemoryConfig:
+    """
+    Configuration for the SUBSTRATE memory provider.
+
+    ``api_key`` defaults to the ``SUBSTRATE_API_KEY`` environment variable.
+    ``base_url`` defaults to the production SUBSTRATE MCP endpoint.
+    """
+
+    api_key: str = ""
+    base_url: str = "https://substrate.garmolabs.com/mcp-server/mcp"
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        # Resolve api_key from env if not provided directly
+        if not self.api_key:
+            key = os.environ.get("SUBSTRATE_API_KEY", "")
+            # frozen=True requires object.__setattr__ for late binding
+            object.__setattr__(self, "api_key", key)
+
+
+class SubstrateMemoryProvider:
+    """
+    CrewAI-compatible external memory provider backed by SUBSTRATE.
+
+    Implements the standard ``save`` / ``search`` / ``reset`` interface that
+    CrewAI expects, plus SUBSTRATE-exclusive methods for emotional context
+    and entity state inspection.
+
+    Usage::
+
+        from crewai import Crew
+        from crewai_substrate import SubstrateMemoryProvider
+
+        memory = SubstrateMemoryProvider(api_key="sk_sub_...")
+        crew = Crew(
+            agents=[...],
+            tasks=[...],
+            memory=True,
+            memory_config={"provider": memory},
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        base_url: str = "https://substrate.garmolabs.com/mcp-server/mcp",
+        timeout: float = 30.0,
+    ) -> None:
+        config = SubstrateMemoryConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        if not config.api_key:
+            raise ValueError(
+                "SUBSTRATE API key required. Pass api_key= or set SUBSTRATE_API_KEY env var."
+            )
+        self._client = SubstrateClient(
+            SubstrateClientConfig(
+                api_key=config.api_key,
+                base_url=config.base_url,
+                timeout=config.timeout,
+            )
+        )
+
+    # -- CrewAI memory interface -------------------------------------------
+
+    def save(self, content: str, metadata: dict[str, Any] | None = None) -> str:
+        """
+        Store a memory through SUBSTRATE's ``respond`` tool.
+
+        The entity processes the message through causal memory, values, and
+        reflection layers. The returned text is the entity's response, which
+        includes any extracted causal rules or insights.
+
+        Args:
+            content: The text content to store in memory.
+            metadata: Optional metadata dict. If provided, it is serialized
+                      and appended to the message for context.
+
+        Returns:
+            The entity's response text after processing the memory.
+        """
+        message = content
+        if metadata:
+            message = f"{content}\n\n[metadata: {json.dumps(metadata)}]"
+
+        try:
+            result = self._client.call_tool("respond", {"message": message})
+            return _extract_text(result)
+        except SubstrateClientError as exc:
+            logger.error("Failed to save memory: %s", exc)
+            raise
+
+    def search(self, query: str, limit: int = 5) -> list[dict[str, Any]]:
+        """
+        Search SUBSTRATE memory using hybrid retrieval (semantic + keyword).
+
+        Falls back to ``memory_search`` if ``hybrid_search`` is not available
+        on the current tier.
+
+        Args:
+            query: The search query string.
+            limit: Maximum number of results to return.
+
+        Returns:
+            A list of result dicts, each with at least a ``text`` key.
+        """
+        try:
+            result = self._client.call_tool(
+                "hybrid_search",
+                {"query": query, "top_k": limit},
+            )
+            text = _extract_text(result)
+            parsed = _parse_json_safe(text)
+            if isinstance(parsed, dict) and "results" in parsed:
+                return parsed["results"]
+            return [{"text": text}]
+        except SubstrateClientError as exc:
+            # hybrid_search requires pro tier; fall back to memory_search
+            if exc.code == -32000 or "not available" in str(exc).lower():
+                logger.info("hybrid_search unavailable, falling back to memory_search")
+                return self._fallback_search(query, limit)
+            raise
+
+    def reset(self) -> None:
+        """
+        No-op for SUBSTRATE.
+
+        SUBSTRATE entities maintain persistent identity and memory across
+        sessions by design. Calling reset is acknowledged but does not
+        destroy memory -- the entity's continuity is preserved.
+        """
+        logger.info("reset() called -- SUBSTRATE memory is persistent; no data was cleared")
+
+    # -- SUBSTRATE-exclusive methods ---------------------------------------
+
+    def get_emotional_context(self) -> dict[str, Any]:
+        """
+        Get the entity's emotional state vector (UASV).
+
+        Returns a dict with valence, arousal, dominance, and certainty
+        dimensions. No other memory provider offers this capability.
+
+        Returns:
+            Dict with emotional dimensions and their current values.
+        """
+        try:
+            result = self._client.call_tool("get_emotion_state")
+            text = _extract_text(result)
+            parsed = _parse_json_safe(text)
+            return parsed if parsed else {"raw": text}
+        except SubstrateClientError as exc:
+            logger.error("Failed to get emotional context: %s", exc)
+            return {"error": str(exc)}
+
+    def get_entity_state(self) -> dict[str, Any]:
+        """
+        Get the entity's identity verification and trust state.
+
+        Combines ``verify_identity`` (cryptographic continuity proof) with
+        ``get_trust_state`` (trust scores, consistency ratings).
+
+        Returns:
+            Dict with ``identity`` and ``trust`` sub-dicts.
+        """
+        state: dict[str, Any] = {}
+
+        try:
+            identity_result = self._client.call_tool("verify_identity")
+            identity_text = _extract_text(identity_result)
+            state["identity"] = _parse_json_safe(identity_text) or {"raw": identity_text}
+        except SubstrateClientError as exc:
+            logger.error("Failed to verify identity: %s", exc)
+            state["identity"] = {"error": str(exc)}
+
+        try:
+            trust_result = self._client.call_tool("get_trust_state")
+            trust_text = _extract_text(trust_result)
+            state["trust"] = _parse_json_safe(trust_text) or {"raw": trust_text}
+        except SubstrateClientError as exc:
+            # get_trust_state requires pro tier
+            logger.warning("get_trust_state unavailable: %s", exc)
+            state["trust"] = {"error": str(exc)}
+
+        return state
+
+    def get_memory_stats(self) -> dict[str, Any]:
+        """
+        Get causal memory statistics.
+
+        Returns episode count, rule count, average rule probability,
+        and high-confidence rule count.
+        """
+        try:
+            result = self._client.call_tool("memory_stats")
+            text = _extract_text(result)
+            parsed = _parse_json_safe(text)
+            return parsed if parsed else {"raw": text}
+        except SubstrateClientError as exc:
+            logger.error("Failed to get memory stats: %s", exc)
+            return {"error": str(exc)}
+
+    # -- Internal ----------------------------------------------------------
+
+    def _fallback_search(self, query: str, limit: int) -> list[dict[str, Any]]:
+        """Use basic memory_search when hybrid_search is unavailable."""
+        try:
+            result = self._client.call_tool("memory_search", {"query": query})
+            text = _extract_text(result)
+            parsed = _parse_json_safe(text)
+            if isinstance(parsed, dict) and "results" in parsed:
+                return parsed["results"][:limit]
+            return [{"text": text}]
+        except SubstrateClientError as exc:
+            logger.error("Fallback memory_search also failed: %s", exc)
+            return []
+
+    def close(self) -> None:
+        """Release the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> SubstrateMemoryProvider:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()