Metadata-Version: 2.4
Name: autogen-substrate-memory
Version: 0.1.1
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: LicenseRef-Proprietary
License-File: LICENSE
Keywords: ai-agents,autogen,cognitive,memory,substrate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
