Codex

Add persistent, cross-session memory to Codex. Install it once, and the plugin will load your OpenViking profile and memory index at session start, recall relevant 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 such as find, search, recall, and remember.

Source: examples/codex-memory-plugin | Blog: motivation and demo

Step 1: Install

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

Claude Code and Codex share this one installer. It asks which tools to install, which source to use (GitHub or the TOS mirror), your language (English/中文), and OpenViking credentials; each step is idempotent, so it is safe to rerun. If you choose the TOS channel for Codex, it installs from a TOS-hosted git repo and can update later with codex plugin marketplace upgrade openviking.

No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads ~/.openviking/ovcli.conf at runtime. After installing:

codex              # approve hooks once via /hooks on first launch

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 (needs GitHub access):

   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.

Step 2: Verify

Launch codex; the SessionStart hook will load your profile on the session's first prompt, then the plugin will recall relevant 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. On SessionStart (startup, clear, or resume), it injects profile.md plus URI and abstract indexes for preferences/ and entities/ through the shared CJK-aware profile builder. 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. Resume may combine the profile with the latest archive digest.

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 priority: environment variables > ovcli.conf > ov.conf > built-in defaults (http://127.0.0.1:1933, no auth).

If recall latency matters most, see Low-latency recall.

For tuning options such as OPENVIKING_RECALL_LIMIT and OPENVIKING_CAPTURE_ASSISTANT_TURNS, see the plugin README.

Troubleshooting

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.