Best Practice: Memories

Codex CLI v0.119.0+ introduced memories — a per-user context system that learns from your threads and injects relevant notes into future sessions. Memories are scoped to your $CODEX_HOME (not per-project), opt-in per thread, and fully resettable.

← Back to Codex CLI Best Practice

Feature Flag

Memories are off by default. Enable in config.toml:

[features]
memories = true

Slash Command

In the TUI, open the memories settings view with /memories. Three controls:

Item	Effect
Use memories	Inject existing memories into new threads (applied at next thread)
Generate memories	Include current + future threads as memory-generation input
Reset all memories	Clear local memory files and summaries. Existing threads stay intact

Reset asks for confirmation and wipes both $CODEX_HOME/memories/ and $CODEX_HOME/memories_extensions/ — it does NOT touch the threads themselves.

A hidden CLI equivalent also exists for scripted environments:

codex debug clear-memories

Config Keys

Full [memories] table (all optional, shown with defaults):

[memories]
use_memories                       = true     # inject into future sessions
generate_memories                  = true     # record threads as generation input
consolidation_model                = "gpt-5.4"        # Phase 2 model
extract_model                      = "gpt-5.4-mini"   # Phase 1 model
max_raw_memories_for_consolidation = 256      # cap 4096
max_rollout_age_days               = 30       # clamp 0..=90
max_rollouts_per_startup           = 16       # cap 128
max_unused_days                    = 30       # drives memory-extension cleanup (0..=365)
min_rollout_idle_hours             = 6        # clamp 1..=48
no_memories_if_mcp_or_web_search   = false    # privacy guard

The pair use_memories + generate_memories replaces a single mode enum — a "use-only" client sets generate_memories = false and still benefits from previously-generated memories.

Per-Thread Override

Each thread carries a memory_mode column in the state DB ("enabled" or "disabled"). Toggled from the TUI settings view or programmatically via the app-server RPC thread/memoryMode/set.

Memory Extensions

An extension is a plug-in that contributes both persistent instructions and transient per-run evidence. On disk:

$CODEX_HOME/memories_extensions/
└── <extension_name>/
    ├── instructions.md              # always loaded if present
    └── resources/
        └── 2026-04-18T14-32-05-notes.md   # per-run artifact, auto-pruned

Cleanup runs during Phase 2 consolidation: resource files older than 7 days are deleted automatically. A full reset wipes the entire memories_extensions/ tree.

Scope Summary

Scope	Location	Notes
Per-thread	state DB threads.memory_mode	/memories toggles or RPC
Per-user (global)	$CODEX_HOME/memories/	Consolidated raw + summaries
Project	(not supported)	Memories do not scope to a project directory

Memory pipeline only runs for root sessions that are: non-ephemeral, feature- enabled, not a sub-agent, and with state DB available.

Good Habits

• Enable memories once, then forget about them — the consolidation pipeline runs in the background between sessions, not mid-turn.
• Keep no_memories_if_mcp_or_web_search = true for threads that touch secrets or untrusted content.
• Treat memories as ambient background context, not a structured knowledge base — if you need durable project facts, put them in AGENTS.md.
• Reset memories if you switch roles or change working domains meaningfully — stale memories hurt more than they help.
• For CI / throwaway workflows, set [features] memories = false or use a separate CODEX_HOME.

Anti-Patterns

Anti-Pattern	Fix
Using [memory] (singular) in config	The table is [memories] (plural)
Expecting memories to scope per project	Memories live under $CODEX_HOME — use AGENTS.md for project context
Storing secrets and expecting cleanup	Use no_memories_if_mcp_or_web_search = true and reset on exposure
Hand-editing $CODEX_HOME/memories/*.md	Reset via /memories — the pipeline owns these files
Editing memory extension resources manually	They're transient — cleanup runs them off every 7 days