memories.md +94 −0 added
1# Memories
2
3Memories are off by default and aren't available in the European Economic
4 Area, the United Kingdom, or Switzerland at launch. Enable them in Codex
5 settings, or set `memories = true` in the `[features]` table in
6 `~/.codex/config.toml`.
7
8Memories let Codex carry useful context from earlier threads into future work.
9After you enable memories, Codex can remember stable preferences, recurring
10workflows, tech stacks, project conventions, and known pitfalls so you don't
11need to repeat the same context in every thread.
12
13Keep required team guidance in `AGENTS.md` or checked-in documentation. Treat
14memories as a helpful local recall layer, not as the only source for rules that
15must always apply.
16
17[Chronicle](https://developers.openai.com/codex/memories/chronicle) helps Codex recover recent working
18context from your screen to build up memory.
19
20## Enable memories
21
22In the Codex app, enable Memories in settings.
23
24For config-based setup, add the feature flag to `config.toml`:
25
26```toml
27[features]
28memories = true
29```
30
31See [Config basics](https://developers.openai.com/codex/config-basic) for where Codex stores user-level
32configuration and how Codex loads `~/.codex/config.toml`.
33
34## How memories work
35
36After you enable memories, Codex can turn useful context from eligible prior
37threads into local memory files. Codex skips active or short-lived sessions,
38redacts secrets from generated memory fields, and updates memories in the
39background instead of immediately at the end of every thread.
40
41Memories may not update right away when a thread ends. Codex waits until a
42thread has been idle long enough to avoid summarizing work that's still in
43progress.
44
45## Memory storage
46
47Codex stores memories under your Codex home directory. By default, that's
48`~/.codex`. See [Config and state locations](https://developers.openai.com/codex/config-advanced#config-and-state-locations)
49for how Codex uses `CODEX_HOME`.
50
51The main memory files live under `~/.codex/memories/` and include summaries,
52durable entries, recent inputs, and supporting evidence from prior threads.
53
54Treat these files as generated state. You can inspect them when troubleshooting
55or before sharing your Codex home directory, but don't rely on editing them by
56hand as your primary control surface.
57
58## Control memories per thread
59
60In the Codex app and Codex TUI, use `/memories` to control memory behavior for
61the current thread. Thread-level choices let you decide whether the current
62thread can use existing memories and whether Codex can use the thread to
63generate future memories.
64
65Thread-level choices don't change your global memory settings.
66
67## Configuration
68
69Enable memories in the Codex app settings, or set `memories = true` in the
70`[features]` section of `config.toml`.
71
72For config file locations and the full list of memory-related settings, see the
73[configuration reference](https://developers.openai.com/codex/config-reference).
74
75Common memory-specific settings include:
76
77- `memories.generate_memories`: controls whether newly created threads can be
78 stored as memory-generation inputs.
79- `memories.use_memories`: controls whether Codex injects existing memories into
80 future sessions.
81- `memories.disable_on_external_context`: when `true`, keeps threads that used
82 external context such as MCP tool calls, web search, or tool search out of
83 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key
84 is still accepted as an alias.
85- `memories.extract_model`: overrides the model used for per-thread memory
86 extraction.
87- `memories.consolidation_model`: overrides the model used for global memory
88 consolidation.
89
90## Review memories
91
92Don't store secrets in memories. Codex redacts secrets from generated memory
93fields, but you should still review memory files before sharing your Codex home
94directory or generated memory artifacts.