How to enable sandbox memory on OpenAI SandboxAgent

Sandbox memory is how later SandboxAgent runs pick up lessons from earlier ones. It is not the SDK’s conversational Session memory. Sessions store message history. Sandbox memory distills useful lessons into files in the workspace so the next agent can search them.

That split is the whole point. A sandbox run otherwise forgets prior corrections unless memory is a first-class capability with files the next agent can open. Resume and snapshots preserve workspace state. Memory preserves reusable guidance about work that happened there: user preferences, corrections, project-specific lessons, and task summaries, without replaying every previous turn.

OpenAI documents three kinds of cost this can reduce:

Agent cost. If a workflow took a long time, the next run should need less exploration, which can cut token usage and time to completion.
User cost. If the user corrected the agent or stated a preference, later runs can remember that feedback and need less human intervention.
Context cost. If the user wants to build on a completed task, they should not have to find the old thread or re-type the context.

Treat generated memory artifacts as retained workspace data. Apply the same sensitivity and retention policy you already use for the sandbox. Conversation files processed for memory can include user input, assistant and tool items, interruptions, and final outputs.

Add `memory()` to the agent

Add memory() as a capability on SandboxAgent. The TypeScript memory guide shows this pattern:

import {
  filesystem,
  Manifest,
  memory,
  SandboxAgent,
  shell,
} from '@openai/agents/sandbox';

const manifest = new Manifest({
  entries: {
    'README.md': {
      type: 'file',
      content: '# Memory demo\n\nA workspace for follow-up runs.\n',
    },
  },
});

const agent = new SandboxAgent({
  name: 'Memory-enabled reviewer',
  model: 'gpt-5.6-sol',
  instructions:
    'Inspect the workspace, verify important claims, and preserve useful lessons for follow-up runs.',
  defaultManifest: manifest,
  capabilities: [filesystem(), shell(), memory()],
});

The Sandbox Agents guide documents the same idea for the Python Agents SDK: attach memory, filesystem, and shell capabilities on SandboxAgent. Sandbox agents are in beta in both SDKs, so API details, defaults, and supported capabilities may change.

If you pass a capabilities list, it replaces the default list. A SandboxAgent already includes filesystem, shell, and compaction by default, so include any of those the agent still needs.

memory() enables both reading and generating memories. If read is enabled, it requires shell(), which lets the agent read and search memory files when the injected summary is not enough. Live memory update is enabled by default and also requires filesystem(), so the agent can update MEMORY.md in the configured memories directory when it finds stale memory or the user asks it to update memory.

How a later run reads memory

Reads use progressive disclosure:

At the start of a run, the SDK injects a small summary (memory_summary.md) of generally useful tips, user preferences, and available memories into the agent’s developer prompt.
When prior work looks relevant, the agent searches the configured memory index (MEMORY.md under memoriesDir) for keywords from the current task.
It opens the matching prior rollout summaries under the configured rollout_summaries/ directory only when the task needs more detail.

Agents are instructed to treat memories as guidance only and to trust the current environment. Memory can go stale. With liveUpdate enabled (the default), the agent can repair the configured MEMORY.md in the same run. Disable live updates when the agent should read memory but not modify it, for example on a latency-sensitive run.

Control generate vs read

Use a narrower mode when a run should not both read and write:

memory({ generate: false }) for agents that should read memory but not generate new memories — for example an internal agent, subagent, checker, or one-off tool agent whose run does not add much signal.
memory({ read: null }) when the run should generate memory for later, but should not be influenced by existing memory.

Read-only, with live updates off:

import { memory } from '@openai/agents/sandbox';

const readOnlyMemory = memory({
  read: { liveUpdate: false },
  generate: false,
});

You can also tune generation with memory({ generate: ... }). Documented options include maxRawMemoriesForConsolidation, phaseOneModel, phaseTwoModel, and extraPrompt (for example, to prioritize workflow corrections, verification commands, and user preferences). If recent raw memories exceed maxRawMemoriesForConsolidation, Phase 2 keeps memories from the newest conversations and drops older ones. Recency is the last time the conversation was updated.

When memory is written

After a run finishes, the sandbox runtime appends that run segment to a conversation file. Accumulated conversation files are processed when the sandbox session closes.

Generation has two phases:

Conversation extraction. A memory-generating model processes one accumulated conversation file and writes a conversation summary. System, developer, and reasoning content are omitted. Over-long conversations are truncated to fit the context window, with the beginning and end preserved. It also writes a raw memory extract: compact notes that Phase 2 can consolidate.
Layout consolidation. A consolidation agent reads raw memories for one memory layout, opens conversation summaries when it needs more evidence, and extracts patterns into MEMORY.md and memory_summary.md.

By default, artifacts live under memories/ in the workspace. The TypeScript memory guide shows this layout:

workspace/
├── sessions/
│   └── <rollout-id>.jsonl
└── memories/
    ├── memory_summary.md
    ├── MEMORY.md
    ├── raw_memories.md
    ├── raw_memories/
    └── rollout_summaries/

The Sandbox Agents guide shows the same core files and also lists phase_two_selection.json, per-rollout files under raw_memories/ and rollout_summaries/, and a skills/ directory.

A fresh empty sandbox starts with empty memory. To reuse artifacts in a later run, preserve the whole configured memories directory: keep the same live sandbox session, resume from persisted session state or a snapshot, or mount persistent storage such as S3.

Multi-turn chats and isolated layouts

For multi-turn sandbox chats, use the normal SDK Session together with the same live sandbox session. Both runs then append to one memory conversation file because they share the same session id. The sandbox session identifies the live workspace; it is not the memory conversation ID. Phase 1 sees the accumulated conversation when the sandbox session closes, so it can extract memory from the whole exchange instead of isolated turns.

When memory associates a run with a conversation, it resolves in this order: conversationId passed to run(...), then the SDK session id, then groupId, then a generated per-run ID.

Memory isolation is based on MemoryLayoutConfig, not agent name. Agents that share a layout and a memory conversation ID share one consolidated memory. Different layouts keep separate rollout files, raw memories, MEMORY.md, and memory_summary.md even in the same sandbox workspace:

import { memory } from '@openai/agents/sandbox';

const engineeringMemory = memory({
  layout: {
    memoriesDir: 'memories/engineering',
    sessionsDir: 'sessions/engineering',
  },
});

const financeMemory = memory({
  layout: {
    memoriesDir: 'memories/finance',
    sessionsDir: 'sessions/finance',
  },
});

That keeps one domain’s analysis from being consolidated into another domain’s memory.

Try it next

Add memory(), filesystem(), and shell() to a SandboxAgent, run two tasks against the same live sandbox session, then inspect MEMORY.md and memory_summary.md in the memories directory after the session closes. For layout isolation, generation prompts, and the full TypeScript walkthrough, read the Agents SDK memory guide. The Sandbox Agents platform guide covers resume, snapshots, and S3-backed persistence.