Guides / Frameworks

OpenAI Agents SDK

For developers on the OpenAI Agents SDK who want an agent to remember each user across conversations. openai-agents-recall gives you a session backed by Recall, instructions that carry what Recall knows about the user, and memory tools.

What memory adds

An SDK session keeps one conversation's items. With Recall behind it, the conversation also teaches the agent about the user:

A session storeWith Recall
The next message in a conversationThe history is replayed.The same, from a RecallSession.
A new conversationEmpty history; the agent knows nothing about the user.The instructions already hold the user's peer card and their most relevant facts.
"Last time I said I'm vegetarian"Only if it is in this conversation.Learned from the earlier one, or saved by the model with recall_remember; recall_ask answers questions about the past.

Recall is memory, not the agent: the SDK still runs the model, the tools and handoffs.

How it maps onto Recall

In the Agents SDKIn RecallWhy
Your appWorkspace, from RECALL_WORKSPACE_IDMemory stays inside it.
The user, context={"user_id": ...}Peer user-8412Recall learns about this person. Use your own stable user id, not an email address.
The agentPeer assistant, not learned aboutIts messages are read as context; facts are learned about the user.
A conversation, RecallSession(id, ...)Session with the same idThe conversation's items in order. Recall learns from the user's messages among them.

Build it

Install the package with pip install openai-agents-recall and set RECALL_API_KEY (create one at app.recallmem.dev/keys), or RECALL_URL for a server of your own.

One agent for every user. recall_instructions adds what Recall knows about the user to your instructions before each model call; recall_tools gives the model recall_search, recall_ask and recall_remember. Both read the user from the run's context; pass user_id= instead when there is one user.

from agents import Agent, Runner
from openai_agents_recall import RecallSession, recall_instructions, recall_tools
from recall_memory import Recall

recall = Recall(workspace_id="assistant-prod")

# One agent for every user. `model` is any Agents SDK model; None uses the SDK's default.
agent = Agent(
    name="Assistant",
    instructions=recall_instructions("You are a helpful assistant.", client=recall),
    tools=recall_tools(client=recall),
    model=model,
)

A conversation. Runner.run(..., session=...) loads the history before the run and stores the new items after it.

# A RecallSession per conversation keeps its history; the run's context names the user.
me = {"user_id": "user-8412"}
session = RecallSession("chat-20261013-a1", user_id="user-8412", client=recall)
first = await Runner.run(
    agent, "I'm vegetarian. Plan dinner for four on Saturday.", session=session, context=me
)
# The next message in the same conversation: the session supplies what was said so far.
second = await Runner.run(agent, "Make it gluten-free too.", session=session, context=me)

A new conversation. No history, but the instructions carry what Recall learned from the first one:

# A new conversation: no history, but the instructions already carry what Recall learned.
await recall.aio.wait_for_idle()  # only for this demo: learning runs in the background
later = await Runner.run(
    agent,
    "Any ideas for lunch tomorrow?",
    session=RecallSession("chat-20261014-b2", user_id="user-8412", client=recall),
    context=me,
)

What the session stores

RecallSession implements the SDK's Session protocol. Every item comes back exactly as it was added, including tool calls, tool results and reasoning items, so runs resume as they would with any other session. Recall learns only from the user's messages: the agent's messages are read as context, and tool and reasoning items are kept for the history only. Messages that other clients write to the same Recall session (a voice front end, say) are read back as user or assistant messages.

pop_item() and clear_session() hide items from the history. Recall keeps the messages and what it learned from them; delete the Recall session to erase them.

Settings that matter

SettingUse
user_id or the run's contextWhose memory the tools and instructions use (user_id_key changes the key read from the context).
session_settings=SessionSettings(limit=...)Replay only the newest items of a long conversation; Recall still has all of it.
max_conclusionsMost facts in the instructions (20 by default).
k, reasoning_levelResults per search, and how hard recall_ask thinks: low by default. See Reasoning levels and models.

Cost and speed

Loading a session lists its messages, 100 per request. The instructions read memory with a context request and no model call: context reads took 0.3 to 0.7 seconds, measured from Europe against the hosted API (Frankfurt), October 2026. The SDK builds instructions before every model call, so a run with tool calls reads more than once. recall_search searches facts and messages without a model call, in about a second; recall_ask is one model call of 2 to 4.5 seconds at low. Learning runs in the background.

Context, search and storage are included. Learning from the user's messages and answering questions are charged; see pricing and Cost and speed for worked examples.

Privacy and forgetting

A RecallSession stores every item of the conversation in Recall, tool results included (Recall does not learn from those). If a tool returns data you must not keep, use a session store of your own for the history and keep Recall for the instructions and tools. Tell users what the agent remembers. To forget someone:

# The user deletes their account: erase them, then the conversations that hold the replies.
user = await recall.aio.peer("user-8412")
conversations = [c async for c in await user.sessions()]
await user.delete()
for conversation in conversations:
    await conversation.delete()

See Forget a person and Privacy, consent and forgetting.

Pitfalls

Next: LangChain and LangGraph · Designing workspaces, peers and sessions