Codex 记忆插件
为 Codex 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回，每轮结束后增量捕获，compaction 前提交给记忆抽取器。插件同时把 Codex 接到 OpenViking 的 /mcp 端点，模型可以直接调用 search、store 等工具管理记忆。
源码：examples/codex-memory-plugin | 博客：动机与效果展示
安装
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)脚本会检查依赖、配置 OpenViking 连接并注册插件。每一步幂等，反复执行安全。
安装完成后：
source ~/.zshrc # 或 ~/.bashrc
codex # 首次启动进 /hooks 审批一次手动安装
前置：Node.js >= 22、Codex >= 0.130.0、codex_hooks feature 已启用。
Shell 函数包装 — 在 shell rc 中追加一个
codex()函数，每次调用时从 ovcli.conf 注入 OpenViking 环境变量。完整函数见 插件 README。插件安装 — 注册本地 marketplace 并启用插件。具体命令见
setup-helper/install.sh。占位符渲染 —
.mcp.json和hooks.json中的占位符在拷贝到 Codex 缓存时需替换为绝对值。installer 会自动做。
验证
type codex # 期望输出：codex is a shell function进入 Codex 后插件会在每次输入前召回记忆。设 OPENVIKING_DEBUG=1 可把事件写到 ~/.openviking/logs/codex-hooks.log。
工作原理
插件挂载到 Codex 的生命周期：每次用户输入前搜索 OpenViking 并注入相关记忆（UserPromptSubmit），每轮结束后把新的对话追加到 session（Stop），compaction 前补齐并 commit 完整 transcript（PreCompact）让记忆抽取器跑在完整上下文上。新 session 启动时还会清理前次运行的孤儿 session。
已知盲区：Codex 在
SIGTERM/Ctrl+C//exit时不触发任何 hook。孤儿 session 由下一次SessionStart的闲置 TTL 清理（30 分钟）或活动窗口启发式回收。
配置
配置优先级：环境变量 > ovcli.conf > ov.conf > 内置默认值（http://127.0.0.1:1933，无鉴权）。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
OPENVIKING_URL / OPENVIKING_BASE_URL | — | 完整服务器 URL |
OPENVIKING_API_KEY | — | API key（通过 Authorization: Bearer 发送） |
OPENVIKING_CODEX_ACTIVE_WINDOW_MS | 120000 | SessionStart 活动窗口阈值 |
OPENVIKING_CODEX_IDLE_TTL_MS | 1800000 | SessionStart 闲置 TTL 清理阈值 |
OPENVIKING_DEBUG | false | 写日志到 ~/.openviking/logs/codex-hooks.log |
调参（OPENVIKING_RECALL_LIMIT、OPENVIKING_CAPTURE_ASSISTANT_TURNS 等）见 插件 README。
故障排查
| 现象 | 原因 | 修复 |
|---|---|---|
MCP server is not logged in | 启动时 OPENVIKING_API_KEY 不在 env 里 | 确认 codex() 函数已 source，ovcli.conf 有 api_key |
4 hooks need review | 首次启动的安全审批 | 在 Codex 输入 /hooks 审批 |
审批后仍 hook (failed) exited with code 1 | 缓存里占位符未渲染 | 重新跑一次一行安装脚本 |
| 召回为空 | 服务器不可达或 URL 不对 | curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health" |
| Hook 401 但 MCP 可用，或反之 | env vs ovcli.conf 不一致 | Hook 每次重读 ovcli.conf，MCP 在启动时读 env。改完重启 codex。 |
参见
- 博客：在 Claude Code / Codex 中接入 OpenViking — 为什么以及如何给你的 Coding Agent 加上长期记忆
- 插件 README — 完整环境变量、架构图
- DESIGN.md — commit 决策树
- MCP 客户端 — MCP 协议、工具列表、其他客户端
- 部署指南 → CLI —
ovcli.conf配置