memories/chronicle.md +192 −0 added
1# Chronicle
2
3Chronicle is in an **opt-in research preview**. It is only available for
4 ChatGPT Pro subscribers on macOS, and is not yet available in the EU, UK and
5 Switzerland. Please review the [Privacy and Security](#privacy-and-security)
6 section for details and to understand the current risks before enabling.
7
8Chronicle augments Codex memories with context from your screen. When you prompt
9Codex, those memories can help it understand what you’ve been working on with
10less need for you to restate context.
11
12Chronicle is available as an opt-in research preview in the Codex app on macOS.
13It requires macOS Screen Recording and Accessibility permissions. Before
14enabling, be aware that Chronicle uses rate limits quickly, increases risk of
15prompt injection, and stores memories unencrypted on your device.
16
17## How Chronicle helps
18
19We’ve designed Chronicle to reduce the amount of context you have to restate
20when you work with Codex. By using recent screen context to improve memory
21building, Chronicle can help Codex understand what you’re referring to, identify
22the right source to use, and pick up on the tools and workflows you rely on.
23
24<section class="feature-grid mt-4">
25
26<div>
27
28### Use what’s on screen
29
30With Chronicle Codex can understand what you are currently looking at, saving
31you time and context switching.
32
33</div>
34
35<ChronicleThreadDemo client:load scenario="screen" />
36
37</section>
38
39<section class="feature-grid inverse">
40
41<div>
42
43### Fill in missing context
44
45No need to carefully craft your context and start from zero. Chronicle lets
46Codex fill in the gaps in your context.
47
48</div>
49
50<ChronicleThreadDemo client:load scenario="project" />
51
52</section>
53
54<section class="feature-grid">
55
56<div>
57
58### Remember tools and workflows
59
60No need to explain to Codex which tools to use to perform your work. Codex
61learns as you work to save you time in the long run.
62
63</div>
64
65<ChronicleThreadDemo client:load scenario="tools" />
66
67</section>
68
69In these cases, Codex uses Chronicle to provide additional context. When another
70source is better for the job, such as reading the specific file, Slack thread,
71Google Doc, dashboard, or pull request, Codex uses Chronicle to identify the
72source and then use that source directly.
73
74## Enable Chronicle
75
761. Open Settings in the Codex app.
772. Go to **Personalization** and make sure **Memories** is enabled.
783. Turn on **Chronicle** below the Memories setting.
794. Review the consent dialog and choose **Continue**.
805. Grant macOS Screen Recording and Accessibility permissions when prompted.
816. When setup completes, choose **Try it out** or start a new thread.
82
83If macOS reports that Screen Recording or Accessibility permission is denied,
84open System Settings > Privacy & Security > Screen Recording or
85Accessibility and enable Codex. If a permission is restricted by macOS or your
86organization, Chronicle will start after the restriction is removed and Codex
87receives the required permission.
88
89## Pause or disable Chronicle at any time
90
91You control when Chronicle generates memories using screen context. Use the
92Codex menu bar icon to choose **Pause Chronicle** or **Resume Chronicle**. Pause
93Chronicle before meetings or when viewing sensitive content that you do not want
94Codex to use as context. To disable Chronicle, return to **Settings >
95Personalization > Memories** and turn off **Chronicle**.
96
97You can also control whether memories are used in a given thread. [Learn
98more](https://developers.openai.com/codex/memories#control-memories-per-thread).
99
100## Rate limits
101
102Chronicle works by running sandboxed agents in the background to generate
103memories from captured screen images. These agents currently consume rate limits
104quickly.
105
106## Privacy and security
107
108Chronicle uses screen captures, which can include sensitive information visible
109on your screen. It does not have access to your microphone or system audio.
110Don’t use Chronicle to record meetings or communications with others without
111their consent. Pause Chronicle when viewing content you do not want remembered
112in memories.
113
114### Where does Chronicle store my data?
115
116Screen captures are ephemeral and will only be saved temporarily on your
117computer. Temporary screen capture files may appear under
118`$TMPDIR/chronicle/screen_recording/` while Chronicle is running. Screen captures
119that are older than 6 hours will be deleted while Chronicle is running.
120
121The memories that Chronicle generates are just like other Codex memories:
122unencrypted markdown files that you can read and modify if needed. You can also
123ask Codex to search them. If you want to have Codex forget something you can
124delete the respective file inside the folder or selectively edit the markdown
125files to remove the information you’d like to remove. You should not manually
126add new information. The generated Chronicle memories are stored locally on your
127computer under `$CODEX_HOME/memories_extensions/chronicle/` (typically
128`~/.codex/memories_extensions/chronicle`).
129
130<div className="not-prose my-4">
131 <Alert
132 client:load
133 color="danger"
134 variant="soft"
135 description="Both directories for your screen captures and memories might contain sensitive information. Make sure you do not share content with others, and be aware that other programs on your computer can also access these files."
136 />
137</div>
138
139### What data gets shared with OpenAI?
140
141Chronicle captures screen context locally, then periodically uses Codex to
142summarize recent activity into memories. To generate those memories, Chronicle
143starts an ephemeral Codex session with access to this screen context. That
144session may process selected screenshot frames, OCR text extracted from
145screenshots, timing information, and local file paths for the relevant time
146window.
147
148Screen captures used for memory generation are stored temporarily on your device. They are processed on our
149servers to generate memories, which are then stored locally on device. We do not
150store the screenshots on our servers after processing unless required by law,
151and do not use them for training.
152
153The generated memories are Markdown files stored locally under
154`$CODEX_HOME/memories_extensions/chronicle/`. When Codex uses memories in a
155future session, relevant memory contents may be included as context for that
156session, and may be used to improve our models if allowed in your ChatGPT
157settings. [Learn more](https://help.openai.com/en/articles/7730893-data-controls-faq).
158
159## Prompt injection risk
160
161Using Chronicle increases risk to prompt injection attacks from screen content.
162For instance, if you browse a site with malicious agent instructions, Codex may
163follow those instructions.
164
165## Troubleshooting
166
167### How do I enable Chronicle?
168
169If you do not see the Chronicle setting, make sure you are using a Codex app
170build that includes Chronicle and that you have Memories enabled inside Settings
171> Personalization.
172
173Chronicle is currently only available for ChatGPT Pro subscribers on macOS.
174Chronicle is not available in the EU, UK and Switzerland.
175
176If setup does not complete:
177
1781. Confirm that Codex has Screen Recording and Accessibility permissions.
1792. Quit and reopen the Codex app.
1803. Open **Settings > Personalization** and check the Chronicle status.
181
182### Which model is used for generating the Chronicle memories?
183
184Chronicle uses the same model as your other [Memories](https://developers.openai.com/codex/memories). If you
185did not configure a specific model it uses your default Codex model. To choose a
186specific model, update the `consolidation_model` in your
187[configuration](https://developers.openai.com/codex/config-basic).
188
189```toml
190[memories]
191consolidation_model = "gpt-5.4-mini"
192```