Memory Compaction

Memory & Compaction for Long-Running Agents

This skill gives you the OpenAI Agents SDK pattern for keeping a multi-turn, multi-batch agent coherent: compaction sustains the current session when context grows, memory carries reusable workflow lessons into future sessions, and a generated, human-reviewed artifact (a memo with citations) remains the only system of record. The three are deliberately separated — no single one of them (not conversation history, not memory, not agent reasoning) replaces human review of the cited output. The reference implementation is an evidence-review agent for compliance investigations, but the pattern applies wherever knowledge workers review evolving context and produce auditable outputs: support escalations under policy updates, security incident summaries, finance exception reconciliation, legal/procurement contract review, M&A diligence.

When to use

Use this skill when:

• A single agent session must survive many turns or sequential evidence/document batches and will hit context limits mid-task.
• You are wiring a SandboxAgent with Filesystem() and Shell() capabilities and need to add Compaction() and/or Memory().
• You must decide, at a phase boundary, what to keep in working context, what to promote to cross-run memory, and what to write into the output artifact.
• Repeated runs of the same kind of task should get better over time without replaying every prior interaction.

Do NOT use this pattern to:

• Store task conclusions or case facts in memory — those belong in the reviewed output artifact with citations.
• Replace a reviewed deliverable with compacted summaries or memory files.
• Manage short sessions that fit comfortably in one context window — the machinery adds no value there.

Rules

1. Separate the three primitives by purpose. Compaction summarizes active conversation and working state so one long-running session can continue. Memory stores patterns, preferences, and process lessons so future sessions improve. The generated memo is the definitive, human-reviewed artifact. Neither compaction nor memory ever stores investigation conclusions.

1. Stage inputs in the workspace, not the prompt. Describe the fresh-session workspace with a Manifest (fields: root — defaults to /workspace; entries; environment; users/groups; extra_path_grants; remote_mount_command_allowlist). Keep entry paths workspace-relative for portability across Unix-local, Docker, and hosted providers. Put long task instructions in workspace files (README.md, task.md); keep agent instructions focused on boundaries. Use small File(...)/Dir(...) entries for tutorials; LocalDir, GitRepo, or storage mounts for production data. Keep mount scopes narrow; inject secrets as runtime configuration, never as prompt text or committed manifests.

1. Make findings citable. Use stable document IDs and a machine-readable manifest (e.g., manifest.csv) so the memo cites traceable sources. The source's baseline instruction requires every finding to cite document IDs from manifest.csv, and requires incomplete evidence to be logged as an open question rather than guessed at.

1. Pick the compaction trigger by how much control you need. Three ways: (a) automatic — attach Compaction() and the SDK compacts when context pressure requires it; often sufficient for production; (b) threshold-based — Compaction(policy=StaticCompactionPolicy(threshold=...)) for predictable context-size behavior (the demo uses 8_000); (c) forced checkpoint — OpenAIResponsesCompactionSession.run_compaction({"force": True}) at an application-defined phase boundary, such as after a major review phase and before the next evidence batch.

1. Tell the agent what compaction must preserve. Amend instructions explicitly. From the source: "When context is compacted, preserve the current batch, cited facts, open questions, artifact paths, and unresolved reviewer concerns." Summarized impressions alone are not enough working state.

1. For forced checkpoints, wrap a persistent session. Construct OpenAIResponsesCompactionSession(session_id=..., underlying_session=SQLiteSession("evidence_review_session.sqlite"), model=COMPACTION_MODEL, compaction_mode="input"), then call await session.run_compaction({"force": True, "compaction_mode": "input"}). Verify effectiveness by comparing session item counts from session.get_items() before and after the call. The demo uses a cheaper dedicated compaction model (COMPACTION_MODEL = "gpt-5.4-mini" vs MODEL = "gpt-5.5" for the agent) and max_turns = 12.

1. Restrict memory to workflow lessons. Good memory candidates: use the manifest first when reviewing file-based evidence workspaces; preserve uncertainty in the memo instead of guessing; keep earlier assumptions visible when later evidence narrows them. Bad candidates (they belong in the memo): specific findings or violations, evidence-specific facts or citations, case conclusions about any entity's conduct.

1. Steer memory generation with MemoryGenerateConfig.extra_prompt. Configure Memory(generate=MemoryGenerateConfig(extra_prompt=...)) and state explicitly what NOT to store — the source's prompt forbids storing case-specific compliance findings, document facts, evidence citations, or memo conclusions, directing them to the memo file instead. The SDK writes memories/MEMORY.md and memories/memory_summary.md via a sandbox pre-stop hook before session termination; let Memory() manage its own artifacts (memories/, sessions/) and keep generated outputs under outputs/.

1. Combine all three in the final agent. Capabilities: [Filesystem(), Shell(), Compaction(), workflow_memory()], plus instructions that say: use compaction as working context; use SDK memory for reusable workflow lessons across runs; do not treat memory as the system of record for findings — those belong in the cited memo artifact.

1. Keep superseded assumptions visible. As batches arrive, do not silently delete assumptions that later evidence narrowed or overturned — track the change in working notes and the memo. The memo (e.g., outputs/compliance_review_memo.md) contains: executive summary (distinguish control gaps from definitive violations), cited findings table (each finding with its supporting document IDs and status), open questions, recommended next steps for the reviewer.

1. Under Zero Data Retention, disable tracing. Set os.environ["OPENAI_AGENTS_DISABLE_TRACING"] = "true" when DISABLE_TRACING is on.

Compaction vs memory at a glance

| Aspect | Compaction | Memory | |---|---|---| | Purpose | Continue one long-running session as context grows | Improve future runs with reusable lessons | | Summarizes | Active conversation and working state | Patterns, preferences, process lessons | | Store conclusions? | No — working state only; memo is the record | No — workflow lessons, not case facts | | Useful when | Mid-review, before later batches or follow-up turns | Across repeated reviews of similar workflows |

Checklist

• [ ] Workspace staged via Manifest (workspace-relative paths); long instructions in README.md/task.md, not the prompt.
• [ ] Stable document IDs + machine-readable manifest.csv so every finding is citable.
• [ ] Compaction trigger chosen: automatic Compaction() (default), StaticCompactionPolicy(threshold=...) (tighter control), or forced run_compaction({"force": True}) at phase boundaries.
• [ ] Instructions amended: on compaction, preserve current batch, cited facts, open questions, artifact paths, unresolved reviewer concerns.
• [ ] Forced-checkpoint path uses OpenAIResponsesCompactionSession over a SQLiteSession, with compaction_mode="input"; item counts compared via get_items() before and after.
• [ ] Cheaper dedicated compaction model configured if cost matters (source: gpt-5.4-mini under gpt-5.5).
• [ ] Memory(generate=MemoryGenerateConfig(extra_prompt=...)) steers memory to workflow lessons only; forbidden content named explicitly.
• [ ] Memory artifacts (memories/MEMORY.md, memories/memory_summary.md, sessions/) left to the SDK; outputs written under outputs/.
• [ ] Final artifact has executive summary, cited findings table, open questions, next steps — and is the only thing handed to reviewers.
• [ ] Incomplete evidence recorded as an open question, never guessed.
• [ ] Secrets injected as runtime configuration; mount scopes narrow; tracing disabled under ZDR.

Anti-patterns

• Treating memory as unreviewed fact storage. "Do not treat Memory() as an unreviewed fact database." Memory helps the next agent work better; it must not become a shadow database of conclusions. If a conclusion matters, write it into the reviewed memo with citations.
• Compacting away necessary working state. Setting thresholds or forcing checkpoints without ensuring cited facts, open questions, and artifact paths survive leaves only summarized impressions — the next turns can't recover.
• Mixing case-specific and workflow-generic memory. Without an explicit extra_prompt steer, memory generation absorbs case findings; keep it strictly on process lessons.
• Silently deleting narrowed assumptions. Superseded assumptions must stay visible in notes and the memo so reviewers can trace how conclusions evolved.
• Pasting large source content into prompts instead of materializing it in the workspace via the Manifest.
• Letting any component replace human review. Compacted history, memory files, and agent reasoning are all inputs; the cited, human-reviewed memo is the record.

Source

• Building Reliable Agents with Memory and Compaction — https://developers.openai.com/cookbook/examples/agentssdk/buildingreliableagentsmemory_compaction — 2026-05-01

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Archive228
• Source: Archive228/lab-skills
• License: MIT

Install and usage instructions live in the source repository linked above.