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

Step 1: Install

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

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 pass OPENVIKING_CODEX_WRAP_EXTRA='codex-custom') to inject credentials there too.

Manual installation

Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the codex_hooks feature enabled.

1. 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.

2. Install the plugin - Register the local marketplace and enable the plugin. See setup-helper/install.sh for the exact commands required.

3. 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.

Step 2: Verify

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 without OPENVIKING_API_KEY and reports MCP 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.

How it works

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.

Known limitation: Codex does not trigger hooks on SIGTERM, Ctrl+C, or /exit. Orphaned sessions are reclaimed during the next SessionStart using either the idle TTL cleanup window (30 minutes) or the active-window heuristic.

Configuration

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.

Troubleshooting

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.

Reference docs

• Blog: OpenViking for Claude Code / Codex - Why and how to add long-term memory to your coding agent.
• Plugin README - Comprehensive list of environment variables and the architecture diagram.
• DESIGN.md - Details on the commit decision tree.