›_ Codex Issues
Codex Issues / #28866

codex resume can OOM on very large local session JSONL

Open 💬 4 comments Opened Jun 18, 2026 by jselvareef
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Codex CLI Issue: resume of very large local session needs excessive RAM/swap

Status: reported upstream after this run.

Summary

codex resume <session_id> can require an extremely large transient amount of
RAM/swap when the local session JSONL is very large. In this workstation, a
long-running production migration session caused the CLI process to be killed
by the OS unless roughly 80 GiB of swap was temporarily available. After the
session loads, memory usage stabilizes, which suggests the peak occurs during
resume/parsing/indexing rather than during normal interaction.

Environment

  • Codex CLI: codex-cli 0.139.0
  • OS: Linux workstation
  • Local Codex data size: 86G under ~/.codex
  • Largest local session files observed:
  • 37,776,204,485 bytes
  • 17,861,589,428 bytes
  • 17,657,202,793 bytes
  • 17,657,089,210 bytes

Actual Behavior

Resuming the long session creates a large transient memory spike. If the
machine does not have enough RAM/swap, the OS kills the Codex CLI process. The
user then needs to add a very large swap file only to resume the session.

Expected Behavior

  • Resume should stream or lazily index large session files instead of loading

enough data to create a large memory spike.

  • If the session is too large to resume safely, the CLI should fail early with

an actionable message.

  • The CLI should offer a supported way to compact, prune, archive, split, or

export a handoff from a large session before it becomes unresumable.

Reproduction Shape

  1. Work in a single Codex session for multiple days.
  2. Let the session JSONL grow to tens of GiB.
  3. Run codex resume <session_id> on a workstation without very large swap.
  4. Observe process termination by the OS during resume.

Current Workaround

For this repository, operational continuity is now moved into versioned runbooks
and control files so a new session can start from files instead of depending on
resuming a huge transcript. This avoids project risk, but it does not solve the
CLI resume behavior.

Requested Improvement

Add one or more of:

  • lazy/streaming resume for large local JSONL sessions;
  • a persistent session compaction or split command;
  • a size warning before resume;
  • a supported handoff export that lets users start a clean session without

losing the important operational context.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #28531
  • #28524
  • #27848
  • #27564

Powered by Codex Action

jselvareef · 2 months ago

I reviewed the duplicate candidates from the bot:

  • #28531: related to Desktop/image-heavy session JSONL and base64 payload externalization.
  • #28524 and #27848: Windows Desktop startup/session hydration memory regressions.
  • #27564: closest match, but it is Desktop/App thread selection with large rollout JSONL.

This report is specifically about the local CLI codex resume <session_id> path on Linux exhausting memory while hydrating a very large preserved session. The observed workaround is adding a very large swap file just for the initial resume spike; after hydration, memory stabilizes. That points to an unbounded eager load/materialization issue in the resume path, even without using the Desktop surface.

I am keeping this open unless maintainers prefer consolidating CLI resume memory behavior under one of the Desktop/session JSONL issues.

Necmttn · 2 months ago

A useful closeout test would separate "resume enough to continue" from "hydrate the whole JSONL into memory."

For very large rollouts, the resume path can build a lightweight index first: session_meta, compaction boundaries, latest user/assistant turns, tool-call ids, byte offsets, and token/count metadata. Large bodies such as base64 images, huge tool outputs, and old function outputs can stay as offset-addressed records until the UI/model actually needs them.

I would expect three behaviors:

  • early warning before trying to resume a file over a size threshold, with a suggested compact/export command;
  • bounded memory fixture against a synthetic huge JSONL that includes long lines and large payload fields;
  • a supported handoff/export path that preserves the latest task state and source pointers without copying every historical body into context.

That would also make this distinct from the Desktop image-heavy issues: the CLI resume invariant is "stream/index first, materialize bodies lazily."

---

_Generated with ax._

boombx403-byte · 9 days ago

Hi @jselvareef, that rollout size is valuable stress evidence. Codex Rescue Alpha5 scans large local session histories with bounded memory and produces aggregate size, media, and compaction diagnostics without loading the whole file into RAM or dumping full payloads.

If you still have an affected closed rollout, you can test it locally:

pip install codex-rescue==0.1.0a5
codex-rescue doctor <path-to-rollout.jsonl>

No raw session upload is needed; sanitized aggregate output is sufficient.