OpenAI Agents SDK

Keep an Agents SDK conversation going across runs and processes. recall-openai-agents is a Session for the OpenAI Agents SDK whose history lives in Recall.

The SDK reads a session's history before each run and writes the new items back after it. With RecallSession that history is in the same database as the agent's memory and state, any process can read it, and writes go under a lease, so two processes never interleave writes to one session.

Install and use

pip install recall-openai-agents

That also installs the recall binary and the polign_db server for Linux, macOS and Windows, so there is no separate database to download.

from agents import Agent, Runner
from recall_openai_agents import RecallSession

agent = Agent(name="assistant", instructions="Reply briefly.")
session = RecallSession("support-42", local_dir="./recall-data")

result = await Runner.run(agent, "Hi, I am Sam.", session=session)
result = await Runner.run(agent, "What is my name?", session=session)
print(result.final_output)   # Sam

Run it twice, or from two processes, and the second run continues the first. The session id names the conversation.

What happens in a run

Before the run, the SDK calls get_items, which reads the session's record and hands the history back oldest first. get_items(limit=n) returns the latest n.
After the run, the SDK calls add_items with the run's new items: the input, the model's messages, tool calls and their outputs. They are appended to the record under the session's lease, taken for the write and handed back after it.
Each item is also a turn of a Recall agent named oa-<session_id>. agent_resume on that id, from the Recall MCP tools or polign_recall.Client.resume, briefs another process with the conversation. That record stays as it was said: pop_item and clear_session change what the SDK reads back, not the record. Pass record_turns=False to keep the history only.
pop_item removes and returns the latest item, and clear_session empties the history, as the SDK expects.

RecallSession implements the SDK's Session protocol, so anything that takes a session takes it: Runner.run, run_sync and run_streamed, SessionSettings(limit=...), and session_input_callback.

Options

Option	Default	What it does
`client`	none	A `polign_recall.Client` opened with `agent=True`, to share one subprocess. Without it, `RecallSession` opens its own and closes it on `close()`.
`backend`, `backend_url`, `backend_key`	what the `recall` binary resolves	Where the records live, the same three names as `recall -backend`, `-url` and `-key`: polign, pgvector, mongodb or qdrant.
`local_dir`	none	Keep the database in this directory and run its server; the short spelling of `backend="local", backend_url=...`.
`env`	process environment	Extra environment for the subprocess, such as `RECALL_COLLECTION`.
`record_turns`	on	Record each item as a turn of the Recall agent `oa-<session_id>` as well.
`lease_ttl`	10	Seconds a write's lease lasts if the process dies in the middle of it.
`lease_wait`	30	Seconds a write waits for another process to finish with the session before failing with `RecallError` code `lease_held`.

Session ids may hold any character. An id Recall cannot use as an agent name as is (anything outside letters, digits, ., _ and -, or longer than 125 characters) is hashed.

Where the records live

local_dir keeps the records on one machine; with no database named at all, the recall binary keeps them in ~/.local/share/recall, the local database every agent on the machine shares. Workers on several machines need one shared database: run polign-server with its store in your S3, GCS or Azure bucket where they can all reach it (Run polign_db shows how), or use PostgreSQL, MongoDB or Qdrant, and name it:

RecallSession("support-42", backend="pgvector", backend_url="postgres://recall:pw@db.internal/recall")

Limits

The history of one session is one Recall record, bounded by Recall's output size of 1 MiB: a few thousand ordinary items. A session that grows past it fails to write, so clear or compact sessions that run that long. SessionSettings(limit=...) bounds what the model sees, not what is stored.
It needs Python 3.10 or later and openai-agents 0.3 or later in 0.x; tested against 0.24.

Source & license

recall-openai-agents is open source under the Apache License 2.0 and lives next to the Python client in github.com/Polign/polign. Bug reports and pull requests go there.