Skip to content

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

docs: refresh Claude Code & Codex memory plugin integration docs (#2457)

t0saki0f6160edafa9
diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.md
index 1c14b2f13..0332fb9b1 100644
--- a/docs/en/agent-integrations/02-claude-code.md
+++ b/docs/en/agent-integrations/02-claude-code.md
@@ -1,6 +1,6 @@
# Claude Code Memory Plugin
-Give [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) a cross-project, cross-session memory that grows smarter over time. Install once — recall and capture happen automatically on every conversation, no MCP tool calls required from the model.
+Give [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) cross-project and cross-session long-term memory. Once installed, every conversation automatically recalls relevant memories and captures new content without requiring the model to make any tool calls.
Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [Blog: motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -10,31 +10,44 @@ Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenV
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
```
-The installer checks dependencies, configures your OpenViking connection, and installs the plugin. Every step is idempotent — re-running is safe.
+The installer checks dependencies, configures your OpenViking connection, and installs the plugin. Every step is idempotent—re-running it is entirely safe.
-After install, start Claude Code and ask it something from a previous session. It remembers.
+After installation, activate the `claude` wrapper in your current terminal (or simply open a new terminal window):
+
+```bash
+source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh
+```
+
+After using it for a while, try starting a new conversation and asking about something you mentioned earlier—it will remember.
<details>
<summary><b>Manual setup</b></summary>
-If you prefer to set things up by hand:
+If you prefer to set it up manually:
-1. **Shell function wrapper** — append a `claude()` function to `~/.zshrc` or `~/.bashrc` that injects `OPENVIKING_URL` and `OPENVIKING_API_KEY` from `~/.openviking/ovcli.conf` at each invocation. This keeps the API key scoped to the `claude` process tree. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf) for the full function and security rationale.
+1. **Wrap `claude`**: Add these two lines to the end of your `~/.zshrc` (for zsh) or `~/.bashrc` (for bash), replacing `<repo-path>` with the absolute path to your local repository. This ensures each `claude` invocation injects `OPENVIKING_URL` and `OPENVIKING_API_KEY` from `~/.openviking/ovcli.conf`, keeping the API key scoped to the `claude` process tree:
-2. **Install the plugin** from the OpenViking repo root:
+ ```bash
+ _ov_wrapper="<repo-path>/examples/claude-code-memory-plugin/setup-helper/wrapper.sh"
+ [ -f "$_ov_wrapper" ] && source "$_ov_wrapper"
+ ```
+
+ For details on the function implementation and why a global `export` is not used, see the [plugin README → Configuring MCP](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuring-mcp).
+
+2. **Install the plugin** from the OpenViking repository root:
```bash
claude plugin marketplace add "$(pwd)/examples"
claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-3. **Start Claude Code** and run `/mcp` to confirm the OpenViking entry shows your server URL.
+3. **Start Claude Code** and run `/mcp` to verify that the OpenViking entry displays your server URL.
-> Don't have `ovcli.conf` yet? See [Deployment Guide → CLI](../guides/03-deployment.md#cli).
+> Don't have `ovcli.conf` yet? See the [Deployment Guide → CLI](../guides/03-deployment.md#cli).
>
-> Pure local mode (`http://127.0.0.1:1933`, no auth)? Skip step 1 — the plugin uses the local default.
+> Using pure local mode (`http://127.0.0.1:1933`, no authentication)? Skip step 1—the plugin automatically defaults to the local setup.
>
-> Claude Code < 2.0? See the [plugin README's Legacy mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20).
+> Running Claude Code < 2.0? See the [Legacy mode section in the plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20).
</details>
@@ -44,22 +57,32 @@ If you prefer to set things up by hand:
type claude # expect: claude is a shell function
```
-Inside Claude Code:
+> If the previous command printed a path instead of `shell function`, the wrapper isn't active yet. Re-source it (or open a new terminal) before launching `claude`, otherwise it silently connects to `127.0.0.1` with no auth.
+
+Launch `claude` from the terminal where `type claude` reports a shell function, then:
-- `/plugins` → find **openviking-memory** in Installed (with **openviking** MCP connected underneath)
-- `/mcp` → the OpenViking entry should show your server URL with valid auth
-- `/openviking-memory:ov` → shows server health, identity, recall/injection stats, and toggle states
+- `/plugins` → Verify that **openviking-memory** is listed under "Installed", with the **openviking** MCP connected below it.
+- `/mcp` → Ensure the OpenViking entry displays your server URL along with valid authentication.
+- `/openviking-memory:ov` → View server health, identity, recall/injection statistics, and toggle states.
-If the plugin doesn't seem to fire, set `OPENVIKING_DEBUG=1` and check `~/.openviking/logs/cc-hooks.log`.
+If the plugin does not seem to activate, set `OPENVIKING_DEBUG=1` and check the logs at `~/.openviking/logs/cc-hooks.log`.
## How it works
-The plugin hooks into Claude Code's lifecycle: it searches OpenViking and injects relevant memories before every prompt, captures new conversation turns after each response, injects your profile and memory index on session start, commits pending messages before compaction and on session end, and gives each subagent an isolated memory session. All write operations run asynchronously so you never wait for OpenViking.
+The plugin hooks into the Claude Code lifecycle:
+
+- **Before every prompt** — searches OpenViking and injects relevant memories
+- **After each response** — captures new conversation turns
+- **On session start** — injects your profile and memory index
+- **Before compaction and on session end** — commits pending messages
+- **For each subagent** — assigns an isolated memory session
+
+All write operations run asynchronously, ensuring they never block your conversation.
<details>
<summary><b>Configuration</b></summary>
-Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).
+Configuration priority: Environment variables > `ovcli.conf` > `ov.conf` > Built-in defaults (`http://127.0.0.1:1933`, no authentication).
| Env Var | Default | Description |
|---------|---------|-------------|
@@ -72,26 +95,26 @@ Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http:
| `OPENVIKING_MEMORY_ENABLED` | (auto) | Force on/off |
| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/cc-hooks.log` |
-For multi-tenant deployments, set `OPENVIKING_ACCOUNT` and `OPENVIKING_USER`. Full env-var list in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration).
+For multi-tenant deployments, configure `OPENVIKING_ACCOUNT` and `OPENVIKING_USER`. The complete list of environment variables is available in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration).
</details>
## Statusline
-The plugin renders an OpenViking status indicator under your Claude Code input box — connection health, recall count, capture progress, and session state at a glance. See [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md) for the full segment glossary and personalization recipes.
+The plugin renders an OpenViking status indicator beneath your Claude Code input box, allowing you to check connection health, recall count, capture progress, and session state at a glance. See [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md) for a complete glossary of segments and personalization recipes.
## Troubleshooting
-| Symptom | Cause | Fix |
+| Issue | Cause | Solution |
|---------|-------|-----|
-| Plugin not activating | No `ov.conf` / `ovcli.conf` found | Run the [installer](#install), or set `OPENVIKING_MEMORY_ENABLED=1` plus URL/API_KEY env vars |
-| Hooks fire but recall is empty | Server not running or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| MCP tools hit `127.0.0.1` instead of remote | Missing function wrapper | Ensure `type claude` says "shell function"; see [Manual setup](#install) |
-| Remote auth 401 / 403 | Wrong API key or missing tenant headers | Check `OPENVIKING_API_KEY`; for multi-tenant also check `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
+| Plugin is not activating | Missing `ov.conf` or `ovcli.conf` | Run the [installer](#install), or set `OPENVIKING_MEMORY_ENABLED=1` along with the URL/API_KEY environment variables |
+| Hooks fire but recall is empty | Server is not running or the URL is incorrect | Check server health: `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| MCP tools hit `127.0.0.1` instead of the remote server | Missing function wrapper | Ensure `type claude` outputs "shell function"; see [Manual setup](#install) |
+| Remote auth 401 / 403 | Incorrect API key or missing tenant headers | Verify `OPENVIKING_API_KEY`; for multi-tenant setups, also check `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
## See also
-- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — motivation, architecture overview, and demo
-- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — full env-var tables, hook details, architecture diagram
-- [MCP Clients](./06-mcp-clients.md) — for MCP tool parameters and other clients
-- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup
+- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — Motivation, architecture overview, and demo
+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — Full environment variable tables, hook details, and architecture diagrams
+- [MCP Clients](./06-mcp-clients.md) — Information on MCP tool parameters and other clients
+- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup instructions
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index 2f3328363..dc3905439 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -1,8 +1,8 @@
# Codex Memory Plugin
-Give [Codex](https://developers.openai.com/codex) persistent memory across sessions. Install once — memories are recalled on every prompt, captured after each turn, and committed before compaction. The plugin also wires Codex up to OpenViking's `/mcp` endpoint so the model can search, store, and manage memories directly.
+Equip [Codex](https://developers.openai.com/codex) with persistent memory across sessions. Install it once, and memories will be automatically recalled with every prompt, captured after each turn, and committed before compaction. The plugin also connects Codex to OpenViking's `/mcp` endpoint, enabling the model to search, store, and manage memories directly.
-Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)
+Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: Motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)
## Install
@@ -12,44 +12,46 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Every step is idempotent.
-After install:
+After installation, activate the `codex` wrapper in your current terminal (or open a new terminal window):
```bash
-source ~/.zshrc # or ~/.bashrc
-codex # first run: approve hooks once when prompted via /hooks
+source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
+codex # First run: approve hooks once when prompted via /hooks
```
<details>
<summary><b>Manual setup</b></summary>
-Prerequisites: Node.js >= 22, Codex >= 0.130.0, `codex_hooks` feature enabled.
+Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `codex_hooks` feature enabled.
-1. **Shell function wrapper** — append a `codex()` function to your shell rc that injects OpenViking env vars from `ovcli.conf`. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) for the full function.
+1. **Shell function wrapper** — Append a `codex()` function to your shell profile (e.g., `.bashrc` or `.zshrc`) to inject OpenViking environment variables from `ovcli.conf`. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) for the full function.
-2. **Plugin install** — register a local marketplace and enable the plugin. See `setup-helper/install.sh` for the exact commands.
+2. **Plugin installation** — Register a local marketplace and enable the plugin. See `setup-helper/install.sh` for the exact commands.
-3. **Placeholder rendering** — the checked-in `.mcp.json` and `hooks.json` contain placeholders that must be substituted when copied to Codex's plugin cache. The installer does this automatically.
+3. **Placeholder rendering** — The provided `.mcp.json` and `hooks.json` files contain placeholders that must be substituted when copied to Codex's plugin cache. The automated installer handles this for you.
</details>
## Verify
```bash
-type codex # expect: codex is a shell function
+type codex # Expectation: codex is a shell function
```
-Inside Codex, the plugin should recall memories on each prompt. Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.
+> If the previous command printed a path instead of `shell function`, the wrapper isn't active yet. Re-source it (or open a new terminal) before launching, otherwise codex starts without `OPENVIKING_API_KEY` and reports `MCP server is not logged in`.
+
+Once inside Codex, the plugin should seamlessly recall memories on every prompt. Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.
## How it works
-The plugin hooks into Codex's lifecycle: it searches OpenViking and injects relevant memories before every prompt (`UserPromptSubmit`), appends new turns to the session after each response (`Stop`), and commits the full transcript before compaction (`PreCompact`) so memory extraction runs against the complete conversation. On fresh session start, it also cleans up orphaned sessions from prior runs.
+The plugin integrates with Codex's lifecycle by hooking into key events. It searches OpenViking and injects relevant memories before every prompt (`UserPromptSubmit`), appends new turns to the session after each response (`Stop`), and commits the full transcript before compaction (`PreCompact`) to ensure memory extraction processes the entire conversation. Upon starting a fresh session, it also cleans up any orphaned sessions from previous runs.
-> **Known gap**: Codex fires no hook on `SIGTERM` / `Ctrl+C` / `/exit`. Orphaned sessions are recovered by the next `SessionStart`'s idle-TTL sweep (30 min) or active-window heuristic.
+> **Known limitation**: Codex does not fire a hook upon `SIGTERM`, `Ctrl+C`, or `/exit`. Orphaned sessions are recovered during the next `SessionStart` via the idle-TTL sweep (30 minutes) or the active-window heuristic.
<details>
<summary><b>Configuration</b></summary>
-Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).
+Configuration priority: Environment variables > `ovcli.conf` > `ov.conf` > Built-in defaults (`http://127.0.0.1:1933`, no authentication).
| Env Var | Default | Description |
|---------|---------|-------------|
@@ -59,7 +61,7 @@ Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http:
| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle-TTL sweep threshold |
| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/codex-hooks.log` |
-Tuning knobs (`OPENVIKING_RECALL_LIMIT`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS`, etc.) are documented in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).
+Additional tuning options (e.g., `OPENVIKING_RECALL_LIMIT`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS`) are documented in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).
</details>
@@ -67,16 +69,16 @@ Tuning knobs (`OPENVIKING_RECALL_LIMIT`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS`, e
| Symptom | Cause | Fix |
|---------|-------|-----|
-| `MCP server is not logged in` | `OPENVIKING_API_KEY` not in env at launch | Ensure `codex()` shell function is sourced and `ovcli.conf` has `api_key` |
-| `4 hooks need review` | First-launch security review | Run `/hooks` in Codex and approve |
-| `hook (failed) exited with code 1` | Stale placeholder in plugin cache | Re-run the one-line installer |
-| Recall returns nothing | Server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| Hook 401 but MCP works (or vice versa) | env vs ovcli.conf mismatch | Hooks re-read ovcli.conf every fire; MCP reads env at startup. Restart codex. |
+| `MCP server is not logged in` | `OPENVIKING_API_KEY` not in env at launch | Ensure the `codex()` shell function is sourced and `ovcli.conf` contains a valid `api_key`. |
+| `4 hooks need review` | Security review on first launch | Run `/hooks` within Codex and approve the hooks. |
+| `hook (failed) exited with code 1` | Stale placeholders in the plugin cache | Re-run the one-line installer. |
+| Recall returns nothing | Server is unreachable or the URL is incorrect | Check the endpoint: `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| Hook 401 but MCP works (or vice versa) | Mismatch between environment variables and `ovcli.conf` | Hooks re-read `ovcli.conf` on every execution, whereas MCP reads environment variables only at startup. Restart Codex to sync. |
## See also
-- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — motivation, architecture overview, and demo
-- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — full env-var list, architecture diagram
-- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit decision tree
-- [MCP Clients](./06-mcp-clients.md) — MCP protocol, tools, and other clients
-- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup
+- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — Motivation, architecture overview, and demo.
+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — Full environment variable list and architecture diagram.
+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — Commit decision tree.
+- [MCP Clients](./06-mcp-clients.md) — MCP protocol, tools, and other clients.
+- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup instructions.
diff --git a/docs/images/agents/en/claude-code.md b/docs/images/agents/en/claude-code.md
index 70990982c..01863e23f 100644
--- a/docs/images/agents/en/claude-code.md
+++ b/docs/images/agents/en/claude-code.md
@@ -1,4 +1,4 @@
-Add cross-project, cross-session long-term memory to [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). Install once; every conversation automatically recalls and captures memory, and the model does not need to call any tools manually.
+Add cross-project, cross-session long-term memory to [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). After installation, every conversation automatically recalls relevant memories and captures new content, with no tool calls required from the model.
Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [Blog: motivation and demo](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -10,14 +10,27 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
The installer checks dependencies, configures the OpenViking connection, and installs the plugin. Each step is idempotent, so it is safe to rerun.
-After installation, start Claude Code and ask what you discussed in the previous session. It should remember.
+After installation, activate the `claude` wrapper in your current terminal, or simply open a new terminal window:
+
+```bash
+source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh
+```
+
+After using it for a while, start a new conversation and ask about something you mentioned earlier. It should remember.
<details>
<summary><b>Manual installation</b></summary>
If you prefer to install manually:
-1. **Shell function wrapper** - Append a `claude()` function to `~/.zshrc` or `~/.bashrc`. Every invocation reads `OPENVIKING_URL` and `OPENVIKING_API_KEY` from `~/.openviking/ovcli.conf`, so the API key only exists inside the `claude` process tree. See the full function and security notes in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf).
+1. **Wrap `claude`** - Add these two lines to the end of `~/.zshrc` (for zsh) or `~/.bashrc` (for bash), replacing `<repo-path>` with the absolute path to your local checkout. Each `claude` invocation then injects `OPENVIKING_URL` and `OPENVIKING_API_KEY` from `~/.openviking/ovcli.conf`, keeping the API key scoped to the `claude` process tree:
+
+ ```bash
+ _ov_wrapper="<repo-path>/examples/claude-code-memory-plugin/setup-helper/wrapper.sh"
+ [ -f "$_ov_wrapper" ] && source "$_ov_wrapper"
+ ```
+
+ For the function implementation and why a global `export` is not used, see the [plugin README -> Configuring MCP](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuring-mcp).
2. **Install the plugin** from the OpenViking repository root:
@@ -30,9 +43,9 @@ If you prefer to install manually:
> No `ovcli.conf` yet? Create it first via Deployment Guide -> CLI.
>
-> Pure local mode (`http://127.0.0.1:1933`, no auth)? Skip step 1. The plugin silently uses the local defaults.
+> Pure local mode (`http://127.0.0.1:1933`, no auth)? Skip step 1. The plugin uses the local defaults.
>
-> Claude Code < 2.0? See the [compatibility mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20) in the plugin README.
+> Claude Code < 2.0? See the [compatibility mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20) in the plugin README.
</details>
@@ -42,7 +55,9 @@ If you prefer to install manually:
type claude # Expected: claude is a shell function
```
-Inside Claude Code:
+> If the previous command printed a path instead of `shell function`, the wrapper isn't active yet. Re-source it (or open a new terminal) before launching `claude`, otherwise it silently connects to `127.0.0.1` with no auth.
+
+Launch `claude` from the terminal where `type claude` reports a shell function, then:
- `/plugins` -> Find **openviking-memory** under Installed. Its **openviking** MCP entry should be connected.
- `/mcp` -> The OpenViking entry should show your server URL and valid authentication.
@@ -52,7 +67,15 @@ If the plugin does not appear to work, set `OPENVIKING_DEBUG=1` and inspect `~/.
## How it works
-The plugin hooks into the Claude Code lifecycle: before every user prompt it searches OpenViking and injects relevant memory; after each assistant response it captures new conversation content; on session start it injects the user profile and memory index; before compact and at session end it commits pending messages; and each subagent gets an isolated memory session. All writes run asynchronously, so they do not block your workflow.
+The plugin hooks into the Claude Code lifecycle:
+
+- **Before every prompt** - searches OpenViking and injects relevant memories
+- **After each response** - captures new conversation turns
+- **On session start** - injects your profile and memory index
+- **Before compaction and on session end** - commits pending messages
+- **For each subagent** - assigns an isolated memory session
+
+All writes run asynchronously, so they never block your workflow.
<details>
<summary><b>Configuration</b></summary>
@@ -89,5 +112,5 @@ The plugin renders OpenViking status below the Claude Code input box: connection
## Reference docs
-- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Why and how to add long-term memory to your coding agent
+- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Motivation, architecture overview, and demo
- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) - Full environment variable table, hook details, and architecture diagram
diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.md
index 28ccaeb21..ccf74280a 100644
--- a/docs/images/agents/en/codex.md
+++ b/docs/images/agents/en/codex.md
@@ -1,4 +1,4 @@
-Add persistent cross-session memory to [Codex](https://developers.openai.com/codex). Install once: the plugin automatically recalls memory before every user prompt, captures updates after each turn, and commits before compaction. It also connects Codex to OpenViking's `/mcp` endpoint so the model can directly call tools such as search and store.
+Add persistent, cross-session memory to [Codex](https://developers.openai.com/codex). Install it once, and the plugin will automatically recall memories before every user prompt, capture updates after each turn, and commit changes before compaction. It also connects Codex to OpenViking's `/mcp` endpoint, allowing the model to directly invoke tools like search and store.
Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: motivation and demo](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -8,12 +8,12 @@ Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
```
-The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Each step is idempotent, so it is safe to rerun.
+The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Each step is idempotent, meaning it is safe to rerun the script at any time.
-After installation:
+After installation, activate the `codex` wrapper in your current terminal (or simply open a new terminal window):
```bash
-source ~/.zshrc # or ~/.bashrc
+source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
codex # approve hooks once via /hooks on first launch
```
@@ -22,11 +22,11 @@ codex # approve hooks once via /hooks on first launch
Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `codex_hooks` feature enabled.
-1. **Shell function wrapper** - Append a `codex()` function to your shell rc file. Each invocation injects OpenViking environment variables from `ovcli.conf`. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) for the full function.
+1. **Shell function wrapper** - Append a `codex()` function to your shell configuration file (e.g., `.bashrc` or `.zshrc`). Each invocation injects OpenViking environment variables from `ovcli.conf`. Refer to the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) for the complete function.
-2. **Install the plugin** - Register the local marketplace and enable the plugin. See `setup-helper/install.sh` for the exact commands.
+2. **Install the plugin** - Register the local marketplace and enable the plugin. See `setup-helper/install.sh` for the exact commands required.
-3. **Render placeholders** - Placeholders in `.mcp.json` and `hooks.json` must be replaced with absolute values when copied into the Codex cache. The installer handles this automatically.
+3. **Render placeholders** - Placeholders in `.mcp.json` and `hooks.json` must be replaced with absolute paths or values when copied into the Codex cache. The automated installer handles this for you.
</details>
@@ -36,13 +36,15 @@ Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `codex_hooks` feature en
type codex # Expected: codex is a shell function
```
-Inside Codex, the plugin recalls memory before every prompt. Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.
+> If the previous command printed a path instead of `shell function`, the wrapper isn't active yet. Re-source it (or open a new terminal) before launching, otherwise codex starts without `OPENVIKING_API_KEY` and reports `MCP server is not logged in`.
+
+Inside Codex, the plugin will now recall memory before every prompt. You can set `OPENVIKING_DEBUG=1` to log events to `~/.openviking/logs/codex-hooks.log`.
## How it works
-The plugin hooks into the Codex lifecycle: it searches OpenViking and injects relevant memory before every user prompt (`UserPromptSubmit`), appends new conversation turns to the session after each response (`Stop`), and completes plus commits the full transcript before compaction (`PreCompact`) so the memory extractor sees the complete context. On new session start, it also cleans up orphan sessions from previous runs.
+The plugin hooks into the Codex lifecycle. It searches OpenViking and injects relevant memories before every user prompt (`UserPromptSubmit`), appends new conversation turns to the session after each response (`Stop`), and completes and commits the full transcript before compaction (`PreCompact`) to ensure the memory extractor has complete context. When a new session starts, it also cleans up orphaned sessions from previous runs.
-> **Known gap**: Codex does not trigger hooks on `SIGTERM`, `Ctrl+C`, or `/exit`. Orphan sessions are reclaimed by the next `SessionStart` using the idle TTL cleanup window (30 minutes) or the active-window heuristic.
+> **Known limitation**: Codex does not trigger hooks on `SIGTERM`, `Ctrl+C`, or `/exit`. Orphaned sessions are reclaimed during the next `SessionStart` using either the idle TTL cleanup window (30 minutes) or the active-window heuristic.
<details>
<summary><b>Configuration</b></summary>
@@ -64,15 +66,15 @@ For tuning options such as `OPENVIKING_RECALL_LIMIT` and `OPENVIKING_CAPTURE_ASS
## Troubleshooting
| Symptom | Cause | Fix |
-|------|------|------|
-| `MCP server is not logged in` | `OPENVIKING_API_KEY` is not in the startup environment | Confirm the `codex()` function has been sourced and `ovcli.conf` has `api_key` |
-| `4 hooks need review` | First-launch security approval | Type `/hooks` in Codex and approve |
-| `hook (failed) exited with code 1` after approval | Placeholders in the cache were not rendered | Rerun the one-line installer |
-| Recall is empty | Server is unreachable or URL is wrong | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| Hooks get 401 while MCP works, or vice versa | Environment and `ovcli.conf` differ | Hooks reread `ovcli.conf` each time; MCP reads env at startup. Restart Codex after changes. |
+|---------|-------|-----|
+| `MCP server is not logged in` | `OPENVIKING_API_KEY` is missing from the startup environment | Confirm the `codex()` function has been sourced and `ovcli.conf` contains an `api_key` |
+| `4 hooks need review` | First-launch security approval is required | Type `/hooks` in Codex and approve them |
+| `hook (failed) exited with code 1` after approval | Placeholders in the cache were not properly rendered | Rerun the one-line install script |
+| Recall is empty | Server is unreachable or the URL is incorrect | Run `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` to test the connection |
+| Hooks get 401 while MCP works, or vice versa | Environment variables and `ovcli.conf` are out of sync | Hooks re-read `ovcli.conf` each time; MCP reads the environment at startup. Restart Codex after making changes. |
## Reference docs
-- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Why and how to add long-term memory to your coding agent
-- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) - Full environment variables and architecture diagram
-- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) - Commit decision tree
+- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Why and how to add long-term memory to your coding agent.
+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) - Comprehensive list of environment variables and the architecture diagram.
+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) - Details on the commit decision tree.
diff --git a/docs/images/agents/zh/claude-code.md b/docs/images/agents/zh/claude-code.md
index 29d41d1d8..0a6d670e9 100644
--- a/docs/images/agents/zh/claude-code.md
+++ b/docs/images/agents/zh/claude-code.md
@@ -1,4 +1,4 @@
-为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具。
+为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 添加跨项目、跨会话(session)的长期记忆功能。安装完成后,每轮对话均会自动召回相关记忆并捕获新内容,无需模型主动调用任何工具。
源码:[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -8,31 +8,44 @@
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
```
-脚本会检查依赖、配置 OpenViking 连接并安装插件。每一步都是幂等的——重复执行安全。
+该脚本将自动检查依赖项、配置 OpenViking 连接并完成插件安装,支持重复运行(幂等操作)。
-安装完成后启动 Claude Code,问它上次 session 聊过什么——它记得。
+安装完成后,需在当前终端激活 `claude` 的封装函数(wrapper),或者直接打开一个新的终端窗口:
+
+```bash
+source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh
+```
+
+使用一段时间后,即便在全新的对话中提及过往的话题,Claude Code 也能准确回忆起来。
<details>
<summary><b>手动安装</b></summary>
-如果你更喜欢手动操作:
+如果您倾向于手动安装:
-1. **Shell 函数包装** — 在 `~/.zshrc` 或 `~/.bashrc` 末尾追加一个 `claude()` 函数,每次调用时从 `~/.openviking/ovcli.conf` 注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`。这样 API Key 只在 `claude` 进程树内有效。完整函数和安全说明见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf)。
+1. **封装 `claude` 命令** — 在 `~/.zshrc`(zsh)或 `~/.bashrc`(bash)文件末尾追加以下代码,并将 `<仓库路径>` 替换为您本地克隆仓库的绝对路径。此操作可确保每次调用 `claude` 时,系统都会从 `~/.openviking/ovcli.conf` 动态注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`,且 API Key 仅在 `claude` 的进程树内有效:
-2. **安装插件**,在 OpenViking 仓库根目录:
+ ```bash
+ _ov_wrapper="<仓库路径>/examples/claude-code-memory-plugin/setup-helper/wrapper.sh"
+ [ -f "$_ov_wrapper" ] && source "$_ov_wrapper"
+ ```
+
+ 关于该函数的具体实现以及“为何不使用全局 `export`”的详细说明,请参阅 [插件 README → Configuring MCP](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuring-mcp)。
+
+2. **安装插件** — 在 OpenViking 仓库根目录下执行:
```bash
claude plugin marketplace add "$(pwd)/examples"
claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-3. **启动 Claude Code**,执行 `/mcp` 确认 OpenViking 这一项显示的是你的服务器 URL。
+3. **启动 Claude Code** — 运行后输入 `/mcp` 命令,确认 OpenViking 对应的服务器 URL 配置正确。
-> 还没有 `ovcli.conf`?先按部署指南 → CLI 创建。
+> 尚未创建 `ovcli.conf`?请先按照部署指南 → CLI 的说明进行配置。
>
-> 纯本地模式(`http://127.0.0.1:1933`,无鉴权)?跳过第 1 步——插件会静默使用本地默认值。
+> 使用纯本地模式(`http://127.0.0.1:1933`,无鉴权)?您可以跳过第 1 步,插件将直接使用本地默认值。
>
-> Claude Code < 2.0?见 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。
+> 使用 Claude Code < 2.0 版本?请参考 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。
</details>
@@ -43,56 +56,66 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
type claude # 期望输出:claude is a shell function
```
-进入 Claude Code 后:
+> 若上一步输出的是一个路径而非 `shell function`,说明 wrapper 尚未生效,请先 `source` 那行 wrapper(或新开一个终端)再启动;否则 `claude` 会静默连到本地 `127.0.0.1` 且不带鉴权。
+
+在 `type claude` 显示为 shell function 的终端中运行 `claude` 启动,随后:
-- `/plugins` → 在 Installed 中找到 **openviking-memory**(下属 **openviking** MCP 应显示已连接)
-- `/mcp` → OpenViking 这一项应显示你的服务器 URL 和有效认证
-- `/openviking-memory:ov` → 展示服务器状态、身份、召回/注入统计和开关状态
+- 输入 `/plugins` → 在 Installed 列表中应能找到 **openviking-memory**(其子项 **openviking** MCP 应显示为已连接状态)。
+- 输入 `/mcp` → OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。
+- 输入 `/openviking-memory:ov` → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。
-如果插件似乎没在工作,设 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。
+若插件未正常工作,可设置环境变量 `OPENVIKING_DEBUG=1`,并查看日志文件 `~/.openviking/logs/cc-hooks.log` 以排查问题。
## 工作原理
-插件挂载到 Claude Code 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆,每轮回复后捕获新的对话内容,session 启动时注入用户画像和记忆索引,compact 前和 session 结束时提交待处理的消息,并为每个 subagent 分配隔离的记忆 session。所有写入操作异步执行,不会让你等待。
+插件通过挂载到 Claude Code 的不同生命周期节点来发挥作用:
+
+- **每次用户输入前** — 搜索 OpenViking 数据库并注入相关记忆。
+- **每轮回复后** — 自动捕获并存储新的对话内容。
+- **会话(session)启动时** — 注入用户画像与记忆索引。
+- **上下文压缩(compact)前及会话结束时** — 提交所有待处理的消息记录。
+- **启动子代理(subagent)时** — 为其分配相互隔离的记忆会话。
+
+所有数据写入操作均为异步执行,不会阻塞当前的对话进程。
<details>
<summary><b>配置</b></summary>
-配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+配置项的读取优先级为:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
-| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动召回 |
-| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮最多注入的记忆条数 |
-| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联内容的 token 预算 |
-| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮结束后自动捕获 |
-| `OPENVIKING_BYPASS_SESSION` | `false` | 跳过当前 session 的所有 hook |
-| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob 模式自动跳过 |
-| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启/关闭 |
-| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/cc-hooks.log` |
+| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动触发记忆召回 |
+| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮对话最多注入的记忆条数 |
+| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联记忆内容的 Token 预算上限 |
+| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮对话结束后自动捕获新记忆 |
+| `OPENVIKING_BYPASS_SESSION` | `false` | 禁用当前会话的所有 Hook |
+| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | 通过 CSV 格式的 glob 模式匹配并自动跳过特定会话 |
+| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启或关闭插件 |
+| `OPENVIKING_DEBUG` | `false` | 将调试日志输出至 `~/.openviking/logs/cc-hooks.log` |
-多租户场景设置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整环境变量列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。
+在多租户场景下,请额外配置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整的环境变量列表请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。
</details>
## 状态行
-插件在 Claude Code 输入框下方渲染 OpenViking 状态:连接健康度、召回数量、捕获进度和 session 状态一目了然。完整段位说明和个性化 recipe 见 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
+插件会在 Claude Code 的输入框下方显示一行 OpenViking 状态栏,用于指示:连接状态、召回条数、捕获进度以及当前会话状态。关于状态栏各部分的详细含义与自定义配置方法,请参阅 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
## 故障排查
| 现象 | 原因 | 修复 |
|------|------|------|
-| 插件未激活 | 找不到 `ov.conf` / `ovcli.conf` | 跑 [安装脚本](#安装),或设 `OPENVIKING_MEMORY_ENABLED=1` + URL/API_KEY |
-| Hook 触发但召回为空 | 服务器没起来或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| MCP 工具连到 `127.0.0.1` 而不是远程 | 缺少函数包装 | 确认 `type claude` 返回 "shell function";见 [手动安装](#安装) |
-| 远程认证 401 / 403 | API Key 错误或缺少租户头 | 检查 `OPENVIKING_API_KEY`;多租户还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
+| 插件未激活 | 未找到 `ov.conf` 或 `ovcli.conf` 配置文件 | 运行 [安装脚本](#安装),或手动设置 `OPENVIKING_MEMORY_ENABLED=1` 配合 URL/API_KEY 使用。 |
+| Hook 已触发但召回结果为空 | 服务器未启动或 URL 配置错误 | 执行命令测试连通性:`curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| MCP 工具连接到了 `127.0.0.1` 而非远程服务器 | 缺少 `claude` 函数封装 | 检查 `type claude` 的输出是否包含 "shell function";详情见 [手动安装](#安装) |
+| 远程认证失败 (401 / 403) | API Key 错误或缺少租户 Header | 检查 `OPENVIKING_API_KEY` 是否正确;多租户环境下还需核对 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
## 参考文档
-- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
-- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 完整环境变量表、hook 细节、架构图
+- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 探讨为 Coding Agent 添加长期记忆的动机与实际效果。
+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 查看完整的环境变量列表、Hook 运行细节及系统架构图。
diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.md
index 1dbd444e2..1cd8f4cae 100644
--- a/docs/images/agents/zh/codex.md
+++ b/docs/images/agents/zh/codex.md
@@ -1,5 +1,4 @@
-
-为 [Codex](https://developers.openai.com/codex) 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器。插件同时把 Codex 接到 OpenViking 的 `/mcp` 端点,模型可以直接调用 search、store 等工具管理记忆。
+为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆。一次安装,即可实现:在用户每次输入前自动召回记忆,每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将记忆提交给抽取器。该插件还将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 search、store 等工具来管理记忆。
源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -9,25 +8,25 @@
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
```
-脚本会检查依赖、配置 OpenViking 连接并注册插件。每一步幂等,反复执行安全。
+该脚本会自动检查依赖、配置 OpenViking 连接并注册插件。所有步骤均具有幂等性,可安全地重复执行。
-安装完成后:
+安装完成后,在当前终端激活 `codex` 封装函数(或重新打开一个终端窗口):
```bash
-source ~/.zshrc # 或 ~/.bashrc
-codex # 首次启动进 /hooks 审批一次
+source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
+codex # 首次启动需执行 /hooks 进行一次安全审批
```
<details>
<summary><b>手动安装</b></summary>
-前置:Node.js >= 22、Codex >= 0.130.0、`codex_hooks` feature 已启用。
+前置条件:Node.js >= 22、Codex >= 0.130.0,且已启用 `codex_hooks` 特性。
-1. **Shell 函数包装** — 在 shell rc 中追加一个 `codex()` 函数,每次调用时从 ovcli.conf 注入 OpenViking 环境变量。完整函数见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。
+1. **Shell 函数包装** — 在 shell 的配置文件(如 `.bashrc` 或 `.zshrc`)中追加一个 `codex()` 函数,以便在每次调用时从 `ovcli.conf` 注入 OpenViking 环境变量。完整函数代码请见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。
-2. **插件安装** — 注册本地 marketplace 并启用插件。具体命令见 `setup-helper/install.sh`。
+2. **插件安装** — 注册本地 marketplace 并启用该插件。具体命令请参考 `setup-helper/install.sh`。
-3. **占位符渲染** — `.mcp.json` 和 `hooks.json` 中的占位符在拷贝到 Codex 缓存时需替换为绝对值。installer 会自动做。
+3. **占位符渲染** — `.mcp.json` 和 `hooks.json` 中的占位符在拷贝至 Codex 缓存时需替换为绝对路径。安装程序会自动完成此操作。
</details>
@@ -38,46 +37,48 @@ codex # 首次启动进 /hooks 审批一次
type codex # 期望输出:codex is a shell function
```
-进入 Codex 后插件会在每次输入前召回记忆。设 `OPENVIKING_DEBUG=1` 可把事件写到 `~/.openviking/logs/codex-hooks.log`。
+> 若上一步输出的是一个路径而非 `shell function`,说明 wrapper 尚未生效,请先 `source` 那行 wrapper(或新开一个终端)再启动;否则 codex 启动时拿不到 `OPENVIKING_API_KEY`,会报 `MCP server is not logged in`。
+
+进入 Codex 后,插件将在每次输入前自动召回记忆。将环境变量 `OPENVIKING_DEBUG` 设置为 `1`,可将事件日志输出至 `~/.openviking/logs/codex-hooks.log`。
## 工作原理
-插件挂载到 Codex 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆(`UserPromptSubmit`),每轮结束后把新的对话追加到 session(`Stop`),compaction 前补齐并 commit 完整 transcript(`PreCompact`)让记忆抽取器跑在完整上下文上。新 session 启动时还会清理前次运行的孤儿 session。
+插件深入挂载于 Codex 的生命周期中:在用户每次输入前,它会检索 OpenViking 并注入相关记忆(`UserPromptSubmit`);每轮对话结束后,将新对话追加到当前会话中(`Stop`);在上下文压缩前,补齐并提交(commit)完整的对话记录(`PreCompact`),以确保记忆抽取器能够在完整的上下文环境中运行。此外,在启动新会话时,它还会自动清理上一次运行遗留的孤儿会话。
-> **已知盲区**:Codex 在 `SIGTERM` / `Ctrl+C` / `/exit` 时不触发任何 hook。孤儿 session 由下一次 `SessionStart` 的闲置 TTL 清理(30 分钟)或活动窗口启发式回收。
+> **已知盲区**:Codex 在收到 `SIGTERM` 信号、用户按下 `Ctrl+C` 或输入 `/exit` 退出时,不会触发任何 hook。这些遗留的孤儿会话将在下一次触发 `SessionStart` 时,通过闲置 TTL(30 分钟)机制或活动窗口启发式算法进行回收清理。
<details>
<summary><b>配置</b></summary>
-配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+配置读取优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整的服务器 URL |
| `OPENVIKING_API_KEY` | — | API key(通过 `Authorization: Bearer` 发送) |
-| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |
-| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |
-| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/codex-hooks.log` |
+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | `SessionStart` 活动窗口阈值 |
+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | `SessionStart` 闲置 TTL 清理阈值 |
+| `OPENVIKING_DEBUG` | `false` | 将日志输出至 `~/.openviking/logs/codex-hooks.log` |
-调参(`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等)见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
+关于更多参数调优(如 `OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等),请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
</details>
## 故障排查
-| 现象 | 原因 | 修复 |
+| 现象 | 原因 | 解决方案 |
|------|------|------|
-| `MCP server is not logged in` | 启动时 `OPENVIKING_API_KEY` 不在 env 里 | 确认 `codex()` 函数已 source,`ovcli.conf` 有 `api_key` |
-| `4 hooks need review` | 首次启动的安全审批 | 在 Codex 输入 `/hooks` 审批 |
-| 审批后仍 `hook (failed) exited with code 1` | 缓存里占位符未渲染 | 重新跑一次一行安装脚本 |
-| 召回为空 | 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| Hook 401 但 MCP 可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次重读 ovcli.conf,MCP 在启动时读 env。改完重启 codex。 |
+| `MCP server is not logged in` | 启动时 `OPENVIKING_API_KEY` 未注入环境变量 | 确认 `codex()` 函数已被 `source` 激活,且 `ovcli.conf` 中包含 `api_key` |
+| `4 hooks need review` | 首次启动触发的安全审批 | 在 Codex 中输入 `/hooks` 完成审批 |
+| 审批后仍提示 `hook (failed) exited with code 1` | 缓存中的占位符未被正确替换 | 重新运行一次单行安装脚本 |
+| 召回为空 | 服务器不可达或 URL 配置错误 | 运行 `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` 检查连接状态 |
+| Hook 返回 401 但 MCP 可用,或反之 | 环境变量与 `ovcli.conf` 配置不一致 | Hook 每次执行都会重新读取 `ovcli.conf`,而 MCP 仅在启动时读取环境变量。修改配置后请重启 Codex。 |
## 参考文档
-- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
-- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、架构图
-- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树
+- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 探讨为何以及如何为您的 Coding Agent 赋予长期记忆
+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 包含完整的环境变量说明及架构图
+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — 详细介绍了 commit 的决策树
diff --git a/docs/images/agents/zh/index.json b/docs/images/agents/zh/index.json
index 1ded85e69..f227a5a41 100644
--- a/docs/images/agents/zh/index.json
+++ b/docs/images/agents/zh/index.json
@@ -1,6 +1,6 @@
{
"version": 1,
- "updatedAt": "2026-06-02",
+ "updatedAt": "2026-06-05",
"cdnBaseUrl": "https://docs.openviking.net/",
"accessMethods": [
{
@@ -61,7 +61,7 @@
"name": "Claude Code",
"tags": ["Plugin"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Claude-Code.png",
- "summary": "为 Claude Code 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具",
+ "summary": "为 Claude Code 添加跨项目、跨会话(session)的长期记忆功能。安装完成后,每轮对话均会自动召回相关记忆并捕获新内容,无需模型主动调用任何工具",
"detailPath": "https://docs.openviking.net/agents/zh/claude-code.md"
},
{
@@ -69,7 +69,7 @@
"name": "Codex",
"tags": ["Plugin"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/codex.png",
- "summary": "为 Codex 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器",
+ "summary": "为 Codex 提供持久化的跨会话(session)记忆。一次安装,即可实现:在用户每次输入前自动召回记忆,每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将记忆提交给抽取器",
"detailPath": "https://docs.openviking.net/agents/zh/codex.md"
},
{
diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.md
index de41746e8..5f85050c8 100644
--- a/docs/zh/agent-integrations/02-claude-code.md
+++ b/docs/zh/agent-integrations/02-claude-code.md
@@ -1,6 +1,6 @@
# Claude Code 记忆插件
-为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具。
+为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 添加跨项目、跨会话(session)的长期记忆功能。安装完成后,每轮对话均会自动召回相关记忆并捕获新内容,无需模型主动调用任何工具。
源码:[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -10,31 +10,44 @@
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
```
-脚本会检查依赖、配置 OpenViking 连接并安装插件。每一步都是幂等的——重复执行安全。
+该脚本将自动检查依赖项、配置 OpenViking 连接并完成插件安装,支持重复运行(幂等操作)。
-安装完成后启动 Claude Code,问它上次 session 聊过什么——它记得。
+安装完成后,需在当前终端激活 `claude` 的封装函数(wrapper),或者直接打开一个新的终端窗口:
+
+```bash
+source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh
+```
+
+使用一段时间后,即便在全新的对话中提及过往的话题,Claude Code 也能准确回忆起来。
<details>
<summary><b>手动安装</b></summary>
-如果你更喜欢手动操作:
+如果您倾向于手动安装:
-1. **Shell 函数包装** — 在 `~/.zshrc` 或 `~/.bashrc` 末尾追加一个 `claude()` 函数,每次调用时从 `~/.openviking/ovcli.conf` 注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`。这样 API Key 只在 `claude` 进程树内有效。完整函数和安全说明见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf)。
+1. **封装 `claude` 命令** — 在 `~/.zshrc`(zsh)或 `~/.bashrc`(bash)文件末尾追加以下代码,并将 `<仓库路径>` 替换为您本地克隆仓库的绝对路径。此操作可确保每次调用 `claude` 时,系统都会从 `~/.openviking/ovcli.conf` 动态注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`,且 API Key 仅在 `claude` 的进程树内有效:
-2. **安装插件**,在 OpenViking 仓库根目录:
+ ```bash
+ _ov_wrapper="<仓库路径>/examples/claude-code-memory-plugin/setup-helper/wrapper.sh"
+ [ -f "$_ov_wrapper" ] && source "$_ov_wrapper"
+ ```
+
+ 关于该函数的具体实现以及“为何不使用全局 `export`”的详细说明,请参阅 [插件 README → Configuring MCP](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuring-mcp)。
+
+2. **安装插件** — 在 OpenViking 仓库根目录下执行:
```bash
claude plugin marketplace add "$(pwd)/examples"
claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-3. **启动 Claude Code**,执行 `/mcp` 确认 OpenViking 这一项显示的是你的服务器 URL。
+3. **启动 Claude Code** — 运行后输入 `/mcp` 命令,确认 OpenViking 对应的服务器 URL 配置正确。
-> 还没有 `ovcli.conf`?先按 [部署指南 → CLI](../guides/03-deployment.md#cli) 创建。
+> 尚未创建 `ovcli.conf`?请先按照 [部署指南 → CLI](../guides/03-deployment.md#cli) 的说明进行配置。
>
-> 纯本地模式(`http://127.0.0.1:1933`,无鉴权)?跳过第 1 步——插件会静默使用本地默认值。
+> 使用纯本地模式(`http://127.0.0.1:1933`,无鉴权)?您可以跳过第 1 步,插件将直接使用本地默认值。
>
-> Claude Code < 2.0?见 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。
+> 使用 Claude Code < 2.0 版本?请参考 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。
</details>
@@ -44,54 +57,64 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
type claude # 期望输出:claude is a shell function
```
-进入 Claude Code 后:
+> 若上一步输出的是一个路径而非 `shell function`,说明 wrapper 尚未生效,请先 `source` 那行 wrapper(或新开一个终端)再启动;否则 `claude` 会静默连到本地 `127.0.0.1` 且不带鉴权。
+
+在 `type claude` 显示为 shell function 的终端中运行 `claude` 启动,随后:
-- `/plugins` → 在 Installed 中找到 **openviking-memory**(下属 **openviking** MCP 应显示已连接)
-- `/mcp` → OpenViking 这一项应显示你的服务器 URL 和有效认证
-- `/openviking-memory:ov` → 展示服务器状态、身份、召回/注入统计和开关状态
+- 输入 `/plugins` → 在 Installed 列表中应能找到 **openviking-memory**(其子项 **openviking** MCP 应显示为已连接状态)。
+- 输入 `/mcp` → OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。
+- 输入 `/openviking-memory:ov` → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。
-如果插件似乎没在工作,设 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。
+若插件未正常工作,可设置环境变量 `OPENVIKING_DEBUG=1`,并查看日志文件 `~/.openviking/logs/cc-hooks.log` 以排查问题。
## 工作原理
-插件挂载到 Claude Code 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆,每轮回复后捕获新的对话内容,session 启动时注入用户画像和记忆索引,compact 前和 session 结束时提交待处理的消息,并为每个 subagent 分配隔离的记忆 session。所有写入操作异步执行,不会让你等待。
+插件通过挂载到 Claude Code 的不同生命周期节点来发挥作用:
+
+- **每次用户输入前** — 搜索 OpenViking 数据库并注入相关记忆。
+- **每轮回复后** — 自动捕获并存储新的对话内容。
+- **会话(session)启动时** — 注入用户画像与记忆索引。
+- **上下文压缩(compact)前及会话结束时** — 提交所有待处理的消息记录。
+- **启动子代理(subagent)时** — 为其分配相互隔离的记忆会话。
+
+所有数据写入操作均为异步执行,不会阻塞当前的对话进程。
<details>
<summary><b>配置</b></summary>
-配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+配置项的读取优先级为:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
-| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动召回 |
-| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮最多注入的记忆条数 |
-| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联内容的 token 预算 |
-| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮结束后自动捕获 |
-| `OPENVIKING_BYPASS_SESSION` | `false` | 跳过当前 session 的所有 hook |
-| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob 模式自动跳过 |
-| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启/关闭 |
-| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/cc-hooks.log` |
+| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动触发记忆召回 |
+| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮对话最多注入的记忆条数 |
+| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联记忆内容的 Token 预算上限 |
+| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮对话结束后自动捕获新记忆 |
+| `OPENVIKING_BYPASS_SESSION` | `false` | 禁用当前会话的所有 Hook |
+| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | 通过 CSV 格式的 glob 模式匹配并自动跳过特定会话 |
+| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启或关闭插件 |
+| `OPENVIKING_DEBUG` | `false` | 将调试日志输出至 `~/.openviking/logs/cc-hooks.log` |
-多租户场景设置 `OPENVIKING_ACCOUNT`、`OPENVIKING_USER`。完整环境变量列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。
+在多租户场景下,请额外配置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整的环境变量列表请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。
</details>
## 状态行
-插件在 Claude Code 输入框下方渲染 OpenViking 状态:连接健康度、召回数量、捕获进度和 session 状态一目了然。完整段位说明和个性化 recipe 见 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
+插件会在 Claude Code 的输入框下方显示一行 OpenViking 状态栏,用于指示:连接状态、召回条数、捕获进度以及当前会话状态。关于状态栏各部分的详细含义与自定义配置方法,请参阅 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
## 故障排查
| 现象 | 原因 | 修复 |
|------|------|------|
-| 插件未激活 | 找不到 `ov.conf` / `ovcli.conf` | 跑 [安装脚本](#安装),或设 `OPENVIKING_MEMORY_ENABLED=1` + URL/API_KEY |
-| Hook 触发但召回为空 | 服务器没起来或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| MCP 工具连到 `127.0.0.1` 而不是远程 | 缺少函数包装 | 确认 `type claude` 返回 "shell function";见 [手动安装](#安装) |
-| 远程认证 401 / 403 | API Key 错误或缺少租户头 | 检查 `OPENVIKING_API_KEY`;多租户还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
+| 插件未激活 | 未找到 `ov.conf` 或 `ovcli.conf` 配置文件 | 运行 [安装脚本](#安装),或手动设置 `OPENVIKING_MEMORY_ENABLED=1` 配合 URL/API_KEY 使用。 |
+| Hook 已触发但召回结果为空 | 服务器未启动或 URL 配置错误 | 执行命令测试连通性:`curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| MCP 工具连接到了 `127.0.0.1` 而非远程服务器 | 缺少 `claude` 函数封装 | 检查 `type claude` 的输出是否包含 "shell function";详情见 [手动安装](#安装) |
+| 远程认证失败 (401 / 403) | API Key 错误或缺少租户 Header | 检查 `OPENVIKING_API_KEY` 是否正确;多租户环境下还需核对 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
## 参见
-- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
-- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 完整环境变量表、hook 细节、架构图
-- [MCP 客户端](./06-mcp-clients.md) — MCP 工具参数与其他客户端
-- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
+- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 探讨为 Coding Agent 添加长期记忆的动机与实际效果。
+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 查看完整的环境变量列表、Hook 运行细节及系统架构图。
+- [MCP 客户端](./06-mcp-clients.md) — 了解 MCP 工具参数及其他客户端集成指南。
+- [部署指南 → CLI](../guides/03-deployment.md#cli) — 学习 `ovcli.conf` 的具体配置方法。
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index 4916a9cd9..3118d9a35 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) 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器。插件同时把 Codex 接到 OpenViking 的 `/mcp` 端点,模型可以直接调用 search、store 等工具管理记忆。
+本插件旨在为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆功能。只需安装一次,即可实现:在每次用户输入前自动召回相关记忆,在每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将完整记录提交给记忆抽取器。同时,该插件将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 `search`、`store` 等工具来主动管理记忆。
源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
@@ -10,25 +10,25 @@
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
```
-脚本会检查依赖、配置 OpenViking 连接并注册插件。每一步幂等,反复执行安全。
+脚本将自动检查依赖项、配置 OpenViking 连接并注册插件。安装过程的每一步均支持幂等操作,可安全地重复执行。
-安装完成后:
+安装完成后,请在当前终端激活 `codex` 的封装函数(或新开一个终端窗口):
```bash
-source ~/.zshrc # 或 ~/.bashrc
-codex # 首次启动进 /hooks 审批一次
+source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
+codex # 首次启动需进入 /hooks 完成一次审批
```
<details>
<summary><b>手动安装</b></summary>
-前置:Node.js >= 22、Codex >= 0.130.0、`codex_hooks` feature 已启用。
+前置条件:需安装 Node.js >= 22、Codex >= 0.130.0,并启用 `codex_hooks` 特性。
-1. **Shell 函数包装** — 在 shell rc 中追加一个 `codex()` 函数,每次调用时从 ovcli.conf 注入 OpenViking 环境变量。完整函数见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。
+1. **Shell 函数封装** — 在 shell 的配置文件(如 rc 文件)中追加一个 `codex()` 函数,确保每次调用时都能从 `ovcli.conf` 注入 OpenViking 相关的环境变量。完整的函数代码请参考 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。
-2. **插件安装** — 注册本地 marketplace 并启用插件。具体命令见 `setup-helper/install.sh`。
+2. **插件安装** — 注册本地 marketplace 并启用插件。具体执行命令请参见 `setup-helper/install.sh`。
-3. **占位符渲染** — `.mcp.json` 和 `hooks.json` 中的占位符在拷贝到 Codex 缓存时需替换为绝对值。installer 会自动做。
+3. **占位符渲染** — 在将 `.mcp.json` 和 `hooks.json` 复制到 Codex 缓存目录时,需将其中的占位符替换为绝对路径或具体数值。自动化安装脚本会自动完成此操作。
</details>
@@ -38,45 +38,47 @@ codex # 首次启动进 /hooks 审批一次
type codex # 期望输出:codex is a shell function
```
-进入 Codex 后插件会在每次输入前召回记忆。设 `OPENVIKING_DEBUG=1` 可把事件写到 `~/.openviking/logs/codex-hooks.log`。
+> 若上一步输出的是一个路径而非 `shell function`,说明 wrapper 尚未生效,请先 `source` 那行 wrapper(或新开一个终端)再启动;否则 codex 启动时拿不到 `OPENVIKING_API_KEY`,会报 `MCP server is not logged in`。
+
+进入 Codex 后,插件将在每次用户输入前自动召回记忆。若设置环境变量 `OPENVIKING_DEBUG=1`,则会将相关事件日志写入 `~/.openviking/logs/codex-hooks.log`。
## 工作原理
-插件挂载到 Codex 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆(`UserPromptSubmit`),每轮结束后把新的对话追加到 session(`Stop`),compaction 前补齐并 commit 完整 transcript(`PreCompact`)让记忆抽取器跑在完整上下文上。新 session 启动时还会清理前次运行的孤儿 session。
+本插件深度挂载于 Codex 的生命周期之中:在每次用户输入前,它会搜索 OpenViking 并注入相关的记忆(触发 `UserPromptSubmit`);在每轮对话结束后,会将新的对话追加至当前会话(触发 `Stop`);在上下文压缩前,补齐并提交(commit)完整的对话记录(触发 `PreCompact`),以确保记忆抽取器能够在完整的上下文环境中运行。此外,在启动新会话时,插件还会自动清理前次运行遗留的孤儿会话(orphan session)。
-> **已知盲区**:Codex 在 `SIGTERM` / `Ctrl+C` / `/exit` 时不触发任何 hook。孤儿 session 由下一次 `SessionStart` 的闲置 TTL 清理(30 分钟)或活动窗口启发式回收。
+> **已知局限**:当通过 `SIGTERM`、`Ctrl+C` 或输入 `/exit` 退出 Codex 时,不会触发任何 hook(钩子)。遗留的孤儿会话将在下一次触发 `SessionStart` 时,通过闲置 TTL(生存时间,默认为 30 分钟)机制或活动窗口启发式策略进行回收清理。
<details>
<summary><b>配置</b></summary>
-配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+配置优先级为:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(默认 URL 为 `http://127.0.0.1:1933`,无鉴权)。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |
-| `OPENVIKING_API_KEY` | — | API key(通过 `Authorization: Bearer` 发送) |
-| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |
-| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |
-| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/codex-hooks.log` |
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整的服务器 URL |
+| `OPENVIKING_API_KEY` | — | API 密钥(将通过 `Authorization: Bearer` 标头发送) |
+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | `SessionStart` 活动窗口阈值(毫秒) |
+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | `SessionStart` 闲置 TTL 清理阈值(毫秒) |
+| `OPENVIKING_DEBUG` | `false` | 是否将日志写入 `~/.openviking/logs/codex-hooks.log` |
-调参(`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等)见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
+更多调参说明(如 `OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等),请参考 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
</details>
## 故障排查
-| 现象 | 原因 | 修复 |
+| 现象 | 可能原因 | 修复方法 |
|------|------|------|
-| `MCP server is not logged in` | 启动时 `OPENVIKING_API_KEY` 不在 env 里 | 确认 `codex()` 函数已 source,`ovcli.conf` 有 `api_key` |
-| `4 hooks need review` | 首次启动的安全审批 | 在 Codex 输入 `/hooks` 审批 |
-| 审批后仍 `hook (failed) exited with code 1` | 缓存里占位符未渲染 | 重新跑一次一行安装脚本 |
-| 召回为空 | 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| Hook 401 但 MCP 可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次重读 ovcli.conf,MCP 在启动时读 env。改完重启 codex。 |
+| `MCP server is not logged in` | 启动时环境变量中缺失 `OPENVIKING_API_KEY` | 确认已 source `codex()` 函数,且 `ovcli.conf` 中配置了 `api_key` |
+| `4 hooks need review` | 首次启动需要进行安全审批 | 在 Codex 终端内输入 `/hooks` 完成审批 |
+| 审批后仍提示 `hook (failed) exited with code 1` | 缓存文件中的占位符未被正确渲染 | 重新执行一次一键安装脚本 |
+| 召回结果为空 | 服务器不可达或 URL 配置错误 | 执行 `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` 检查服务器状态 |
+| Hook 报 401 但 MCP 正常可用,或反之 | 环境变量与 `ovcli.conf` 的配置不一致 | Hook 每次触发均会重新读取 `ovcli.conf`,而 MCP 仅在启动时读取环境变量。请修改配置并重启 Codex。 |
## 参见
- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
-- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、架构图
-- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树
-- [MCP 客户端](./06-mcp-clients.md) — MCP 协议、工具列表、其他客户端
-- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整的环境变量说明与架构图
+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — 提交(commit)决策树
+- [MCP 客户端](./06-mcp-clients.md) — MCP 协议、工具列表及其他客户端
+- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置说明