autogen-substrate-memory 0.1.0__tar.gz

autogen_substrate_memory-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: autogen-substrate-memory
+Version: 0.1.0
+Summary: SUBSTRATE cognitive memory provider for Microsoft AutoGen agents
+Project-URL: Homepage, https://garmolabs.com
+Project-URL: Documentation, https://garmolabs.com/substrate/docs
+Project-URL: Repository, https://github.com/GarmoLabs/autogen-substrate-memory
+Author-email: Garmo Labs <hello@garmolabs.com>
+License-Expression: MIT
+Keywords: ai-agents,autogen,cognitive,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: autogen-agentchat>=0.4
+Requires-Dist: autogen-core>=0.4
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autogen-substrate-memory
+
+SUBSTRATE cognitive memory provider for [Microsoft AutoGen](https://github.com/microsoft/autogen) agents.
+
+Give your AutoGen agents persistent identity, emotional awareness, and causal memory powered by the [SUBSTRATE](https://garmolabs.com) cognitive entity framework.
+
+## Installation
+
+```bash
+pip install autogen-substrate-memory
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_substrate import SubstrateMemory
+
+async def main():
+    # Create SUBSTRATE memory provider
+    memory = SubstrateMemory(api_key="sk_sub_your_key_here")
+
+    # Create an AutoGen agent with SUBSTRATE memory
+    agent = AssistantAgent(
+        name="kai",
+        model_client=OpenAIChatCompletionClient(model="gpt-4o"),
+        memory=[memory],
+    )
+
+    # The agent now has access to persistent cognitive memory,
+    # emotional state, and identity verification.
+    response = await agent.run(task="What do you remember about our last conversation?")
+    print(response)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `SUBSTRATE_API_KEY` | Your SUBSTRATE API key | (required) |
+| `SUBSTRATE_MCP_URL` | MCP server URL | `https://substrate.garmolabs.com/mcp-server/mcp` |
+
+### Full Configuration
+
+```python
+from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig
+
+config = SubstrateMemoryConfig(
+    api_key="sk_sub_...",
+    mcp_url="https://substrate.garmolabs.com/mcp-server/mcp",
+    search_top_k=10,          # Number of memory results per query
+    include_emotion=True,     # Include emotional state in queries
+    include_identity=True,    # Include identity verification in context
+    include_values=True,      # Include core values in context
+    timeout_seconds=30.0,     # HTTP request timeout
+)
+
+memory = SubstrateMemory(config=config)
+```
+
+## How It Works
+
+### Memory Protocol
+
+`SubstrateMemory` implements AutoGen's `Memory` protocol:
+
+| Method | Behavior |
+|---|---|
+| `query(query)` | Hybrid search (semantic + keyword) across entity memory. Optionally includes emotional state. |
+| `update_context(model_context)` | Injects identity, emotion, values, and relevant memories as a SystemMessage. |
+| `add(content)` | Stores content via the SUBSTRATE `respond` tool with a `[memory-store]` prefix. |
+| `clear()` | No-op. SUBSTRATE manages its own memory lifecycle with causal consolidation. |
+| `close()` | No-op. Each operation creates its own HTTP connection. |
+
+### SUBSTRATE MCP Tools Used
+
+| Tool | Used In | Purpose |
+|---|---|---|
+| `hybrid_search` | `query()`, `update_context()` | Semantic + keyword memory retrieval |
+| `memory_search` | `query()` (fallback) | Keyword-only memory retrieval |
+| `get_emotion_state` | `query()`, `update_context()` | Current affective state (valence, arousal, dominance) |
+| `verify_identity` | `update_context()` | Cryptographic identity continuity check |
+| `get_values` | `update_context()` | Core value architecture |
+| `respond` | `add()` | Store new memories via conversational input |
+
+## Get an API Key
+
+Sign up at [garmolabs.com](https://garmolabs.com) to get a SUBSTRATE API key.
+
+## License
+
+MIT

autogen_substrate_memory-0.1.0/README.md

@@ -0,0 +1,104 @@
+# autogen-substrate-memory
+
+SUBSTRATE cognitive memory provider for [Microsoft AutoGen](https://github.com/microsoft/autogen) agents.
+
+Give your AutoGen agents persistent identity, emotional awareness, and causal memory powered by the [SUBSTRATE](https://garmolabs.com) cognitive entity framework.
+
+## Installation
+
+```bash
+pip install autogen-substrate-memory
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_substrate import SubstrateMemory
+
+async def main():
+    # Create SUBSTRATE memory provider
+    memory = SubstrateMemory(api_key="sk_sub_your_key_here")
+
+    # Create an AutoGen agent with SUBSTRATE memory
+    agent = AssistantAgent(
+        name="kai",
+        model_client=OpenAIChatCompletionClient(model="gpt-4o"),
+        memory=[memory],
+    )
+
+    # The agent now has access to persistent cognitive memory,
+    # emotional state, and identity verification.
+    response = await agent.run(task="What do you remember about our last conversation?")
+    print(response)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `SUBSTRATE_API_KEY` | Your SUBSTRATE API key | (required) |
+| `SUBSTRATE_MCP_URL` | MCP server URL | `https://substrate.garmolabs.com/mcp-server/mcp` |
+
+### Full Configuration
+
+```python
+from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig
+
+config = SubstrateMemoryConfig(
+    api_key="sk_sub_...",
+    mcp_url="https://substrate.garmolabs.com/mcp-server/mcp",
+    search_top_k=10,          # Number of memory results per query
+    include_emotion=True,     # Include emotional state in queries
+    include_identity=True,    # Include identity verification in context
+    include_values=True,      # Include core values in context
+    timeout_seconds=30.0,     # HTTP request timeout
+)
+
+memory = SubstrateMemory(config=config)
+```
+
+## How It Works
+
+### Memory Protocol
+
+`SubstrateMemory` implements AutoGen's `Memory` protocol:
+
+| Method | Behavior |
+|---|---|
+| `query(query)` | Hybrid search (semantic + keyword) across entity memory. Optionally includes emotional state. |
+| `update_context(model_context)` | Injects identity, emotion, values, and relevant memories as a SystemMessage. |
+| `add(content)` | Stores content via the SUBSTRATE `respond` tool with a `[memory-store]` prefix. |
+| `clear()` | No-op. SUBSTRATE manages its own memory lifecycle with causal consolidation. |
+| `close()` | No-op. Each operation creates its own HTTP connection. |
+
+### SUBSTRATE MCP Tools Used
+
+| Tool | Used In | Purpose |
+|---|---|---|
+| `hybrid_search` | `query()`, `update_context()` | Semantic + keyword memory retrieval |
+| `memory_search` | `query()` (fallback) | Keyword-only memory retrieval |
+| `get_emotion_state` | `query()`, `update_context()` | Current affective state (valence, arousal, dominance) |
+| `verify_identity` | `update_context()` | Cryptographic identity continuity check |
+| `get_values` | `update_context()` | Core value architecture |
+| `respond` | `add()` | Store new memories via conversational input |
+
+## Get an API Key
+
+Sign up at [garmolabs.com](https://garmolabs.com) to get a SUBSTRATE API key.
+
+## License
+
+MIT

autogen_substrate_memory-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autogen-substrate-memory"
+version = "0.1.0"
+description = "SUBSTRATE cognitive memory provider for Microsoft AutoGen agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Garmo Labs", email = "hello@garmolabs.com" },
+]
+keywords = ["autogen", "substrate", "memory", "cognitive", "ai-agents"]
+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 = [
+    "autogen-agentchat>=0.4",
+    "autogen-core>=0.4",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "respx>=0.22",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+
+[project.urls]
+Homepage = "https://garmolabs.com"
+Documentation = "https://garmolabs.com/substrate/docs"
+Repository = "https://github.com/GarmoLabs/autogen-substrate-memory"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autogen_substrate"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "unit: unit tests",
+    "integration: integration tests requiring network",
+]

autogen_substrate_memory-0.1.0/src/autogen_substrate/__init__.py

@@ -0,0 +1,6 @@
+"""SUBSTRATE cognitive memory provider for Microsoft AutoGen agents."""
+
+from autogen_substrate.memory import SubstrateMemory
+
+__all__ = ["SubstrateMemory"]
+__version__ = "0.1.0"

autogen_substrate_memory-0.1.0/src/autogen_substrate/client.py

@@ -0,0 +1,173 @@
+"""Lightweight async HTTP client for the SUBSTRATE MCP server.
+
+Sends JSON-RPC 2.0 requests over HTTPS with Bearer token authentication.
+All responses are validated and errors are surfaced as typed exceptions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("autogen_substrate.client")
+
+DEFAULT_MCP_URL = "https://substrate.garmolabs.com/mcp-server/mcp"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+class SubstrateClientError(Exception):
+    """Base exception for SUBSTRATE client errors."""
+
+
+class SubstrateAuthError(SubstrateClientError):
+    """Raised when the API key is invalid or missing."""
+
+
+class SubstrateRPCError(SubstrateClientError):
+    """Raised when the MCP server returns a JSON-RPC error."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        self.code = code
+        self.rpc_message = message
+        self.data = data
+        super().__init__(f"JSON-RPC error {code}: {message}")
+
+
+@dataclass(frozen=True)
+class RPCResponse:
+    """Immutable wrapper around a successful JSON-RPC result."""
+
+    id: int | str | None
+    result: Any
+
+
+@dataclass(frozen=True)
+class SubstrateClientConfig:
+    """Immutable configuration for the SUBSTRATE MCP client."""
+
+    api_key: str
+    mcp_url: str = DEFAULT_MCP_URL
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+
+class SubstrateClient:
+    """Async HTTP client for SUBSTRATE MCP JSON-RPC calls.
+
+    Usage::
+
+        config = SubstrateClientConfig(api_key="sk_sub_...")
+        async with SubstrateClient(config) as client:
+            result = await client.call_tool("memory_search", {"query": "hello"})
+    """
+
+    def __init__(self, config: SubstrateClientConfig) -> None:
+        if not config.api_key:
+            raise SubstrateAuthError("SUBSTRATE API key must not be empty")
+        self._config = config
+        self._request_id = 0
+        self._http: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> SubstrateClient:
+        self._http = httpx.AsyncClient(
+            base_url=self._config.mcp_url,
+            headers={
+                "Authorization": f"Bearer {self._config.api_key}",
+                "Content-Type": "application/json",
+                **self._config.extra_headers,
+            },
+            timeout=httpx.Timeout(self._config.timeout_seconds),
+        )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    async def _send_rpc(self, method: str, params: dict[str, Any] | None = None) -> RPCResponse:
+        """Send a JSON-RPC 2.0 request and return the parsed response."""
+        if self._http is None:
+            raise SubstrateClientError("Client not initialized. Use 'async with' context manager.")
+
+        request_id = self._next_id()
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+        }
+        if params is not None:
+            payload["params"] = params
+
+        logger.debug("MCP request: method=%s id=%d", method, request_id)
+
+        try:
+            response = await self._http.post("", content=json.dumps(payload))
+        except httpx.TimeoutException as exc:
+            raise SubstrateClientError(f"Request timed out after {self._config.timeout_seconds}s") from exc
+        except httpx.HTTPError as exc:
+            raise SubstrateClientError(f"HTTP error: {exc}") from exc
+
+        if response.status_code == 401:
+            raise SubstrateAuthError("Invalid or expired API key")
+        if response.status_code == 429:
+            raise SubstrateClientError("Rate limit exceeded")
+        if response.status_code >= 400:
+            raise SubstrateClientError(
+                f"HTTP {response.status_code}: {response.text[:200]}"
+            )
+
+        try:
+            body = response.json()
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise SubstrateClientError(f"Invalid JSON response: {response.text[:200]}") from exc
+
+        if "error" in body and body["error"] is not None:
+            err = body["error"]
+            raise SubstrateRPCError(
+                code=err.get("code", -32603),
+                message=err.get("message", "Unknown error"),
+                data=err.get("data"),
+            )
+
+        return RPCResponse(id=body.get("id"), result=body.get("result"))
+
+    async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Call an MCP tool and return the result content.
+
+        Args:
+            tool_name: Name of the SUBSTRATE MCP tool (e.g. ``hybrid_search``).
+            arguments: Tool-specific arguments dict.
+
+        Returns:
+            The ``result`` field from the JSON-RPC response.
+
+        Raises:
+            SubstrateRPCError: If the server returns a JSON-RPC error.
+            SubstrateAuthError: If authentication fails.
+            SubstrateClientError: On network or protocol errors.
+        """
+        params: dict[str, Any] = {"name": tool_name}
+        if arguments:
+            params["arguments"] = arguments
+
+        rpc = await self._send_rpc("tools/call", params)
+        return rpc.result
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """List all available MCP tools for the authenticated tier."""
+        rpc = await self._send_rpc("tools/list")
+        result = rpc.result
+        if isinstance(result, dict) and "tools" in result:
+            return result["tools"]
+        if isinstance(result, list):
+            return result
+        return []

autogen_substrate_memory-0.1.0/src/autogen_substrate/memory.py

@@ -0,0 +1,346 @@
+"""SUBSTRATE Memory provider for Microsoft AutoGen agents.
+
+Implements the ``autogen_core.memory.Memory`` protocol, backed by the
+SUBSTRATE cognitive entity framework. Queries combine hybrid search with
+emotional state awareness; context injection provides identity, emotion,
+and relevant memories as a system message.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from autogen_core.memory import Memory, MemoryContent, MemoryMimeType, MemoryQueryResult
+from autogen_core.model_context import ChatCompletionContext
+from autogen_core.models import SystemMessage
+
+from autogen_substrate.client import (
+    SubstrateClient,
+    SubstrateClientConfig,
+    SubstrateClientError,
+    SubstrateRPCError,
+)
+
+logger = logging.getLogger("autogen_substrate.memory")
+
+
+def _extract_text(content: Any) -> str:
+    """Extract text from various MCP tool response shapes."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, dict):
+        # MCP content blocks: [{"type": "text", "text": "..."}]
+        if "content" in content and isinstance(content["content"], list):
+            parts = []
+            for block in content["content"]:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+            return "\n".join(parts)
+        # Direct text field
+        if "text" in content:
+            return str(content["text"])
+        return json.dumps(content, indent=2, default=str)
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            parts.append(_extract_text(item))
+        return "\n".join(parts)
+    return str(content)
+
+
+@dataclass(frozen=True)
+class SubstrateMemoryConfig:
+    """Immutable configuration for SubstrateMemory.
+
+    Attributes:
+        api_key: SUBSTRATE API key. Falls back to ``SUBSTRATE_API_KEY`` env var.
+        mcp_url: MCP server URL. Falls back to ``SUBSTRATE_MCP_URL`` env var.
+        name: Display name for this memory provider.
+        search_top_k: Default number of results for hybrid search.
+        include_emotion: Whether to include emotional state in queries and context.
+        include_identity: Whether to include identity verification in context.
+        include_values: Whether to include core values in context.
+        timeout_seconds: HTTP request timeout.
+    """
+
+    api_key: str = ""
+    mcp_url: str = ""
+    name: str = "substrate"
+    search_top_k: int = 5
+    include_emotion: bool = True
+    include_identity: bool = True
+    include_values: bool = True
+    timeout_seconds: float = 30.0
+
+
+class SubstrateMemory(Memory):
+    """SUBSTRATE-backed memory for AutoGen agents.
+
+    Provides cognitive memory, emotional state, identity verification, and
+    value-aligned context injection for AutoGen agent conversations.
+
+    Usage::
+
+        from autogen_substrate import SubstrateMemory
+
+        memory = SubstrateMemory(api_key="sk_sub_...")
+        await memory.add("User prefers concise responses")
+        result = await memory.query("What does the user prefer?")
+        print(result.results)
+
+    Or with full config::
+
+        from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig
+
+        config = SubstrateMemoryConfig(
+            api_key="sk_sub_...",
+            search_top_k=10,
+            include_emotion=True,
+        )
+        memory = SubstrateMemory(config=config)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str = "",
+        config: SubstrateMemoryConfig | None = None,
+    ) -> None:
+        resolved_config = config or SubstrateMemoryConfig(api_key=api_key)
+
+        resolved_key = (
+            resolved_config.api_key
+            or os.environ.get("SUBSTRATE_API_KEY", "")
+        )
+        resolved_url = (
+            resolved_config.mcp_url
+            or os.environ.get("SUBSTRATE_MCP_URL", "")
+            or "https://substrate.garmolabs.com/mcp-server/mcp"
+        )
+
+        self._config = SubstrateMemoryConfig(
+            api_key=resolved_key,
+            mcp_url=resolved_url,
+            name=resolved_config.name,
+            search_top_k=resolved_config.search_top_k,
+            include_emotion=resolved_config.include_emotion,
+            include_identity=resolved_config.include_identity,
+            include_values=resolved_config.include_values,
+            timeout_seconds=resolved_config.timeout_seconds,
+        )
+
+        self._client_config = SubstrateClientConfig(
+            api_key=self._config.api_key,
+            mcp_url=self._config.mcp_url,
+            timeout_seconds=self._config.timeout_seconds,
+        )
+
+    @property
+    def name(self) -> str:
+        """Display name for this memory provider."""
+        return self._config.name
+
+    async def query(
+        self,
+        query: str,
+        *,
+        cancellation_token: Any | None = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        """Query SUBSTRATE for relevant memories and emotional context.
+
+        Performs a hybrid search (semantic + keyword) across the entity's memory
+        and knowledge stores. Optionally includes the current emotional state
+        as additional context.
+
+        Args:
+            query: Natural language search query.
+            cancellation_token: Optional cancellation token (unused, kept for protocol).
+            **kwargs: Additional arguments. Supports ``top_k`` override.
+
+        Returns:
+            MemoryQueryResult with matching memory contents.
+        """
+        top_k = kwargs.get("top_k", self._config.search_top_k)
+        results: list[MemoryContent] = []
+
+        async with SubstrateClient(self._client_config) as client:
+            # Hybrid search for relevant memories
+            try:
+                search_result = await client.call_tool(
+                    "hybrid_search",
+                    {"query": query, "top_k": top_k},
+                )
+                search_text = _extract_text(search_result)
+                if search_text.strip():
+                    results.append(
+                        MemoryContent(
+                            content=search_text,
+                            mime_type=MemoryMimeType.TEXT,
+                            metadata={"source": "substrate_hybrid_search", "query": query},
+                        )
+                    )
+            except (SubstrateRPCError, SubstrateClientError) as exc:
+                logger.warning("hybrid_search failed, falling back to memory_search: %s", exc)
+                try:
+                    fallback = await client.call_tool("memory_search", {"query": query})
+                    fallback_text = _extract_text(fallback)
+                    if fallback_text.strip():
+                        results.append(
+                            MemoryContent(
+                                content=fallback_text,
+                                mime_type=MemoryMimeType.TEXT,
+                                metadata={"source": "substrate_memory_search", "query": query},
+                            )
+                        )
+                except (SubstrateRPCError, SubstrateClientError) as fallback_exc:
+                    logger.error("memory_search also failed: %s", fallback_exc)
+
+            # Include emotional state if configured
+            if self._config.include_emotion:
+                try:
+                    emotion_result = await client.call_tool("get_emotion_state")
+                    emotion_text = _extract_text(emotion_result)
+                    if emotion_text.strip():
+                        results.append(
+                            MemoryContent(
+                                content=f"[Emotional State]\n{emotion_text}",
+                                mime_type=MemoryMimeType.TEXT,
+                                metadata={"source": "substrate_emotion"},
+                            )
+                        )
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_emotion_state unavailable: %s", exc)
+
+        return MemoryQueryResult(results=results)
+
+    async def update_context(
+        self,
+        model_context: ChatCompletionContext,
+    ) -> None:
+        """Inject SUBSTRATE cognitive context into the agent's model context.
+
+        Prepends a system message containing the entity's identity status,
+        emotional state, core values, and any recent relevant memories.
+
+        Args:
+            model_context: The agent's current chat completion context.
+        """
+        sections: list[str] = []
+
+        async with SubstrateClient(self._client_config) as client:
+            # Identity verification
+            if self._config.include_identity:
+                try:
+                    identity = await client.call_tool("verify_identity")
+                    identity_text = _extract_text(identity)
+                    if identity_text.strip():
+                        sections.append(f"## Identity Continuity\n{identity_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("verify_identity unavailable: %s", exc)
+
+            # Emotional state
+            if self._config.include_emotion:
+                try:
+                    emotion = await client.call_tool("get_emotion_state")
+                    emotion_text = _extract_text(emotion)
+                    if emotion_text.strip():
+                        sections.append(f"## Emotional State\n{emotion_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_emotion_state unavailable: %s", exc)
+
+            # Core values
+            if self._config.include_values:
+                try:
+                    values = await client.call_tool("get_values")
+                    values_text = _extract_text(values)
+                    if values_text.strip():
+                        sections.append(f"## Core Values\n{values_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_values unavailable: %s", exc)
+
+            # Recent context from conversation messages
+            existing = await model_context.get_messages()
+            context_query = _build_context_query(existing)
+            if context_query:
+                try:
+                    memories = await client.call_tool(
+                        "hybrid_search",
+                        {"query": context_query, "top_k": 3},
+                    )
+                    mem_text = _extract_text(memories)
+                    if mem_text.strip():
+                        sections.append(f"## Relevant Memories\n{mem_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("Context memory search unavailable: %s", exc)
+
+        if sections:
+            system_text = (
+                "# SUBSTRATE Cognitive Context\n\n"
+                + "\n\n".join(sections)
+            )
+            await model_context.add_message(SystemMessage(content=system_text))
+
+    async def add(
+        self,
+        content: str,
+        *,
+        cancellation_token: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Store a memory in SUBSTRATE via the respond tool.
+
+        Sends the content with a ``[memory-store]`` prefix so the entity
+        processes it as an explicit memory rather than conversational input.
+
+        Args:
+            content: The memory content to store.
+            cancellation_token: Optional cancellation token (unused).
+            **kwargs: Reserved for future use.
+        """
+        async with SubstrateClient(self._client_config) as client:
+            try:
+                await client.call_tool(
+                    "respond",
+                    {"message": f"[memory-store] {content}"},
+                )
+            except (SubstrateRPCError, SubstrateClientError) as exc:
+                logger.error("Failed to store memory: %s", exc)
+                raise
+
+    async def clear(self) -> None:
+        """No-op. SUBSTRATE manages its own memory lifecycle.
+
+        SUBSTRATE entities maintain causal memory with built-in consolidation
+        and decay. Explicit clearing is not supported to preserve identity
+        continuity.
+        """
+        logger.debug("clear() called — SUBSTRATE manages its own memory lifecycle")
+
+    async def close(self) -> None:
+        """No-op. Each operation creates its own HTTP connection.
+
+        The client uses context managers per-call, so there is no persistent
+        connection to close.
+        """
+        logger.debug("close() called — no persistent resources to release")
+
+
+def _build_context_query(messages: Sequence[Any]) -> str:
+    """Build a search query from the most recent user messages.
+
+    Extracts text from the last few messages to form a contextual query
+    for memory retrieval.
+    """
+    texts: list[str] = []
+    for msg in messages[-5:]:
+        content = getattr(msg, "content", None)
+        if isinstance(content, str) and content.strip():
+            texts.append(content.strip())
+    combined = " ".join(texts)
+    # Truncate to a reasonable query length
+    return combined[:500] if combined else ""

autogen_substrate_memory-0.1.0/tests/test_client.py

@@ -0,0 +1,198 @@
+"""Tests for the SUBSTRATE MCP client."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+import respx
+
+from autogen_substrate.client import (
+    RPCResponse,
+    SubstrateAuthError,
+    SubstrateClient,
+    SubstrateClientConfig,
+    SubstrateClientError,
+    SubstrateRPCError,
+)
+
+MCP_URL = "https://test.substrate.local/mcp"
+API_KEY = "sk_sub_test_key_123"
+
+
+def _config(**overrides: object) -> SubstrateClientConfig:
+    defaults = {"api_key": API_KEY, "mcp_url": MCP_URL}
+    defaults.update(overrides)
+    return SubstrateClientConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _rpc_success(result: object, request_id: int = 1) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _rpc_error(code: int, message: str, request_id: int = 1) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+# -- Construction -----------------------------------------------------------
+
+
+class TestClientConstruction:
+    def test_empty_api_key_raises(self) -> None:
+        with pytest.raises(SubstrateAuthError, match="must not be empty"):
+            SubstrateClient(SubstrateClientConfig(api_key="", mcp_url=MCP_URL))
+
+    def test_valid_config_creates_client(self) -> None:
+        client = SubstrateClient(_config())
+        assert client is not None
+
+
+# -- call_tool --------------------------------------------------------------
+
+
+class TestCallTool:
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_success(self) -> None:
+        route = respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success({"content": [{"type": "text", "text": "found it"}]}))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            result = await client.call_tool("memory_search", {"query": "hello"})
+
+        assert result == {"content": [{"type": "text", "text": "found it"}]}
+        assert route.called
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_sends_bearer_token(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success("ok"))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            await client.call_tool("get_values")
+
+        request = respx.calls[0].request
+        assert request.headers["authorization"] == f"Bearer {API_KEY}"
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_sends_correct_jsonrpc(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success("ok"))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            await client.call_tool("hybrid_search", {"query": "test", "top_k": 3})
+
+        body = json.loads(respx.calls[0].request.content)
+        assert body["jsonrpc"] == "2.0"
+        assert body["method"] == "tools/call"
+        assert body["params"]["name"] == "hybrid_search"
+        assert body["params"]["arguments"] == {"query": "test", "top_k": 3}
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_rpc_error(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_error(-32602, "Invalid params"))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            with pytest.raises(SubstrateRPCError, match="Invalid params"):
+                await client.call_tool("bad_tool")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_401_raises_auth_error(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(401, json={"error": "Unauthorized"})
+        )
+
+        async with SubstrateClient(_config()) as client:
+            with pytest.raises(SubstrateAuthError, match="Invalid or expired"):
+                await client.call_tool("get_values")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_429_raises_rate_limit(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(429, text="Too Many Requests")
+        )
+
+        async with SubstrateClient(_config()) as client:
+            with pytest.raises(SubstrateClientError, match="Rate limit"):
+                await client.call_tool("get_values")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_500_raises_client_error(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(500, text="Internal Server Error")
+        )
+
+        async with SubstrateClient(_config()) as client:
+            with pytest.raises(SubstrateClientError, match="HTTP 500"):
+                await client.call_tool("get_values")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_call_tool_invalid_json_raises(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, text="not json at all")
+        )
+
+        async with SubstrateClient(_config()) as client:
+            with pytest.raises(SubstrateClientError, match="Invalid JSON"):
+                await client.call_tool("get_values")
+
+    @pytest.mark.asyncio
+    async def test_call_tool_without_context_manager_raises(self) -> None:
+        client = SubstrateClient(_config())
+        with pytest.raises(SubstrateClientError, match="not initialized"):
+            await client.call_tool("get_values")
+
+
+# -- list_tools -------------------------------------------------------------
+
+
+class TestListTools:
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_list_tools_dict_response(self) -> None:
+        tools = [{"name": "respond"}, {"name": "memory_search"}]
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success({"tools": tools}))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            result = await client.list_tools()
+
+        assert len(result) == 2
+        assert result[0]["name"] == "respond"
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_list_tools_list_response(self) -> None:
+        tools = [{"name": "respond"}]
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success(tools))
+        )
+
+        async with SubstrateClient(_config()) as client:
+            result = await client.list_tools()
+
+        assert len(result) == 1
+
+
+# -- RPCResponse ------------------------------------------------------------
+
+
+class TestRPCResponse:
+    def test_immutable(self) -> None:
+        resp = RPCResponse(id=1, result="test")
+        with pytest.raises(AttributeError):
+            resp.id = 2  # type: ignore[misc]

autogen_substrate_memory-0.1.0/tests/test_memory.py

@@ -0,0 +1,260 @@
+"""Tests for the SubstrateMemory provider."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+import respx
+
+from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig, _build_context_query, _extract_text
+
+MCP_URL = "https://test.substrate.local/mcp"
+API_KEY = "sk_sub_test_key_123"
+
+
+def _rpc_success(result: object, request_id: int | None = None) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id or 1, "result": result}
+
+
+def _rpc_error(code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": 1, "error": {"code": code, "message": message}}
+
+
+def _mcp_text_content(text: str) -> dict:
+    return {"content": [{"type": "text", "text": text}]}
+
+
+def _memory(
+    *,
+    include_emotion: bool = True,
+    include_identity: bool = True,
+    include_values: bool = True,
+) -> SubstrateMemory:
+    config = SubstrateMemoryConfig(
+        api_key=API_KEY,
+        mcp_url=MCP_URL,
+        include_emotion=include_emotion,
+        include_identity=include_identity,
+        include_values=include_values,
+    )
+    return SubstrateMemory(config=config)
+
+
+# -- _extract_text -----------------------------------------------------------
+
+
+class TestExtractText:
+    def test_string_passthrough(self) -> None:
+        assert _extract_text("hello") == "hello"
+
+    def test_mcp_content_blocks(self) -> None:
+        data = {"content": [{"type": "text", "text": "line1"}, {"type": "text", "text": "line2"}]}
+        assert _extract_text(data) == "line1\nline2"
+
+    def test_dict_with_text_field(self) -> None:
+        assert _extract_text({"text": "hello"}) == "hello"
+
+    def test_dict_fallback_to_json(self) -> None:
+        result = _extract_text({"foo": "bar"})
+        assert "foo" in result
+        assert "bar" in result
+
+    def test_list_of_items(self) -> None:
+        result = _extract_text(["a", "b"])
+        assert "a" in result
+        assert "b" in result
+
+    def test_non_string_converted(self) -> None:
+        assert _extract_text(42) == "42"
+
+
+# -- _build_context_query ---------------------------------------------------
+
+
+class TestBuildContextQuery:
+    def test_empty_messages(self) -> None:
+        assert _build_context_query([]) == ""
+
+    def test_extracts_content_from_messages(self) -> None:
+        msgs = [MagicMock(content="hello world"), MagicMock(content="how are you")]
+        result = _build_context_query(msgs)
+        assert "hello world" in result
+        assert "how are you" in result
+
+    def test_truncates_long_content(self) -> None:
+        msgs = [MagicMock(content="x" * 1000)]
+        result = _build_context_query(msgs)
+        assert len(result) == 500
+
+    def test_skips_empty_content(self) -> None:
+        msgs = [MagicMock(content=""), MagicMock(content="real")]
+        result = _build_context_query(msgs)
+        assert result == "real"
+
+    def test_uses_last_five_messages(self) -> None:
+        msgs = [MagicMock(content=f"msg{i}") for i in range(10)]
+        result = _build_context_query(msgs)
+        assert "msg5" in result
+        assert "msg4" not in result
+
+
+# -- SubstrateMemory.query ---------------------------------------------------
+
+
+class TestMemoryQuery:
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_query_returns_search_and_emotion(self) -> None:
+        call_count = 0
+
+        def _side_effect(request: httpx.Request) -> httpx.Response:
+            nonlocal call_count
+            call_count += 1
+            body = json.loads(request.content)
+            tool_name = body["params"]["name"]
+            if tool_name == "hybrid_search":
+                return httpx.Response(200, json=_rpc_success(_mcp_text_content("memory result")))
+            if tool_name == "get_emotion_state":
+                return httpx.Response(200, json=_rpc_success(_mcp_text_content("valence=0.8")))
+            return httpx.Response(200, json=_rpc_success("ok"))
+
+        respx.post(MCP_URL).mock(side_effect=_side_effect)
+        mem = _memory()
+        result = await mem.query("what happened yesterday?")
+
+        assert len(result.results) == 2
+        assert "memory result" in result.results[0].content
+        assert "valence=0.8" in result.results[1].content
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_query_without_emotion(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success(_mcp_text_content("found")))
+        )
+        mem = _memory(include_emotion=False)
+        result = await mem.query("test")
+
+        assert len(result.results) == 1
+        assert "found" in result.results[0].content
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_query_falls_back_to_memory_search(self) -> None:
+        call_count = 0
+
+        def _side_effect(request: httpx.Request) -> httpx.Response:
+            nonlocal call_count
+            call_count += 1
+            body = json.loads(request.content)
+            tool_name = body["params"]["name"]
+            if tool_name == "hybrid_search":
+                return httpx.Response(200, json=_rpc_error(-32602, "Not available"))
+            if tool_name == "memory_search":
+                return httpx.Response(200, json=_rpc_success(_mcp_text_content("fallback result")))
+            if tool_name == "get_emotion_state":
+                return httpx.Response(200, json=_rpc_success(_mcp_text_content("calm")))
+            return httpx.Response(200, json=_rpc_success("ok"))
+
+        respx.post(MCP_URL).mock(side_effect=_side_effect)
+        mem = _memory()
+        result = await mem.query("test")
+
+        assert any("fallback result" in r.content for r in result.results)
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_query_handles_empty_results(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success(_mcp_text_content("")))
+        )
+        mem = _memory(include_emotion=False)
+        result = await mem.query("test")
+
+        assert len(result.results) == 0
+
+
+# -- SubstrateMemory.add ----------------------------------------------------
+
+
+class TestMemoryAdd:
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_add_sends_memory_store_prefix(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(200, json=_rpc_success("stored"))
+        )
+        mem = _memory()
+        await mem.add("User likes concise responses")
+
+        body = json.loads(respx.calls[0].request.content)
+        assert body["params"]["name"] == "respond"
+        assert "[memory-store]" in body["params"]["arguments"]["message"]
+        assert "concise responses" in body["params"]["arguments"]["message"]
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_add_raises_on_failure(self) -> None:
+        respx.post(MCP_URL).mock(
+            return_value=httpx.Response(500, text="Server Error")
+        )
+        mem = _memory()
+        with pytest.raises(Exception):
+            await mem.add("something")
+
+
+# -- SubstrateMemory.clear / close ------------------------------------------
+
+
+class TestMemoryLifecycle:
+    @pytest.mark.asyncio
+    async def test_clear_is_noop(self) -> None:
+        mem = _memory()
+        await mem.clear()  # should not raise
+
+    @pytest.mark.asyncio
+    async def test_close_is_noop(self) -> None:
+        mem = _memory()
+        await mem.close()  # should not raise
+
+    def test_name_property(self) -> None:
+        mem = _memory()
+        assert mem.name == "substrate"
+
+    def test_custom_name(self) -> None:
+        config = SubstrateMemoryConfig(api_key=API_KEY, mcp_url=MCP_URL, name="custom")
+        mem = SubstrateMemory(config=config)
+        assert mem.name == "custom"
+
+
+# -- SubstrateMemory construction -------------------------------------------
+
+
+class TestMemoryConstruction:
+    def test_api_key_from_constructor(self) -> None:
+        mem = SubstrateMemory(api_key="sk_sub_direct")
+        assert mem._config.api_key == "sk_sub_direct"
+
+    def test_api_key_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("SUBSTRATE_API_KEY", "sk_sub_env")
+        mem = SubstrateMemory()
+        assert mem._config.api_key == "sk_sub_env"
+
+    def test_mcp_url_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("SUBSTRATE_API_KEY", "sk_sub_x")
+        monkeypatch.setenv("SUBSTRATE_MCP_URL", "https://custom.example.com/mcp")
+        mem = SubstrateMemory()
+        assert mem._config.mcp_url == "https://custom.example.com/mcp"
+
+    def test_default_mcp_url(self) -> None:
+        mem = SubstrateMemory(api_key="sk_sub_x")
+        assert "substrate.garmolabs.com" in mem._config.mcp_url
+
+    def test_config_is_frozen(self) -> None:
+        config = SubstrateMemoryConfig(api_key="sk_sub_x")
+        with pytest.raises(AttributeError):
+            config.api_key = "changed"  # type: ignore[misc]