OpenAI Agents SDK

SurrealDB Agent Memory gives agents built with the OpenAI Agents SDK a durable, shared memory. An agent can remember across runs, recall what it needs before answering, and share memory with other agents through a common scope.

Package: agent-memory-openai-agents-sdk (PyPI). Memory works two ways, and they compose: function tools the agent calls itself, and automatic memory wrapped around a run.

Installation

pip install agent-memory-openai-agents-sdk

Environment

export OPENAI_API_KEY="your-openai-api-key"
export AGENT_MEMORY_URL="https://your-agent-memory-endpoint"
export SPECTRON_NAMESPACE="your-namespace"
export SPECTRON_DATABASE="your-database"
export AGENT_MEMORY_TOKEN="your-token"   # optional for local, unsecured instances

Memory as function tools

The agent decides when to remember, recall, context, reflect, or forget. get_agent_memory_tools builds the tools from the AGENT_MEMORY_* environment by default; pass client= for an explicit AgentMemoryClient or include= to expose a subset:

from agents import Agent, Runner
from agent_memory_openai_agents_sdk import get_agent_memory_tools

agent = Agent(
    name="assistant",
    instructions=(
        "You are a helpful assistant. Use recall to check memory before you "
        "answer, and use remember to store anything worth keeping."
    ),
    tools=get_agent_memory_tools(session_id="user-123"),
)

Runner.run_sync(agent, "My name is Ada and I work on databases.")

result = Runner.run_sync(agent, "What do you know about me?")
print(result.final_output)

Automatic memory around a run

run_with_memory recalls memory relevant to the input, injects it into the prompt, runs the agent, and stores the result. The agent needs no memory tools of its own:

import asyncio
from agents import Agent
from agent_memory_openai_agents_sdk import MemoryScope, run_with_memory

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
scope = MemoryScope(session_id="user-123")

async def main():
    await run_with_memory(agent, "My name is Ada.", scope=scope)

    result = await run_with_memory(agent, "What is my name?", scope=scope)
    print(result.final_output)

asyncio.run(main())

Persisting output with hooks

To save an agent's output while running it yourself, attach AgentMemoryHooks:

from agents import Runner
from agent_memory_openai_agents_sdk import AgentMemoryClient, AgentMemoryHooks, MemoryScope

client = AgentMemoryClient.from_env()
hooks = AgentMemoryHooks(client, MemoryScope(session_id="user-123"))

await Runner.run(agent, "Summarize our project decisions.", hooks=hooks)

Multi-agent shared memory

Both approaches talk to SurrealDB Agent Memory through a single AgentMemoryClient, scoped by a MemoryScope (agent_id, session_id, user_id). Agents that share a MemoryScope read and write the same memory, so what one agent stores is available to another.

When to use MCP or the SDK instead

• •

  For an MCP-native host, use the MCP server.

• •

  To call SurrealDB Agent Memory directly, use the Python SDK.