docs/images/agents/en/codex.md
Add persistent, cross-session memory to Codex. Install it once, and the plugin will automatically recall memories before every user prompt, capture updates after each turn, and commit changes before compaction. It also connects Codex to OpenViking's /mcp endpoint, allowing the model to directly invoke tools like search and store.
Source: examples/codex-memory-plugin | Blog: motivation and demo
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/codex-memory-plugin/tos-install.sh)
The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Each step is idempotent, meaning it is safe to rerun the script at any time.
After installation, activate the codex wrapper in your current terminal (or simply open a new terminal window):
source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
codex # approve hooks once via /hooks on first launch
<details> <summary><b>Manual installation</b></summary>Launch Codex through a custom command? A wrapper script like
codex-custom, or a multi-word launcher (a base command plus a sub-command) — list it at the installer's "Extra launch commands" step (or passOPENVIKING_CODEX_WRAP_EXTRA='codex-custom') to inject credentials there too.
Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the codex_hooks feature enabled.
Shell function wrapper - Append a codex() function to your shell configuration file (e.g., .bashrc or .zshrc). Each invocation injects OpenViking environment variables from ovcli.conf. Refer to the plugin README for the complete function.
Install the plugin - Register the local marketplace and enable the plugin. See setup-helper/install.sh for the exact commands required.
Render placeholders - Placeholders in .mcp.json and hooks.json must be replaced with absolute paths or values when copied into the Codex cache. The automated installer handles this for you.
type codex # Expected: codex is a shell function
If the previous command printed a path instead of
shell function, the wrapper isn't active yet. Re-source it (or open a new terminal) before launching, otherwise codex starts withoutOPENVIKING_API_KEYand reportsMCP server is not logged in.
Inside Codex, the plugin will now recall memory before every prompt. You can set OPENVIKING_DEBUG=1 to log events to ~/.openviking/logs/codex-hooks.log.
The plugin hooks into the Codex lifecycle. It searches OpenViking and injects relevant memories before every user prompt (UserPromptSubmit), appends new conversation turns to the session after each response (Stop), and completes and commits the full transcript before compaction (PreCompact) to ensure the memory extractor has complete context. When a new session starts, it also cleans up orphaned sessions from previous runs.
<details> <summary><b>Configuration</b></summary>Known limitation: Codex does not trigger hooks on
SIGTERM,Ctrl+C, or/exit. Orphaned sessions are reclaimed during the nextSessionStartusing either the idle TTL cleanup window (30 minutes) or the active-window heuristic.
Configuration priority: environment variables > ovcli.conf > ov.conf > built-in defaults (http://127.0.0.1:1933, no auth).
| Environment variable | Default | Description |
|---|---|---|
OPENVIKING_URL / OPENVIKING_BASE_URL | - | Full server URL |
OPENVIKING_API_KEY | - | API key sent as Authorization: Bearer |
OPENVIKING_CODEX_ACTIVE_WINDOW_MS | 120000 | SessionStart active-window threshold |
OPENVIKING_CODEX_IDLE_TTL_MS | 1800000 | SessionStart idle TTL cleanup threshold |
OPENVIKING_DEBUG | false | Write logs to ~/.openviking/logs/codex-hooks.log |
For tuning options such as OPENVIKING_RECALL_LIMIT and OPENVIKING_CAPTURE_ASSISTANT_TURNS, see the plugin README.
| Symptom | Cause | Fix |
|---|---|---|
MCP server is not logged in | OPENVIKING_API_KEY is missing from the startup environment | Confirm the codex() function has been sourced and ovcli.conf contains an api_key |
type codex shows a path instead of a shell function (wrapper inactive) | The rc wasn't sourced after install, or you launched from a terminal that didn't load it | Run source ~/.zshrc (or ~/.bashrc on bash), or open a new terminal |
Launching via an alias (e.g. cx) injects no credentials | The alias name was listed in OPENVIKING_CODEX_WRAP_EXTRA (alias names are skipped), or the alias's target command isn't wrapped | Wrap the command the alias points to, not the alias: alias cx=codex needs nothing; for alias cx=codex-custom, add codex-custom |
4 hooks need review | First-launch security approval is required | Type /hooks in Codex and approve them |
hook (failed) exited with code 1 after approval | Placeholders in the cache were not properly rendered | Rerun the one-line install script |
| Recall is empty | Server is unreachable or the URL is incorrect | Run curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health" to test the connection |
| Hooks get 401 while MCP works, or vice versa | Environment variables and ovcli.conf are out of sync | Hooks re-read ovcli.conf each time; MCP reads the environment at startup. Restart Codex after making changes. |