memories.md Codex Docs, 2026-03-31 06:35 UTC → 2026-05-01 18:29 UTC

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 

45Memory generation can also skip a background pass when your Codex rate-limit

46remaining percentage is below the configured threshold, so Codex doesn't spend

47quota when you're near a limit.

48 

49## Memory storage

50 

51Codex stores memories under your Codex home directory. By default, that's

52`~/.codex`. See [Config and state locations](https://developers.openai.com/codex/config-advanced#config-and-state-locations)

53for how Codex uses `CODEX_HOME`.

54 

55The main memory files live under `~/.codex/memories/` and include summaries,

56durable entries, recent inputs, and supporting evidence from prior threads.

57 

58Treat these files as generated state. You can inspect them when troubleshooting

59or before sharing your Codex home directory, but don't rely on editing them by

60hand as your primary control surface.

61 

62## Control memories per thread

63 

64In the Codex app and Codex TUI, use `/memories` to control memory behavior for

65the current thread. Thread-level choices let you decide whether the current

66thread can use existing memories and whether Codex can use the thread to

67generate future memories.

68 

69Thread-level choices don't change your global memory settings.

70 

71## Configuration

72 

73Enable memories in the Codex app settings, or set `memories = true` in the

74`[features]` section of `config.toml`.

75 

76For config file locations and the full list of memory-related settings, see the

77[configuration reference](https://developers.openai.com/codex/config-reference).

78 

79Common memory-specific settings include:

80 

81- `memories.generate_memories`: controls whether newly created threads can be

82 stored as memory-generation inputs.

83- `memories.use_memories`: controls whether Codex injects existing memories into

84 future sessions.

85- `memories.disable_on_external_context`: when `true`, keeps threads that used

86 external context such as MCP tool calls, web search, or tool search out of

87 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key

88 is still accepted as an alias.

89- `memories.min_rate_limit_remaining_percent`: controls the minimum remaining

90 Codex rate-limit percentage required before memory generation starts.

91- `memories.extract_model`: overrides the model used for per-thread memory

92 extraction.

93- `memories.consolidation_model`: overrides the model used for global memory

94 consolidation.

95 

96## Review memories

97 

98Don't store secrets in memories. Codex redacts secrets from generated memory

99fields, but you should still review memory files before sharing your Codex home

100directory or generated memory artifacts.