memories.md +87 −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## Enable memories
18
19In the Codex app, enable Memories in settings.
20
21For config-based setup, add the feature flag to `config.toml`:
22
23```toml
24[features]
25memories = true
26```
27
28See [Config basics](https://developers.openai.com/codex/config-basic) for where Codex stores user-level
29configuration and how Codex loads `~/.codex/config.toml`.
30
31## How memories work
32
33After you enable memories, Codex can turn useful context from eligible prior
34threads into local memory files. Codex skips active or short-lived sessions,
35redacts secrets from generated memory fields, and updates memories in the
36background instead of immediately at the end of every thread.
37
38Memories may not update right away when a thread ends. Codex waits until a
39thread has been idle long enough to avoid summarizing work that's still in
40progress.
41
42## Memory storage
43
44Codex stores memories under your Codex home directory. By default, that's
45`~/.codex`. See [Config and state locations](https://developers.openai.com/codex/config-advanced#config-and-state-locations)
46for how Codex uses `CODEX_HOME`.
47
48The main memory files live under `~/.codex/memories/` and include summaries,
49durable entries, recent inputs, and supporting evidence from prior threads.
50
51Treat these files as generated state. You can inspect them when troubleshooting
52or before sharing your Codex home directory, but don't rely on editing them by
53hand as your primary control surface.
54
55## Control memories per thread
56
57In the Codex app and Codex TUI, use `/memories` to control memory behavior for
58the current thread. Thread-level choices let you decide whether the current
59thread can use existing memories and whether Codex can use the thread to
60generate future memories.
61
62Thread-level choices don't change your global memory settings.
63
64## Configuration
65
66Enable memories in the Codex app settings, or set `memories = true` in the
67`[features]` section of `config.toml`.
68
69For config file locations and the full list of memory-related settings, see the
70[configuration reference](https://developers.openai.com/codex/config-reference).
71
72Common memory-specific settings include:
73
74- `memories.generate_memories`: controls whether newly created threads can be
75 stored as memory-generation inputs.
76- `memories.use_memories`: controls whether Codex injects existing memories into
77 future sessions.
78- `memories.extract_model`: overrides the model used for per-thread memory
79 extraction.
80- `memories.consolidation_model`: overrides the model used for global memory
81 consolidation.
82
83## Review memories
84
85Don't store secrets in memories. Codex redacts secrets from generated memory
86fields, but you should still review memory files before sharing your Codex home
87directory or generated memory artifacts.