history.persistence
Not published in the reference (Codex saves history by default)Published Jul 15, 2026 · Verified against the official config docs
history.persistence decides whether Codex writes your session transcripts to history.jsonl. Two values: save-all keeps them, none turns local history off. The config reference doesn't publish a default, but Codex saves history out of the box, so none is the deliberate privacy switch. If your history vanished, this key plus the file at $CODEX_HOME/history.jsonl is the first thing to check.
history.persistence is the on/off switch for saving what you and Codex say to each other. When it’s on, every session’s transcript gets appended to history.jsonl. That file is what powers arrow-key recall of past prompts and, in newer builds, the conversation history search. Turn it off and none of that gets written to disk.
Values
| Value | What it does |
|---|---|
save-all |
Codex appends each session’s transcript to history.jsonl. |
none |
Codex stops writing to history.jsonl — nothing from the session persists there. |
The reference lists both values but doesn’t publish which one is the default. In practice Codex writes history.jsonl the moment you start using it, so save-all is the effective default and none is something you turn on deliberately.
When to change it
Set it to none when the machine is shared or regulated and you don’t want past prompts sitting in ~/.codex/history.jsonl for anyone with file access to read. Same call if you’re screen-recording a demo, or if your prompts routinely carry secrets you’d rather never touch disk. Leave it on save-all for normal solo work. You lose prompt recall and history search the second it’s off, and that’s most of the reason to have a history file at all.
Gotchas
none only governs history.jsonl. Full per-session transcripts still land under ~/.codex/sessions/YYYY/MM/DD/, which is a separate storage path with its own archiving lifecycle. So flipping this key is not a scrub of everything Codex writes locally.
History gone and you didn’t touch this? Check the key first, then confirm the file exists at $CODEX_HOME/history.jsonl (CODEX_HOME defaults to ~/.codex). A wrong CODEX_HOME points Codex at an empty directory, and the history looks lost when it’s just being read from the wrong place.
[history]
persistence = "save-all" # save-all | none
max_bytes = 5_242_880 # optional: cap the file, drops oldest entries firstRelated settings
history.max_bytes lives in the same table and caps how big history.jsonl gets before Codex drops the oldest entries. See history.max_bytes. Both keys read from CODEX_HOME, so if you relocate that env var, history and every other bit of Codex state move with it.