Documentation

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:

/hooks

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
`UserPromptSubmit`	Before each prompt	Searches Crosmos and injects relevant memories as extra context.
`Stop`	At the end of a turn	Captures new meaningful conversation turns.
`PreCompact`	Before 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.json`	Registers the Crosmos Codex hooks. Existing hook entries are preserved.
`~/.codex/crosmos/cli.mjs`	Bundled plugin script that the hooks run.
`~/.codex/skills/crosmos-save/SKILL.md`	Skill instructions for explicit memory saves.
`~/.crosmos/credentials.json`	Local 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_KEY`	API key. Overrides saved credentials.
`CROSMOS_API_BASE_URL`	API base URL. Defaults to `https://api.crosmos.dev`.
`CROSMOS_SPACE_ID`	Pin a memory space by UUID.
`CROSMOS_SPACE_NAME`	Resolve and pin a memory space by name.
`CROSMOS_RECALL_LIMIT`	Maximum memories injected per prompt. Defaults to `5`.
`CROSMOS_RECALL_MODE`	Recall mode: `auto`, `always`, or `off`. Defaults to `auto`.
`CROSMOS_CAPTURE_TURNS`	Meaningful turns to batch before capture. Defaults to `3`; set `0` to disable capture.
`CROSMOS_DEBUG`	Write 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:

/hooks

Review and approve the Crosmos hooks. If hooks are disabled in ~/.codex/config.toml, remove this setting:

[features]
hooks = false

No API key is configured

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 else

By 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:

export CROSMOS_DEBUG=1

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.

Agent Plugins

Codex

Prerequisites

Install

Verify

How it works

What gets installed

Configuration

Troubleshooting

Hooks are not running

No API key is configured

No memory space is available

`CODEX_HOME` points somewhere else

Debug hook behavior

Uninstall

Next steps

MCP

Memory tools

​Prerequisites

​Install

​Verify

​How it works

​What gets installed

​Configuration

​Troubleshooting

​Hooks are not running

​No API key is configured

​No memory space is available

​CODEX_HOME points somewhere else

​Debug hook behavior

​Uninstall

​Next steps

MCP

Memory tools

Prerequisites

Install

Verify

How it works

What gets installed

Configuration

Troubleshooting

Hooks are not running

No API key is configured

No memory space is available

`CODEX_HOME` points somewhere else

Debug hook behavior

Uninstall

Next steps