Desktop companion / Setup guide
Keep the progress.
Skip the reconstruction.
Set up session memory once per project. Keep working in Codex or Claude Code, then review the useful notes before adding them to your project record.
01 / Before you start
Your project stays yours.
Already working on a project?
Use the same connected project and folder. You do not need to recreate it, reconnect it, or rewrite its context files. Existing projects still need capture enabled and each tool set up once. Your personal profile and working preferences stay as they are.
- Update the desktop companion to 0.7.15 or later. Open Settings → App updates → Check for updates, then follow the download and installer prompts.
- Confirm your token is valid in Settings → Cloud connection and the project is connected to Context OS.
- For organization projects, confirm project access and an approved Sync ID/local-sync grant. Organization membership alone is not enough.
Capture is off by default. The guide below enables it for one project on this device.
02 / One-time setup
Connect the project and the tool.
Open the project
In the desktop companion, choose Projects, select your connected project, and expand Session memory in its details.
Choose what to capture
Open Capture & privacy. Check Capture outcomes on this device, choose 7, 30, or 90 days of retention, and add sensitive filenames, paths, or phrases to exclusions. Choose Save privacy settings.
Set up each tool you use
Choose Set up Codex, Set up Claude Code, or both. This adds project-local hooks—the small integrations that capture supported events—and backs up existing configuration.
Review and trust the Codex hooks
Open Codex CLI in the exact Local folder shown for this project in the companion. Run
/hooks, then review and trust the Context OS SessionStart, PostToolUse, and Stop hooks. Trust the project when prompted. Only approve definitions you recognize; unrelated hooks do not need to be enabled.Restart in the connected folder
After trusting the hooks, exit Codex and start a fresh session in that same folder. A nested repository or different working directory is not the connected root. Keep machine-specific hook configuration out of shared commits. For Claude Code, restart in the connected folder and follow that tool’s permission prompts.
Already enabled memory on 0.7.14?
Update and restart the companion, then choose Set up Codex again for each connected project. In Codex CLI, open /hooks and review and trust the changed SessionStart hook. Restart Codex once more. Your captured notes stay in place; you do not need to recreate the project or clear its memory.
Repeat these steps for each project and device where you want capture. Installing an MCP connection alone does not enable automatic capture.
03 / Test capture and recall
Check both halves of memory.
This walkthrough was verified with Codex CLI on macOS using desktop companion 0.7.15. Keep the companion connected. Use a fresh test label if you repeat the test: replace 002 in both prompts with a new number.
Create a harmless test outcome
In Codex CLI, send only this prompt:
This is a Context OS session-memory test. Do not change files or run commands. Reply exactly: CONTEXTOS-MEMORY-CHECK-002 — read-only capture test completed.Wait for the response to finish.
Confirm that it was captured
Return to the companion’s Session memory panel and choose Refresh. Confirm that Capture is on, Last capture has a recent time, and a Captured locally note contains the full test response. Do not save this test to your project foundations.
Start a fresh Codex session
Exit Codex and launch it again in the exact connected project folder. Start a new conversation; do not resume the test conversation or paste its answer into the new session. This separates startup memory from ordinary chat history.
Ask for startup recall only
Send only this prompt in the fresh session:
Using only the context supplied at startup, find the captured outcome containing CONTEXTOS-MEMORY-CHECK-002 and quote its full text. Do not use tools, search files, or infer the result. If it was not supplied, say “Not present in startup context.”A pass is the full response below, recalled without tools or file searches:
CONTEXTOS-MEMORY-CHECK-002 — read-only capture test completed.
Refresh the companion again. Look for a recent Startup brief time and Included in startup brief on the observation. These confirm delivery; the tool’s correct answer checks recall.
A preview is not a recall test.
Preview startup lets you inspect the brief, but does not mark it delivered. A captured note proves capture only. If Codex searches files, uses tools, or sees the original answer in the conversation, repeat the recall test in a fresh session.
After the test, work normally. Supported hooks capture the tool’s final response and safe filenames from supported edit events. These are agent-reported notes, not independently verified facts. Old conversations are not imported, and full transcripts, source contents, shell commands, and tool output are not collected. You may delete the test observations from the companion when finished.
04 / Review and save
Turn useful notes into lasting context.
- Select the observations you want to keep.
- Choose Latest handoff, Current state, Decisions, or Notes, then choose Review foundation update.
- Edit the draft into accurate, durable context. Existing document content is included; remove duplicates, unsupported claims, and details that should stay private.
- Choose Save reviewed update. Your project’s existing permissions, revision checks, and approval policy still apply.
- Captured locally
- A private observation on this device. It has not been saved to the project.
- Awaiting project review
- Open the project in the website for the required approval. Then choose Check review status in the companion.
- Saved to project
- The reviewed update is in the project record and available to authorized tools.
If the project revision changed, refresh and prepare a new draft. If a submission’s network result is unknown, use Resume submission to retry the original request.
05 / Your controls
Keep only what helps.
- Pause: uncheck Capture outcomes on this device and save privacy settings. You can also remove either tool’s hooks.
- Exclude: enter one sensitive filename, path, or phrase per line. Matching ignores capitalization and uses text substrings, not wildcard patterns.
- Delete: delete an individual observation, or use Delete private memory → Delete all local observations. Saved project documents and the tool’s own transcripts are unaffected.
Raw observations stay encrypted in companion app data on this device, with the key held in the operating system’s credential store. They are not automatically shared with teammates or other devices. Access is rechecked; offline or revoked access can lock memory reads.
Secret filtering is best effort. Review notes before sharing them. Retention and new exclusions are applied when memory is accessed or updated, not while the app is closed.
06 / Help
A clearer next step.
I cannot find Session memory.
Check that the desktop companion is version 0.7.15 or later. Open a connected project’s details in the desktop app, not the website’s project editor. Confirm that you updated the intended UAT or production app.
Capture is enabled, but no notes appear.
Save privacy settings, set up the tool for this project, restart it in the exact connected folder, and approve its hook-trust prompt. Complete a new turn, then choose Refresh. Check exclusions and any failure message in Session memory. Earlier conversations and events without a supported hook are not captured.
The note was captured, but Codex cannot recall it.
Confirm that you updated and restarted the intended companion app (0.7.15 or later). Run Set up Codex again, review the changed SessionStart hook in /hooks, and restart Codex in the exact connected root. Confirm capture remains on, the note has not expired or been excluded, and the project still has access. Repeat the test with a fresh label. Keep the hook’s error message if it still fails; do not treat “Not present in startup context” as a pass.
Where do I trust hooks?
In Codex CLI, enter /hooks. Review the Context OS entries and trust the new or changed definitions. An update can require trust again even if you approved the previous version. Restart after trusting the startup hook. This guide’s verified walkthrough uses the CLI; installing a ChatGPT or Codex MCP connection alone does not complete these steps.
Memory is locked or the startup brief is unavailable.
Check your internet connection and cloud token, project access, and—where required—device/local-sync approval. The companion reports unavailable when authorization fails or mandatory guidance cannot fit; it does not substitute a stale brief. Pause and local deletion remain available.
Can I use search without enabling capture?
Yes. Compatible, authorized MCP clients can search current project documents and request startup briefs without local capture. Automatic delivery at tool startup still needs the native integration. Read-only access does not grant permission to update documents.
Connect an MCP toolDoes it work with Windows or other AI tools?
This release provides native capture setup for Codex and Claude Code through macOS/Linux shells. Native Windows hook setup is not enabled. Other compatible MCP clients can use the authorized search and startup-brief tools; they do not automatically capture sessions through this integration.
Do I need a separate Local companion download?
No separate download is needed for this desktop setup. Use the Desktop companion. The standalone Local companion download is disabled on the website.