# Memory Compaction

> Operating procedure for keeping a long-running agent coherent using the OpenAI Agents SDK memory and compaction primitives: three ways to trigger compaction (automatic, threshold-based, forced checkpoint), exact rules for what working state to preserve through a compaction, and what belongs in cross-run memory versus the reviewed output artifact. Trigger when building or operating an agent whose…

- **Type:** Skill
- **Install:** `agentstack add skill-archive228-lab-skills-memory-compaction`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Archive228](https://agentstack.voostack.com/s/archive228)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Archive228](https://github.com/Archive228)
- **Source:** https://github.com/Archive228/lab-skills/tree/main/skills/memory-compaction

## Install

```sh
agentstack add skill-archive228-lab-skills-memory-compaction
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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`.

7. **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.

8. **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/`.

9. **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.

10. **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.

11. **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/agents_sdk/building_reliable_agents_memory_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](https://github.com/Archive228)
- **Source:** [Archive228/lab-skills](https://github.com/Archive228/lab-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-archive228-lab-skills-memory-compaction
- Seller: https://agentstack.voostack.com/s/archive228
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.