autogen-substrate-memory 0.2.0

SUBSTRATE cognitive memory provider for Microsoft AutoGen agents

autogen-substrate-memory

SUBSTRATE cognitive memory provider for Microsoft AutoGen agents.

Give your AutoGen agents persistent identity, emotional awareness, and causal memory powered by the SUBSTRATE cognitive entity framework.

Installation

pip install autogen-substrate-memory

Or install from source:

pip install -e ".[dev]"

Quick Start

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

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 to get a SUBSTRATE API key.

License

MIT