Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

refactor(plugin/codex): switch MCP from local stdio to OV /mcp directly (#2022)

t0sakib0076110ae9d
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index 094cc180f..2d7c0cb75 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -1,6 +1,6 @@
# Codex Memory Plugin
-Long-term semantic memory for [Codex](https://developers.openai.com/codex). Auto-recalls relevant memories on every prompt, incrementally captures each turn, and commits to OpenViking's memory extractor before compaction — the model doesn't need to call any MCP tool explicitly.
+Long-term semantic memory for [Codex](https://developers.openai.com/codex). Auto-recalls relevant memories on every prompt, incrementally captures each turn, commits to OpenViking's memory extractor before compaction, and wires Codex up to OpenViking's native `/mcp` endpoint so the model can `search` / `store` / `read` / `grep` / `glob` / `list` / `forget` / `add_resource` memories directly — no local MCP server to maintain.
Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
@@ -14,16 +14,15 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
The installer checks `codex`, `git`, and Node.js 22+, refreshes (or clones on first run) `~/.openviking/openviking-repo`, registers a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`, and pre-populates Codex's plugin cache so the plugin resolves immediately. Rerunning the installer is idempotent — it always pulls latest before installing.
-It uses `~/.openviking/ovcli.conf` when present; otherwise the plugin falls back to `http://127.0.0.1:1933` unless `OPENVIKING_URL` / `OPENVIKING_API_KEY` are set in the env.
+It reads `~/.openviking/ovcli.conf` for the OpenViking URL, renders the `/mcp` endpoint into the cached `.mcp.json`, and appends a `codex()` shell function to your rc that pulls `OPENVIKING_API_KEY` / `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` from ovcli.conf at every codex invocation. The API key stays in `ovcli.conf`; the `.mcp.json` on disk only references `OPENVIKING_API_KEY` via `bearer_token_env_var`, never embeds it.
-After install, start Codex:
+After install:
```bash
-codex
+source ~/.zshrc # or ~/.bashrc
+codex # first run: review /hooks once when prompted
```
-Codex will prompt `/hooks` to review the four new lifecycle hooks the first time — approve them once. From then on, recall runs on every prompt and capture runs on every `Stop`.
-
### Manual setup
Prerequisites:
@@ -34,58 +33,44 @@ codex --version # >= 0.130.0
codex features list | grep codex_hooks
```
-Enable plugin lifecycle hooks in `~/.codex/config.toml`:
-
-```toml
-[features]
-plugin_hooks = true
-```
-
-From an OpenViking checkout, register a local marketplace:
-
-```bash
-mkdir -p /tmp/ov-codex-mp/.claude-plugin
-ln -s "$(pwd)/examples/codex-memory-plugin" /tmp/ov-codex-mp/openviking-memory
-cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
-{
- "name": "openviking-plugins-local",
- "plugins": [
- { "name": "openviking-memory", "source": "./openviking-memory" }
- ]
-}
-EOF
-
-codex plugin marketplace add /tmp/ov-codex-mp
-cat >> ~/.codex/config.toml <<'EOF'
-
-[plugins."openviking-memory@openviking-plugins-local"]
-enabled = true
-EOF
-```
-
-Pre-populate Codex's cache so the plugin resolves on first launch:
-
-```bash
-INSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memory
-mkdir -p "$INSTALL_DIR"
-cp -R "$(pwd)/examples/codex-memory-plugin" "$INSTALL_DIR/0.4.1"
-```
-
-Configure the OpenViking client, sharing the same file as the `ov` CLI:
-
-```jsonc
-// ~/.openviking/ovcli.conf
-{
- "url": "https://ov.example.com",
- "api_key": "<your-key>",
- "account": "default",
- "user": "<your-user>"
-}
-```
-
-For local-server mode (`http://127.0.0.1:1933`) you can skip this file.
-
-`npm install && npm run build` is only needed when editing `src/memory-server.ts` — the checked-in plugin already includes `servers/memory-server.js`.
+Three steps the installer does for you, that you can do manually:
+
+1. **Shell function wrapper** in `~/.zshrc` / `~/.bashrc` that promotes ovcli.conf into env vars before exec'ing codex (uses `node` rather than `jq` to avoid a silent fallback to OAuth when `jq` is missing — Codex already requires Node 22+):
+
+ ```bash
+ codex() {
+ local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
+ local _ov_env
+ _ov_env=$(node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";
+ process.stdout.write(
+ out("OV_URL", c.url) +
+ out("OV_KEY", c.api_key) +
+ out("OV_ACCOUNT", c.account) +
+ out("OV_USER", c.user)
+ );
+ } catch {}
+ ' "$_ov_conf" 2>/dev/null)
+ eval "$_ov_env"
+ OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
+ OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
+ OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
+ OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
+ OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
+ command codex "$@"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ else
+ command codex "$@"
+ fi
+ }
+ ```
+
+2. **Plugin install** via a local marketplace pointing at the plugin directory. See `setup-helper/install.sh` for the exact `codex plugin marketplace add` invocation.
+
+3. **Placeholder rendering**: the checked-in `.mcp.json` keeps `__OPENVIKING_MCP_URL__` and `hooks/hooks.json` keeps `__OPENVIKING_PLUGIN_ROOT__`; both must be `sed`-substituted to absolute values when the plugin is copied into Codex's cache (`~/.codex/plugins/cache/...`). The installer does this automatically.
## Configuration
@@ -93,19 +78,19 @@ Resolution priority for every connection / identity field — env vars always wi
1. **Environment variables** (`OPENVIKING_*`)
2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
-3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (top-level `server.*` + optional `codex.*` tuning block)
+3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)
4. **Built-in defaults** (`http://127.0.0.1:1933`, unauthenticated)
-Setting `OPENVIKING_URL` alone is enough to run in env-var-only mode (no config files needed) — useful for daemon-spawned agents.
+Hooks resolve this chain on every fire (changes to ovcli.conf take effect on the next hook). The MCP server URL is baked into `.mcp.json` at install time (changing the URL requires a re-install); the API key is read fresh from env on every codex launch via `bearer_token_env_var`, so rotating `OPENVIKING_API_KEY` in ovcli.conf only requires a codex restart, not a re-install.
-Auth is sent as `Authorization: Bearer <api_key>` plus the legacy `X-API-Key` header during the transition window.
+Auth is sent as `Authorization: Bearer <api_key>` to both the REST API (used by hooks) and the `/mcp` endpoint (used by the model).
### Key environment variables
| Variable | Default | Notes |
|----------|---------|-------|
-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL |
-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key (sent as `Authorization: Bearer` either way) |
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL (the `/mcp` endpoint is derived from this at install time) |
+| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key, sent as `Authorization: Bearer` |
| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | Multi-tenant identity headers |
| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | Alternate `ovcli.conf` path |
| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | Alternate `ov.conf` path |
@@ -135,14 +120,12 @@ The full field list is in the [plugin README](https://github.com/volcengine/Open
| Hook | When | Behavior |
|------|------|----------|
| `SessionStart` (matcher `clear\|startup`) | Fresh process, `/new`, or `/clear` | Active-window heuristic: if exactly one other state file was touched in the last 2 min, commit it (the just-ended session). Idle-TTL sweep at the tail picks up SIGTERM/`/exit` orphans older than 30 min. `source=resume` is a hard no-op. |
-| `UserPromptSubmit` | Every prompt | Search OpenViking, rank, inject top results into `hookSpecificOutput.additionalContext`. |
+| `UserPromptSubmit` | Every prompt | Search OpenViking REST `/search/find`, rank, inject top results into `hookSpecificOutput.additionalContext`. |
| `Stop` | Every turn end | Append new user/assistant turns to the long-lived OpenViking session keyed by Codex `session_id`. No commit per turn. |
| `PreCompact` | Before Codex summarizes | Catch-up append + commit so OpenViking's extractor runs against the full pre-compact transcript, then null `ovSessionId` so the next `Stop` opens a fresh OV session. |
`Stop` deliberately does not commit per turn — committing extracts memories, and per-turn extraction would over-fragment the memory tree. The decision tree behind which hook seals which OV session is in [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md).
-The MCP server (`servers/memory-server.js`) is launched lazily by `scripts/start-memory-server.mjs` on first MCP invocation — `npm ci` runs into `${CODEX_PLUGIN_DATA}/runtime` once and is reused after that.
-
### Known gap: SIGTERM / Ctrl+C / `/exit` are silent
Codex fires no hook on process exit. If you `/exit` without `/compact`, the OV session for that codex session_id stays open server-side. Two fallbacks recover the orphan:
@@ -150,26 +133,21 @@ Codex fires no hook on process exit. If you `/exit` without `/compact`, the OV s
1. The next `SessionStart` (source=startup|clear) idle-TTL sweep commits any state file older than 30 min.
2. The active-window heuristic catches the orphan if you `/new` or `/clear` shortly after.
-If you need to preserve memory from a specific session, run `/compact` first or call `openviking_store` with the conclusions you want kept.
-
## MCP tools
-For explicit memory operations, the plugin also exposes four MCP tools:
+The plugin wires Codex up to OpenViking's built-in `/mcp` endpoint via streamable HTTP. Tool list, per-tool semantics, and protocol details live in the [MCP Integration Guide](../guides/06-mcp-integration.md) — not duplicated here.
-- `openviking_recall` — search memories
-- `openviking_store` — store a memory by creating a short OV session and committing
-- `openviking_forget` — delete an exact memory URI
-- `openviking_health` — server reachability check
+`.mcp.json` ships with the OV server URL rendered at install time and uses `bearer_token_env_var: "OPENVIKING_API_KEY"` plus `env_http_headers` for the multi-tenant identity headers. The API key never lands on disk in `.mcp.json`; it's pulled from env at codex launch by the shell function wrapper.
## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
-| `MCP startup failed: connection closed: initialize response` | MCP launcher couldn't find the script (e.g., stale plugin cache) | Re-run the [one-line installer](#one-line-installer-recommended) — it now refreshes `~/.openviking/openviking-repo` |
+| `MCP server is not logged in. Run codex mcp login` | `OPENVIKING_API_KEY` not in env at codex launch, and OV server returned 401, so Codex fell back to OAuth | Make sure the `codex()` shell function is sourced (`type codex` should say "shell function") and `ovcli.conf` has `api_key` |
| `4 hooks need review before they can run` | First-launch security review | Open `/hooks` in Codex and approve |
+| `hook (failed) exited with code 1` after approval | Stale `hooks.json` placeholder; cache wasn't re-rendered | Rerun the one-line installer |
| Hook runs but recall returns nothing | OpenViking server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| Remote auth 401/403 | API key wrong or multi-tenant headers missing | Check `OPENVIKING_API_KEY`; multi-tenant also needs `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
-| `Stop` hook timeout | Server slow + sync write path | Raise the `Stop` timeout in `hooks/hooks.json` |
+| Remote auth 401/403 from hooks but MCP works (or vice versa) | env vs ovcli.conf mismatch | Hooks re-read ovcli.conf every fire; MCP reads env only at codex start. Restart codex if you changed env. |
Verbose debug logging: set `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.conf` to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.
@@ -177,15 +155,16 @@ Verbose debug logging: set `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.
| Aspect | Claude Code Plugin | Codex Plugin |
|--------|--------------------|--------------|
-| Plugin root env | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
+| Plugin root env | `CLAUDE_PLUGIN_ROOT` (expanded by CC) | `CODEX_PLUGIN_ROOT` (NOT expanded by Codex 0.130; installer renders absolute paths) |
| `UserPromptSubmit` output | `decision: "approve"` + `additionalContext` | `additionalContext` only — `approve` is not a Codex output |
| Compaction hook | n/a | `PreCompact` — full-transcript commit before context loss |
| Config section | `claude_code` | `codex` |
| Default config file | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`, falls back to `ov.conf` |
+| MCP server | Local stdio (CC's `.mcp.json` doesn't support env-var Bearer) | Streamable-HTTP to OpenViking's native `/mcp` |
## See also
- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — full env-var list, validation SOP, architecture diagram
- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit decision tree
-- [MCP Integration Guide](../guides/06-mcp-integration.md) — for clients without lifecycle hooks
+- [MCP Integration Guide](../guides/06-mcp-integration.md) — protocol, tools, and how OpenViking exposes `/mcp`
- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index f992d9c49..eff714fa6 100644
--- a/docs/zh/agent-integrations/04-codex.md
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -1,6 +1,6 @@
# Codex 记忆插件
-为 [Codex](https://developers.openai.com/codex) 提供长期语义记忆。每次用户输入前自动召回相关记忆,每轮对话结束后增量捕获,并在 compaction 之前提交给 OpenViking 的记忆抽取器——模型不需要主动调用任何 MCP 工具。
+为 [Codex](https://developers.openai.com/codex) 提供长期语义记忆。每次用户输入前自动召回相关记忆,每轮对话结束后增量捕获,compaction 前提交给 OpenViking 的记忆抽取器;同时把 Codex 直接接到 OpenViking 自带的 `/mcp` endpoint,模型可以直接调用 `search` / `store` / `read` / `grep` / `glob` / `list` / `forget` / `add_resource` 等工具——**没有本地 MCP server 进程要维护**。
源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
@@ -12,18 +12,17 @@
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
```
-脚本会检查 `codex`、`git`、Node.js 22+;首次运行时把 OpenViking 仓库 clone 到 `~/.openviking/openviking-repo`,已存在则自动 `git fetch` + `reset --hard` 到 main;注册本地 `openviking-plugins-local` marketplace、启用 `openviking-memory@openviking-plugins-local`、把 `features.plugin_hooks = true` 写入 `~/.codex/config.toml`,并预填 Codex 的 plugin 缓存让插件立即解析到。每一步幂等,反复执行安全。
+脚本会检查 `codex`、`git`、Node.js 22+;首次运行时把 OpenViking 仓库 clone 到 `~/.openviking/openviking-repo`,已存在则自动 `git fetch + reset --hard` 到 main;注册本地 `openviking-plugins-local` marketplace、启用 `openviking-memory@openviking-plugins-local`、把 `features.plugin_hooks = true` 写入 `~/.codex/config.toml`,并预填 Codex 的 plugin 缓存让插件立即解析到。每一步幂等,反复执行安全。
-存在 `~/.openviking/ovcli.conf` 时直接读它;否则插件回落到 `http://127.0.0.1:1933`,或读取 env 中的 `OPENVIKING_URL` / `OPENVIKING_API_KEY`。
+存在 `~/.openviking/ovcli.conf` 时直接读它,把 `/mcp` URL 渲染进缓存里的 `.mcp.json`;同时往你的 shell rc 追加一个 `codex()` 函数包装,每次调用 codex 时从 ovcli.conf 把 `OPENVIKING_API_KEY` / `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` 注入到环境变量。API key 只留在 `ovcli.conf` 里,**`.mcp.json` 磁盘文件里只通过 `bearer_token_env_var` 引用变量名,永远不会包含 key 明文**。
安装完成后启动 Codex:
```bash
-codex
+source ~/.zshrc # 或 ~/.bashrc
+codex # 首次启动进 /hooks 审批一次
```
-首次启动时 Codex 会提示 `4 hooks need review before they can run`——进入 `/hooks` 审批一次后续都不会再问。之后每次用户输入会自动召回,每轮 `Stop` 会自动捕获。
-
### 手动安装
前置:
@@ -34,58 +33,44 @@ codex --version # >= 0.130.0
codex features list | grep codex_hooks
```
-在 `~/.codex/config.toml` 启用插件生命周期 hooks:
-
-```toml
-[features]
-plugin_hooks = true
-```
-
-在 OpenViking 检出目录注册一个本地 marketplace:
-
-```bash
-mkdir -p /tmp/ov-codex-mp/.claude-plugin
-ln -s "$(pwd)/examples/codex-memory-plugin" /tmp/ov-codex-mp/openviking-memory
-cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
-{
- "name": "openviking-plugins-local",
- "plugins": [
- { "name": "openviking-memory", "source": "./openviking-memory" }
- ]
-}
-EOF
-
-codex plugin marketplace add /tmp/ov-codex-mp
-cat >> ~/.codex/config.toml <<'EOF'
-
-[plugins."openviking-memory@openviking-plugins-local"]
-enabled = true
-EOF
-```
-
-预填 Codex 的 plugin 缓存,首次启动直接命中:
-
-```bash
-INSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memory
-mkdir -p "$INSTALL_DIR"
-cp -R "$(pwd)/examples/codex-memory-plugin" "$INSTALL_DIR/0.4.1"
-```
-
-配置 OpenViking 客户端(与 `ov` CLI 共用同一份文件):
-
-```jsonc
-// ~/.openviking/ovcli.conf
-{
- "url": "https://ov.example.com",
- "api_key": "<你的 API key>",
- "account": "default",
- "user": "<你的 user>"
-}
-```
-
-只用本地服务器(`http://127.0.0.1:1933`)可以跳过这一步。
-
-只有修改 `src/memory-server.ts` 才需要 `npm install && npm run build`——仓库里已经带了 `servers/memory-server.js`。
+installer 替你做的三件事,你也可以自己手动做:
+
+1. **shell 函数包装**追加到 `~/.zshrc` / `~/.bashrc`,把 ovcli.conf 提升成环境变量后再 exec codex(用 `node` 而不是 `jq` 解析 conf —— 这样在没装 `jq` 的机器上也能跑,Codex 本身已经强依赖 Node 22+):
+
+ ```bash
+ codex() {
+ local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
+ local _ov_env
+ _ov_env=$(node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";
+ process.stdout.write(
+ out("OV_URL", c.url) +
+ out("OV_KEY", c.api_key) +
+ out("OV_ACCOUNT", c.account) +
+ out("OV_USER", c.user)
+ );
+ } catch {}
+ ' "$_ov_conf" 2>/dev/null)
+ eval "$_ov_env"
+ OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
+ OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
+ OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
+ OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
+ OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
+ command codex "$@"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ else
+ command codex "$@"
+ fi
+ }
+ ```
+
+2. **插件安装**——通过指向插件目录的本地 marketplace。`setup-helper/install.sh` 里有完整的 `codex plugin marketplace add` 调用。
+
+3. **占位符渲染**——仓库里 checked-in 的 `.mcp.json` 保留 `__OPENVIKING_MCP_URL__`,`hooks/hooks.json` 保留 `__OPENVIKING_PLUGIN_ROOT__`;这两个占位符必须在拷贝到 Codex 缓存目录 (`~/.codex/plugins/cache/...`) 时被 `sed` 替换成绝对值。installer 自动做。
## 配置
@@ -96,16 +81,16 @@ cp -R "$(pwd)/examples/codex-memory-plugin" "$INSTALL_DIR/0.4.1"
3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(顶层 `server.*` + 可选的 `codex.*` 调参块)
4. **内置默认值**(`http://127.0.0.1:1933`,无鉴权)
-只设 `OPENVIKING_URL` 一个变量就足以跑 env-only 模式(不需要任何配置文件),适合 daemon 派生 agent 的场景。
+Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一次 hook 立即生效。MCP server URL 在 install 时固化进 `.mcp.json`(改 URL 要重跑 installer),但 API key 通过 `bearer_token_env_var` 在 codex 启动时从 env 读,所以**轮换 API key 只需重启 codex,不必重装**。
-鉴权头同时发送 `Authorization: Bearer <api_key>`(主)和 `X-API-Key`(兼容旧版自托管服务)。
+鉴权头同时发给 REST API(hook 用)和 `/mcp` endpoint(模型用):`Authorization: Bearer <api_key>`。
### 关键环境变量
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |
-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key(两个变量都通过 `Authorization: Bearer` 发送) |
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL(`/mcp` endpoint 在 install 时由此推导) |
+| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key,通过 `Authorization: Bearer` 发送 |
| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | 多租户身份头 |
| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | 备用 `ovcli.conf` 路径 |
| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | 备用 `ov.conf` 路径 |
@@ -135,41 +120,34 @@ cp -R "$(pwd)/examples/codex-memory-plugin" "$INSTALL_DIR/0.4.1"
| Hook | 触发时机 | 行为 |
|------|---------|------|
| `SessionStart`(matcher `clear\|startup`) | 全新进程 / `/new` / `/clear` | 活动窗口启发式:如果最近 2 分钟内恰好只有一个其他 state 文件被更新,就把它 commit 掉(视为刚刚结束的 session)。尾部的闲置 TTL 清理会捕获 30 分钟以上的孤儿 state(SIGTERM / `/exit` 等)。`source=resume` 是硬 no-op。 |
-| `UserPromptSubmit` | 每次用户输入 | 搜索 OpenViking → 排序 → 把 top 结果通过 `hookSpecificOutput.additionalContext` 注入到模型上下文。 |
+| `UserPromptSubmit` | 每次用户输入 | 走 REST `/search/find` 搜索 OpenViking → 排序 → 把 top 结果通过 `hookSpecificOutput.additionalContext` 注入到模型上下文。 |
| `Stop` | 每轮结束 | 把新的 user/assistant turn 追加到由 Codex `session_id` 索引的长生命周期 OV session。**不**每轮 commit。 |
| `PreCompact` | Codex 即将做摘要前 | 补齐追加 + commit,让 OV 抽取器跑在完整的 pre-compact transcript 上;commit 后清空 `ovSessionId`,下一次 `Stop` 会打开一个全新的 OV session。 |
`Stop` 故意不每轮 commit——commit 会触发记忆抽取,每轮抽取会过度碎片化记忆树。完整的「哪个 hook 负责封住哪个 OV session」决策树见 [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md)。
-MCP 服务器(`servers/memory-server.js`)由 `scripts/start-memory-server.mjs` 懒加载启动 —— 首次 MCP 调用时跑一次 `npm ci` 到 `${CODEX_PLUGIN_DATA}/runtime`,后续复用。
-
### 已知盲区:SIGTERM / Ctrl+C / `/exit` 不触发任何 hook
-Codex 在进程退出时不发任何 hook。如果你 `/exit` 之前没跑 `/compact`,那个 codex session 对应的 OV session 会在服务端保持打开状态。两条兜底路径会回收孤儿:
+如果你 `/exit` 之前没跑 `/compact`,那个 codex session 对应的 OV session 会在服务端保持打开状态。两条兜底路径会回收孤儿:
1. 下一次 `SessionStart`(source=startup|clear)的闲置 TTL 清理会 commit 30 分钟以上的孤儿 state。
2. 如果你在孤儿之后立即 `/new` 或 `/clear`,活动窗口启发式会精准命中并 commit。
-如果你想保住某个 session 的记忆,退出前先 `/compact`,或者用 `openviking_store` 显式记下结论。
-
## MCP 工具
-除了自动 hook,插件还暴露四个 MCP 工具供显式调用:
+插件通过 streamable HTTP 把 Codex 接到 OpenViking 自带的 `/mcp` endpoint。工具列表、每个工具的语义、协议细节统一见 [MCP 集成指南](../guides/06-mcp-integration.md),这里不重复。
-- `openviking_recall` — 搜索记忆
-- `openviking_store` — 创建一个短 OV session、写入内容、commit
-- `openviking_forget` — 删除指定 URI 的记忆
-- `openviking_health` — 服务可达性探测
+`.mcp.json` 在 install 时写入 OV server URL,用 `bearer_token_env_var: "OPENVIKING_API_KEY"` + `env_http_headers` 传多租户身份头。**API key 永远不会落到 `.mcp.json` 文件里**,是 codex 启动时由 shell 函数包装从 env 取。
## 故障排查
| 现象 | 原因 | 修复 |
|------|------|------|
-| `MCP startup failed: connection closed: initialize response` | MCP 启动脚本找不到(典型成因:plugin 缓存陈旧) | 重新跑[一行安装脚本](#一行安装推荐)——它会自动刷新 `~/.openviking/openviking-repo` |
-| `4 hooks need review before they can run` | 首次启动的安全审批 | 进入 Codex 输入 `/hooks` 批准一次 |
+| `MCP server is not logged in. Run codex mcp login` | codex 启动时 `OPENVIKING_API_KEY` 不在 env 里,OV 返回 401,Codex 回落到 OAuth | 确认 `codex()` shell 函数已 source(`type codex` 应该返回"shell function")、且 `ovcli.conf` 里有 `api_key` |
+| `4 hooks need review before they can run` | 首次启动的安全审批 | 进入 Codex 输入 `/hooks` 批准 |
+| 审批后还是 `hook (failed) exited with code 1` | `hooks.json` 占位符没渲染,cache 是旧的 | 重新跑一次一行安装脚本 |
| Hook 触发但召回为空 | OpenViking 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| 远程鉴权 401 / 403 | API key 错或多租户头缺失 | 检查 `OPENVIKING_API_KEY`;多租户场景还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
-| `Stop` hook 超时 | 服务器慢 + 同步写路径 | 调高 `hooks/hooks.json` 里 `Stop` 的 timeout |
+| Hook 401/403 但 MCP 工具可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次都重读 ovcli.conf,MCP 只在 codex 启动读 env。改完 env 要重启 codex。 |
调试日志:设 `OPENVIKING_DEBUG=1` 或 `ovcli.conf` 里 `codex.debug=true`,会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。
@@ -177,15 +155,16 @@ Codex 在进程退出时不发任何 hook。如果你 `/exit` 之前没跑 `/com
| 维度 | Claude Code 插件 | Codex 插件 |
|------|------------------|-----------|
-| Plugin root env | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
+| Plugin root env | `CLAUDE_PLUGIN_ROOT`(CC 会展开) | `CODEX_PLUGIN_ROOT`(Codex 0.130 **不展开**;installer 渲染成绝对路径) |
| `UserPromptSubmit` 输出 | `decision: "approve"` + `additionalContext` | 只有 `additionalContext` —— Codex 没有 `approve` 这个 decision |
| Compaction hook | 无 | `PreCompact` —— 在上下文丢失前 commit 完整 transcript |
| 配置区块 | `claude_code` | `codex` |
| 默认配置文件 | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`,回落到 `ov.conf` |
+| MCP server | 本地 stdio(CC `.mcp.json` 不支持 env-var Bearer) | streamable-HTTP,直连 OpenViking 自带 `/mcp` |
## 参见
- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、Validation SOP、架构图
- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树
-- [MCP 集成指南](../guides/06-mcp-integration.md) — 用于不支持生命周期 hook 的客户端
+- [MCP 集成指南](../guides/06-mcp-integration.md) — 协议、工具列表、OpenViking 如何暴露 `/mcp`
- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.json
index 0674085d1..7fcb9ecdd 100644
--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json
+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.4.1",
+ "version": "0.5.0",
"description": "Long-term semantic memory for Codex, powered by OpenViking. Recall on UserPromptSubmit, incremental add_message on Stop (per turn), commit on PreCompact, and active-window heuristic + idle-TTL sweep on SessionStart (source=startup|clear).",
"author": {
"name": "OpenViking",
diff --git a/examples/codex-memory-plugin/.mcp.json b/examples/codex-memory-plugin/.mcp.json
index d968463f7..40bf6d264 100644
--- a/examples/codex-memory-plugin/.mcp.json
+++ b/examples/codex-memory-plugin/.mcp.json
@@ -1,11 +1,13 @@
{
"mcpServers": {
"openviking-memory": {
- "command": "node",
- "args": [
- "scripts/start-memory-server.mjs"
- ],
- "cwd": "."
+ "url": "__OPENVIKING_MCP_URL__",
+ "bearer_token_env_var": "OPENVIKING_API_KEY",
+ "env_http_headers": {
+ "X-OpenViking-Account": "OPENVIKING_ACCOUNT",
+ "X-OpenViking-User": "OPENVIKING_USER",
+ "X-OpenViking-Agent": "OPENVIKING_AGENT_ID"
+ }
}
}
}
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index ddd80719f..f408bb606 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -8,126 +8,88 @@ This is the Codex counterpart to [`claude-code-memory-plugin`](../claude-code-me
- **Incremental capture on `Stop`** (turn end): append the new user/assistant turns to a single long-lived OpenViking session keyed by Codex `session_id`. No commit per turn.
- **Commit on `PreCompact`**: trigger OpenViking's memory extractor on the full pre-compact transcript before Codex summarizes it.
- **Commit on `SessionStart` (source=startup|clear)**: active-window heuristic — if exactly one *other* state file was touched within the last 2 min, commit it (the just-ended session). On `≥2`, defer to idle-TTL sweep at the tail. `source=resume` is a hard no-op (short reconnects re-fire `resume` and we don't want to commit a still-active session). See `DESIGN.md` for the full decision tree.
-- **MCP runtime bootstrap is lazy**: the MCP launcher (`start-memory-server.mjs`) installs runtime deps on first MCP invocation, not in a hook.
-It also exposes explicit MCP tools (`openviking_recall`, `openviking_store`, `openviking_forget`, `openviking_health`) for manual use.
+It also wires Codex up to OpenViking's native `/mcp` endpoint (streamable HTTP, Bearer auth), so the model has direct access to the `search`, `store`, `read`, `list`, `grep`, `glob`, `forget`, `add_resource`, and `health` tools — no local MCP server process to maintain.
## Quick Start
-Installation is first here, matching the shape of the [Claude Code integration doc](../../docs/en/agent-integrations/02-claude-code.md).
-
### One-line installer (recommended)
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
```
-The installer checks `codex`, `git`, and Node.js 22+, clones OpenViking to `~/.openviking/openviking-repo` if needed, registers a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`, and pre-populates Codex's plugin cache so the plugin resolves immediately. It uses `~/.openviking/ovcli.conf` when present; otherwise the plugin falls back to `http://127.0.0.1:1933`.
-
-If you'd rather do it by hand, use the manual setup below.
-
-### Manual setup
-
-#### 1. Install prerequisites
-
-```bash
-node --version # >= 22
-codex --version # >= 0.124.0
-```
-
-Make sure `codex_hooks` is enabled:
-
-```bash
-codex features list | grep codex_hooks
-```
-
-Plugin lifecycle hooks also require `plugin_hooks`:
+The installer:
-```toml
-[features]
-plugin_hooks = true
-```
-
-#### 2. Install the plugin
+1. Checks `codex`, `git`, and Node.js 22+
+2. Clones or refreshes `~/.openviking/openviking-repo`
+3. Registers a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`
+4. Renders the cached `.mcp.json` URL from `ovcli.conf` (or `OPENVIKING_URL`)
+5. Renders the cached `hooks.json` with absolute script paths (Codex 0.130 doesn't inject `CODEX_PLUGIN_ROOT` into hook env)
+6. Appends a `codex()` shell function to your rc that pulls `OPENVIKING_API_KEY` / `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` from `ovcli.conf` at invocation — keeps the key out of `.mcp.json` on disk
-The plugin lives at `examples/codex-memory-plugin/`.
+After install:
```bash
-mkdir -p /tmp/ov-codex-mp/.claude-plugin
-ln -s /abs/path/to/OpenViking/examples/codex-memory-plugin /tmp/ov-codex-mp/openviking-memory
-cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
-{
- "name": "openviking-plugins-local",
- "plugins": [
- { "name": "openviking-memory", "source": "./openviking-memory" }
- ]
-}
-EOF
-
-codex plugin marketplace add /tmp/ov-codex-mp
-cat >> ~/.codex/config.toml <<'EOF'
-
-[plugins."openviking-memory@openviking-plugins-local"]
-enabled = true
-EOF
+source ~/.zshrc # or ~/.bashrc
+codex # first run: review /hooks once
```
-For local development, pre-populate Codex's plugin cache so it resolves immediately:
-
-```bash
-INSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memory
-mkdir -p "$INSTALL_DIR"
-cp -R /abs/path/to/OpenViking/examples/codex-memory-plugin "$INSTALL_DIR/0.4.1"
-```
-
-#### 3. Configure OpenViking
-
-Use the same client config file as the `ov` CLI:
-
-```jsonc
-// ~/.openviking/ovcli.conf
-{
- "url": "https://ov.example.com",
- "api_key": "<your-key>",
- "account": "default",
- "user": "<your-user>"
-}
-```
-
-Local server mode works without this file; the plugin falls back to `http://127.0.0.1:1933`.
-
-#### 4. Start Codex
-
-```bash
-codex
-```
-
-First MCP launch installs runtime deps; later launches reuse them.
-
-### Development from source
-
-Only needed when editing `src/memory-server.ts`:
-
-```bash
-cd examples/codex-memory-plugin
-npm install
-npm run build
-```
+### Manual setup
-`codex exec` does not reliably fire plugin lifecycle hooks in current Codex builds. For hook validation, use an interactive `codex` session or the scripts in `hooks/hooks.json` with synthetic JSON input.
+If you don't want the installer touching your rc, do these three things yourself:
+
+1. **Wire a `codex()` shell function** that injects OpenViking creds at invocation time. Add to `~/.zshrc` / `~/.bashrc` (uses `node` rather than `jq` so it works on any machine that already has Codex — Codex requires Node 22+):
+
+ ```bash
+ codex() {
+ local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
+ local _ov_env
+ _ov_env=$(node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";
+ process.stdout.write(
+ out("OV_URL", c.url) +
+ out("OV_KEY", c.api_key) +
+ out("OV_ACCOUNT", c.account) +
+ out("OV_USER", c.user)
+ );
+ } catch {}
+ ' "$_ov_conf" 2>/dev/null)
+ eval "$_ov_env"
+ OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
+ OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
+ OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
+ OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
+ OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
+ command codex "$@"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ else
+ command codex "$@"
+ fi
+ }
+ ```
+
+2. **Add the plugin** via a local marketplace pointing at this directory. See `setup-helper/install.sh` for the exact `codex plugin marketplace add` invocation.
+
+3. **Render the `__OPENVIKING_MCP_URL__` placeholder** in `.mcp.json` and the `__OPENVIKING_PLUGIN_ROOT__` placeholders in `hooks/hooks.json` to absolute values. The installer does this automatically when copying the plugin into Codex's cache; for manual setup you do it once with `sed`.
## Configuration
-Resolution priority, highest to lowest:
+Connection / identity resolution order (highest to lowest, applies to both hooks and MCP):
-1. Environment variables: `OPENVIKING_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_AGENT_ID`
-2. `ovcli.conf`: `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
-3. `ov.conf`: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE`
-4. Built-in defaults
+1. **Environment variables**: `OPENVIKING_URL` / `OPENVIKING_BASE_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_AGENT_ID`
+2. **`ovcli.conf`**: `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
+3. **`ov.conf`**: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)
+4. **Built-in defaults**: `http://127.0.0.1:1933`, unauthenticated
-Auth is sent as `Authorization: Bearer <key>` plus legacy `X-API-Key` during migration.
+The shell function wrapper handles step 1 for you by promoting ovcli.conf fields into env vars before exec'ing codex. Hooks then re-resolve the full chain inside Node; the MCP server URL is baked into `.mcp.json` at install time and the API key flows in via `OPENVIKING_API_KEY` (referenced by `bearer_token_env_var` in `.mcp.json`).
-Optional Codex-specific tuning can live under `codex` in `ovcli.conf`:
+Auth is sent as `Authorization: Bearer <api_key>` to both the REST API (used by hooks) and the `/mcp` endpoint (used by the model).
+
+Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:
```jsonc
{
@@ -161,24 +123,21 @@ Optional Codex-specific tuning can live under `codex` in `ovcli.conf`:
└────┬──────────┘ └────┬──────┘ └──────┬──────┘ └──────────┬──────┘
│ │ │ │
│ ┌───▼────────────────▼───────────────────▼──┐
- └────────────►│ OpenViking server │
+ └────────────►│ OpenViking REST API │
│ /api/v1/search/find │
│ /api/v1/sessions [+/{id}/{messages,commit}]│
│ /api/v1/content/read │
- └───────────────────────────────────────────┘
-
- ┌──────────────────────────────────────┐
- │ MCP Server (memory-server.ts) │
- │ Tools for explicit use: │
- │ • openviking_recall │
- │ • openviking_store │
- │ • openviking_forget │
- │ • openviking_health │
- │ Lazily npm ci's its runtime on │
- │ first launch. │
- └──────────────────────────────────────┘
+ └─────────────────┬─────────────────────────┘
+ │
+ Codex ◄──────── streamable-HTTP MCP ◄ /mcp (search, store, read, list,
+ (bearer token via grep, glob, forget,
+ OPENVIKING_API_KEY) add_resource, health)
```
+The plugin no longer bundles a local stdio MCP server. Codex talks to OpenViking's built-in `/mcp` endpoint directly via streamable HTTP, with `bearer_token_env_var: "OPENVIKING_API_KEY"` in `.mcp.json` so the key stays in `ovcli.conf` and the shell function — never on disk in `.mcp.json` itself.
+
+For details on OpenViking's MCP endpoint, tools, and protocol, see the [MCP Integration Guide](../../docs/en/guides/06-mcp-integration.md). The tools list and per-tool semantics are documented there once, not duplicated here.
+
## How It Works
> See [`DESIGN.md`](./DESIGN.md) for the commit decision tree — it's the source of truth for *which* OpenViking session is sealed by *which* hook event.
@@ -187,7 +146,7 @@ Optional Codex-specific tuning can live under `codex` in `ovcli.conf`:
Codex fires `SessionStart` with one of three `source` values: `startup` (fresh process / `/new` / zouk daemon spawn-without-sessionId), `resume` (`/resume` or short reconnect), and `clear` (`/clear` — the previous transcript is orphaned and a new session_id is created). `resume` is the *only* source we treat as a hard no-op; on `startup` and `clear` we run the same active-window heuristic.
-`hooks.json` registers `SessionStart` with `matcher: "clear|startup"` so codex's dispatcher invokes the script on both sources (the matcher is matched against the SessionStart `source` field — see [`codex-rs/hooks/src/events/session_start.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/events/session_start.rs)). `session-start-commit.mjs` gates internally on `source ∈ {startup, clear}` as defense-in-depth.
+`hooks.json` registers `SessionStart` with `matcher: "clear|startup"` so codex's dispatcher invokes the script on both sources. `session-start-commit.mjs` gates internally on `source ∈ {startup, clear}` as defense-in-depth.
On `startup` or `clear`, the script:
@@ -195,15 +154,13 @@ On `startup` or `clear`, the script:
- **0 active** → no-op (no orphan to commit)
- **1 active** → commit it (the just-ended session)
- **≥2 active** → skip; rely on idle TTL (we can't tell which one ended)
-2. **Idle-TTL sweep at the tail**: any state file (regardless of session_id) older than `OPENVIKING_CODEX_IDLE_TTL_MS` (default 30 min) gets committed and cleared. This catches `SIGTERM` / Ctrl+C / `/exit` exits and crashes that left state files orphaned. The sweep runs *only* at SessionStart — the Stop hook deliberately does not sweep, because state-write-on-every-turn already gives us the freshness signal.
+2. **Idle-TTL sweep at the tail**: any state file (regardless of session_id) older than `OPENVIKING_CODEX_IDLE_TTL_MS` (default 30 min) gets committed and cleared.
-On any /commit failure (OV unreachable, non-2xx, timeout) we **preserve state** (don't `clearState`) so the next sweep can retry. A transient OV outage shouldn't lose memory.
-
-MCP runtime install does **not** live in this hook — it lazily runs from `scripts/start-memory-server.mjs` on first MCP launch.
+On any /commit failure (OV unreachable, non-2xx, timeout) we **preserve state** (don't `clearState`) so the next sweep can retry.
### Auto-recall (every UserPromptSubmit)
-`auto-recall.mjs` reads `prompt` from stdin, calls `/api/v1/search/find` for both `viking://user/memories` and `viking://agent/memories` (and `viking://agent/skills`), ranks results with query-aware scoring (leaf boost, preference boost, temporal boost, lexical overlap), reads full content for top-ranked leaves, and emits:
+`auto-recall.mjs` reads `prompt` from stdin, calls `/api/v1/search/find`, ranks results, reads full content for top-ranked leaves, and emits:
```json
{ "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "<relevant-memories>...</relevant-memories>" } }
@@ -213,32 +170,22 @@ Codex injects `additionalContext` into the model turn, so memories arrive withou
### Stop (turn end → `add_message`, NOT `commit`)
-Codex's `Stop` fires per turn, not at session end. So `auto-capture.mjs` keeps **one** long-lived OpenViking session per Codex `session_id` and incrementally appends every new user/assistant turn from the rollout JSONL via `/api/v1/sessions/{id}/messages`. Per-codex-session state lives at `~/.openviking/codex-plugin-state/<safe-session-id>.json` and tracks `{ ovSessionId, capturedTurnCount, lastUpdatedAt }`.
-
-We do **not** call `/commit` per turn — committing extracts memories, and per-turn extraction would over-fragment the memory tree and waste OV's extractor.
+`auto-capture.mjs` keeps one long-lived OpenViking session per Codex `session_id` and incrementally appends every new user/assistant turn via `/api/v1/sessions/{id}/messages`. Per-codex-session state lives at `~/.openviking/codex-plugin-state/<safe-session-id>.json`. No `/commit` per turn — that would over-fragment memory extraction.
### PreCompact (deterministic commit)
-`PreCompact` fires before Codex summarizes. `pre-compact-capture.mjs` does:
+`pre-compact-capture.mjs`:
-1. **Catch-up**: append any transcript turns Stop hasn't captured yet (race-safe via `capturedTurnCount`).
-2. **Commit** the long-lived OV session for this Codex `session_id` so OV's extractor runs against the full pre-compact transcript.
-3. **Reset** state: clear `ovSessionId` so the next `Stop` opens a fresh OV session for the post-compact half. `capturedTurnCount` stays so we don't re-capture pre-compact turns.
+1. Catch-up append for any turns Stop hasn't captured yet (race-safe via `capturedTurnCount`)
+2. Commit the long-lived OV session so the extractor runs against the full pre-compact transcript
+3. Reset state so the next `Stop` opens a fresh OV session for the post-compact half
### Known gap: SIGTERM / Ctrl+C / `/exit` are silent
-Codex fires no hook on process exit. `/compact` (PreCompact) is the only fully-deterministic "context disappearing" signal. If you `/exit` (or Ctrl+C, or kill the process) without first running `/compact`, the OpenViking session for that codex session_id stays open with messages but never has memories extracted in that moment.
-
-Two fallbacks recover the orphan:
-
-1. **Idle-TTL sweep**: the next `SessionStart` (source=startup|clear) on the same machine commits any state file older than 30 min (`OPENVIKING_CODEX_IDLE_TTL_MS`). So as long as you start another codex session within ~30 min, the orphan is reclaimed.
-2. **Active-window heuristic**: if you run `/new` or `/clear` shortly after the orphaned session was last touched, the heuristic catches it as the unique "recently-active" state and commits it deterministically.
-
-The remaining limitation: if you never start another codex on this machine, no sweep runs and the OV session stays open server-side. If you care about preserving memory from a particular session before exiting, run `/compact` first or call `openviking_store` with the conclusions you want kept.
-
-### MCP tools (explicit, on demand)
+Codex fires no hook on process exit. `/compact` is the only fully-deterministic "context disappearing" signal. If you `/exit` without `/compact`, the OV session for that codex session_id stays open. Two fallbacks recover the orphan:
-The MCP server provides tools for when Codex or the user needs explicit memory operations. See "Tools" below.
+1. The idle-TTL sweep at the next `SessionStart` commits any state file older than 30 min
+2. The active-window heuristic catches it if you `/new` or `/clear` shortly after
## Codex hook output schema
@@ -251,151 +198,8 @@ Codex's hook output schema differs from Claude Code's. Notably:
| `Stop` | `last_assistant_message`, `transcript_path`, `session_id` | `systemMessage` (only) |
| `PreCompact` | `trigger` (`manual`/`auto`), `transcript_path`, `session_id` | `systemMessage` (only) |
-> Note: this plugin acts on `SessionStart` when `source=startup` or `source=clear` (matcher `clear|startup`). `source=resume` is a no-op because codex re-fires it on short reconnects.
-
Unlike Claude Code, **Codex does not support `decision: "approve"`**; only `decision: "block"`. A no-op is `{}` (which is what these scripts emit when there's nothing to add).
-Source: [`codex-rs/hooks/schema/generated/`](https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated).
-
-## Validation SOP
-
-This is the canonical end-to-end validation for an OpenViking plugin. Run it after any plugin change.
-
-```bash
-export OPENVIKING_API_KEY=<your-key>
-export OPENVIKING_URL=https://ov.example.com # or your server
-ACCT=default
-
-# 1. Trigger something memorable in a Codex session, then close it.
-# e.g.: "I prefer pour-over coffee for memory testing — please remember."
-
-# 2. Verify a session was created and committed.
-ov --account "$ACCT" ls viking://session | head
-# Pick the most recently created session id (one we just made).
-
-SID=<paste session id>
-
-# 3. Confirm the session has messages + history archive.
-ov --account "$ACCT" ls "viking://session/$SID"
-ov --account "$ACCT" ls "viking://session/$SID/history"
-# Expect: messages.jsonl and a history/archive_NNN/ entry.
-
-# 4. Read the messages back to confirm the captured payload.
-ov --account "$ACCT" read "viking://session/$SID/messages.jsonl"
-
-# 5. Wait ~1 minute (or `ov wait`) for OV's extraction pipeline.
-ov --account "$ACCT" wait --timeout 120
-
-# 6. Verify long-term memories landed under the user (and/or agent) folder.
-ov --account "$ACCT" find "<your seed phrase>" -u viking://user/<user>/memories -n 5
-# Expect leaf memories under preferences/, events/, entities/, etc.
-```
-
-If step 6 returns no leaf memories, check:
-
-- The capture hook actually ran — `tail -f ~/.openviking/logs/codex-hooks.log` (with `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.conf`).
-- The OV server's extraction queue isn't backed up — `ov --account "$ACCT" status`.
-- The committed text passed `shouldCapture` thresholds (`length`, `commands`, `keyword` mode).
-
-## Configuration
-
-| Field (`codex` section) | Default | Description |
-|-------------------------|---------|-------------|
-| `agentId` | `codex` | Agent identity for memory isolation |
-| `timeoutMs` | `15000` | HTTP request timeout for recall/general requests (ms) |
-| `autoRecall` | `true` | Enable auto-recall on every user prompt |
-| `recallLimit` | `6` | Max memories to inject per turn |
-| `scoreThreshold` | `0.01` | Min relevance score (0–1) |
-| `minQueryLength` | `3` | Skip recall for very short queries |
-| `logRankingDetails` | `false` | Per-candidate ranking logs (verbose) |
-| `autoCapture` | `true` | Enable auto-capture on Stop |
-| `captureMode` | `semantic` | `semantic` (always capture) or `keyword` (trigger-based) |
-| `captureMaxLength` | `24000` | Max text length for capture |
-| `captureTimeoutMs` | `30000` | HTTP request timeout for capture/commit (ms) |
-| `captureAssistantTurns` | `false` | Include assistant turns in transcript-incremental capture |
-| `captureLastAssistantOnStop` | `true` | Capture `last_assistant_message` separately on every Stop |
-| `autoCommitOnCompact` | `true` | Commit the full transcript on `PreCompact` |
-| `debug` | `false` | Write structured debug logs |
-
-Connection settings resolve in this strict priority — env vars always win:
-
-1. **Environment variables** (`OPENVIKING_*`)
-2. **`ovcli.conf`** — CLI client config (`url`, `api_key`, `account`, `user`, `agent_id`)
-3. **`ov.conf`** — server config (`server.*` + optional `codex.*` tuning block)
-4. **Built-in defaults**
-
-Setting `OPENVIKING_URL` alone is enough to run in env-var-only mode (no config files needed) — useful for daemon-spawned agents.
-
-File-path overrides (aligned with `ov` CLI and `claude-code-memory-plugin`):
-
-- `OPENVIKING_CLI_CONFIG_FILE` — alternate `ovcli.conf` path (default `~/.openviking/ovcli.conf`)
-- `OPENVIKING_CONFIG_FILE` — alternate `ov.conf` path (default `~/.openviking/ov.conf`). For backward compat, if this points at an ovcli-shaped file (top-level `url`/`api_key`, no `server` section), it is treated as the CLI config.
-
-Connection / identity overrides:
-
-- `OPENVIKING_URL` / `OPENVIKING_BASE_URL` — server URL
-- `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` — API key (sent as `Authorization: Bearer` either way)
-- `OPENVIKING_ACCOUNT` — account
-- `OPENVIKING_USER` — user
-- `OPENVIKING_AGENT_ID` — agent identity
-
-State-file / SessionStart tuning:
-
-- `OPENVIKING_CODEX_STATE_DIR`: state file directory (default `~/.openviking/codex-plugin-state`)
-- `OPENVIKING_CODEX_ACTIVE_WINDOW_MS`: SessionStart active-window threshold in ms (default `120000` = 2 min)
-- `OPENVIKING_CODEX_IDLE_TTL_MS`: SessionStart idle-TTL sweep threshold in ms (default `1800000` = 30 min)
-
-### Auth header
-
-Requests send both `Authorization: Bearer <api_key>` (primary — required by OpenViking Cloud) and `X-API-Key` (legacy — accepted by older self-hosted servers). The legacy header will be dropped once `X-API-Key` is fully retired upstream.
-
-## Hook timeouts
-
-| Hook | Default timeout | Notes |
-|------|-----------------|-------|
-| `SessionStart` | `120s` | First session may need time to install runtime deps |
-| `UserPromptSubmit` | `8s` | Recall must stay fast — keep `timeoutMs` low |
-| `Stop` | `45s` | Gives capture room to finish |
-| `PreCompact` | `60s` | Whole transcript posts plus commit |
-
-## Debug logging
-
-Set `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.conf` to write structured JSON-Lines events to `~/.openviking/logs/codex-hooks.log`. Each entry is `{ts, hook, stage, data}` (or `error`).
-
-## MCP Tools
-
-### `openviking_recall`
-
-Search OpenViking memory.
-
-Parameters:
-
-- `query`: search query
-- `target_uri`: optional search scope, default `viking://user/memories`
-- `limit`: optional max results
-- `score_threshold`: optional minimum score
-
-### `openviking_store`
-
-Store a memory by creating a short OpenViking session, adding the text, and committing. Memory creation is extraction-dependent; the tool reports when OpenViking commits the session but extracts zero items.
-
-Parameters:
-
-- `text`: information to store
-- `role`: optional message role, default `user`
-
-### `openviking_forget`
-
-Delete an exact memory URI. Use `openviking_recall` first to find the URI.
-
-Parameters:
-
-- `uri`: exact `viking://user/.../memories/...` or `viking://agent/.../memories/...`
-
-### `openviking_health`
-
-Check server reachability.
-
## Plugin Structure
```
@@ -404,37 +208,37 @@ codex-memory-plugin/
│ └── plugin.json # Plugin manifest (hooks + mcp wiring)
├── hooks/
│ └── hooks.json # SessionStart + UserPromptSubmit + Stop + PreCompact
+│ (uses __OPENVIKING_PLUGIN_ROOT__ placeholder;
+│ installer renders to absolute paths)
├── scripts/
│ ├── config.mjs # Shared config loader (ovcli.conf + env)
│ ├── debug-log.mjs # Structured JSONL logger
-│ ├── runtime-common.mjs # Plugin data root + install-state helpers
-│ ├── bootstrap-runtime.mjs # SessionStart installer
-│ ├── start-memory-server.mjs # Launches MCP server through the runtime
-│ ├── auto-recall.mjs # UserPromptSubmit hook
-│ ├── auto-capture.mjs # Stop hook
-│ └── pre-compact-capture.mjs # PreCompact hook (commits full transcript)
-├── servers/
-│ └── memory-server.js # Compiled MCP server (checked in)
-├── src/
-│ └── memory-server.ts # MCP server source
-├── .mcp.json # MCP server definition (consumed by Codex)
-├── package.json
-├── tsconfig.json
+│ ├── session-state.mjs # Per-codex-session OV session state
+│ ├── auto-recall.mjs # UserPromptSubmit hook (REST /search/find)
+│ ├── auto-capture.mjs # Stop hook (REST /sessions/{id}/messages)
+│ ├── session-start-commit.mjs # SessionStart hook (active-window + idle TTL)
+│ └── pre-compact-capture.mjs # PreCompact hook
+├── setup-helper/
+│ └── install.sh # One-line installer
+├── .mcp.json # Streamable-HTTP MCP wiring (renders __OPENVIKING_MCP_URL__)
+├── DESIGN.md
+├── VERIFICATION.md
└── README.md
```
+No `src/`, `servers/`, `node_modules/`, or `package.json`: there is no local MCP server to build or run. All hook scripts are zero-dep `.mjs` running on Codex's bundled Node 22.
+
## Differences from the Claude Code Plugin
| Aspect | Claude Code Plugin | Codex Plugin |
|--------|--------------------|--------------|
-| Plugin root env var | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
-| Plugin data env var | `CLAUDE_PLUGIN_DATA` | `CODEX_PLUGIN_DATA` |
+| Plugin root env var | `CLAUDE_PLUGIN_ROOT` (expanded by CC) | `CODEX_PLUGIN_ROOT` (NOT expanded by Codex 0.130; installer renders absolute paths into the cached copies) |
| `UserPromptSubmit` injection | `decision: "approve"` + `hookSpecificOutput.additionalContext` | `hookSpecificOutput.additionalContext` only — `approve` is not a Codex output |
| `Stop` decision | `decision: "approve"` no-op | `{}` no-op — only `block` is a valid Codex `decision` |
| Compaction hook | n/a (Claude Code does not expose one) | `PreCompact` — full-transcript commit before context loss |
| Config section | `claude_code` | `codex` |
| Default config file | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`, falls back to `ov.conf` |
-| Identity headers | `X-OpenViking-Agent` only | Adds `X-OpenViking-Account` + `X-OpenViking-User` when configured |
+| MCP server | Local stdio (CC quirk: `.mcp.json` doesn't support env var auth) | Streamable HTTP to OpenViking's native `/mcp` (Codex supports `bearer_token_env_var`) |
## License
diff --git a/examples/codex-memory-plugin/VERIFICATION.md b/examples/codex-memory-plugin/VERIFICATION.md
index 1ca663d1d..4cd28db2b 100644
--- a/examples/codex-memory-plugin/VERIFICATION.md
+++ b/examples/codex-memory-plugin/VERIFICATION.md
@@ -1,4 +1,4 @@
-# Verification SOP — codex plugin (v0.4.1)
+# Verification SOP — codex plugin (v0.5.0)
End-to-end smoke test against a live OpenViking server. Run this whenever the
hook scripts change. Takes ~3 minutes; the only async wait is OV's memory
diff --git a/examples/codex-memory-plugin/package-lock.json b/examples/codex-memory-plugin/package-lock.json
deleted file mode 100644
index 84e9148f2..000000000
--- a/examples/codex-memory-plugin/package-lock.json
+++ /dev/null
@@ -1,1174 +0,0 @@
-{
- "name": "codex-openviking-memory",
- "version": "0.4.1",
- "lockfileVersion": 3,
- "requires": true,
- "packages": {
- "": {
- "name": "codex-openviking-memory",
- "version": "0.4.1",
- "dependencies": {
- "@modelcontextprotocol/sdk": "^1.12.1",
- "zod": "^4.3.6"
- },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "typescript": "^5.7.0"
- }
- },
- "node_modules/@hono/node-server": {
- "version": "1.19.14",
- "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
- "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
- "license": "MIT",
- "engines": {
- "node": ">=18.14.1"
- },
- "peerDependencies": {
- "hono": "^4"
- }
- },
- "node_modules/@modelcontextprotocol/sdk": {
- "version": "1.29.0",
- "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
- "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
- "license": "MIT",
- "dependencies": {
- "@hono/node-server": "^1.19.9",
- "ajv": "^8.17.1",
- "ajv-formats": "^3.0.1",
- "content-type": "^1.0.5",
- "cors": "^2.8.5",
- "cross-spawn": "^7.0.5",
- "eventsource": "^3.0.2",
- "eventsource-parser": "^3.0.0",
- "express": "^5.2.1",
- "express-rate-limit": "^8.2.1",
- "hono": "^4.11.4",
- "jose": "^6.1.3",
- "json-schema-typed": "^8.0.2",
- "pkce-challenge": "^5.0.0",
- "raw-body": "^3.0.0",
- "zod": "^3.25 || ^4.0",
- "zod-to-json-schema": "^3.25.1"
- },
- "engines": {
- "node": ">=18"
- },
- "peerDependencies": {
- "@cfworker/json-schema": "^4.1.1",
- "zod": "^3.25 || ^4.0"
- },
- "peerDependenciesMeta": {
- "@cfworker/json-schema": {
- "optional": true
- },
- "zod": {
- "optional": false
- }
- }
- },
- "node_modules/@types/node": {
- "version": "22.19.18",
- "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.18.tgz",
- "integrity": "sha512-9v00a+dn2yWVsYDEunWC4g/TcRKVq3r8N5FuZp7u0SGrPvdN9c2yXI9bBuf5Fl0hNCb+QTIePTn5pJs2pwBOQQ==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "undici-types": "~6.21.0"
- }
- },
- "node_modules/accepts": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
- "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
- "license": "MIT",
- "dependencies": {
- "mime-types": "^3.0.0",
- "negotiator": "^1.0.0"
- },
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/ajv": {
- "version": "8.20.0",
- "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
- "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
- "license": "MIT",
- "dependencies": {
- "fast-deep-equal": "^3.1.3",
- "fast-uri": "^3.0.1",
- "json-schema-traverse": "^1.0.0",
- "require-from-string": "^2.0.2"
- },
- "funding": {
- "type": "github",
- "url": "https://github.com/sponsors/epoberezkin"
- }
- },
- "node_modules/ajv-formats": {
- "version": "3.0.1",
- "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
- "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
- "license": "MIT",
- "dependencies": {
- "ajv": "^8.0.0"
- },
- "peerDependencies": {
- "ajv": "^8.0.0"
- },
- "peerDependenciesMeta": {
- "ajv": {
- "optional": true
- }
- }
- },
- "node_modules/body-parser": {
- "version": "2.2.2",
- "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
- "integrity": "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==",
- "license": "MIT",
- "dependencies": {
- "bytes": "^3.1.2",
- "content-type": "^1.0.5",
- "debug": "^4.4.3",
- "http-errors": "^2.0.0",
- "iconv-lite": "^0.7.0",
- "on-finished": "^2.4.1",
- "qs": "^6.14.1",
- "raw-body": "^3.0.1",
- "type-is": "^2.0.1"
- },
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/bytes": {
- "version": "3.1.2",
- "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
- "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/call-bind-apply-helpers": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
- "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "function-bind": "^1.1.2"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/call-bound": {
- "version": "1.0.4",
- "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
- "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.2",
- "get-intrinsic": "^1.3.0"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/content-disposition": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
- "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/content-type": {
- "version": "1.0.5",
- "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
- "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/cookie": {
- "version": "0.7.2",
- "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
- "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/cookie-signature": {
- "version": "1.2.2",
- "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
- "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
- "license": "MIT",
- "engines": {
- "node": ">=6.6.0"
- }
- },
- "node_modules/cors": {
- "version": "2.8.6",
- "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
- "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
- "license": "MIT",
- "dependencies": {
- "object-assign": "^4",
- "vary": "^1"
- },
- "engines": {
- "node": ">= 0.10"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/cross-spawn": {
- "version": "7.0.6",
- "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
- "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
- "license": "MIT",
- "dependencies": {
- "path-key": "^3.1.0",
- "shebang-command": "^2.0.0",
- "which": "^2.0.1"
- },
- "engines": {
- "node": ">= 8"
- }
- },
- "node_modules/debug": {
- "version": "4.4.3",
- "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
- "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
- "license": "MIT",
- "dependencies": {
- "ms": "^2.1.3"
- },
- "engines": {
- "node": ">=6.0"
- },
- "peerDependenciesMeta": {
- "supports-color": {
- "optional": true
- }
- }
- },
- "node_modules/depd": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
- "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/dunder-proto": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
- "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.1",
- "es-errors": "^1.3.0",
- "gopd": "^1.2.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/ee-first": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
- "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
- "license": "MIT"
- },
- "node_modules/encodeurl": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
- "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/es-define-property": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
- "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/es-errors": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
- "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/es-object-atoms": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
- "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/escape-html": {
- "version": "1.0.3",
- "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
- "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
- "license": "MIT"
- },
- "node_modules/etag": {
- "version": "1.8.1",
- "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
- "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/eventsource": {
- "version": "3.0.7",
- "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
- "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
- "license": "MIT",
- "dependencies": {
- "eventsource-parser": "^3.0.1"
- },
- "engines": {
- "node": ">=18.0.0"
- }
- },
- "node_modules/eventsource-parser": {
- "version": "3.0.8",
- "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.8.tgz",
- "integrity": "sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ==",
- "license": "MIT",
- "engines": {
- "node": ">=18.0.0"
- }
- },
- "node_modules/express": {
- "version": "5.2.1",
- "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
- "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
- "license": "MIT",
- "dependencies": {
- "accepts": "^2.0.0",
- "body-parser": "^2.2.1",
- "content-disposition": "^1.0.0",
- "content-type": "^1.0.5",
- "cookie": "^0.7.1",
- "cookie-signature": "^1.2.1",
- "debug": "^4.4.0",
- "depd": "^2.0.0",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "etag": "^1.8.1",
- "finalhandler": "^2.1.0",
- "fresh": "^2.0.0",
- "http-errors": "^2.0.0",
- "merge-descriptors": "^2.0.0",
- "mime-types": "^3.0.0",
- "on-finished": "^2.4.1",
- "once": "^1.4.0",
- "parseurl": "^1.3.3",
- "proxy-addr": "^2.0.7",
- "qs": "^6.14.0",
- "range-parser": "^1.2.1",
- "router": "^2.2.0",
- "send": "^1.1.0",
- "serve-static": "^2.2.0",
- "statuses": "^2.0.1",
- "type-is": "^2.0.1",
- "vary": "^1.1.2"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/express-rate-limit": {
- "version": "8.5.1",
- "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.1.tgz",
- "integrity": "sha512-5O6KYmyJEpuPJV5hNTXKbAHWRqrzyu+OI3vUnSd2kXFubIVpG7ezpgxQy76Zo5GQZtrQBg86hF+CM/NX+cioiQ==",
- "license": "MIT",
- "dependencies": {
- "ip-address": "^10.2.0"
- },
- "engines": {
- "node": ">= 16"
- },
- "funding": {
- "url": "https://github.com/sponsors/express-rate-limit"
- },
- "peerDependencies": {
- "express": ">= 4.11"
- }
- },
- "node_modules/fast-deep-equal": {
- "version": "3.1.3",
- "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
- "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
- "license": "MIT"
- },
- "node_modules/fast-uri": {
- "version": "3.1.2",
- "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
- "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/fastify"
- },
- {
- "type": "opencollective",
- "url": "https://opencollective.com/fastify"
- }
- ],
- "license": "BSD-3-Clause"
- },
- "node_modules/finalhandler": {
- "version": "2.1.1",
- "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
- "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.0",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "on-finished": "^2.4.1",
- "parseurl": "^1.3.3",
- "statuses": "^2.0.1"
- },
- "engines": {
- "node": ">= 18.0.0"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/forwarded": {
- "version": "0.2.0",
- "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
- "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/fresh": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz",
- "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/function-bind": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
- "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/get-intrinsic": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
- "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.2",
- "es-define-property": "^1.0.1",
- "es-errors": "^1.3.0",
- "es-object-atoms": "^1.1.1",
- "function-bind": "^1.1.2",
- "get-proto": "^1.0.1",
- "gopd": "^1.2.0",
- "has-symbols": "^1.1.0",
- "hasown": "^2.0.2",
- "math-intrinsics": "^1.1.0"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/get-proto": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
- "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
- "license": "MIT",
- "dependencies": {
- "dunder-proto": "^1.0.1",
- "es-object-atoms": "^1.0.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/gopd": {
- "version": "1.2.0",
- "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
- "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/has-symbols": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
- "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/hasown": {
- "version": "2.0.3",
- "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
- "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
- "license": "MIT",
- "dependencies": {
- "function-bind": "^1.1.2"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/hono": {
- "version": "4.12.18",
- "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.18.tgz",
- "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==",
- "license": "MIT",
- "engines": {
- "node": ">=16.9.0"
- }
- },
- "node_modules/http-errors": {
- "version": "2.0.1",
- "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
- "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
- "license": "MIT",
- "dependencies": {
- "depd": "~2.0.0",
- "inherits": "~2.0.4",
- "setprototypeof": "~1.2.0",
- "statuses": "~2.0.2",
- "toidentifier": "~1.0.1"
- },
- "engines": {
- "node": ">= 0.8"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/iconv-lite": {
- "version": "0.7.2",
- "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
- "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
- "license": "MIT",
- "dependencies": {
- "safer-buffer": ">= 2.1.2 < 3.0.0"
- },
- "engines": {
- "node": ">=0.10.0"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/inherits": {
- "version": "2.0.4",
- "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
- "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
- "license": "ISC"
- },
- "node_modules/ip-address": {
- "version": "10.2.0",
- "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
- "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
- "license": "MIT",
- "engines": {
- "node": ">= 12"
- }
- },
- "node_modules/ipaddr.js": {
- "version": "1.9.1",
- "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
- "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/is-promise": {
- "version": "4.0.0",
- "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
- "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
- "license": "MIT"
- },
- "node_modules/isexe": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
- "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
- "license": "ISC"
- },
- "node_modules/jose": {
- "version": "6.2.3",
- "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
- "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/panva"
- }
- },
- "node_modules/json-schema-traverse": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
- "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
- "license": "MIT"
- },
- "node_modules/json-schema-typed": {
- "version": "8.0.2",
- "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
- "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
- "license": "BSD-2-Clause"
- },
- "node_modules/math-intrinsics": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
- "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/media-typer": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
- "integrity": "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/merge-descriptors": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz",
- "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/mime-db": {
- "version": "1.54.0",
- "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
- "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/mime-types": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
- "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
- "license": "MIT",
- "dependencies": {
- "mime-db": "^1.54.0"
- },
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/ms": {
- "version": "2.1.3",
- "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
- "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
- "license": "MIT"
- },
- "node_modules/negotiator": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
- "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/object-assign": {
- "version": "4.1.1",
- "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
- "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
- "license": "MIT",
- "engines": {
- "node": ">=0.10.0"
- }
- },
- "node_modules/object-inspect": {
- "version": "1.13.4",
- "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
- "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/on-finished": {
- "version": "2.4.1",
- "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
- "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
- "license": "MIT",
- "dependencies": {
- "ee-first": "1.1.1"
- },
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/once": {
- "version": "1.4.0",
- "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
- "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
- "license": "ISC",
- "dependencies": {
- "wrappy": "1"
- }
- },
- "node_modules/parseurl": {
- "version": "1.3.3",
- "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
- "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/path-key": {
- "version": "3.1.1",
- "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
- "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
- "license": "MIT",
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/path-to-regexp": {
- "version": "8.4.2",
- "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
- "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
- "license": "MIT",
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/pkce-challenge": {
- "version": "5.0.1",
- "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
- "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
- "license": "MIT",
- "engines": {
- "node": ">=16.20.0"
- }
- },
- "node_modules/proxy-addr": {
- "version": "2.0.7",
- "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
- "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
- "license": "MIT",
- "dependencies": {
- "forwarded": "0.2.0",
- "ipaddr.js": "1.9.1"
- },
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/qs": {
- "version": "6.15.1",
- "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
- "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==",
- "license": "BSD-3-Clause",
- "dependencies": {
- "side-channel": "^1.1.0"
- },
- "engines": {
- "node": ">=0.6"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/range-parser": {
- "version": "1.2.1",
- "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
- "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/raw-body": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
- "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
- "license": "MIT",
- "dependencies": {
- "bytes": "~3.1.2",
- "http-errors": "~2.0.1",
- "iconv-lite": "~0.7.0",
- "unpipe": "~1.0.0"
- },
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/require-from-string": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
- "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
- "license": "MIT",
- "engines": {
- "node": ">=0.10.0"
- }
- },
- "node_modules/router": {
- "version": "2.2.0",
- "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
- "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.0",
- "depd": "^2.0.0",
- "is-promise": "^4.0.0",
- "parseurl": "^1.3.3",
- "path-to-regexp": "^8.0.0"
- },
- "engines": {
- "node": ">= 18"
- }
- },
- "node_modules/safer-buffer": {
- "version": "2.1.2",
- "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
- "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
- "license": "MIT"
- },
- "node_modules/send": {
- "version": "1.2.1",
- "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
- "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.3",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "etag": "^1.8.1",
- "fresh": "^2.0.0",
- "http-errors": "^2.0.1",
- "mime-types": "^3.0.2",
- "ms": "^2.1.3",
- "on-finished": "^2.4.1",
- "range-parser": "^1.2.1",
- "statuses": "^2.0.2"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/serve-static": {
- "version": "2.2.1",
- "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz",
- "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==",
- "license": "MIT",
- "dependencies": {
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "parseurl": "^1.3.3",
- "send": "^1.2.0"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/setprototypeof": {
- "version": "1.2.0",
- "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
- "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
- "license": "ISC"
- },
- "node_modules/shebang-command": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
- "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
- "license": "MIT",
- "dependencies": {
- "shebang-regex": "^3.0.0"
- },
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/shebang-regex": {
- "version": "3.0.0",
- "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
- "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
- "license": "MIT",
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/side-channel": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
- "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "object-inspect": "^1.13.3",
- "side-channel-list": "^1.0.0",
- "side-channel-map": "^1.0.1",
- "side-channel-weakmap": "^1.0.2"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-list": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
- "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "object-inspect": "^1.13.4"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-map": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
- "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
- "license": "MIT",
- "dependencies": {
- "call-bound": "^1.0.2",
- "es-errors": "^1.3.0",
- "get-intrinsic": "^1.2.5",
- "object-inspect": "^1.13.3"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-weakmap": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
- "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
- "license": "MIT",
- "dependencies": {
- "call-bound": "^1.0.2",
- "es-errors": "^1.3.0",
- "get-intrinsic": "^1.2.5",
- "object-inspect": "^1.13.3",
- "side-channel-map": "^1.0.1"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/statuses": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
- "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/toidentifier": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
- "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
- "license": "MIT",
- "engines": {
- "node": ">=0.6"
- }
- },
- "node_modules/type-is": {
- "version": "2.0.1",
- "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
- "integrity": "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==",
- "license": "MIT",
- "dependencies": {
- "content-type": "^1.0.5",
- "media-typer": "^1.1.0",
- "mime-types": "^3.0.0"
- },
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/typescript": {
- "version": "5.9.3",
- "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
- "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
- "dev": true,
- "license": "Apache-2.0",
- "bin": {
- "tsc": "bin/tsc",
- "tsserver": "bin/tsserver"
- },
- "engines": {
- "node": ">=14.17"
- }
- },
- "node_modules/undici-types": {
- "version": "6.21.0",
- "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
- "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/unpipe": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
- "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/vary": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
- "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/which": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
- "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
- "license": "ISC",
- "dependencies": {
- "isexe": "^2.0.0"
- },
- "bin": {
- "node-which": "bin/node-which"
- },
- "engines": {
- "node": ">= 8"
- }
- },
- "node_modules/wrappy": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
- "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
- "license": "ISC"
- },
- "node_modules/zod": {
- "version": "4.4.3",
- "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
- "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/colinhacks"
- }
- },
- "node_modules/zod-to-json-schema": {
- "version": "3.25.2",
- "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
- "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
- "license": "ISC",
- "peerDependencies": {
- "zod": "^3.25.28 || ^4"
- }
- }
- }
-}
diff --git a/examples/codex-memory-plugin/package.json b/examples/codex-memory-plugin/package.json
deleted file mode 100644
index e70643290..000000000
--- a/examples/codex-memory-plugin/package.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
- "name": "codex-openviking-memory",
- "version": "0.4.1",
- "description": "OpenViking memory plugin for Codex — hooks (recall/capture/pre-compact) + MCP server for explicit memory operations.",
- "type": "module",
- "scripts": {
- "build": "tsc",
- "dev": "tsc --watch",
- "start": "node ./servers/memory-server.js"
- },
- "dependencies": {
- "@modelcontextprotocol/sdk": "^1.12.1",
- "zod": "^4.3.6"
- },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "typescript": "^5.7.0"
- }
-}
diff --git a/examples/codex-memory-plugin/scripts/bootstrap-runtime.mjs b/examples/codex-memory-plugin/scripts/bootstrap-runtime.mjs
deleted file mode 100644
index bc94705a0..000000000
--- a/examples/codex-memory-plugin/scripts/bootstrap-runtime.mjs
+++ /dev/null
@@ -1,39 +0,0 @@
-import {
- computeSourceState,
- ensureRuntimeInstalled,
- getRuntimePaths,
-} from "./runtime-common.mjs";
-
-async function main() {
- // Codex hook stdin: JSON object — we ignore it (SessionStart payload).
- // Read & discard to keep the pipe clean across platforms.
- process.stdin.resume();
- for await (const _ of process.stdin) { /* drain */ }
-
- let paths;
- try {
- paths = getRuntimePaths();
- } catch (err) {
- process.stderr.write(
- `[openviking-memory] CODEX_PLUGIN_ROOT not set; skipping runtime bootstrap. ${err instanceof Error ? err.message : String(err)}\n`,
- );
- return;
- }
-
- const expectedState = await computeSourceState(paths);
-
- try {
- await ensureRuntimeInstalled(paths, expectedState);
- } catch (err) {
- process.stderr.write(
- `[openviking-memory] Failed to prepare MCP runtime dependencies: ${err instanceof Error ? err.message : String(err)}\n`,
- );
- }
-}
-
-main().catch((err) => {
- process.stderr.write(
- `[openviking-memory] Runtime bootstrap failed: ${err instanceof Error ? err.message : String(err)}\n`,
- );
- process.exit(0);
-});
diff --git a/examples/codex-memory-plugin/scripts/runtime-common.mjs b/examples/codex-memory-plugin/scripts/runtime-common.mjs
deleted file mode 100644
index b7f7952b0..000000000
--- a/examples/codex-memory-plugin/scripts/runtime-common.mjs
+++ /dev/null
@@ -1,288 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
-import { access, copyFile, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-export const INSTALL_TIMEOUT_MS = 120000;
-
-const LOCK_STALE_MS = 10 * 60 * 1000;
-const FALLBACK_PLUGIN_DATA_ROOT = join(homedir(), ".openviking", "codex-memory-plugin");
-const RUNTIME_ENV_META_PATH = ".runtime-env.json";
-const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
-const PLUGIN_ROOT_FROM_SCRIPT = resolve(SCRIPT_DIR, "..");
-
-export function getRuntimePaths() {
- // Codex 0.130 does not expand ${CODEX_PLUGIN_ROOT} in .mcp.json args and does
- // not always inject CODEX_PLUGIN_ROOT into MCP child env, so fall back to the
- // script's own location (scripts/ lives directly under the plugin root).
- const pluginRoot = process.env.CODEX_PLUGIN_ROOT || PLUGIN_ROOT_FROM_SCRIPT;
- const pluginDataRoot = process.env.CODEX_PLUGIN_DATA || FALLBACK_PLUGIN_DATA_ROOT;
-
- const runtimeRoot = join(pluginDataRoot, "runtime");
-
- return {
- pluginRoot,
- pluginDataRoot,
- runtimeRoot,
- sourcePackagePath: join(pluginRoot, "package.json"),
- sourceLockPath: join(pluginRoot, "package-lock.json"),
- sourceConfigPath: join(pluginRoot, "scripts", "config.mjs"),
- sourceServerPath: join(pluginRoot, "servers", "memory-server.js"),
- runtimePackagePath: join(runtimeRoot, "package.json"),
- runtimeLockPath: join(runtimeRoot, "package-lock.json"),
- runtimeConfigPath: join(runtimeRoot, "scripts", "config.mjs"),
- runtimeServerPath: join(runtimeRoot, "servers", "memory-server.js"),
- runtimeNodeModulesPath: join(runtimeRoot, "node_modules"),
- statePath: join(runtimeRoot, "install-state.json"),
- lockDir: join(runtimeRoot, ".install-lock"),
- envMetaPath: join(runtimeRoot, RUNTIME_ENV_META_PATH),
- usingFallbackPluginData: !process.env.CODEX_PLUGIN_DATA,
- };
-}
-
-export async function computeSourceState(paths) {
- const [pkgRaw, lockRaw, configRaw, serverRaw] = await Promise.all([
- readFile(paths.sourcePackagePath),
- readFile(paths.sourceLockPath),
- readFile(paths.sourceConfigPath),
- readFile(paths.sourceServerPath),
- ]);
-
- const pkg = JSON.parse(pkgRaw.toString("utf8"));
-
- return {
- pluginVersion: typeof pkg.version === "string" ? pkg.version : "0.0.0",
- manifestHash: sha256(pkgRaw, lockRaw),
- serverHash: sha256(configRaw, serverRaw),
- };
-}
-
-export async function loadInstallState(paths) {
- try {
- return JSON.parse(await readFile(paths.statePath, "utf8"));
- } catch {
- return null;
- }
-}
-
-export async function writeInstallState(paths, state) {
- await mkdir(paths.runtimeRoot, { recursive: true });
- await writeFile(
- paths.statePath,
- JSON.stringify(
- {
- ...state,
- updatedAt: new Date().toISOString(),
- },
- null,
- 2,
- ) + "\n",
- );
-}
-
-export async function writeRuntimeEnvMeta(paths) {
- await mkdir(paths.runtimeRoot, { recursive: true });
- await writeFile(
- paths.envMetaPath,
- JSON.stringify(
- {
- pluginDataRoot: paths.pluginDataRoot,
- runtimeRoot: paths.runtimeRoot,
- usingFallbackPluginData: paths.usingFallbackPluginData,
- updatedAt: new Date().toISOString(),
- },
- null,
- 2,
- ) + "\n",
- );
-}
-
-export async function runtimeIsReady(paths, expectedState) {
- const state = await loadInstallState(paths);
- if (!state || state.status !== "ready") return false;
- if (state.manifestHash !== expectedState.manifestHash) return false;
- if (state.serverHash !== expectedState.serverHash) return false;
-
- for (const target of [
- paths.runtimePackagePath,
- paths.runtimeLockPath,
- paths.runtimeConfigPath,
- paths.runtimeServerPath,
- paths.runtimeNodeModulesPath,
- ]) {
- if (!(await pathExists(target))) return false;
- }
-
- return true;
-}
-
-export async function syncRuntimeFiles(paths) {
- await mkdir(join(paths.runtimeRoot, "servers"), { recursive: true });
- await mkdir(join(paths.runtimeRoot, "scripts"), { recursive: true });
- await copyFile(paths.sourcePackagePath, paths.runtimePackagePath);
- await copyFile(paths.sourceLockPath, paths.runtimeLockPath);
- await copyFile(paths.sourceConfigPath, paths.runtimeConfigPath);
- await copyFile(paths.sourceServerPath, paths.runtimeServerPath);
- await writeRuntimeEnvMeta(paths);
-}
-
-export async function acquireInstallLock(paths, timeoutMs = INSTALL_TIMEOUT_MS) {
- const startedAt = Date.now();
-
- while (Date.now() - startedAt < timeoutMs) {
- await mkdir(paths.runtimeRoot, { recursive: true });
-
- try {
- await mkdir(paths.lockDir);
- await writeFile(
- join(paths.lockDir, "owner.json"),
- JSON.stringify({
- pid: process.pid,
- createdAt: new Date().toISOString(),
- }) + "\n",
- );
- return async () => {
- await rm(paths.lockDir, { recursive: true, force: true });
- };
- } catch (err) {
- if (err?.code !== "EEXIST") throw err;
-
- if (await isStaleLock(paths.lockDir)) {
- await rm(paths.lockDir, { recursive: true, force: true });
- continue;
- }
-
- await wait(500);
- }
- }
-
- throw new Error(`Timed out waiting for install lock in ${paths.runtimeRoot}`);
-}
-
-export async function waitForRuntime(paths, expectedState, options = {}) {
- const timeoutMs = options.timeoutMs ?? INSTALL_TIMEOUT_MS;
- const pollMs = options.pollMs ?? 500;
- const graceMs = options.graceMs ?? 5000;
- const startedAt = Date.now();
- let sawLock = await pathExists(paths.lockDir);
-
- while (Date.now() - startedAt < timeoutMs) {
- if (await runtimeIsReady(paths, expectedState)) return true;
-
- const lockExists = await pathExists(paths.lockDir);
- sawLock ||= lockExists;
-
- if (!sawLock && Date.now() - startedAt >= graceMs) return false;
-
- await wait(pollMs);
- }
-
- return runtimeIsReady(paths, expectedState);
-}
-
-export function wait(ms) {
- return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export async function ensureRuntimeInstalled(paths, expectedState) {
- if (await runtimeIsReady(paths, expectedState)) return false;
-
- const releaseLock = await acquireInstallLock(paths, INSTALL_TIMEOUT_MS);
-
- try {
- if (await runtimeIsReady(paths, expectedState)) return false;
-
- await syncRuntimeFiles(paths);
- const result = spawnSync(getNpmCommand(), installArgs(), {
- cwd: paths.runtimeRoot,
- encoding: "utf8",
- stdio: "pipe",
- shell: process.platform === "win32",
- });
-
- if (result.error) throw result.error;
- if (result.status !== 0) throw new Error(formatInstallFailure(result));
-
- await writeInstallState(paths, {
- status: "ready",
- pluginVersion: expectedState.pluginVersion,
- manifestHash: expectedState.manifestHash,
- serverHash: expectedState.serverHash,
- pluginDataRoot: paths.pluginDataRoot,
- usingFallbackPluginData: paths.usingFallbackPluginData,
- });
-
- return true;
- } catch (err) {
- await rm(paths.runtimeNodeModulesPath, { recursive: true, force: true });
-
- await writeInstallState(paths, {
- status: "error",
- pluginVersion: expectedState.pluginVersion,
- manifestHash: expectedState.manifestHash,
- serverHash: expectedState.serverHash,
- pluginDataRoot: paths.pluginDataRoot,
- usingFallbackPluginData: paths.usingFallbackPluginData,
- error: err instanceof Error ? err.message : String(err),
- });
-
- throw err;
- } finally {
- await releaseLock();
- }
-}
-
-async function pathExists(target) {
- try {
- await access(target, fsConstants.F_OK);
- return true;
- } catch {
- return false;
- }
-}
-
-async function isStaleLock(lockDir) {
- try {
- const info = await stat(lockDir);
- return Date.now() - info.mtimeMs > LOCK_STALE_MS;
- } catch {
- return false;
- }
-}
-
-function sha256(...buffers) {
- const hash = createHash("sha256");
- for (const buf of buffers) hash.update(buf);
- return hash.digest("hex");
-}
-
-function getNpmCommand() {
- return process.platform === "win32" ? "npm.cmd" : "npm";
-}
-
-function installArgs() {
- return ["ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund"];
-}
-
-function formatInstallFailure(result) {
- const lines = [
- `npm ci exited with status ${result.status ?? "unknown"}`,
- trimOutput(result.stderr),
- trimOutput(result.stdout),
- ].filter(Boolean);
-
- return lines.join("\n");
-}
-
-function trimOutput(output) {
- if (!output) return "";
- const text = output.trim();
- if (!text) return "";
-
- const maxChars = 4000;
- if (text.length <= maxChars) return text;
- return text.slice(-maxChars);
-}
diff --git a/examples/codex-memory-plugin/scripts/start-memory-server.mjs b/examples/codex-memory-plugin/scripts/start-memory-server.mjs
deleted file mode 100644
index 423b79420..000000000
--- a/examples/codex-memory-plugin/scripts/start-memory-server.mjs
+++ /dev/null
@@ -1,54 +0,0 @@
-import { spawn } from "node:child_process";
-import {
- computeSourceState,
- ensureRuntimeInstalled,
- getRuntimePaths,
- loadInstallState,
-} from "./runtime-common.mjs";
-
-async function main() {
- const paths = getRuntimePaths();
- const expectedState = await computeSourceState(paths);
-
- try {
- await ensureRuntimeInstalled(paths, expectedState);
- } catch {
- const state = await loadInstallState(paths);
- const detail = state?.error ? ` Last install error: ${state.error}` : "";
- process.stderr.write(
- `[openviking-memory] MCP runtime is not ready in ${paths.runtimeRoot}.${detail}\n`,
- );
- process.exit(1);
- return;
- }
-
- const child = spawn(process.execPath, [paths.runtimeServerPath], {
- cwd: paths.runtimeRoot,
- env: process.env,
- stdio: "inherit",
- });
-
- for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
- process.on(signal, () => {
- if (!child.killed) child.kill(signal);
- });
- }
-
- child.on("error", (err) => {
- process.stderr.write(
- `[openviking-memory] Failed to start MCP server: ${err instanceof Error ? err.message : String(err)}\n`,
- );
- process.exit(1);
- });
-
- child.on("exit", (code) => {
- process.exit(code ?? 1);
- });
-}
-
-main().catch((err) => {
- process.stderr.write(
- `[openviking-memory] MCP launcher failed: ${err instanceof Error ? err.message : String(err)}\n`,
- );
- process.exit(1);
-});
diff --git a/examples/codex-memory-plugin/servers/memory-server.js b/examples/codex-memory-plugin/servers/memory-server.js
deleted file mode 100644
index 6dae16595..000000000
--- a/examples/codex-memory-plugin/servers/memory-server.js
+++ /dev/null
@@ -1,274 +0,0 @@
-import { createHash } from "node:crypto";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-// Shared with scripts/*.mjs so hook surface and MCP server resolve identity identically.
-// Compiled output lives in servers/memory-server.js, so the relative path stays valid.
-// @ts-ignore -- pure JS module, no type declarations
-import { loadConfig } from "../scripts/config.mjs";
-function md5Short(value) {
- return createHash("md5").update(value).digest("hex").slice(0, 12);
-}
-function clampScore(value) {
- if (typeof value !== "number" || Number.isNaN(value))
- return 0;
- return Math.max(0, Math.min(1, value));
-}
-function isMemoryUri(uri) {
- return /^viking:\/\/(?:user|agent)\/[^/]+\/memories(?:\/|$)/.test(uri);
-}
-function totalCommitMemories(result) {
- return Object.values(result.memories_extracted ?? {}).reduce((sum, count) => sum + count, 0);
-}
-function sleep(ms) {
- return new Promise((resolve) => setTimeout(resolve, ms));
-}
-const shared = loadConfig();
-const config = {
- configPath: shared.configPath,
- baseUrl: shared.baseUrl,
- apiKey: shared.apiKey,
- // The MCP server defaults missing account/user to "default" rather than "" so the
- // X-OpenViking-* headers carry a value; hooks leave them empty (server-side default).
- accountId: shared.account || "default",
- userId: shared.user || "default",
- agentId: shared.agentId || "codex",
- timeoutMs: shared.timeoutMs,
- recallLimit: shared.recallLimit,
- scoreThreshold: shared.scoreThreshold,
-};
-if (!config.baseUrl) {
- process.stderr.write("[openviking-memory] No OpenViking URL resolved. Set OPENVIKING_URL or provide ovcli.conf / ov.conf.\n");
- process.exit(1);
-}
-class OpenVikingClient {
- baseUrl;
- apiKey;
- accountId;
- userId;
- agentId;
- timeoutMs;
- runtimeIdentity = null;
- constructor(baseUrl, apiKey, accountId, userId, agentId, timeoutMs) {
- this.baseUrl = baseUrl;
- this.apiKey = apiKey;
- this.accountId = accountId;
- this.userId = userId;
- this.agentId = agentId;
- this.timeoutMs = timeoutMs;
- }
- async request(path, init = {}) {
- const controller = new AbortController();
- const timer = setTimeout(() => controller.abort(), this.timeoutMs);
- try {
- const headers = new Headers(init.headers ?? {});
- if (this.apiKey) {
- // OV Cloud only accepts Authorization: Bearer; self-hosted servers
- // still accept X-API-Key, so we emit both for transition compat.
- headers.set("Authorization", `Bearer ${this.apiKey}`);
- headers.set("X-API-Key", this.apiKey);
- }
- if (this.accountId)
- headers.set("X-OpenViking-Account", this.accountId);
- if (this.userId)
- headers.set("X-OpenViking-User", this.userId);
- if (this.agentId)
- headers.set("X-OpenViking-Agent", this.agentId);
- if (init.body && !headers.has("Content-Type"))
- headers.set("Content-Type", "application/json");
- const response = await fetch(`${this.baseUrl}${path}`, {
- ...init,
- headers,
- signal: controller.signal,
- });
- const payload = (await response.json().catch(() => ({})));
- if (!response.ok || payload.status === "error") {
- const code = payload.error?.code ? ` [${payload.error.code}]` : "";
- const message = payload.error?.message ?? `HTTP ${response.status}`;
- throw new Error(`OpenViking request failed${code}: ${message}`);
- }
- return (payload.result ?? payload);
- }
- finally {
- clearTimeout(timer);
- }
- }
- async healthCheck() {
- try {
- await this.request("/health");
- return true;
- }
- catch {
- return false;
- }
- }
- async getRuntimeIdentity() {
- if (this.runtimeIdentity)
- return this.runtimeIdentity;
- const fallback = { userId: this.userId || "default", agentId: this.agentId || "default" };
- try {
- const status = await this.request("/api/v1/system/status");
- const userId = typeof status.user === "string" && status.user.trim() ? status.user.trim() : fallback.userId;
- this.runtimeIdentity = { userId, agentId: this.agentId || "default" };
- return this.runtimeIdentity;
- }
- catch {
- this.runtimeIdentity = fallback;
- return fallback;
- }
- }
- async normalizeMemoryTargetUri(targetUri) {
- const trimmed = targetUri.trim().replace(/\/+$/, "");
- const match = trimmed.match(/^viking:\/\/(user|agent)\/memories(?:\/(.*))?$/);
- if (!match)
- return trimmed;
- const scope = match[1];
- const rest = match[2] ? `/${match[2]}` : "";
- const identity = await this.getRuntimeIdentity();
- const space = scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`);
- return `viking://${scope}/${space}/memories${rest}`;
- }
- async find(query, targetUri, limit, scoreThreshold) {
- const normalizedTargetUri = await this.normalizeMemoryTargetUri(targetUri);
- return this.request("/api/v1/search/find", {
- method: "POST",
- body: JSON.stringify({
- query,
- target_uri: normalizedTargetUri,
- limit,
- score_threshold: scoreThreshold,
- }),
- });
- }
- async read(uri) {
- return this.request(`/api/v1/content/read?uri=${encodeURIComponent(uri)}`);
- }
- async createSession() {
- const result = await this.request("/api/v1/sessions", {
- method: "POST",
- body: JSON.stringify({}),
- });
- return result.session_id;
- }
- async addSessionMessage(sessionId, role, content) {
- await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`, {
- method: "POST",
- body: JSON.stringify({ role, content }),
- });
- }
- async commitSession(sessionId) {
- const result = await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`, { method: "POST", body: JSON.stringify({}) });
- if (!result.task_id)
- return result;
- const deadline = Date.now() + Math.max(this.timeoutMs, 30000);
- while (Date.now() < deadline) {
- await sleep(500);
- const task = await this.getTask(result.task_id).catch(() => null);
- if (!task)
- break;
- if (task.status === "completed") {
- const taskResult = (task.result ?? {});
- return {
- ...result,
- status: "completed",
- memories_extracted: (taskResult.memories_extracted ?? {}),
- };
- }
- if (task.status === "failed")
- return { ...result, status: "failed", error: task.error };
- }
- return { ...result, status: "timeout" };
- }
- async getTask(taskId) {
- return this.request(`/api/v1/tasks/${encodeURIComponent(taskId)}`, { method: "GET" });
- }
- async deleteSession(sessionId) {
- await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
- }
- async deleteUri(uri) {
- await this.request(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, { method: "DELETE" });
- }
-}
-function formatMemoryResults(items) {
- return items
- .map((item, index) => {
- const summary = item.abstract?.trim() || item.overview?.trim() || item.uri;
- const score = Math.round(clampScore(item.score) * 100);
- return `${index + 1}. ${summary}\n URI: ${item.uri}\n Score: ${score}%`;
- })
- .join("\n\n");
-}
-const client = new OpenVikingClient(config.baseUrl, config.apiKey, config.accountId, config.userId, config.agentId, config.timeoutMs);
-const server = new McpServer({ name: "openviking-memory-codex", version: "0.1.0" });
-server.tool("openviking_recall", "Find OpenViking long-term memory.", {
- query: z.string().describe("Find query"),
- target_uri: z.string().optional().describe("Find scope URI, default viking://user/memories"),
- limit: z.number().optional().describe("Max results, default 6"),
- score_threshold: z.number().optional().describe("Minimum relevance score 0-1, default 0.01"),
-}, async ({ query, target_uri, limit, score_threshold }) => {
- const recallLimit = limit ?? config.recallLimit;
- const threshold = score_threshold ?? config.scoreThreshold;
- const result = await client.find(query, target_uri ?? "viking://user/memories", recallLimit, threshold);
- const items = [...(result.memories ?? []), ...(result.resources ?? []), ...(result.skills ?? [])]
- .filter((item) => clampScore(item.score) >= threshold)
- .sort((left, right) => clampScore(right.score) - clampScore(left.score))
- .slice(0, recallLimit);
- if (items.length === 0) {
- return { content: [{ type: "text", text: "No relevant OpenViking memories found." }] };
- }
- return { content: [{ type: "text", text: formatMemoryResults(items) }] };
-});
-server.tool("openviking_store", "Store information in OpenViking long-term memory.", {
- text: z.string().describe("Information to store"),
- role: z.string().optional().describe("Message role, default user"),
-}, async ({ text, role }) => {
- let sessionId;
- try {
- sessionId = await client.createSession();
- await client.addSessionMessage(sessionId, role || "user", text);
- const result = await client.commitSession(sessionId);
- const count = totalCommitMemories(result);
- if (result.status === "failed") {
- return { content: [{ type: "text", text: `Memory extraction failed: ${String(result.error)}` }] };
- }
- if (result.status === "timeout") {
- return {
- content: [{
- type: "text",
- text: `Memory extraction is still running (task_id=${result.task_id ?? "unknown"}).`,
- }],
- };
- }
- if (count === 0) {
- return {
- content: [{
- type: "text",
- text: "Committed session, but OpenViking extracted 0 memory item(s).",
- }],
- };
- }
- return { content: [{ type: "text", text: `Stored memory. Extracted ${count} item(s).` }] };
- }
- finally {
- if (sessionId)
- await client.deleteSession(sessionId).catch(() => { });
- }
-});
-server.tool("openviking_forget", "Delete an exact OpenViking memory URI. Use openviking_recall first if you only have a query.", {
- uri: z.string().describe("Exact memory URI to delete"),
-}, async ({ uri }) => {
- if (!isMemoryUri(uri)) {
- return { content: [{ type: "text", text: `Refusing to delete non-memory URI: ${uri}` }] };
- }
- await client.deleteUri(uri);
- return { content: [{ type: "text", text: `Deleted memory: ${uri}` }] };
-});
-server.tool("openviking_health", "Check whether the OpenViking server is reachable.", {}, async () => {
- const ok = await client.healthCheck();
- const text = ok
- ? `OpenViking is reachable at ${config.baseUrl}.`
- : `OpenViking is unreachable at ${config.baseUrl}.`;
- return { content: [{ type: "text", text }] };
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
diff --git a/examples/codex-memory-plugin/setup-helper/install.sh b/examples/codex-memory-plugin/setup-helper/install.sh
index bc03f92d5..bff51523b 100755
--- a/examples/codex-memory-plugin/setup-helper/install.sh
+++ b/examples/codex-memory-plugin/setup-helper/install.sh
@@ -11,6 +11,10 @@ MARKETPLACE_ROOT="${OPENVIKING_CODEX_MARKETPLACE_ROOT:-$HOME/.codex/${MARKETPLAC
PLUGIN_NAME="openviking-memory"
PLUGIN_ID="${PLUGIN_NAME}@${MARKETPLACE_NAME}"
CODEX_CONFIG="${CODEX_CONFIG_FILE:-$HOME/.codex/config.toml}"
+OVCLI_CONF="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+DEFAULT_MCP_URL="http://127.0.0.1:1933/mcp"
+WRAPPER_MARKER_BEGIN="# >>> openviking-codex-plugin >>>"
+WRAPPER_MARKER_END="# <<< openviking-codex-plugin <<<"
need() {
command -v "$1" >/dev/null 2>&1 || {
@@ -49,7 +53,39 @@ if [ ! -d "$PLUGIN_DIR/.codex-plugin" ]; then
exit 1
fi
-PLUGIN_VERSION="$(node -e 'const p=require(process.argv[1]); console.log(p.version || "0.0.0")' "$PLUGIN_DIR/package.json")"
+PLUGIN_VERSION="$(node -e 'const p=require(process.argv[1]); console.log(p.version || "0.0.0")' "$PLUGIN_DIR/.codex-plugin/plugin.json")"
+
+# Resolve the OpenViking /mcp endpoint at install time. Priority:
+# OPENVIKING_MCP_URL (env, full /mcp URL) > OPENVIKING_URL (env, base URL) >
+# ovcli.conf .url > default localhost.
+resolve_mcp_url() {
+ if [ -n "${OPENVIKING_MCP_URL:-}" ]; then
+ printf '%s' "$OPENVIKING_MCP_URL"
+ return
+ fi
+ if [ -n "${OPENVIKING_URL:-}" ]; then
+ printf '%s/mcp' "${OPENVIKING_URL%/}"
+ return
+ fi
+ if [ -f "$OVCLI_CONF" ] && command -v node >/dev/null 2>&1; then
+ local from_conf
+ from_conf="$(node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ if (typeof c.url === "string" && c.url) {
+ process.stdout.write(c.url.replace(/\/+$/, "") + "/mcp");
+ }
+ } catch {}
+ ' "$OVCLI_CONF" 2>/dev/null || true)"
+ if [ -n "$from_conf" ]; then
+ printf '%s' "$from_conf"
+ return
+ fi
+ fi
+ printf '%s' "$DEFAULT_MCP_URL"
+}
+
+MCP_URL="$(resolve_mcp_url)"
mkdir -p "$MARKETPLACE_ROOT/.claude-plugin"
rm -f "$MARKETPLACE_ROOT/$PLUGIN_NAME"
@@ -159,19 +195,131 @@ if [ -f "$HOOKS_JSON" ]; then
rm -f "${HOOKS_JSON}.bak"
fi
-if [ ! -f "$HOME/.openviking/ovcli.conf" ]; then
- cat >&2 <<'EOF'
+# Render the OpenViking /mcp URL into the cached .mcp.json. The repo's
+# checked-in .mcp.json keeps the __OPENVIKING_MCP_URL__ placeholder.
+MCP_JSON="$CACHE_DIR/.mcp.json"
+if [ -f "$MCP_JSON" ]; then
+ MCP_URL_ESC="$(printf '%s' "$MCP_URL" | sed -e 's/[\\/&]/\\&/g')"
+ sed -i.bak -e "s|__OPENVIKING_MCP_URL__|$MCP_URL_ESC|g" "$MCP_JSON"
+ rm -f "${MCP_JSON}.bak"
+fi
+
+# ----- Shell rc wrapper -----
+#
+# The MCP server reads OPENVIKING_API_KEY (and OPENVIKING_ACCOUNT / _USER /
+# _AGENT_ID) from the process env at codex launch. Add a `codex` shell function
+# that pulls these from ovcli.conf at invocation time so the user doesn't have
+# to `export` secrets globally.
+
+case "${SHELL:-}" in
+ */zsh) RC="$HOME/.zshrc" ;;
+ */bash) RC="$HOME/.bashrc" ;;
+ *)
+ if [ -f "$HOME/.zshrc" ]; then RC="$HOME/.zshrc"
+ elif [ -f "$HOME/.bashrc" ]; then RC="$HOME/.bashrc"
+ else RC=""; fi
+ ;;
+esac
+
+# The wrapper uses `node` (already a hard requirement of this installer) to
+# parse ovcli.conf instead of `jq`. This avoids a silent-auth-loss failure
+# mode where `jq` is missing on the user's machine, the wrapper's
+# `command -v jq` check fails, and codex starts with no Bearer token →
+# OpenViking returns 401 → Codex falls back to OAuth.
+read -r -d '' WRAPPER_BODY <<'WRAPPER' || true
+codex() {
+ local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
+ local _ov_env
+ _ov_env=$(node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";
+ process.stdout.write(
+ out("OV_URL", c.url) +
+ out("OV_KEY", c.api_key) +
+ out("OV_ACCOUNT", c.account) +
+ out("OV_USER", c.user)
+ );
+ } catch {}
+ ' "$_ov_conf" 2>/dev/null)
+ eval "$_ov_env"
+ OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
+ OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
+ OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
+ OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
+ OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
+ command codex "$@"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ else
+ command codex "$@"
+ fi
+}
+WRAPPER
+
+# Wrap the function body with marker lines.
+WRAPPER_BLOCK="$WRAPPER_MARKER_BEGIN
+$WRAPPER_BODY
+$WRAPPER_MARKER_END"
-Note: ~/.openviking/ovcli.conf was not found.
-The plugin will use http://127.0.0.1:1933 unless OPENVIKING_URL / OPENVIKING_API_KEY are set.
+if [ -z "$RC" ]; then
+ cat >&2 <<EOF
+
+Note: could not detect a shell rc to install the codex() wrapper into.
+Add this snippet to your rc manually so OPENVIKING_API_KEY reaches codex:
+
+$WRAPPER_BLOCK
+EOF
+else
+ touch "$RC"
+ if grep -qF "$WRAPPER_MARKER_BEGIN" "$RC"; then
+ # Replace existing block in place — only if BOTH markers are present, so
+ # a corrupted rc (manual edit that lost the END marker) cannot cause us
+ # to drop everything from the BEGIN marker to EOF. Otherwise leave the
+ # file untouched and append a fresh block, so the user can inspect what
+ # they have and clean up themselves.
+ if grep -qF "$WRAPPER_MARKER_END" "$RC"; then
+ echo "Replacing existing openviking codex() wrapper in $RC"
+ awk -v b="$WRAPPER_MARKER_BEGIN" -v e="$WRAPPER_MARKER_END" '
+ $0 == b {skip=1; next}
+ $0 == e {skip=0; next}
+ !skip
+ ' "$RC" > "$RC.tmp" && mv "$RC.tmp" "$RC"
+ else
+ cat >&2 <<EOF
+Warning: $WRAPPER_MARKER_BEGIN found in $RC but $WRAPPER_MARKER_END is missing.
+Refusing to in-place rewrite; appending a fresh block instead. Please
+remove the stray begin marker manually.
+EOF
+ fi
+ else
+ echo "Appending codex() wrapper to $RC"
+ fi
+ printf '\n%s\n' "$WRAPPER_BLOCK" >> "$RC"
+fi
+
+if [ ! -f "$OVCLI_CONF" ]; then
+ cat >&2 <<EOF
+
+Note: $OVCLI_CONF was not found.
+The plugin will hit $MCP_URL with no Bearer token.
+Either create ovcli.conf (see https://docs.openviking.ai/zh/guides/03-deployment#cli)
+or export OPENVIKING_URL / OPENVIKING_API_KEY before running codex.
EOF
fi
cat <<EOF
-Installed $PLUGIN_ID.
+
+Installed $PLUGIN_ID (version $PLUGIN_VERSION).
Marketplace: $MARKETPLACE_ROOT
Plugin cache: $CACHE_DIR
+MCP endpoint: $MCP_URL
-Restart Codex with:
- codex
+Next:
EOF
+if [ -n "$RC" ]; then
+ echo " source $RC # pick up the codex() wrapper"
+else
+ echo " (paste the codex() snippet printed above into your shell rc, then restart your shell)"
+fi
+echo " codex # restart codex; review /hooks if prompted"
diff --git a/examples/codex-memory-plugin/src/memory-server.ts b/examples/codex-memory-plugin/src/memory-server.ts
deleted file mode 100644
index 12520309e..000000000
--- a/examples/codex-memory-plugin/src/memory-server.ts
+++ /dev/null
@@ -1,374 +0,0 @@
-import { createHash } from "node:crypto"
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
-import { z } from "zod"
-// Shared with scripts/*.mjs so hook surface and MCP server resolve identity identically.
-// Compiled output lives in servers/memory-server.js, so the relative path stays valid.
-// @ts-ignore -- pure JS module, no type declarations
-import { loadConfig } from "../scripts/config.mjs"
-
-type FindResultItem = {
- uri: string
- level?: number
- abstract?: string
- overview?: string
- category?: string
- score?: number
-}
-
-type FindResult = {
- memories?: FindResultItem[]
- resources?: FindResultItem[]
- skills?: FindResultItem[]
-}
-
-type CommitSessionResult = {
- task_id?: string
- status?: string
- memories_extracted?: Record<string, number>
- error?: unknown
-}
-
-type TaskResult = {
- status?: string
- result?: Record<string, unknown>
- error?: unknown
-}
-
-type SystemStatus = {
- user?: unknown
-}
-
-function md5Short(value: string): string {
- return createHash("md5").update(value).digest("hex").slice(0, 12)
-}
-
-function clampScore(value: number | undefined): number {
- if (typeof value !== "number" || Number.isNaN(value)) return 0
- return Math.max(0, Math.min(1, value))
-}
-
-function isMemoryUri(uri: string): boolean {
- return /^viking:\/\/(?:user|agent)\/[^/]+\/memories(?:\/|$)/.test(uri)
-}
-
-function totalCommitMemories(result: CommitSessionResult): number {
- return Object.values(result.memories_extracted ?? {}).reduce((sum, count) => sum + count, 0)
-}
-
-function sleep(ms: number): Promise<void> {
- return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
-const shared = loadConfig() as {
- baseUrl: string
- apiKey: string
- account: string
- user: string
- agentId: string
- timeoutMs: number
- recallLimit: number
- scoreThreshold: number
- configPath: string | null
-}
-
-const config = {
- configPath: shared.configPath,
- baseUrl: shared.baseUrl,
- apiKey: shared.apiKey,
- // The MCP server defaults missing account/user to "default" rather than "" so the
- // X-OpenViking-* headers carry a value; hooks leave them empty (server-side default).
- accountId: shared.account || "default",
- userId: shared.user || "default",
- agentId: shared.agentId || "codex",
- timeoutMs: shared.timeoutMs,
- recallLimit: shared.recallLimit,
- scoreThreshold: shared.scoreThreshold,
-}
-
-if (!config.baseUrl) {
- process.stderr.write(
- "[openviking-memory] No OpenViking URL resolved. Set OPENVIKING_URL or provide ovcli.conf / ov.conf.\n",
- )
- process.exit(1)
-}
-
-class OpenVikingClient {
- private runtimeIdentity: { userId: string; agentId: string } | null = null
-
- constructor(
- private readonly baseUrl: string,
- private readonly apiKey: string,
- private readonly accountId: string,
- private readonly userId: string,
- private readonly agentId: string,
- private readonly timeoutMs: number,
- ) {}
-
- private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
- const controller = new AbortController()
- const timer = setTimeout(() => controller.abort(), this.timeoutMs)
-
- try {
- const headers = new Headers(init.headers ?? {})
- if (this.apiKey) {
- // OV Cloud only accepts Authorization: Bearer; self-hosted servers
- // still accept X-API-Key, so we emit both for transition compat.
- headers.set("Authorization", `Bearer ${this.apiKey}`)
- headers.set("X-API-Key", this.apiKey)
- }
- if (this.accountId) headers.set("X-OpenViking-Account", this.accountId)
- if (this.userId) headers.set("X-OpenViking-User", this.userId)
- if (this.agentId) headers.set("X-OpenViking-Agent", this.agentId)
- if (init.body && !headers.has("Content-Type")) headers.set("Content-Type", "application/json")
-
- const response = await fetch(`${this.baseUrl}${path}`, {
- ...init,
- headers,
- signal: controller.signal,
- })
- const payload = (await response.json().catch(() => ({}))) as {
- status?: string
- result?: T
- error?: { code?: string; message?: string }
- }
-
- if (!response.ok || payload.status === "error") {
- const code = payload.error?.code ? ` [${payload.error.code}]` : ""
- const message = payload.error?.message ?? `HTTP ${response.status}`
- throw new Error(`OpenViking request failed${code}: ${message}`)
- }
-
- return (payload.result ?? payload) as T
- } finally {
- clearTimeout(timer)
- }
- }
-
- async healthCheck(): Promise<boolean> {
- try {
- await this.request("/health")
- return true
- } catch {
- return false
- }
- }
-
- private async getRuntimeIdentity(): Promise<{ userId: string; agentId: string }> {
- if (this.runtimeIdentity) return this.runtimeIdentity
-
- const fallback = { userId: this.userId || "default", agentId: this.agentId || "default" }
- try {
- const status = await this.request<SystemStatus>("/api/v1/system/status")
- const userId = typeof status.user === "string" && status.user.trim() ? status.user.trim() : fallback.userId
- this.runtimeIdentity = { userId, agentId: this.agentId || "default" }
- return this.runtimeIdentity
- } catch {
- this.runtimeIdentity = fallback
- return fallback
- }
- }
-
- async normalizeMemoryTargetUri(targetUri: string): Promise<string> {
- const trimmed = targetUri.trim().replace(/\/+$/, "")
- const match = trimmed.match(/^viking:\/\/(user|agent)\/memories(?:\/(.*))?$/)
- if (!match) return trimmed
-
- const scope = match[1]
- const rest = match[2] ? `/${match[2]}` : ""
- const identity = await this.getRuntimeIdentity()
- const space = scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`)
- return `viking://${scope}/${space}/memories${rest}`
- }
-
- async find(query: string, targetUri: string, limit: number, scoreThreshold: number): Promise<FindResult> {
- const normalizedTargetUri = await this.normalizeMemoryTargetUri(targetUri)
- return this.request<FindResult>("/api/v1/search/find", {
- method: "POST",
- body: JSON.stringify({
- query,
- target_uri: normalizedTargetUri,
- limit,
- score_threshold: scoreThreshold,
- }),
- })
- }
-
- async read(uri: string): Promise<string> {
- return this.request<string>(`/api/v1/content/read?uri=${encodeURIComponent(uri)}`)
- }
-
- async createSession(): Promise<string> {
- const result = await this.request<{ session_id: string }>("/api/v1/sessions", {
- method: "POST",
- body: JSON.stringify({}),
- })
- return result.session_id
- }
-
- async addSessionMessage(sessionId: string, role: string, content: string): Promise<void> {
- await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`, {
- method: "POST",
- body: JSON.stringify({ role, content }),
- })
- }
-
- async commitSession(sessionId: string): Promise<CommitSessionResult> {
- const result = await this.request<CommitSessionResult>(
- `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
- { method: "POST", body: JSON.stringify({}) },
- )
-
- if (!result.task_id) return result
-
- const deadline = Date.now() + Math.max(this.timeoutMs, 30000)
- while (Date.now() < deadline) {
- await sleep(500)
- const task = await this.getTask(result.task_id).catch(() => null)
- if (!task) break
- if (task.status === "completed") {
- const taskResult = (task.result ?? {}) as Record<string, unknown>
- return {
- ...result,
- status: "completed",
- memories_extracted: (taskResult.memories_extracted ?? {}) as Record<string, number>,
- }
- }
- if (task.status === "failed") return { ...result, status: "failed", error: task.error }
- }
-
- return { ...result, status: "timeout" }
- }
-
- async getTask(taskId: string): Promise<TaskResult> {
- return this.request<TaskResult>(`/api/v1/tasks/${encodeURIComponent(taskId)}`, { method: "GET" })
- }
-
- async deleteSession(sessionId: string): Promise<void> {
- await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" })
- }
-
- async deleteUri(uri: string): Promise<void> {
- await this.request(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, { method: "DELETE" })
- }
-}
-
-function formatMemoryResults(items: FindResultItem[]): string {
- return items
- .map((item, index) => {
- const summary = item.abstract?.trim() || item.overview?.trim() || item.uri
- const score = Math.round(clampScore(item.score) * 100)
- return `${index + 1}. ${summary}\n URI: ${item.uri}\n Score: ${score}%`
- })
- .join("\n\n")
-}
-
-const client = new OpenVikingClient(
- config.baseUrl,
- config.apiKey,
- config.accountId,
- config.userId,
- config.agentId,
- config.timeoutMs,
-)
-const server = new McpServer({ name: "openviking-memory-codex", version: "0.1.0" })
-
-server.tool(
- "openviking_recall",
- "Find OpenViking long-term memory.",
- {
- query: z.string().describe("Find query"),
- target_uri: z.string().optional().describe("Find scope URI, default viking://user/memories"),
- limit: z.number().optional().describe("Max results, default 6"),
- score_threshold: z.number().optional().describe("Minimum relevance score 0-1, default 0.01"),
- },
- async ({ query, target_uri, limit, score_threshold }) => {
- const recallLimit = limit ?? config.recallLimit
- const threshold = score_threshold ?? config.scoreThreshold
- const result = await client.find(query, target_uri ?? "viking://user/memories", recallLimit, threshold)
- const items = [...(result.memories ?? []), ...(result.resources ?? []), ...(result.skills ?? [])]
- .filter((item) => clampScore(item.score) >= threshold)
- .sort((left, right) => clampScore(right.score) - clampScore(left.score))
- .slice(0, recallLimit)
-
- if (items.length === 0) {
- return { content: [{ type: "text" as const, text: "No relevant OpenViking memories found." }] }
- }
-
- return { content: [{ type: "text" as const, text: formatMemoryResults(items) }] }
- },
-)
-
-server.tool(
- "openviking_store",
- "Store information in OpenViking long-term memory.",
- {
- text: z.string().describe("Information to store"),
- role: z.string().optional().describe("Message role, default user"),
- },
- async ({ text, role }) => {
- let sessionId: string | undefined
- try {
- sessionId = await client.createSession()
- await client.addSessionMessage(sessionId, role || "user", text)
- const result = await client.commitSession(sessionId)
- const count = totalCommitMemories(result)
-
- if (result.status === "failed") {
- return { content: [{ type: "text" as const, text: `Memory extraction failed: ${String(result.error)}` }] }
- }
- if (result.status === "timeout") {
- return {
- content: [{
- type: "text" as const,
- text: `Memory extraction is still running (task_id=${result.task_id ?? "unknown"}).`,
- }],
- }
- }
- if (count === 0) {
- return {
- content: [{
- type: "text" as const,
- text: "Committed session, but OpenViking extracted 0 memory item(s).",
- }],
- }
- }
-
- return { content: [{ type: "text" as const, text: `Stored memory. Extracted ${count} item(s).` }] }
- } finally {
- if (sessionId) await client.deleteSession(sessionId).catch(() => {})
- }
- },
-)
-
-server.tool(
- "openviking_forget",
- "Delete an exact OpenViking memory URI. Use openviking_recall first if you only have a query.",
- {
- uri: z.string().describe("Exact memory URI to delete"),
- },
- async ({ uri }) => {
- if (!isMemoryUri(uri)) {
- return { content: [{ type: "text" as const, text: `Refusing to delete non-memory URI: ${uri}` }] }
- }
-
- await client.deleteUri(uri)
- return { content: [{ type: "text" as const, text: `Deleted memory: ${uri}` }] }
- },
-)
-
-server.tool(
- "openviking_health",
- "Check whether the OpenViking server is reachable.",
- {},
- async () => {
- const ok = await client.healthCheck()
- const text = ok
- ? `OpenViking is reachable at ${config.baseUrl}.`
- : `OpenViking is unreachable at ${config.baseUrl}.`
- return { content: [{ type: "text" as const, text }] }
- },
-)
-
-const transport = new StdioServerTransport()
-await server.connect(transport)
diff --git a/examples/codex-memory-plugin/tsconfig.json b/examples/codex-memory-plugin/tsconfig.json
deleted file mode 100644
index 7f284c9a1..000000000
--- a/examples/codex-memory-plugin/tsconfig.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
- "compilerOptions": {
- "target": "ES2022",
- "module": "ESNext",
- "moduleResolution": "bundler",
- "outDir": "./servers",
- "rootDir": "./src",
- "strict": true,
- "esModuleInterop": true,
- "skipLibCheck": true,
- "declaration": false,
- "sourceMap": false
- },
- "include": ["src/**/*.ts"]
-}