openai-agents-memorysync

Long-term memory for the OpenAI Agents SDK, backed by MemorySync — including the first drop-in implementation of the SDK's Session protocol from any memory vendor.

• MemorySyncSession — durable server-side conversation history for Runner.run(..., session=...): survives restarts and deploys, follows multi-agent handoffs, and sends user messages to fact extraction so durable facts become long-term memories.
• memory_instructions — dynamic instructions that inject recalled memory context per run.
• Five agent tools — add, search, list, update, delete; they never raise.
• Async helpers — get_memory_context, search_memories, save_turn.

pip install openai-agents-memorysync openai-agents

Set MEMORYSYNC_API_KEY in the environment (create a key at app.memorysync.io), or pass api_key explicitly. Python 3.10+. The package never imports the Agents SDK at runtime — the Session contract is a structural protocol — so it never constrains which SDK version you run.

The drop-in session

from agents import Agent, Runner
from openai_agents_memorysync import MemorySyncSession

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")

session = MemorySyncSession(
    "thread-42",          # the conversation
    user_id="customer-7", # the end user it belongs to — required
)

# First conversation
await Runner.run(agent, "I'm vegetarian and I fly aisle.", session=session)

# Any later run — same session id, any process, any deploy
result = await Runner.run(agent, "Book my trip.", session=session)
# The model saw the full prior history — no manual .to_input_list() plumbing.

Session items live in MemorySync conversation history, one turn per item, and get_items() returns them exactly as the SDK wrote them — assistant messages, function calls, tool outputs, reasoning items — verified in the test suite against OpenAI's own SQLiteSession, item for item. Conversation history is not memory: it never shows up in memory search, recall or the memory list. Each session is stored under its own server-side owner: clear_session() can only ever reach that one conversation, and function-call JSON never reaches the user's long-term memories.

Long-term memory: with long_term=True (the default), the text of each user message is also sent to fact extraction, so durable facts ("I'm vegetarian") become memories for user_id that every MemorySync surface can recall. Assistant replies are not stored as memories. Pass long_term=False to keep a session out of long-term memory.

Multi-agent handoffs: the SDK shares one session across every agent in a run, so with a correct Session implementation, cross-handoff memory needs no extra code.

Failure discipline: the transcript IS the conversation state, so session-plane errors raise (a silently empty history would corrupt every following turn); the auxiliary long-term plane degrades through on_error. pop_item/clear_session refuse loudly when the key cannot delete. Transcript writes converge under retries — total and partial batch failures alike — via position + content-hash idempotency keys.

Long-term memory in instructions

from openai_agents_memorysync import memory_instructions

agent = Agent(
    name="Assistant",
    instructions=memory_instructions(
        "You are a helpful assistant.",
        user_id="customer-7",                      # or a per-run resolver:
        # user_id=lambda ctx: ctx.context.user_id,
    ),
)

Every run starts with what MemorySync knows about the user. Recall failure degrades to the base instructions — reported through on_error, never thrown. Modes: "profile" (default — an overview of the user: the newest facts, listed, no query needed), "query" (semantic recall for the text your prompt resolver returns), "full" (both). 1.0.3 note: profile mode is a listing; 1.0.1 searched with a generic overview prompt, which production answered with nothing for ordinary users, so the default injected no memory.

Agent tools

from openai_agents_memorysync import create_memory_tools

agent = Agent(
    name="Assistant",
    instructions="Use the memory tools to remember durable facts.",
    tools=create_memory_tools(user_id="customer-7"),
)

# Untrusted agents: search + list only.
create_memory_tools(user_id="customer-7", read_only=True)

add_memory, search_memory, list_memories, update_memory, delete_memory — the same five operations, same response strings as the MemorySync LangChain, AI SDK, CrewAI and Mastra tool sets. All async; failures return short readable strings, never exceptions.

Helpers

from openai_agents_memorysync import get_memory_context, save_turn, search_memories

context = await get_memory_context("what should I cook?", user_id="customer-7")
hits = await search_memories("dietary preferences", user_id="customer-7")
await save_turn(user_id="customer-7", user="I'm vegetarian", assistant="Noted!")

save_turn sends the user message to fact extraction, so the durable facts in it become memories; assistant is accepted but not stored as a memory. All surfaces share the same turn seeds, so the same user message sent for the same session through both MemorySyncSession and save_turn is extracted once. save_turn raises on failure — an explicit persist call is owed the truth.

Version support

CI drives a real Runner — SQLite parity oracle, handoffs, retry convergence — against the latest openai-agents release on every push.

Documentation

• OpenAI Agents SDK Memory guide
• MemorySync docs
• Get an API key