Sessions are the OpenAI Agents SDK's built-in memory. Pass a session into a run and the SDK stores and replays the conversation history for that session ID, with backends such as SQLiteSession, SQLAlchemySession, RedisSession and OpenAIConversationsSession. Sandbox agents have a Memory capability as well, which writes lessons from prior runs to workspace files. A session is one conversation's transcript and sandbox memory belongs to a workspace, so neither gives you facts about one user that follow them into a new session and get corrected when they change. Maximem Synap adds that as two function tools, synap_search and synap_store, bound to user_id and customer_id at construction, so the model never sees the user identity.
Where OpenAI Agents SDK Excels
OpenAI gave developers a small set of primitives that compose well. Agents carry instructions and tools, handoffs pass control between specialised agents, and guardrails validate inputs and outputs. Function tools turn a typed Python function into a tool with a generated schema; tracing and sessions come built in. If your agent needs to call tools, reason across multiple steps, or hand off between agents, the SDK handles the orchestration well.
What remains open is what the agent knows when a user comes back tomorrow in a different conversation.
How OpenAI Agents Memory Works Today
Before each run, the runner loads the history stored under the session ID and prepends it to the new input; afterwards it saves the new items. The sessions documentation lists the available backends.
Persistent sessions. SQLiteSession keeps history in memory or in a file. SQLAlchemySession, RedisSession, MongoDBSession and DaprSession put it in infrastructure you already run, and OpenAIConversationsSession stores it with OpenAI. All of these survive a process restart, with the single exception of an in-memory SQLite database.
Compaction. OpenAIResponsesCompactionSession wraps another session and uses the Responses API to compact stored history, which keeps a long conversation inside the context window. Compaction clears and rewrites the session history, so the detail of early turns is replaced by what the compaction keeps.
Sandbox memory. For sandbox agents, the Memory capability distills lessons from earlier runs into files such as MEMORY.md in the sandbox workspace. Isolation follows the workspace layout, and a fresh empty sandbox starts with empty memory.
These solve conversation continuity and they solve it properly. You can even use a user ID as the session ID, which gives every user one ever-growing transcript. What a session does not give you is a set of facts about a person that a different conversation can query, that links "John" to the email address he signs in with, and that changes when the fact changes. The docs are also explicit that a session ID does not authenticate a user or authorise access to that history. Those are memory-layer problems.
What Synap Adds
Synap is agentic context management. It does not replace the SDK's sessions. It adds a per-user memory store beside them, and the synap_openai_agents package connects to it at three points.
Two tools. create_search_tool and create_store_tool return async callables that you wrap with the SDK's function_tool helper. The search tool takes a query and returns Synap's formatted context for that user; the store tool takes content and ingests it as a memory. Scope is fixed when you create them.
Run hooks. SynapRunHooks is a RunHooks subclass that reports tool calls, tool results, model reasoning and the agent's reply to Synap, and report_user_turn reports the user's message before the run. Both need an open Synap stream (sdk.instance.listen()) and do nothing without one. With the stream open, each turn is recorded without the model having to decide to store it.
Short-term context. synap_st_instructions returns an instructions callable that prepends Synap's compacted summary and recent turns for a conversation ID to your own system text.
Synap retrieval has two modes: fast (vector-only, 50 to 100ms) and accurate (graph traversal + reranking, 200 to 500ms). The search tool in this package requests accurate mode.
We built this because agents kept stalling in production, and the cause was rarely tool logic; it was context that lived in a different session last Tuesday. Production testing hit 92% LongMemEval, 93.2% on LoCoMo (a benchmark measuring cross-session fact recall across long, multi-turn conversations). Fast mode retrieves in under 100ms.
For why context management is infrastructure and not a feature, read What Is Agentic Context Management?. For build-versus-buy numbers, see The Real Cost of DIY Agent Memory.
What Synap Adds to OpenAI Agents SDK
Persistence
OpenAI Agents SDK Native. Conversation history per session ID, in SQLite, SQLAlchemy, Redis, MongoDB, Dapr or OpenAI's Conversations API. With Synap. Per-user memory survives across sessions and restarts.
Entity Resolution
OpenAI Agents SDK Native. Stored items are replayed as written. The sessions documentation describes no entity linking. With Synap. "John" and "[email protected]" resolve to one canonical entity across every session, using embedding-based matching at the memory layer.
Compaction
OpenAI Agents SDK Native. OpenAIResponsesCompactionSession compacts one session's history through the Responses API. With Synap. Server-side compaction with configurable levels, delivered to the agent through synap_st_instructions.
Retrieval Latency
OpenAI Agents SDK Native. No retrieval step; the stored history is loaded and prepended. With Synap. 50 to 100ms fast mode (vector-only, best for chat). 200 to 500ms accurate mode (graph traversal + reranking, best for complex reasoning tasks).
Long-Term Recall
OpenAI Agents SDK Native. The sessions documentation gives no cross-session recall figure. With Synap. 92% on LongMemEval.
Failure Handling
OpenAI Agents SDK Native. A function tool that raises is reported to the model as an error by default, and the run continues. With Synap. Both tools raise SynapIntegrationError on an SDK failure and log it once, so that default applies: the model is told the call failed. The run hooks never raise.
User Scoping
OpenAI Agents SDK Native. Session ID, which your application chooses and authorises. With Synap. user_id and customer_id bound at construction; conversation_id is optional and must be a UUID.
What Production Teams Gain
Cross-session continuity. Your user chats on Monday and returns on Wednesday in a new session. The transcript is empty, and synap_search still returns what Synap holds for that user.
Accuracy that ships. 92% LongMemEval, 93.2% on LoCoMo measures whether agents recall facts across long, multi-turn conversations spanning multiple sessions.
Latency that does not block. Fast retrieval: 50 to 100ms. Accurate mode with graph traversal and reranking: 200 to 500ms. Both degrade without crashing. A failure reaches the model as a tool error and a log line, not a broken agent.
How to Get Started
Setup
Install the package alongside the OpenAI Agents SDK:
pip install maximem-synap-openai-agents openai-agents
Configure your API key. Generate one from the Synap Dashboard.
.env
SYNAP_API_KEY=synap_your_key_here
OPENAI_API_KEY=your-openai-api-key
Initialize the Synap SDK once at application startup. See SDK Initialization for the full lifecycle and configuration options.
Basic integration The smallest useful integration registers both tools on an agent and runs a query. The agent reads its tool descriptions, decides whether to search or store, and calls the matching function:
import asynciofrom agents import Agent, Runner, function_tool from maximem_synap import MaximemSynapSDK from synap_openai_agents import create_search_tool, create_store_tool
async def main(): sdk = MaximemSynapSDK() # reads SYNAP_API_KEY await sdk.initialize()
# customer_id is for B2B instances only; leave it out on B2C search_fn = create_search_tool(sdk=sdk, user_id="alice", customer_id="acme") store_fn = create_store_tool(sdk=sdk, user_id="alice", customer_id="acme") agent = Agent( name="Memory Agent", instructions=( "Use synap_search to recall facts about the user. " "Use synap_store to remember new information they share." ), tools=[ function_tool(search_fn, name_override="synap_search"), function_tool(store_fn, name_override="synap_store"), ], ) result = await Runner.run(agent, "What do you know about my project deadlines?") print(result.final_output) await sdk.shutdown()
asyncio.run(main())
Wrap the callables with function_tool, the helper. The FunctionTool dataclass takes a schema and an invoke handler and raises a TypeError when it is handed a bare function. The scoping pair (user_id, optional customer_id) is bound when you construct the tool, so the agent only ever sees the query and content parameters and never the user identity. This keeps the model from leaking or spoofing user IDs.
To record every turn instead of leaving the decision to the model, call await sdk.instance.listen() at startup, call report_user_turn before each run, and pass hooks=SynapRunHooks(sdk, user_id="alice", conversation_id=conversation_id) to Runner.run. The OpenAI Agents integration docs cover the full lifecycle.
OpenAI's sessions hold a conversation, and they hold it well. Per-user memory beside them is what gives you an agent that improves with each conversation and users who stop repeating themselves.
Related Posts
- I Spoke to 500+ Voice AI Builders in India Over 3 Months. Here Is What I Found.
- Synap Scores 92% on LongMemEval and 93.2% on LoCoMo: What the Numbers Mean
