OpenAI Agent Memory Explained (2026): Sessions, State, Checkpoints, Long-Term Memory and Context Management

AI agents do not have one single kind of “memory.” In production systems, memory is a stack of different mechanisms: conversation history, server-managed continuation, application context, resumable run state, persistent workspace state, and—more recently in OpenAI’s Agents SDK—sandbox memory that can distill lessons from previous runs.

That distinction matters. If every mechanism is treated as the same thing, agent systems become expensive, hard to debug, and risky to secure. A good architecture decides what should be remembered, where it should live, how long it should persist, and which agent is allowed to read it.

This guide explains OpenAI agent memory in 2026, including Sessions, Responses API continuation, RunState checkpoints, local context, sandbox snapshots, and the new sandbox Memory capability. It also shows how these pieces fit together in long-running and multi-agent systems.

What “memory” means in an OpenAI agent

The word memory is overloaded. In the OpenAI Agents SDK, several distinct systems can preserve information across time, but they solve different problems.

• Session memory stores conversation history across multiple agent runs.
• Server-managed continuation uses conversation_id or previous_response_id to continue an OpenAI-managed conversation.
• Run context carries local application data and dependencies during a run, but is not automatically sent to the model.
• RunState serializes an interrupted agent run so it can be resumed later.
• Sandbox session state and snapshots preserve files and workspace state across sandbox runs.
• Sandbox Memory is a separate beta capability that distills useful lessons from prior runs into persisted memory files.

OpenAI explicitly separates conversational Session memory from sandbox Memory. Sessions preserve message history; sandbox Memory extracts reusable lessons into files inside the workspace.

1. Sessions: persistent conversation history

The Agents SDK provides built-in Sessions for conversation memory. A Session automatically loads prior history before a run and saves new items after the run. That means developers do not need to manually rebuild the conversation input every time.

OpenAI’s SDK documentation describes three core behaviors when Sessions are enabled:

• Before each run, the SDK retrieves stored history and prepends it to the new input.
• After the run, new user messages, agent messages, tool calls, and related items are stored.
• Later runs using the same session can continue with that history.

The simplest local implementation is SQLiteSession. The SDK also documents Redis and MongoDB session backends for applications that need shared or horizontally scalable storage.

from agents import Agent, Runner, SQLiteSession

agent = Agent(
    name="Support Agent",
    instructions="Answer clearly and concisely."
)

session = SQLiteSession("customer_42")

first = await Runner.run(
    agent,
    "My deployment failed after the database migration.",
    session=session
)

second = await Runner.run(
    agent,
    "What should I check first?",
    session=session
)

The second run can use the history from the first run because both calls use the same session.

Sessions are not free context

Persistent history still has a cost. Previous messages may be fed back into later model calls, which can increase input-token usage. The SDK’s usage documentation notes that each run reports its own usage, while prior Session history can still affect the input token count of that run.

This is one reason production agents eventually need context trimming, summarization, compaction, or selective memory retrieval instead of endlessly replaying every historical turn.

2. Client-managed vs OpenAI-managed state

OpenAI currently documents four common ways to carry state into the next turn:

• result.to_input_list() — your application manually carries the conversation forward.
• session — your storage plus the Agents SDK manages persistent history.
• conversation_id — OpenAI-managed named conversation state that can be shared across services.
• previous_response_id — lightweight Responses API continuation from one response to the next.

The important production rule is: pick one persistence strategy per conversation unless you have a deliberate reconciliation design. The SDK warns that mixing client-managed history with server-managed continuation can duplicate context.

Sessions also cannot be combined in the same run with conversation_id, previous_response_id, or auto_previous_response_id. If OpenAI manages continuation, let that layer own it; if your application manages history, keep ownership there.

When to use conversation_id

Use conversation_id when a named server-side conversation should be available to multiple workers or services. For example, a customer-support conversation might continue across a web app, a background worker, and a human escalation service.

When to use previous_response_id

Use previous_response_id when you want the lightest continuation primitive. The previous OpenAI response becomes the chain point for the next turn, without requiring you to maintain a full client-side message list.

This distinction is especially useful when designing the runtime described in our AI Agent Runtime guide.

3. Context is not the same as memory

The Agents SDK also has a RunContextWrapper. This is often confused with model memory, but OpenAI explicitly describes it as local context available to your code.

You can place things such as these in local context:

• user IDs and tenant IDs,
• database clients,
• authorization policy helpers,
• loggers and tracing utilities,
• feature flags,
• request-scoped dependencies.

The key property is that the context object is not automatically sent to the LLM. Tool functions and lifecycle hooks can read it locally.

That makes context a good place for operational state that the model should not see directly. For example, a tool may receive a user ID through local context, verify permissions, and return only the minimum data needed for the model.

This is closely related to context engineering: not everything your system knows should be inserted into the model prompt.

4. RunState: checkpoints for interrupted agent runs

Conversation memory helps across turns, but long-running agents have another problem: what happens if the run pauses in the middle?

OpenAI’s Agents SDK uses RunState as a durable pause/resume boundary. It can serialize enough information to continue an interrupted run later, including model responses, generated items, approval state, usage, and optional server-managed conversation identifiers.

This is especially important for human-in-the-loop workflows. Imagine an agent that wants to delete a file, send a payment, change production infrastructure, or publish content. The run can stop at the approval boundary, persist its state, and resume only after a human decision.

A checkpoint is therefore different from a Session. A Session answers, “What happened in earlier conversation turns?” A RunState answers, “Where exactly was this execution when it stopped, and what still needs to happen?”

For a broader architecture around retries, recovery, and durable execution, see AI Agent Runtime Explained and AI Agent Reliability Engineering.

5. Sandbox sessions, snapshots, and workspace state

OpenAI’s Sandbox Agents add another persistence layer: the agent’s actual working environment.

A sandbox can contain files, repositories, generated artifacts, tool outputs, and other workspace state. Later runs can reconnect by reusing a live sandbox session, restoring a serialized session_state, restoring state embedded in RunState, or starting from a saved snapshot.

This is not conversational memory. It is closer to persistent execution state.

For example, a coding agent might:

1. clone a repository,
2. inspect files,
3. change several modules,
4. run tests,
5. pause for review,
6. resume the same workspace tomorrow.

The repository changes belong to the sandbox workspace, while the conversation history may belong to a Session and the paused execution may belong to RunState. Those are three different persistence layers.

This is why sandbox design and AI agent sandboxing should be treated as part of the memory architecture rather than a separate infrastructure topic.

6. Sandbox Memory: actual long-term learned memory

The most interesting memory feature in the current Agents SDK is the Sandbox Agent Memory capability. OpenAI labels Sandbox Agents and their memory features as beta, so developers should expect API details and defaults to evolve.

Unlike Session memory, Sandbox Memory does not simply replay messages. It distills lessons from previous runs into memory artifacts inside the workspace.

OpenAI’s documentation explains that memory can reduce:

• agent cost by reducing repeated exploration,
• user cost by remembering corrections or preferences,
• context cost by allowing future tasks to reuse prior lessons without reconstructing the entire old thread.

How sandbox memory is stored

By default, memory artifacts live in a memories/ directory in the sandbox workspace. The documented layout includes files such as:

• memory_summary.md — a small summary that can be injected early,
• MEMORY.md — an index of consolidated memory,
• raw memory extracts,
• rollout summaries from earlier runs.

To reuse that memory later, the configured memory directory must survive. That can happen by keeping the same sandbox session or restoring it from persisted session state or a snapshot. A completely fresh empty sandbox starts with empty memory.

Progressive disclosure

One of the strongest design choices is that the agent does not need to inject all historical memory into every prompt.

The SDK uses a progressive disclosure pattern. A small memory summary can be presented first. If prior work looks relevant, the agent can search the memory index and open detailed rollout summaries only when needed.

This is much more scalable than putting every historical interaction into the context window.

Memory generation has two stages

The documented memory generation process has two broad phases:

1. Conversation extraction: accumulated run conversations are processed into summaries and compact raw memory notes.
2. Layout consolidation: a consolidation process turns relevant patterns into MEMORY.md and memory_summary.md.

This makes long-term memory a form of curated compression rather than a raw transcript archive.

7. Session memory vs long-term memory

This distinction is critical enough to make explicit:

If your agent only needs to remember the previous user turn, a Session may be enough. If it needs to learn durable operational lessons from weeks of work, raw conversation replay is the wrong abstraction.

8. The production memory architecture

A robust production agent usually benefits from multiple persistence layers with clear boundaries.

A practical layering model

Layer 1 — immediate turn context: Only the instructions, task, and retrieved information needed for the current model call.

Layer 2 — conversational continuity: Session or server-managed continuation for recent multi-turn history.

Layer 3 — execution continuity: RunState for paused workflows and approvals.

Layer 4 — workspace continuity: sandbox session state and snapshots for files and artifacts.

Layer 5 — durable knowledge: curated long-term memory that can be searched and selectively inserted when relevant.

This model keeps the model context small while still making the overall system stateful.

9. Memory and multi-agent systems

Multi-agent systems introduce another question: should every subagent share the same memory?

Usually, no.

A finance agent, coding agent, and customer-support agent may operate in the same application but have very different data-access requirements. OpenAI’s sandbox memory documentation supports separate memory layouts, allowing different agents to keep distinct memories/ and sessions/ paths even inside the same workspace.

This is a useful security boundary. Memory sharing should be intentional, not automatic.

A good multi-agent design may use:

• a shared orchestration Session for high-level workflow continuity,
• separate sandbox memory layouts for specialist agents,
• explicit handoff summaries instead of unrestricted historical access,
• local context for authorization and tenant boundaries.

For orchestration patterns and subagents, see our OpenAI Agents API guide and AI Agents Explained.

10. Memory security: the hidden attack surface

Persistent memory increases capability, but it also creates a durable attack surface.

If malicious content enters memory and is reused later, one compromised run can influence many future runs. This is the core problem behind memory poisoning.

Production systems should therefore treat memory as untrusted retained data rather than as permanent truth.

Key controls

• Provenance: record where a memory came from.
• Scope: isolate memory by user, tenant, agent, or workflow.
• Retention: remove stale or unnecessary memory.
• Review: require approval before promoting high-impact facts into durable memory.
• Freshness checks: trust the current environment over old memory.
• Sensitive-data policy: do not retain secrets simply because they appeared in a conversation.
• Retrieval filtering: retrieve only memory relevant to the current task.

OpenAI’s sandbox memory documentation itself notes that memory can become stale and instructs agents to treat it as guidance while trusting the current environment.

For a deeper security treatment, read AI Agent Memory Security Explained, AI Agent Red Teaming, and AI Agent Guardrails.

11. What should an agent remember?

A common mistake is to store everything. Better systems distinguish between temporary context and durable knowledge.

Good candidates for durable memory include:

• stable user preferences explicitly confirmed by the user,
• verified environment conventions,
• repeated workflow lessons,
• confirmed debugging discoveries,
• project-specific architectural decisions,
• validated constraints that will matter in future runs.

Poor candidates include:

• temporary tool outputs,
• unverified model guesses,
• secrets and credentials,
• one-off transient failures,
• stale business data,
• information copied from potentially adversarial content without validation.

The goal is not maximum memory. The goal is maximum useful continuity with minimum context and security cost.

12. Memory and retrieval are different

Long-term memory is also different from retrieval-augmented generation.

RAG retrieves external knowledge from documents or databases. Memory usually represents retained knowledge about prior runs, preferences, actions, or learned workflow patterns.

A production agent often uses both:

• RAG: “What does the current policy document say?”
• Memory: “Last time this deployment failed because this repository needs a special migration order.”

See Agentic RAG Explained for the retrieval side of this architecture.

13. Memory and context-window management

A model context window is not a database. Even if a model supports a large context, filling that window with every prior turn is usually a poor memory strategy.

As history grows:

• token cost rises,
• latency rises,
• irrelevant history competes with important instructions,
• old mistakes can remain influential,
• debugging becomes harder.

Better memory architectures compress, summarize, retrieve selectively, and preserve raw history outside the model context.

Sandbox Agents also include a Compaction capability for long-running flows, reinforcing the idea that working context should be actively managed rather than allowed to grow indefinitely.

14. A production decision framework

Use this simple decision sequence:

Question 1: Do I only need the previous conversation?

Use a Session, conversation_id, or previous_response_id.

Question 2: Do I need to pause and resume the exact workflow?

Persist RunState.

Question 3: Do I need files and artifacts to survive?

Persist or snapshot the sandbox workspace.

Question 4: Do I want future runs to learn reusable lessons?

Use sandbox Memory or build a separate curated memory layer.

Question 5: Does the model actually need to see this data?

If not, keep it in local context or application storage rather than injecting it into prompts.

15. Example architecture: long-running research agent

Consider a research agent that works on a company over several weeks.

Its memory design could look like this:

1. A Session stores recent user interactions.
2. RunContextWrapper contains tenant ID, database client, and permission policy.
3. RunState captures the workflow when human approval is required.
4. A sandbox stores downloaded reports, notes, and generated artifacts.
5. A snapshot lets the agent reopen that workspace later.
6. Sandbox Memory extracts durable lessons such as preferred report format or repeatedly useful data sources.
7. RAG retrieves current source documents at task time.

Notice that none of these components replaces the others. They solve different continuity problems.

16. Cost implications of memory

Memory architecture directly affects agent cost.

Replaying a large conversation every turn increases input tokens. Re-discovering the same repository structure every run increases tool calls. Re-downloading the same dataset increases infrastructure cost. On the other hand, retaining too much memory increases storage, retrieval, and governance complexity.

The best architecture reduces repeated reasoning while keeping model input selective.

For broader operational budgeting, see AI Agent Cost Management Explained.

17. Observability for memory systems

Memory failures are often invisible unless you explicitly trace them.

Useful observability signals include:

• which memories were retrieved,
• which memory influenced a tool decision,
• memory age and source,
• Session history size,
• context tokens added by memory,
• checkpoint creation and resume events,
• snapshot IDs and workspace versions,
• memory update or deletion events.

This becomes especially important after a bad outcome. If an agent made the wrong decision, you need to know whether the cause was the current prompt, a retrieved document, an old Session message, or a persistent memory artifact.

See AI Agent Observability Explained for the wider tracing architecture.

18. Common mistakes

Storing the full transcript forever

This is easy to build but scales poorly. Raw history is valuable for audit, but it should not automatically become model context.

Calling application context “model memory”

RunContextWrapper is local application context. The model does not automatically see it.

Using both Session and server-managed continuation in the same run

The Agents SDK explicitly treats these as alternative persistence strategies.

Using memory without tenant isolation

Cross-user memory leakage is one of the most serious risks in multi-tenant systems.

Trusting old memory over the live environment

Repositories change, users change preferences, APIs change, and policies change. Memory should guide—not override—fresh evidence.

Persisting secrets inside durable state

Serialization and memory retention can accidentally turn short-lived credentials into long-lived data. Keep secrets in dedicated secret-management systems.

19. How OpenAI’s memory model is evolving

The current Agents SDK shows a clear progression from simple conversation history toward a layered state model:

• Sessions provide conversation continuity.
• Responses API primitives provide server-managed continuation.
• RunState provides durable execution checkpoints.
• Sandbox sessions and snapshots preserve workspaces.
• Sandbox Memory provides cross-run learned memory.

This matters because modern agents are moving beyond “chat with tools.” They are becoming long-running software processes that need state, recovery, artifacts, isolation, and selective learning from prior work.

FAQ

Does the OpenAI Agents SDK have built-in memory?

Yes. The SDK has Session memory for conversation history. Sandbox Agents also have a separate beta Memory capability that distills reusable lessons from prior runs into persisted workspace files.

What is the difference between a Session and Memory?

A Session stores conversation history. Sandbox Memory distills reusable lessons from past runs. They solve different problems.

What is the difference between Session and RunState?

A Session preserves conversation history across turns. RunState is a serializable checkpoint of an in-progress or interrupted agent execution.

Can I use a Session with previous_response_id?

Not in the same run. OpenAI’s Agents SDK documentation says Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id in the same run.

Does RunContextWrapper get sent to the model?

No. OpenAI documents local context as application-side data for tools, hooks, and dependencies. It is not automatically sent to the LLM.

Is sandbox Memory production-stable?

OpenAI currently labels Sandbox Agents and their memory functionality as beta, so API details and defaults may change.

Should every subagent share memory?

Usually not. Separate memory layouts and explicit sharing are safer for specialist agents, tenants, and sensitive workflows.

Should memory replace RAG?

No. Memory is useful for retained lessons and continuity; RAG is useful for retrieving external knowledge. Production agents often use both.

Final takeaway

OpenAI agent memory in 2026 is not a single feature. It is a layered architecture.

Sessions remember conversations. Responses API continuation preserves server-side conversational state. RunContextWrapper carries local application context. RunState checkpoints execution. Sandbox state preserves the working environment. Sandbox Memory distills reusable lessons across runs.

The strongest agent systems do not ask, “How do we make the model remember everything?” They ask, “Which state deserves to persist, who should be allowed to read it, and when should it enter the model context?”

That shift—from raw history to deliberate state architecture—is what makes long-running agents cheaper, safer, and more reliable.

Related Vynula Guides

• OpenAI Agents API Explained (2026)
• AI Agent Runtime Explained (2026)
• Context Engineering for AI Agents (2026)
• AI Agent Memory Security Explained (2026)
• Agentic RAG Explained (2026)
• AI Agent Sandboxing Explained (2026)
• AI Agent Observability Explained (2026)
• AI Agent Reliability Engineering Explained (2026)
• AI Agent Cost Management Explained (2026)
• AI Agent Red Teaming Explained (2026)

Primary Sources

• OpenAI Agents SDK — Sessions
• OpenAI Agents SDK — Running agents and state management
• OpenAI Agents SDK — Context management
• OpenAI Agents SDK — RunState reference
• OpenAI Agents SDK — Sandbox Agents concepts
• OpenAI Agents SDK — Agent memory