Skip to content

codex-memory.md

Latest commit

 

History

History
120 lines (92 loc) · 4.5 KB

codex-memory.md

File metadata and controls

120 lines (92 loc) · 4.5 KB
Raw

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 Codex

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