Codex Memory Plugin

Equip Codex with persistent memory across sessions. Install it once, and memories will be automatically recalled with every prompt, captured after each turn, and committed before compaction. The plugin also connects Codex to OpenViking's /mcp endpoint, enabling the model to search, store, and manage memories directly.

Source: examples/codex-memory-plugin | Blog: Motivation & demo

Install

Claude Code and Codex share one installer. It asks for your language (English/中文), which harnesses to install, the download source, and your OpenViking credentials; every step is idempotent.

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

In regions where GitHub is hard to reach, run the same installer from the Volcengine TOS mirror (or pick "TOS mirror" at the download-source prompt). Codex installs from a TOS-hosted git repo and keeps remote update support:

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --dist tos

No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads ~/.openviking/ovcli.conf (or OPENVIKING_* env vars) at runtime, same as the hooks. After installing:

codex              # First run: approve hooks once when prompted via /hooks

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

1. Configure the connection — write ~/.openviking/ovcli.conf (url, api_key, optional account/user), or run the bundled wizard node <plugin-dir>/scripts/setup.mjs after installing.

2. Install the plugin from the remote marketplace:

   bashCopy

   codex plugin marketplace add volcengine/OpenViking
   codex plugin add openviking-memory@openviking
   

   Then enable plugin hooks in ~/.codex/config.toml if your build doesn't already: [features] → plugin_hooks = true. Update later with codex plugin marketplace upgrade openviking.

Verify

Launch codex; the plugin should seamlessly recall memories on every prompt. Set OPENVIKING_DEBUG=1 to write events to ~/.openviking/logs/codex-hooks.log.

How it works

The plugin integrates with Codex's lifecycle by hooking into key events. It searches OpenViking and injects relevant memories before every prompt (UserPromptSubmit), appends new turns to the session after each response (Stop), and commits the full transcript before compaction (PreCompact) to ensure memory extraction processes the entire conversation. Upon starting a fresh session, it also cleans up any orphaned sessions from previous runs.

Known limitation: Codex does not fire a hook upon SIGTERM, Ctrl+C, or /exit. Orphaned sessions are recovered during the next SessionStart via the idle-TTL sweep (30 minutes) or the active-window heuristic.

Credential source: active ovcli.conf wins by default (OPENVIKING_CLI_CONFIG_FILE or ~/.openviking/ovcli.conf), so ov config switch <name> changes hooks, MCP proxy, and child ov commands together on the next launch. Set OPENVIKING_CREDENTIAL_SOURCE=env only when you intentionally want env vars to override the CLI config. Without an ovcli config, env vars then ov.conf then built-in defaults are used.

Additional tuning options (e.g., OPENVIKING_RECALL_LIMIT, OPENVIKING_CAPTURE_ASSISTANT_TURNS) are documented in the plugin README.

Troubleshooting

See also

• Blog: OpenViking in Claude Code / Codex — Motivation, architecture overview, and demo.
• Plugin README — Full environment variable list and architecture diagram.
• DESIGN.md — Commit decision tree.
• MCP Clients — MCP protocol, tools, and other clients.
• Deployment Guide → CLI — ovcli.conf setup instructions.