Codex Memory Plugin

Give Codex persistent memory across sessions. Install once — memories are recalled on every prompt, captured after each turn, and committed before compaction. The plugin also wires Codex up to OpenViking's /mcp endpoint so the model can search, store, and manage memories directly.

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

Install

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

The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Every step is idempotent.

After install:

source ~/.zshrc    # or ~/.bashrc
codex              # first run: approve hooks once when prompted via /hooks

Manual setup

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

1. Shell function wrapper — append a codex() function to your shell rc that injects OpenViking env vars from ovcli.conf. See the plugin README for the full function.

2. Plugin install — register a local marketplace and enable the plugin. See setup-helper/install.sh for the exact commands.

3. Placeholder rendering — the checked-in .mcp.json and hooks.json contain placeholders that must be substituted when copied to Codex's plugin cache. The installer does this automatically.

Verify

type codex         # expect: codex is a shell function

Inside Codex, the plugin should recall memories on each prompt. Set OPENVIKING_DEBUG=1 to write events to ~/.openviking/logs/codex-hooks.log.

How it works

The plugin hooks into Codex's lifecycle: 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) so memory extraction runs against the complete conversation. On fresh session start, it also cleans up orphaned sessions from prior runs.

Known gap: Codex fires no hook on SIGTERM / Ctrl+C / /exit. Orphaned sessions are recovered by the next SessionStart's idle-TTL sweep (30 min) or active-window heuristic.

Configuration

Config priority: env vars > ovcli.conf > ov.conf > built-in defaults (http://127.0.0.1:1933, no auth).

Env Var	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 sweep threshold
OPENVIKING_DEBUG	false	Write logs to ~/.openviking/logs/codex-hooks.log

Tuning knobs (OPENVIKING_RECALL_LIMIT, OPENVIKING_CAPTURE_ASSISTANT_TURNS, etc.) are documented in the plugin README.

Troubleshooting

Symptom	Cause	Fix
MCP server is not logged in	OPENVIKING_API_KEY not in env at launch	Ensure codex() shell function is sourced and ovcli.conf has api_key
4 hooks need review	First-launch security review	Run /hooks in Codex and approve
hook (failed) exited with code 1	Stale placeholder in plugin cache	Re-run the one-line installer
Recall returns nothing	Server unreachable or wrong URL	curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"
Hook 401 but MCP works (or vice versa)	env vs ovcli.conf mismatch	Hooks re-read ovcli.conf every fire; MCP reads env at startup. Restart codex.

See also

• Blog: OpenViking in Claude Code / Codex — motivation, architecture overview, and demo
• Plugin README — full env-var list, architecture diagram
• DESIGN.md — commit decision tree
• MCP Clients — MCP protocol, tools, and other clients
• Deployment Guide → CLI — ovcli.conf setup