OpenAI Agents SDK - supermemory | Memory API for the AI era

OpenAI’s Agents SDK gives you a straightforward way to build agents with tools, handoffs, and guardrails. But agents don’t remember users between sessions. Supermemory adds that missing piece: your agents can store what they learn and recall it later.

What you can do

Pull user profiles and relevant memories before an agent runs
Store agent outputs and decisions for future sessions
Give agents tools to search and add memories on their own

Setup

Install the packages:

pip install openai-agents supermemory python-dotenv

Set up your environment:

# .env
SUPERMEMORY_API_KEY=your-supermemory-api-key
OPENAI_API_KEY=your-openai-api-key

Get your Supermemory API key from console.supermemory.ai.

Basic integration

The simplest approach: fetch user context and pass it in the agent’s instructions.

import os
from agents import Agent, Runner
from supermemory import Supermemory
from dotenv import load_dotenv

load_dotenv()

memory = Supermemory()

def get_user_context(user_id: str, query: str) -> str:
    """Fetch profile and relevant memories for a user."""
    result = memory.profile(container_tag=user_id, q=query)

    static = result.profile.static or []
    dynamic = result.profile.dynamic or []
    memories = result.search_results.results if result.search_results else []

    return f"""
User background:
{chr(10).join(static) if static else 'No profile yet.'}

Current focus:
{chr(10).join(dynamic) if dynamic else 'No recent activity.'}

Related memories:
{chr(10).join([m.memory or m.chunk for m in memories[:5]]) if memories else 'None.'}
"""

def create_agent(user_id: str, task: str) -> Agent:
    """Create an agent with user context in its instructions."""
    context = get_user_context(user_id, task)

    return Agent(
        name="assistant",
        instructions=f"""You are a helpful assistant.

Here's what you know about this user:
{context}

Use this to personalize your responses.""",
        model="gpt-4o"
    )

async def run_with_memory(user_id: str, message: str) -> str:
    """Run an agent and store the interaction."""
    agent = create_agent(user_id, message)
    result = await Runner.run(agent, message)

    # Save for next time
    memory.add(
        content=f"User asked: {message}\nResponse: {result.final_output}",
        container_tag=user_id
    )

    return result.final_output

Core concepts

User profiles

Supermemory keeps two buckets of user info:

Static facts: Stuff that doesn’t change much (preferences, job, expertise)
Dynamic context: What they’re working on right now

result = memory.profile(
    container_tag="user_123",
    q="travel planning"  # Also searches for relevant memories
)

print(result.profile.static)   # ["Prefers window seats", "Vegetarian"]
print(result.profile.dynamic)  # ["Planning trip to Japan", "Traveling in March"]

Storing memories

Save agent interactions so future sessions have context:

def store_interaction(user_id: str, task: str, result: str):
    memory.add(
        content=f"Task: {task}\nOutcome: {result}",
        container_tag=user_id,
        metadata={"type": "agent_run"}
    )

Searching memories

Look up past interactions before running an agent:

results = memory.search.memories(
    q="previous travel recommendations",
    container_tag="user_123",
    search_mode="hybrid",
    limit=5
)

for r in results.results:
    print(r.memory or r.chunk)

Adding memory tools to agents

You can give agents direct access to memory operations. They’ll decide when to search or store information.

from agents import Agent, Runner, function_tool
from supermemory import Supermemory

memory = Supermemory()

@function_tool
def search_memories(query: str, user_id: str) -> str:
    """Search the user's memories for relevant information.

    Args:
        query: What to search for
        user_id: The user's identifier
    """
    results = memory.search.memories(
        q=query,
        container_tag=user_id,
        limit=5
    )

    if not results.results:
        return "No relevant memories found."

    return "\n".join([
        r.memory or r.chunk
        for r in results.results
    ])

@function_tool
def save_memory(content: str, user_id: str) -> str:
    """Store something important about the user for later.

    Args:
        content: The information to remember
        user_id: The user's identifier
    """
    memory.add(
        content=content,
        container_tag=user_id
    )
    return f"Saved: {content}"

agent = Agent(
    name="assistant",
    instructions="""You are a helpful assistant with memory.

When users share preferences or important information, save it.
When they ask questions, search your memories first.""",
    tools=[search_memories, save_memory],
    model="gpt-4o"
)

Example: support agent with memory

A support agent that knows who it’s talking to. Past tickets, account info, communication preferences - all available without the customer repeating themselves.

import os
from agents import Agent, Runner, function_tool
from supermemory import Supermemory
from dotenv import load_dotenv

load_dotenv()

class SupportAgent:
    def __init__(self):
        self.memory = Supermemory()

    def get_customer_context(self, customer_id: str, issue: str) -> dict:
        """Pull customer profile and past support interactions."""
        result = self.memory.profile(
            container_tag=customer_id,
            q=issue,
            threshold=0.5
        )

        return {
            "profile": result.profile.static or [],
            "recent": result.profile.dynamic or [],
            "history": [m.memory for m in (result.search_results.results or [])[:3]]
        }

    def build_instructions(self, context: dict) -> str:
        """Turn customer context into agent instructions."""
        parts = ["You are a customer support agent."]

        if context["profile"]:
            parts.append(f"Customer info: {', '.join(context['profile'])}")

        if context["recent"]:
            parts.append(f"Recent activity: {', '.join(context['recent'])}")

        if context["history"]:
            parts.append(f"Past issues: {'; '.join(context['history'])}")

        parts.append("Be helpful and reference past interactions when relevant.")

        return "\n\n".join(parts)

    @function_tool
    def escalate_to_human(self, reason: str) -> str:
        """Escalate the issue to a human agent.

        Args:
            reason: Why escalation is needed
        """
        return f"Escalated: {reason}. A human agent will follow up."

    @function_tool
    def check_order_status(self, order_id: str) -> str:
        """Check the status of an order.

        Args:
            order_id: The order identifier
        """
        # In reality, this would call your order system
        return f"Order {order_id}: Shipped, arriving Thursday"

    def create_agent(self, context: dict) -> Agent:
        return Agent(
            name="support",
            instructions=self.build_instructions(context),
            tools=[self.escalate_to_human, self.check_order_status],
            model="gpt-4o"
        )

    async def handle(self, customer_id: str, message: str) -> str:
        """Handle a support request."""
        context = self.get_customer_context(customer_id, message)
        agent = self.create_agent(context)

        result = await Runner.run(agent, message)

        # Store the interaction
        self.memory.add(
            content=f"Support request: {message}\nResolution: {result.final_output}",
            container_tag=customer_id,
            metadata={"type": "support", "resolved": True}
        )

        return result.final_output


async def main():
    support = SupportAgent()

    # Add some customer context
    support.memory.add(
        content="Premium customer since 2021. Prefers email communication.",
        container_tag="customer_456"
    )

    response = await support.handle(
        "customer_456",
        "My order hasn't arrived yet. Order ID is ORD-789."
    )
    print(response)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Multi-agent handoffs with shared memory

Agents handing off to each other usually lose context. Not if they’re sharing a memory store.

from agents import Agent, Runner

class AgentTeam:
    def __init__(self, user_id: str):
        self.user_id = user_id
        self.memory = Supermemory()

    def get_shared_context(self, topic: str) -> str:
        """Get context that all agents can use."""
        result = self.memory.profile(
            container_tag=self.user_id,
            q=topic
        )

        memories = result.search_results.results if result.search_results else []
        return "\n".join([m.memory or m.chunk for m in memories[:5]])

    def create_researcher(self) -> Agent:
        context = self.get_shared_context("research preferences")
        return Agent(
            name="researcher",
            instructions=f"""You research topics and gather information.

User context: {context}""",
            model="gpt-4o"
        )

    def create_writer(self) -> Agent:
        context = self.get_shared_context("writing style preferences")
        return Agent(
            name="writer",
            instructions=f"""You write clear, helpful content.

User context: {context}""",
            model="gpt-4o"
        )

    async def research_and_write(self, topic: str) -> str:
        """Research a topic, then write about it."""
        # Research phase
        researcher = self.create_researcher()
        research = await Runner.run(researcher, f"Research: {topic}")

        # Store research for the writer
        self.memory.add(
            content=f"Research on {topic}: {research.final_output[:500]}",
            container_tag=self.user_id,
            metadata={"type": "research", "topic": topic}
        )

        # Writing phase
        writer = self.create_writer()
        article = await Runner.run(
            writer,
            f"Write about {topic} using this research:\n{research.final_output}"
        )

        return article.final_output

Metadata for filtering

Tags let you narrow down searches later:

# Store with metadata
memory.add(
    content="User prefers detailed technical explanations",
    container_tag="user_123",
    metadata={
        "type": "preference",
        "category": "communication_style",
        "source": "support_chat"
    }
)

# Search with filters
results = memory.search.memories(
    q="communication preferences",
    container_tag="user_123",
    filters={
        "AND": [
            {"key": "type", "value": "preference"},
            {"key": "category", "value": "communication_style"}
        ]
    }
)

User profiles

How automatic profiling works

Search

Filtering and search modes

OpenAI SDK

Function calling with the regular OpenAI SDK

LangChain

Memory for LangChain apps

​What you can do

​Setup

​Basic integration

​Core concepts

​User profiles

​Storing memories

​Searching memories

​Adding memory tools to agents

​Example: support agent with memory

​Multi-agent handoffs with shared memory

​Metadata for filtering

​Related docs

User profiles

Search

OpenAI SDK

LangChain

What you can do

Setup

Basic integration

Core concepts

User profiles

Storing memories

Searching memories

Adding memory tools to agents

Example: support agent with memory

Multi-agent handoffs with shared memory

Metadata for filtering

Related docs