Harness Notes

Codex has built-in local memories, off by default. Turn them on with [features] memories = true in ~/.codex/config.toml, codex features enable memories, or by typing /memories in the TUI and choosing "Yes, enable" (applies to new threads). Once enabled, memories.use_memories = false stops injecting memories and memories.generate_memories = false stops new threads from becoming memory inputs; codex features disable memories turns the whole feature off.

The feature is marked stable but still defaults to off; the old key memory_tool is accepted as an alias.

Admins can force it on or off for managed users with features.memories in requirements.toml.

In the ChatGPT desktop app the switch is Settings > Personalization > Enable Codex memories.

Auto memory is on by default in local sessions. Toggle it in a session with /memory (writes autoMemoryEnabled to ~/.claude/settings.json), set "autoMemoryEnabled": false in any settings file (user, project, local or managed) to turn it off, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 for a session (=0 forces it on even over autoMemoryEnabled: false or --bare).

--bare (CLAUDE_CODE_SIMPLE=1) and --safe-mode start without auto memory.

Sessions in a self-hosted environment have auto memory off by default.

From a background session, or a claude started by another Claude Code session, /memory can turn auto memory off but not back on.

A background job writes memories, not the chat you're in. Each time you start a turn in an interactive root session, Codex looks at your other threads that have been idle for at least 6 hours and are at most 10 days old. It summarizes up to 2 of them per pass with a low-effort model. At most every 6 hours, a sandboxed consolidation agent with no network access merges those summaries into the memory files. The agent in your chat only adds a note when you explicitly ask it to.

Only CLI/TUI, IDE extension and ChatGPT desktop threads feed memories. codex exec runs, ephemeral sessions and subagent threads do not.

Generation is skipped while less than 25% of your Codex rate limit remains (memories.min_rate_limit_remaining_percent). New memories can therefore take hours or days to appear.

Tunable with memories.min_rollout_idle_hours (1-48), memories.max_rollout_age_days (0-90), memories.max_rollouts_per_startup (1-128), memories.extract_model and memories.consolidation_model.

Set memories.disable_on_external_context = true to keep threads that used MCP tools, web search or tool search out of memory generation.

Secrets are redacted from the generated memory fields.

Claude itself writes memories during the session, when it judges something will be useful later: your role and preferences (user), corrections and confirmed approaches (feedback), ongoing work and decisions not visible in the code (project), and pointers to outside resources (reference). It skips anything derivable from the codebase or already in CLAUDE.md, and doesn't save something every session; you see a "Saved N memories" notice when it does.

Each memory file's frontmatter records its kind in a type field, and Claude Code stamps a modified ISO 8601 timestamp on every write (v2.1.214+) so stale facts are visible.

Memories are stored under $CODEX_HOME/memories (default ~/.codex/memories). Setting memories.version = "v2" uses ~/.codex/memories_v2 instead. There is one global store per Codex home, shared by every project, repo and worktree on that machine. The index of memory files is kept in the local state database.

Files include memory_summary.md, MEMORY.md, raw_memories.md, rollout_summaries/, skills/ and extensions/. The folder is also a local git repository that Codex uses to track changes between consolidation runs.

Memories live in ~/.claude/projects/<project>/memory/ (under $CLAUDE_CONFIG_DIR/projects/ if you set that): a MEMORY.md index plus one markdown file per memory. <project> comes from the git repository, so all worktrees and subdirectories of one repo share a single memory directory; outside git the project root is used. Set autoMemoryDirectory (absolute or ~/ path, any settings scope) to store it elsewhere.

An autoMemoryDirectory from a repo's .claude/settings.json only takes effect after workspace trust, and is ignored entirely while permissions.blockReadsOutsideWorkingDirectories is on.

With CLAUDE_CODE_PROJECT_DIR_NAME set beside CLAUDE_CONFIG_DIR (v2.1.234+), every project launched with that config dir shares one memory directory.

Memory files are excluded from the cleanupPeriodDays transcript cleanup and stay until edited or deleted.

At the start of each thread, Codex injects memory_summary.md as developer instructions, truncated to 2,500 tokens, together with guidance on how to use the memory folder. MEMORY.md (the searchable index), rollout_summaries/ and memory skills/ are not loaded. The agent searches or opens them on demand when a task looks related, usually in 4-6 search steps or fewer. A change to use_memories takes effect from the next thread.

When the agent uses a memory file, its reply ends with a memory citation block.

memories.dedicated_tools = true (off by default) gives the agent dedicated memory list/search/read/add_ad_hoc_note tools, instead of having it read the files with shell commands.

At the start of every session Claude Code loads the first 200 lines or first 25KB of MEMORY.md, whichever comes first; anything past that is dropped. Topic files are not loaded at startup; Claude reads them on demand with its file tools (shown as "Recalled N memories").

When a write leaves MEMORY.md near or over the limit, Claude Code tells Claude to compact the index (one line per entry, details in topic files).

Recalled memories come with a note on how old they are.

Partly

There's no memory browser. To see what Codex remembers, open the Markdown files in ~/.codex/memories (start with memory_summary.md and MEMORY.md). /memories in the TUI only toggles "Use memories" and "Generate memories" and offers "Reset all memories". OpenAI calls these files generated state: you can read them, but don't edit them by hand to control behaviour, because the next consolidation rewrites them.

In 0.162.1 the /memories toggles are written to config.toml as memories.use_memories and memories.generate_memories, so they apply globally rather than per chat. The 'Generate' toggle also updates the current thread.

Run /memory and choose the auto memory folder to open it; the same dialog lists your CLAUDE.md files and has the auto memory toggle. Memories are plain markdown in ~/.claude/projects/<project>/memory/, so you can also open and edit them in any editor. In the VS Code extension, the Memory dialog lets you view, edit and delete saved memories.

Partly

Ask the agent directly, for example "remember that we deploy with make ship". When you explicitly ask, it writes a small note to ~/.codex/memories/extensions/ad_hoc/notes/<timestamp>-<slug>.md. The next background consolidation merges the note into the memory files, so it is not available immediately. Rules that must always apply belong in AGENTS.md instead.

Notes are treated as information only, never as instructions, and remembered facts are tagged "[ad-hoc note]".

Ask in plain language, e.g. "remember that the API tests require a local Redis instance" or "always use pnpm, not npm", and Claude saves it to auto memory. To make it a standing instruction instead, say "add this to CLAUDE.md" or edit CLAUDE.md via /memory.

To correct or remove one fact, ask the agent to forget or update it. It records your request as an ad-hoc note, and the next consolidation applies it. To wipe everything, run /memories > Reset all memories in the TUI, or the hidden codex debug clear-memories command. Both delete the memory folders under ~/.codex and the memory records in the local state database, but leave your threads untouched.

Memories that haven't been used for 30 days drop out of consolidation (memories.max_unused_days).

The ChatGPT desktop app offers the same wipe as Settings > Personalization > Delete Codex memories.

Edit or delete the markdown files (and their line in MEMORY.md) through /memory or any editor, or ask Claude to update or remove a memory. To wipe a project's memory, delete its ~/.claude/projects/<project>/memory/ directory; there is no dedicated reset command.

Not supported

No. Memories stay local to one machine's Codex home and don't sync, and there's no project-level memory file to commit. Put shared team knowledge in AGENTS.md or checked-in docs, which the official docs recommend.

The IDE extension uses the memory store of the Codex host it is connected to.

Review the memory files before you share your ~/.codex directory.

Partly

The main auto memory is machine-local: it is shared across worktrees of one repo but not across machines or cloud environments, and it lives outside the repo. To share, put the facts in a checked-in CLAUDE.md, or point autoMemoryDirectory at a synced folder yourself. Subagent memory with memory: project lives in .claude/agent-memory/ and is meant to be committed.

Remote sessions can also recall from mounted team memory stores (CLAUDE_MEMORY_STORES), which are set up outside the CLI.

Partly

Subagents have no memory of their own. They inherit the parent's config, so they read the same global memory summary, but their threads never feed memory generation. A custom agent role can turn memory off for itself with [features] memories = false in its role config file.

Yes. Add memory: user, memory: project or memory: local to a subagent's frontmatter to give it its own memory directory (~/.claude/agent-memory/<agent>/, .claude/agent-memory/<agent>/, or .claude/agent-memory-local/<agent>/); it loads the first 200 lines/25KB of its own MEMORY.md and gets Read/Write/Edit to maintain it. Subagents never see the main conversation's auto memory (forks excepted), and the field does nothing when auto memory is turned off.

project is the recommended scope; local keeps it out of version control.