uv add --prerelease=allow supermemory-agent-framework

pip install --pre supermemory-agent-framework

uv add supermemory-agent-framework[async]
# or
pip install supermemory-agent-framework[async]

import asyncio
from agent_framework.openai import OpenAIResponsesClient
from supermemory_agent_framework import (
    SupermemoryChatMiddleware,
    SupermemoryMiddlewareOptions,
)

async def main():
    # Create Supermemory middleware
    middleware = SupermemoryChatMiddleware(
        container_tag="user-123",
        options=SupermemoryMiddlewareOptions(
            mode="full",        # "profile", "query", or "full"
            verbose=True,       # Enable logging
            add_memory="always" # Automatically save conversations
        ),
    )

    # Create agent with middleware
    agent = OpenAIResponsesClient().as_agent(
        name="MemoryAgent",
        instructions="You are a helpful assistant with memory.",
        middleware=[middleware],
    )

    # Use normally - memories are automatically injected!
    response = await agent.run(
        "What's my favorite programming language?"
    )
    print(response.text)

asyncio.run(main())

import asyncio
from agent_framework import AgentSession
from agent_framework.openai import OpenAIResponsesClient
from supermemory_agent_framework import SupermemoryContextProvider

async def main():
    # Create context provider
    provider = SupermemoryContextProvider(
        container_tag="user-123",
        api_key="your-supermemory-api-key",
        mode="full",
        store_conversations=True,
    )

    # Create agent with context provider
    agent = OpenAIResponsesClient().as_agent(
        name="MemoryAgent",
        instructions="You are a helpful assistant with memory.",
        context_providers=[provider],
    )

    # Use with a session - memories are automatically fetched and injected
    session = AgentSession()
    response = await agent.run(
        "What's my favorite programming language?",
        session=session,
    )
    print(response.text)

asyncio.run(main())

import asyncio
from agent_framework.openai import OpenAIResponsesClient
from supermemory_agent_framework import SupermemoryTools

async def main():
    # Create memory tools
    tools = SupermemoryTools(
        api_key="your-supermemory-api-key",
        config={"project_id": "my-project"},
    )

    # Create agent
    agent = OpenAIResponsesClient().as_agent(
        name="MemoryAgent",
        instructions="You are a helpful assistant with access to user memories.",
    )

    # Run with memory tools
    response = await agent.run(
        "Remember that I prefer tea over coffee",
        tools=tools.get_tools(),
    )
    print(response.text)

asyncio.run(main())

import asyncio
from agent_framework.openai import OpenAIResponsesClient
from supermemory_agent_framework import (
    SupermemoryChatMiddleware,
    SupermemoryMiddlewareOptions,
    SupermemoryTools,
)

async def main():
    api_key = "your-supermemory-api-key"

    middleware = SupermemoryChatMiddleware(
        container_tag="user-123",
        options=SupermemoryMiddlewareOptions(mode="full"),
        api_key=api_key,
    )

    tools = SupermemoryTools(api_key=api_key)

    agent = OpenAIResponsesClient().as_agent(
        name="MemoryAgent",
        instructions="You are a helpful assistant with memory.",
        middleware=[middleware],
    )

    # Middleware injects context automatically,
    # tools let the agent explicitly search/add memories
    response = await agent.run(
        "What do you remember about me?",
        tools=tools.get_tools(),
    )
    print(response.text)

asyncio.run(main())

SupermemoryMiddlewareOptions(mode="profile")

SupermemoryMiddlewareOptions(mode="query")

SupermemoryMiddlewareOptions(mode="full")

# Always save conversations as memories
SupermemoryMiddlewareOptions(add_memory="always")

# Never save conversations (default)
SupermemoryMiddlewareOptions(add_memory="never")

SupermemoryMiddlewareOptions(
    conversation_id="chat-session-456",  # Group messages into conversations
    verbose=True,                        # Enable detailed logging
    mode="full",                         # Use both profile and query
    add_memory="always"                  # Auto-save conversations
)

tools = SupermemoryTools(
    api_key="your-api-key",
    config={
        "project_id": "my-project",       # or use container_tags
        "base_url": "https://custom.com", # optional
    }
)

# Get FunctionTool instances for Agent.run()
agent_tools = tools.get_tools()

# Or use directly
result = await tools.search_memories("user preferences")
result = await tools.add_memory("User prefers dark mode")
result = await tools.get_profile()

middleware = SupermemoryChatMiddleware(
    container_tag="user-123",           # Memory scope identifier
    options=SupermemoryMiddlewareOptions(...),
    api_key="your-api-key",             # Or set SUPERMEMORY_API_KEY env var
)

middleware = with_supermemory_middleware(
    "user-123",
    SupermemoryMiddlewareOptions(mode="full"),
)

provider = SupermemoryContextProvider(
    container_tag="user-123",
    api_key="your-api-key",           # Or set SUPERMEMORY_API_KEY env var
    mode="full",                      # "profile", "query", or "full"
    store_conversations=True,         # Save conversations after each run
    conversation_id="chat-456",       # Optional grouping ID
    context_prompt="## Memories\n...",  # Custom header for injected memories
    verbose=True,                     # Enable logging
)

from supermemory_agent_framework import (
    SupermemoryConfigurationError,
    SupermemoryAPIError,
    SupermemoryNetworkError,
    SupermemoryMemoryOperationError,
)

try:
    middleware = SupermemoryChatMiddleware("user-123")
except SupermemoryConfigurationError as e:
    print(f"Configuration issue: {e}")

# Setup
cd packages/agent-framework-python
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy src/supermemory_agent_framework

# Formatting
uv run black src/ tests/
uv run isort src/ tests/