The Crosmos Codex plugin adds project memory to the OpenAI Codex CLI. It recalls relevant context before each prompt, saves session context through lifecycle hooks, and gives you a crosmos-save skill for explicit notes.
Use this plugin when you want Codex to remember project decisions, preferences, and prior work without manually calling memory tools. If you only need callable memory tools, use MCP instead.
Prerequisites
OpenAI Codex CLI
Node.js 18 or later
A Crosmos API key from the Crosmos Console
At least one Crosmos memory space
Keys use the csk_ prefix. The installer can save your key to ~/.crosmos/credentials.json, or you can set CROSMOS_API_KEY before installing.
Install npx @crosmos/codex install
The installer validates your API key, resolves a memory space, registers Codex hooks, copies the bundled plugin script, and installs the crosmos-save skill.
After installing, open Codex and run:
Review and approve the Crosmos hooks. Codex requires this trust step before non-managed hooks can run.
Run the package with npx. Do not install it globally, because its binary is named codex and a global install can shadow the OpenAI Codex CLI.
Verify npx @crosmos/codex status
The status command checks your API key, API base URL, hook registration, installed bundle, installed skill, and resolved memory space.
If recall or capture is not running after a successful install, run /hooks in Codex and confirm the hooks are approved.
How it works The plugin uses Codex lifecycle hooks and the Crosmos SDK. Memory failures do not block your Codex session.
Hook When it runs What it does UserPromptSubmitBefore each prompt Searches Crosmos and injects relevant memories as extra context. StopAt the end of a turn Captures new meaningful conversation turns. PreCompactBefore compaction Flushes pending conversation context before it can be lost.
The installed crosmos-save skill lets you ask Codex to save a specific note:
Remember that this repo uses Bun for package scripts.
Codex can then run the bundled save command with a concise note. Automatic capture still happens through hooks.
What gets installed Path Purpose ~/.codex/hooks.jsonRegisters the Crosmos Codex hooks. Existing hook entries are preserved. ~/.codex/crosmos/cli.mjsBundled plugin script that the hooks run. ~/.codex/skills/crosmos-save/SKILL.mdSkill instructions for explicit memory saves. ~/.crosmos/credentials.jsonLocal API credentials, saved only when you enter a key during install.
The installer backs up existing files before it changes them. It does not edit ~/.codex/config.toml.
Configuration Configure the plugin with environment variables or ~/.codex/crosmos.json. Environment variables override the config file.
Environment variable Purpose CROSMOS_API_KEYAPI key. Overrides saved credentials. CROSMOS_API_BASE_URLAPI base URL. Defaults to https://api.crosmos.dev. CROSMOS_SPACE_IDPin a memory space by UUID. CROSMOS_SPACE_NAMEResolve and pin a memory space by name. CROSMOS_RECALL_LIMITMaximum memories injected per prompt. Defaults to 5. CROSMOS_RECALL_MODERecall mode: auto, always, or off. Defaults to auto. CROSMOS_CAPTURE_TURNSMeaningful turns to batch before capture. Defaults to 3; set 0 to disable capture. CROSMOS_DEBUGWrite debug logs to /tmp/crosmos-codex-<session>.log.
Example config file:
{ "spaceName" : "engineering" , "baseUrl" : "https://api.crosmos.dev" , "recallLimit" : 5 , "recallMode" : "auto" , "captureTurns" : 3 , "debug" : false }
If neither spaceId nor spaceName is set, the plugin resolves the first available memory space and caches its ID in ~/.codex/crosmos.json.
Troubleshooting Hooks are not running Open Codex and run:
Review and approve the Crosmos hooks. If hooks are disabled in ~/.codex/config.toml, remove this setting:
Set CROSMOS_API_KEY or rerun the installer:
export CROSMOS_API_KEY = "csk_..." npx @crosmos/codex install
No memory space is available Create a memory space in the Crosmos Console , then rerun:
npx @crosmos/codex install
You can also pin a specific space with CROSMOS_SPACE_ID or CROSMOS_SPACE_NAME.
CODEX_HOME points somewhere elseBy default, the installer writes to ~/.codex. If CODEX_HOME is set, the installer stops before writing unless you pass --force.
npx @crosmos/codex install --force
Use --force only when you intentionally want to install into that Codex home.
Debug hook behavior Enable debug logging:
Logs are written to /tmp/crosmos-codex-<session>.log.
Uninstall npx @crosmos/codex uninstall
Uninstall removes the Crosmos hook entries, bundled script, skill directory, and ~/.codex/crosmos.json. Existing memories in Crosmos are preserved.
Next steps
MCP Connect Crosmos memory tools to AI clients.
Memory tools See the callable memory tool schemas.
