zzos/OpenViking
1
0
Fork 0
mirror of https://github.com/volcengine/OpenViking.git synced 2026-09-29 16:58:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(hermes): recommend memory setup openviking (#4098)

Browse Source 
* docs(hermes): recommend memory setup openviking

Point Hermes docs at `hermes memory setup openviking` and describe the
real wizard. Shorten Volcengine console agent guides to TOS + cloud API
key, and mark docs/images as console-only.

* docs(hermes): drop setup filler

Keep the command and the two connection paths. Remove picker
explanations and wizard narration.

* docs: keep images AGENTS.md.local local-only

Ignore AGENTS.md.local like AGENTS.md. Drop the unused
docs/images/README.md.

* docs(console): keep harness setup to command plus API key

Drop installer narration, idempotency notes, and copied site
guides. Console pages only need the TOS command and cloud key.

* docs(console): restore Install / Verify / Troubleshoot

Keep the short cloud setup, put it back under the three section
headings the console pages use.

* docs(console): add Reference links

Point each harness page at docs.openviking.net, the coding-agent
blog where it exists, and the example source.

* docs(console): label Reference as manual settings and blog

Use Docs on Manual Settings for the full site page. Use Blog
about how it works where a how-it-works writeup exists.
This commit is contained in:
Zayn Jarvis
2026-08-18 20:19:29 +08:00
committed by GitHub
parent 868a9600d0
commit c1fc0b730e
24 changed files with 242 additions and 600 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -147,6 +147,7 @@ RAGbenchmark/*.log
CLAUDE.md
*.so
AGENTS.md
AGENTS.md.local
# Git worktrees
.worktrees/
docs/en/agent-integrations/05-hermes.md
+4 -12
View File
@@ -15,19 +15,13 @@ service.
## Setup
Run the Hermes memory setup wizard:
```bash
hermes memory setup
hermes memory setup openviking
```
The wizard prompts for:
- **OpenViking server URL** — your self-hosted server (default `http://127.0.0.1:1933`) or OpenViking Service (VolcEngine Cloud)
- **API key** — leave blank for local dev mode
- **Tenant account / user / peer IDs** — for multi-tenant deployments. Legacy `agent_id` settings map to the request actor peer during migration.
Configuration is saved to Hermes's `config.yaml` and `.env` files.
- Cloud: keep **OpenViking Service (VolcEngine Cloud)**, paste the API key
- Custom: URL (default `http://127.0.0.1:1933`) and API key; leave the key empty for local dev
- Reuse an existing `ovcli.conf` profile if the wizard offers one
## Verify
@@ -35,8 +29,6 @@ Configuration is saved to Hermes's `config.yaml` and `.env` files.
hermes memory status
```
Once configured, Hermes uses the OpenViking memory provider to inject context, prefetch relevant memories, and sync and extract memories after sessions. Available tools include `viking_search`, `viking_read`, `viking_browse`, `viking_remember`, `viking_forget`, and `viking_add_resource`.
## See also
- [Hermes — OpenViking memory provider docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — full setup guide and configuration options
docs/images/agents/en/claude-code.md
+19 -92
View File
@@ -1,103 +1,30 @@
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/)
## Step 1: Install
## Install
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness claude --dist tos
```
Claude Code and Codex share this one installer. It asks which tools to install, which source to use (GitHub or the TOS mirror), your language (English/中文), and OpenViking credentials; each step is idempotent, so it is safe to rerun. No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads `~/.openviking/ovcli.conf` at runtime.
Select **Volcengine OpenViking Cloud**. Paste the API key from this page.
> If you choose the TOS channel for Claude Code, the installer registers a local directory marketplace that cannot auto-update — re-run the command above to update.
## Verify
After using it for a while, start a new conversation and ask about something you mentioned earlier. It should remember.
Restart Claude Code, then:
<details>
<summary><b>Manual installation</b></summary>
- `/plugins` → **openviking-memory** is installed, **openviking** MCP is connected
- `/mcp` → shows the cloud URL and valid auth
- `/openviking-memory:ov` → server is healthy
If you prefer to install manually:
## Troubleshoot
1. **Configure the connection** - write `~/.openviking/ovcli.conf` (`url`, `api_key`, optional `account`/`user`), or run the bundled wizard `node <plugin-dir>/scripts/setup.mjs` after installing.
| Problem | Fix |
|---|---|
| Plugin is not active | Re-run Install, or check `~/.openviking/ovcli.conf` |
| Recall is empty | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| 401 / 403 | Paste the API key from this page again |
| Need logs | `OPENVIKING_DEBUG=1` and `~/.openviking/logs/cc-hooks.log` |
2. **Install the plugin** from the remote marketplace (needs GitHub access):
## Reference
```bash
claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json
claude plugin install openviking-memory@openviking
```
3. **Start Claude Code** and run `/mcp` to confirm the OpenViking entry is connected.
> 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 uses the local defaults.
>
> Claude Code < 2.0? The installer detects it and falls back to compatibility mode automatically; 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>
## Step 2: Verify
Launch `claude`, 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.
- `/openviking-memory:ov` -> Shows server status, identity, recall/injection stats, and toggle state.
If the plugin does not appear to work, set `OPENVIKING_DEBUG=1` and inspect `~/.openviking/logs/cc-hooks.log`.
## How it works
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>
Configuration priority: environment variables > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).
| Environment variable | Default | Description |
|---------|--------|------|
| `OPENVIKING_AUTO_RECALL` | `true` | Automatically recall before each user prompt |
| `OPENVIKING_RECALL_LIMIT` | `10` | Legacy width override converted to per-category coding quotas |
| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | Inline token budget for the final raw-find fallback |
| `OPENVIKING_AUTO_CAPTURE` | `true` | Automatically capture after each turn |
| `OPENVIKING_BYPASS_SESSION` | `false` | Skip all hooks for the current session |
| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob patterns for automatic bypass |
| `OPENVIKING_MEMORY_ENABLED` | (auto) | Force enable or disable |
| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/cc-hooks.log` |
If recall latency matters most, see [Low-latency recall](https://docs.openviking.net/en/agent-integrations/01-overview#low-latency-recall).
For multi-tenant deployments, set `OPENVIKING_ACCOUNT` and `OPENVIKING_USER`. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration) for the full environment variable list.
</details>
## Status line
The plugin renders OpenViking status below the Claude Code input box: connection health, recall count, capture progress, and session state are visible at a glance. See [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md) for the full status levels and customization recipes.
## Troubleshooting
| Symptom | Cause | Fix |
|------|------|------|
| Plugin is not active | `ov.conf` / `ovcli.conf` cannot be found | Run [Step 1: Install](#step-1-install), or set `OPENVIKING_MEMORY_ENABLED=1` plus URL/API_KEY |
| Hooks run but recall is empty | Server is down or URL is wrong | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| MCP tools connect to `127.0.0.1` instead of remote | Missing shell function wrapper | Confirm `type claude` returns "shell function"; see [Step 1: Install](#step-1-install) |
| `type claude` shows a path instead of a shell function (wrapper inactive) | The rc wasn't `source`d after install, or you launched from a terminal that didn't load it | Run `source ~/.zshrc` (or `~/.bashrc` on bash), or open a new terminal |
| Launching via an alias (e.g. `cc`) injects no credentials | The alias *name* was listed in `OPENVIKING_CC_WRAP_EXTRA` (alias names are skipped), or the alias's target command isn't wrapped | Wrap the command the alias points to, not the alias: `alias cc=claude` needs nothing; for `alias cc=claude-custom`, add `claude-custom` |
| Remote auth returns 401 / 403 | API key is wrong or tenant headers are missing | Check `OPENVIKING_API_KEY`; for multi-tenant deployments also verify `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
## Reference docs
- [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
- Docs on Manual Settings: [Claude Code](https://docs.openviking.net/en/agent-integrations/02-claude-code)
- Blog about how it works: [OpenViking for coding agents](https://blog.openviking.ai/post/openviking-coding-agent/)
- Code: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin)
docs/images/agents/en/codex.md
+16 -71
View File
@@ -1,81 +1,26 @@
Add persistent, cross-session memory to [Codex](https://developers.openai.com/codex). Install it once, and the plugin will load your OpenViking profile and memory index at session start, recall relevant memories before every user prompt, capture updates after each turn, and commit changes before compaction. It also connects Codex to OpenViking's `/mcp` endpoint, allowing the model to directly invoke tools such as find, search, read, and remember.
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/)
## Step 1: Install
## Install
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness codex --dist tos
```
Claude Code and Codex share this one installer. It asks which tools to install, which source to use (GitHub or the TOS mirror), your language (English/中文), and OpenViking credentials; each step is idempotent, so it is safe to rerun. If you choose the TOS channel for Codex, it installs from a TOS-hosted git repo and can update later with `codex plugin marketplace upgrade openviking`.
Select **Volcengine OpenViking Cloud**. Paste the API key from this page.
No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads `~/.openviking/ovcli.conf` at runtime. After installing:
## Verify
```bash
codex # approve hooks once via /hooks on first launch
```
Launch `codex`. Approve hooks once with `/hooks`. The first prompt should load your profile.
<details>
<summary><b>Manual installation</b></summary>
## Troubleshoot
Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `plugin_hooks` feature enabled.
| Problem | Fix |
|---|---|
| Auth error | Check `api_key` in `~/.openviking/ovcli.conf`, restart Codex |
| Connection error | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| `4 hooks need review` | `/hooks` and approve |
| Need logs | `OPENVIKING_DEBUG=1` and `~/.openviking/logs/codex-hooks.log` |
1. **Configure the connection** - write `~/.openviking/ovcli.conf` (`url`, `api_key`, optional `account`/`user`), or run the bundled wizard `node <plugin-dir>/scripts/setup.mjs` after installing.
## Reference
2. **Install the plugin** from the remote marketplace (needs GitHub access):
```bash
codex plugin marketplace add volcengine/OpenViking
codex plugin add openviking-memory@openviking
```
Then enable plugin hooks in `~/.codex/config.toml` if your build doesn't already: `[features]` → `plugin_hooks = true`.
</details>
## Step 2: Verify
Launch `codex`; the `SessionStart` hook will load your profile on the session's first prompt, then the plugin will recall relevant memory before every prompt. You can set `OPENVIKING_DEBUG=1` to log events to `~/.openviking/logs/codex-hooks.log`.
## How it works
The plugin hooks into the Codex lifecycle. On `SessionStart` (`startup`, `clear`, or `resume`), it injects `profile.md` plus URI and abstract indexes for `preferences/` and `entities/` through the shared CJK-aware profile builder. It searches OpenViking and injects relevant memories before every user prompt (`UserPromptSubmit`), appends new conversation turns to the session after each response (`Stop`), and completes and commits the full transcript before compaction (`PreCompact`) to ensure the memory extractor has complete context. When a new session starts, it also cleans up orphaned sessions from previous runs. Resume may combine the profile with the latest archive digest.
> **Known limitation**: Codex does not trigger hooks on `SIGTERM`, `Ctrl+C`, or `/exit`. Orphaned sessions are reclaimed during the next `SessionStart` using either the idle TTL cleanup window (30 minutes) or the active-window heuristic.
<details>
<summary><b>Configuration</b></summary>
Configuration priority: environment variables > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).
| Environment variable | Default | Description |
|---------|--------|------|
| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | - | Full server URL |
| `OPENVIKING_API_KEY` | - | API key sent as `Authorization: Bearer` |
| `OPENVIKING_NO_AUTO_INJECT` | `false` | Disable fixed session-start profile/background injection without disabling per-prompt recall |
| `OPENVIKING_PROFILE_TOKEN_BUDGET` | `10000` | CJK-aware token budget for the profile and memory indexes |
| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart active-window threshold |
| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle TTL cleanup threshold |
| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/codex-hooks.log` |
If recall latency matters most, see [Low-latency recall](https://docs.openviking.net/en/agent-integrations/01-overview#low-latency-recall).
For tuning options such as `OPENVIKING_RECALL_LIMIT` and `OPENVIKING_CAPTURE_ASSISTANT_TURNS`, see the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).
</details>
## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| MCP tool calls fail with an auth error | `ovcli.conf` has no valid `api_key` for an authenticated server | Fix `ovcli.conf` (or run `node <plugin-dir>/scripts/setup.mjs`) and restart Codex |
| MCP tool calls fail with a connection error | Server is unreachable or the URL is incorrect | Run `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` to test the connection |
| `4 hooks need review` | First-launch security approval is required | Type `/hooks` in Codex and approve them |
| Plugin still targets an old server after `ov config switch` | Codex keeps the proxy process from the previous session | Restart Codex; the stdio proxy resolves credentials at startup |
## 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) - 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.
- Docs on Manual Settings: [Codex](https://docs.openviking.net/en/agent-integrations/04-codex)
- Blog about how it works: [OpenViking for coding agents](https://blog.openviking.ai/post/openviking-coding-agent/)
- Code: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
docs/images/agents/en/cursor.md
+14 -13
View File
@@ -1,25 +1,26 @@
## Install the Cursor integration
Requires macOS/Linux and Node.js 18+. The command installs Hooks, MCP, Rule, and Skill together:
## Install
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness cursor --dist tos
```
When asked where to connect, select **Volcengine OpenViking Cloud** and enter your API key. Choose **Self-hosted / local** only for a locally running OpenViking server.
Select **Volcengine OpenViking Cloud**. Paste the API key from this page.
## Verify
1. Restart Cursor and start a new Agent session.
2. In **Cursor Settings → Hooks**, confirm that the lifecycle Hooks ran `cursor-hook.mjs`, the URI protection Hooks ran `uri-guard.mjs`, and the prompt Hook returned `additional_context`.
3. In **Cursor Settings → Tools & MCPs**, confirm that `openviking` is connected.
2. **Cursor Settings → Hooks**: lifecycle hooks run `cursor-hook.mjs`.
3. **Cursor Settings → Tools & MCPs**: `openviking` is connected.
See the complete [Cursor integration guide](https://docs.openviking.ai/en/agent-integrations/12-cursor).
## Troubleshoot
## Troubleshooting
| Problem | Suggested fix |
| Problem | Fix |
|---|---|
| Hooks do not run after installation | Quit Cursor completely, restart it, and create a new Agent session. |
| Recall runs more than once | Check the Execution Log for an imported legacy Claude OpenViking Hook, then upgrade or remove the legacy plugin reported by the installer. |
| Connection/authentication fails | Check `~/.openviking/ovcli.conf` and restart Cursor. |
| Hooks do not run | Quit Cursor completely, restart, new Agent session |
| Connection / auth fails | Check `~/.openviking/ovcli.conf` and restart Cursor |
| Need logs | `OPENVIKING_DEBUG=1` and `~/.openviking/logs/cursor-hooks.log` |
## Reference
- Docs on Manual Settings: [Cursor](https://docs.openviking.net/en/agent-integrations/12-cursor)
- Code: [examples/cursor-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/cursor-memory-plugin)
docs/images/agents/en/deerflow-mcp.md
+2 -2
View File
@@ -2,7 +2,7 @@ DeerFlow can connect to OpenViking through an MCP Server. MCP integration lets D
## Step 1: Configure OpenViking credentials
Edit the `.env` file in the DeerFlow project root and add the OpenViking USER API Key:
Edit the `.env` file in the DeerFlow project root and add the API key from this page:
```bash
OPENVIKING_API_KEY=[TODO]your-api-key
@@ -26,7 +26,7 @@ Open `extensions_config.json` in the project root and add OpenViking under `mcpS
"openviking": {
"enabled": true,
"type": "http",
"url": "[TODO]openviking-base-url/mcp",
"url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
"headers": {
"X-API-Key": "$OPENVIKING_API_KEY"
}
docs/images/agents/en/deerflow-memory-manager.md
+3 -3
View File
@@ -2,7 +2,7 @@ DeerFlow can use OpenViking as a long-term memory backend through MemoryManager.
## Step 1: Configure OpenViking credentials
Edit the `.env` file in the DeerFlow project root and add the OpenViking USER API Key:
Edit the `.env` file in the DeerFlow project root and add the API key from this page:
```bash
OPENVIKING_API_KEY=[TODO]your-api-key
@@ -20,7 +20,7 @@ memory:
manager_class: openviking
mode: middleware
backend_config:
base_url: [TODO]openviking-base-url
base_url: https://api.vikingdb.cn-beijing.volces.com/openviking
owner_user_id: default
api_key_env: OPENVIKING_API_KEY
startup_policy: fail_fast
@@ -57,7 +57,7 @@ Successful log examples:
```text
Memory manager resolved: OpenVikingMemoryManager (manager_class='openviking')
HTTP Request: GET [TODO]openviking-base-url/health "HTTP/1.1 200 OK"
HTTP Request: GET https://api.vikingdb.cn-beijing.volces.com/openviking/health "HTTP/1.1 200 OK"
```
## Step 5: Verify memory write and recall
docs/images/agents/en/hermes.md
+15 -20
View File
@@ -1,32 +1,27 @@
[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) includes OpenViking as a built-in memory provider. No plugin installation is required. Point Hermes to your OpenViking service to enable native memory storage, recall, and extraction.
## Step 1: Run the Hermes memory setup wizard
## Install
```bash
hermes memory setup
hermes memory setup openviking
```
## Step 2: Copy the Base URL and Authentication management
Keep **OpenViking Service (VolcEngine Cloud)**. Paste the API key from this page.
After running the setup command, Hermes prompts for the Base URL and Authentication management. Copy them and paste them into Hermes:
- Base URL: Copy the following Base URL into Hermes:
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
- Authentication management: Copy the Authentication management shown on the page into your Hermes terminal
- Tenant account / user / agent ID: Used for multi-tenant deployments
The configuration is saved to Hermes `config.yaml` and `.env` files.
## Step 3: Verify Hermes memory status
## Verify
```bash
hermes memory status
```
After configuration, Hermes uses the OpenViking memory provider to inject context, prefetch relevant memories, and sync and extract memories after sessions. Available tools include `viking_search`, `viking_read`, `viking_browse`, `viking_remember`, `viking_forget`, and `viking_add_resource`.
Expect `Provider: openviking` and `Status: available`. Start a new Hermes session.
## Reference docs
## Troubleshoot
- [Hermes - OpenViking memory provider documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) - Full configuration guide
| Problem | Fix |
|---|---|
| Provider is not openviking | Re-run `hermes memory setup openviking` |
| Status is not available | Check the API key from this page |
## Reference
- Docs on Manual Settings: [Hermes](https://docs.openviking.net/en/agent-integrations/05-hermes)
- Blog about how it works: [OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking)
docs/images/agents/en/index.json
+2 -2
View File
@@ -1,6 +1,6 @@
{
"version": 1,
"updatedAt": "2026-08-12",
"updatedAt": "2026-08-18",
"cdnBaseUrl": "https://docs.openviking.net/",
"accessMethods": [
{
@@ -53,7 +53,7 @@
"name": "Hermes Agent",
"tags": ["Provider"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",
"summary": "Hermes includes OpenViking as a native memory provider. Point Hermes to your OpenViking service to enable storage, recall, and extraction.",
"summary": "Hermes includes OpenViking as a native memory provider. Run hermes memory setup openviking, keep VolcEngine Cloud, and paste the API key.",
"detailPath": "https://docs.openviking.net/agents/en/hermes.md"
},
{
docs/images/agents/en/openclaw.md
+21 -21
View File
@@ -1,25 +1,25 @@
## Step 1: Install OpenViking
On the terminal of the machine running OpenClaw, run the following command to install the OpenViking plugin:
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup
```
## Step 2: Copy the Base URL and API Key
After running the install command, the setup flow prompts for the Base URL and API Key. Copy them and paste them into your agent terminal:
- Base URL: Copy the following Base URL into your agent terminal
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
- API Key: Copy the API Key shown on the page into your agent terminal
## Step 3: Restart OpenClaw
Copy the following command into the agent terminal to restart OpenClaw. After restart, the console automatically detects the agent connection status.
## Install
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <API-key-from-this-page>
openclaw gateway restart
```
## Verify
```bash
openclaw openviking status
```
## Troubleshoot
| Problem | Fix |
|---|---|
| Plugin not active | Re-run Install, then `openclaw gateway restart` |
| 401 / 403 | Paste the API key from this page again |
## Reference
- Docs on Manual Settings: [OpenClaw](https://docs.openviking.net/en/agent-integrations/03-openclaw)
- Code: [examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin)
docs/images/agents/en/opencode.md
+14 -46
View File
@@ -1,56 +1,24 @@
Add persistent, cross-session memory and indexed repository context to [OpenCode](https://opencode.ai/). Install it once, and the plugin will automatically recall memories on every prompt, capture turns into OpenViking sessions, and commit before compaction. Model-callable tools come from the same OpenViking MCP proxy used by the Claude Code and Codex plugins.
Source: [examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
## Step 1: Install
## Install
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness opencode --dist tos
```
OpenCode shares this one installer with Claude Code and Codex. It asks which tools to install, which source to use (GitHub or the TOS mirror), your language (English/中文), and OpenViking credentials; each step is idempotent, so it is safe to rerun. On the TOS channel the plugin is installed as local files — rerun the installer to update.
Select **Volcengine OpenViking Cloud**. Paste the API key from this page.
<details>
<summary><b>Manual installation</b></summary>
## Verify
Prerequisites: OpenCode, Node.js 18+, and a reachable OpenViking server (`curl http://localhost:1933/health`).
Restart OpenCode. Ask it to search OpenViking memory. Tools look like `openviking_search`, `openviking_read`, `openviking_remember`.
1. **Configure the connection** - write `~/.openviking/ovcli.conf` (`url`, `api_key`, optional `account`/`user`), or run the bundled wizard `node <plugin-dir>/scripts/setup.mjs` after installing.
## Troubleshoot
2. **Register the npm plugin** (needs npm registry access) — merge `"@openviking/opencode-plugin"` into the `plugin` array of `~/.config/opencode/opencode.json`:
| Problem | Fix |
|---|---|
| Plugin is not loaded | Check `~/.config/opencode/opencode.json` includes `@openviking/opencode-plugin` |
| Wrong server / 401 | Check `~/.openviking/ovcli.conf` and the API key from this page |
| Recall is empty | Confirm the cloud instance has memories |
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
```
## Reference
OpenCode downloads the package at startup, and the plugin registers its `openviking` MCP server automatically.
</details>
## Step 2: Verify
Restart OpenCode. The plugin exposes MCP tools with the `openviking_` prefix, for example `openviking_search`, `openviking_read`, `openviking_remember`, `openviking_health`. Ask OpenCode to search or browse OpenViking memory.
Behavior knobs (recall limits, commit thresholds) live in `~/.config/opencode/openviking-config.json`; credentials come from `~/.openviking/ovcli.conf` or `OPENVIKING_*` environment variables. Runtime logs:
```bash
~/.config/opencode/openviking/openviking-memory.log
~/.config/opencode/openviking/openviking-session-state.json
```
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| Plugin is not loaded | Check `~/.config/opencode/opencode.json` references `@openviking/opencode-plugin`, or `~/.config/opencode/plugins/openviking.js` for file installs |
| MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars / `OPENVIKING_PLUGIN_CONFIG` |
| 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; trusted-mode deployments also need `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
| Recall is empty | Confirm OpenViking has memories/resources and `autoRecall.enabled` is `true` |
## Reference docs
- [Plugin README](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin) - full tool list, configuration fields, and runtime details
- [Deployment Guide](https://docs.openviking.ai/en/guides/03-deployment) - setting up OpenViking server and CLI config
- Docs on Manual Settings: [OpenCode](https://docs.openviking.net/en/agent-integrations/10-opencode)
- Code: [examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
docs/images/agents/en/trae.md
+13 -18
View File
@@ -1,6 +1,4 @@
## Install the TRAE Integration
Requires macOS/Linux and Node.js 18+. Run the command for your client; Hooks and MCP are configured together:
## Install
```bash
# TRAE
@@ -8,26 +6,23 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
# TRAE CN
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae-cn --dist tos
# Both
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae,trae-cn --dist tos
```
When asked where to connect, select **Volcengine OpenViking Cloud** and enter your API key. Choose **Self-hosted / local** only for a locally running OpenViking server.
Select **Volcengine OpenViking Cloud**. Paste the API key from this page.
## Verify
1. Restart TRAE after installation.
2. Confirm that `openviking` is connected in TRAE settings.
3. Start a new session and ask about a previous project or preference.
4. Share a temporary preference and ask for it in the next session to verify capture and commit.
Restart TRAE. Confirm `openviking` is connected in settings.
See the complete [TRAE integration guide](https://docs.openviking.ai/en/agent-integrations/13-trae).
## Troubleshoot
## Troubleshooting
| Problem | Suggested fix |
| Problem | Fix |
|---|---|
| Automatic recall does not run after installation | Quit TRAE completely, restart it, and create a new Agent session. |
| A new session cannot recall the previous turn | Check `~/.openviking/logs/trae-hooks.log` or `trae-cn-hooks.log` and confirm that Stop committed successfully. |
| Connection/authentication fails | Check `~/.openviking/ovcli.conf` and restart TRAE. |
| No auto recall | Quit TRAE completely, restart, new Agent session |
| Connection / auth fails | Check `~/.openviking/ovcli.conf` and restart TRAE |
| Need logs | `~/.openviking/logs/trae-hooks.log` or `trae-cn-hooks.log` |
## Reference
- Docs on Manual Settings: [TRAE](https://docs.openviking.net/en/agent-integrations/13-trae)
- Code: [examples/trae-memory-hooks](https://github.com/volcengine/OpenViking/tree/main/examples/trae-memory-hooks)
docs/images/agents/zh/claude-code.md
+18 -94
View File
@@ -1,106 +1,30 @@
为 [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/)
## 步骤 1：安装
## 安装
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness claude --dist tos
```
Claude Code 和 Codex 共用这一个安装脚本。它会依次询问要安装的工具、安装源（GitHub 或 TOS 镜像）、界面语言（English/中文）和 OpenViking 凭据；所有步骤幂等，支持重复运行。不再需要任何 shell wrapper——插件自带的 stdio MCP 代理会在运行时读取 `~/.openviking/ovcli.conf`。
选 **火山引擎 OpenViking 云服务**，把本页 API Key 贴进去。
> 若为 Claude Code 选择 TOS 渠道，安装脚本会注册本地目录 marketplace，无法自动更新——更新请重跑上面的安装命令。
## 验证
使用一段时间后，即便在全新的对话中提及过往的话题，Claude Code 也能准确回忆起来。
<details>
<summary><b>手动安装</b></summary>
如果您倾向于手动安装：
1. **配置连接** — 手写 `~/.openviking/ovcli.conf`（`url`、`api_key`，可选 `account`/`user`），或装完后运行插件自带向导 `node <插件目录>/scripts/setup.mjs`。
2. **安装插件** — 从远程 marketplace（需可访问 GitHub）：
```bash
claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json
claude plugin install openviking-memory@openviking
```
3. **启动 Claude Code** — 运行后输入 `/mcp` 命令，确认 OpenViking 条目已连接。
> 尚未创建 `ovcli.conf`？请先按照部署指南 → CLI 的说明进行配置。
>
> 使用纯本地模式（`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)。
</details>
## 步骤 2：验证
启动 `claude`，随后：
- 输入 `/plugins` → 在 Installed 列表中应能找到 **openviking-memory**（其子项 **openviking** MCP 应显示为已连接状态）。
- 输入 `/mcp` → OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。
- 输入 `/openviking-memory:ov` → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。
若插件未正常工作，可设置环境变量 `OPENVIKING_DEBUG=1`，并查看日志文件 `~/.openviking/logs/cc-hooks.log` 以排查问题。
## 工作原理
插件通过挂载到 Claude Code 的不同生命周期节点来发挥作用：
- **每次用户输入前** — 搜索 OpenViking 数据库并注入相关记忆。
- **每轮回复后** — 自动捕获并存储新的对话内容。
- **会话（session）启动时** — 注入用户画像与记忆索引。
- **上下文压缩（compact）前及会话结束时** — 提交所有待处理的消息记录。
- **启动子代理（subagent）时** — 为其分配相互隔离的记忆会话。
所有数据写入操作均为异步执行，不会阻塞当前的对话进程。
<details>
<summary><b>配置</b></summary>
配置项的读取优先级为：环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值（`http://127.0.0.1:1933`，无鉴权）。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动触发记忆召回 |
| `OPENVIKING_RECALL_LIMIT` | `10` | 遗留宽度覆盖，会转换为各分类 coding 配额 |
| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 最终 raw-find fallback 的内联 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` |
如果更看重召回响应速度，请参阅[低延迟召回](https://docs.openviking.net/zh/agent-integrations/01-overview#低延迟召回)。
在多租户场景下，请额外配置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整的环境变量列表请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#配置)。
</details>
## 状态行
插件会在 Claude Code 的输入框下方显示一行 OpenViking 状态栏，用于指示：连接状态、召回条数、捕获进度以及当前会话状态。关于状态栏各部分的详细含义与自定义配置方法，请参阅 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
重启 Claude Code，然后：
- `/plugins` → **openviking-memory** 已安装，**openviking** MCP 已连接
- `/mcp` → 显示云端 URL 且鉴权有效
- `/openviking-memory:ov` → 服务健康
## 故障排查
| 现象 | 原因 | 修复 |
|------|------|------|
| 插件未激活 | 未找到 `ov.conf` 或 `ovcli.conf` 配置文件 | 运行 [步骤 1：安装](#步骤-1安装)，或手动设置 `OPENVIKING_MEMORY_ENABLED=1` 配合 URL/API_KEY 使用。 |
| Hook 已触发但召回结果为空 | 服务器未启动或 URL 配置错误 | 执行命令测试连通性：`curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| MCP 工具连接到了 `127.0.0.1` 而非远程服务器 | `~/.openviking/ovcli.conf` 中没有 `url`（代理回退到本地默认值） | 修正 `ovcli.conf`（或运行 `node <插件目录>/scripts/setup.mjs`）后重启 Claude Code |
| 远程认证失败 (401 / 403) | API Key 错误或缺少租户 Header | 检查 `OPENVIKING_API_KEY` 是否正确；多租户环境下还需核对 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| 问题 | 处理 |
|---|---|
| 插件未激活 | 重跑安装，或检查 `~/.openviking/ovcli.conf` |
| 召回为空 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| 401 / 403 | 重新粘贴本页 API Key |
| 需要日志 | `OPENVIKING_DEBUG=1`，看 `~/.openviking/logs/cc-hooks.log` |
## 参考
## 参考文档
- [博客：在 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_CN.md) — 查看完整的环境变量列表、Hook 运行细节及系统架构图。
- 手动配置文档：[Claude Code](https://docs.openviking.net/zh/agent-integrations/02-claude-code)
- 原理博客：[OpenViking for coding agents](https://blog.openviking.ai/post/openviking-coding-agent/)
- 源码：[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin)
docs/images/agents/zh/cli.md
+1 -1
View File
@@ -14,7 +14,7 @@ npm i -g @openviking/cli && ov config
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
- API Key: 复制以下 API Key 到你的终端
- API Key: 把本页展示的 API Key 粘贴到终端
### 步骤3：配置完成后，可运行以下命令查看 CLI 用法：
docs/images/agents/zh/codex.md
+15 -74
View File
@@ -1,85 +1,26 @@
为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话（session）记忆。一次安装，即可实现：在会话开始时加载 OpenViking profile 与记忆索引，在用户每次输入前自动召回相关记忆，每轮对话结束后进行增量捕获，并在上下文压缩（compaction）前将记忆提交给抽取器。该插件还将 Codex 连接至 OpenViking 的 `/mcp` 端点，使模型能够直接调用 find、search、read、remember 等工具来管理记忆。
源码：[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客：动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
## 步骤 1：安装
## 安装
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness codex --dist tos
```
Claude Code 和 Codex 共用这一个安装脚本。它会依次询问要安装的工具、安装源（GitHub 或 TOS 镜像）、界面语言（English/中文）和 OpenViking 凭据；所有步骤幂等，可安全地重复执行。若为 Codex 选择 TOS 渠道，安装脚本会使用 TOS 托管的 git 仓库，之后仍可用 `codex plugin marketplace upgrade openviking` 远程更新。
选 **火山引擎 OpenViking 云服务**，把本页 API Key 贴进去。
不再需要任何 shell wrapper——插件自带的 stdio MCP 代理会在运行时读取 `~/.openviking/ovcli.conf`。安装完成后：
```bash
codex # 首次启动需执行 /hooks 进行一次安全审批
```
<details>
<summary><b>手动安装</b></summary>
前置条件：Node.js >= 22、Codex >= 0.130.0，且已启用 `plugin_hooks` 特性。
1. **配置连接** — 手写 `~/.openviking/ovcli.conf`（`url`、`api_key`，可选 `account`/`user`），或装完后运行插件自带向导 `node <插件目录>/scripts/setup.mjs`。
2. **从远程 marketplace 安装插件**（需可访问 GitHub）：
```bash
codex plugin marketplace add volcengine/OpenViking
codex plugin add openviking-memory@openviking
```
若你的 Codex 版本未默认启用 plugin hooks，在 `~/.codex/config.toml` 中加上 `[features]` → `plugin_hooks = true`。
</details>
## 步骤 2：验证
启动 `codex` 后，当前会话首次提交 prompt 时触发的 `SessionStart` 会加载 profile，之后插件将在每次输入前自动召回相关记忆。将环境变量 `OPENVIKING_DEBUG` 设置为 `1`，可将事件日志输出至 `~/.openviking/logs/codex-hooks.log`。
## 工作原理
插件深入挂载于 Codex 的生命周期中：在 `SessionStart`（`startup`、`clear` 或 `resume`）阶段，它会复用共享的 CJK-aware profile 构建逻辑，注入 `profile.md`，以及 `preferences/`、`entities/` 的 URI 和摘要索引；在用户每次输入前，它会检索 OpenViking 并注入相关记忆（`UserPromptSubmit`）；每轮对话结束后，将新对话追加到当前会话中（`Stop`）；在上下文压缩前，补齐并提交（commit）完整的对话记录（`PreCompact`），以确保记忆抽取器能够在完整的上下文环境中运行。此外，在启动新会话时，它还会自动清理上一次运行遗留的孤儿会话。恢复已有会话时，profile 还会与最新的 archive digest 合并注入。
> **已知盲区**：Codex 在收到 `SIGTERM` 信号、用户按下 `Ctrl+C` 或输入 `/exit` 退出时，不会触发任何 hook。这些遗留的孤儿会话将在下一次触发 `SessionStart` 时，通过闲置 TTL（30 分钟）机制或活动窗口启发式算法进行回收清理。
<details>
<summary><b>配置</b></summary>
配置读取优先级：环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值（`http://127.0.0.1:1933`，无鉴权）。
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整的服务器 URL |
| `OPENVIKING_API_KEY` | — | API key（通过 `Authorization: Bearer` 发送） |
| `OPENVIKING_NO_AUTO_INJECT` | `false` | 关闭会话启动阶段的固定 profile/背景注入，但不关闭逐 prompt 语义召回 |
| `OPENVIKING_PROFILE_TOKEN_BUDGET` | `10000` | profile 及记忆索引共用的 CJK-aware token 预算 |
| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | `SessionStart` 活动窗口阈值 |
| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | `SessionStart` 闲置 TTL 清理阈值 |
| `OPENVIKING_DEBUG` | `false` | 将日志输出至 `~/.openviking/logs/codex-hooks.log` |
如果更看重召回响应速度，请参阅[低延迟召回](https://docs.openviking.net/zh/agent-integrations/01-overview#低延迟召回)。
关于更多参数调优（如 `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>
## 验证
启动 `codex`，用 `/hooks` 审批一次。第一次提交 prompt 时应加载 profile。
## 故障排查
| 现象 | 原因 | 解决方案 |
|------|------|------|
| MCP 工具调用报认证错误 | `ovcli.conf` 中没有 authenticated server 所需的有效 `api_key` | 修正 `ovcli.conf`（或运行 `node <插件目录>/scripts/setup.mjs`）后重启 Codex |
| MCP 工具调用报连接错误 | 服务器不可达或 URL 配置错误 | 运行 `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` 检查连接状态 |
| `4 hooks need review` | 首次启动触发的安全审批 | 在 Codex 中输入 `/hooks` 完成审批 |
| `ov config switch` 后插件仍指向旧服务器 | 上个会话的代理进程仍在运行 | 重启 Codex；stdio 代理在启动时解析凭据 |
| 问题 | 处理 |
|---|---|
| 鉴权失败 | 检查 `~/.openviking/ovcli.conf` 的 `api_key`，重启 Codex |
| 连接失败 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| `4 hooks need review` | `/hooks` 里批准 |
| 需要日志 | `OPENVIKING_DEBUG=1`，看 `~/.openviking/logs/codex-hooks.log` |
## 参考
## 参考文档
- [博客：在 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 的决策树
- 手动配置文档：[Codex](https://docs.openviking.net/zh/agent-integrations/04-codex)
- 原理博客：[OpenViking for coding agents](https://blog.openviking.ai/post/openviking-coding-agent/)
- 源码：[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
docs/images/agents/zh/cursor.md
+13 -12
View File
@@ -1,25 +1,26 @@
## 安装 Cursor 集成
需要 macOS/Linux 和 Node.js 18+。以下命令会一次完成 Hook、MCP、Rule 和 Skill 安装：
## 安装
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness cursor --dist tos
```
安装器询问连接方式时，请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。只有本机已运行 OpenViking 服务时才选择 **自建 / 本地**。
选 **火山引擎 OpenViking 云服务**，把本页 API Key 贴进去。
## 验证
1. 重启 Cursor 并新建 Agent 会话。
2. 在 **Cursor Settings → Hooks** 中确认生命周期 Hook 执行了 `cursor-hook.mjs`、URI 保护 Hook 执行了 `uri-guard.mjs`，且 prompt Hook 返回 `additional_context`。
3. 在 **Cursor Settings → Tools & MCPs** 中确认 `openviking` 已连接。
完整说明见 [Cursor 接入文档](https://docs.openviking.ai/zh/agent-integrations/12-cursor)。
1. 重启 Cursor，新建 Agent 会话。
2. **Cursor Settings → Hooks**：生命周期 Hook 执行 `cursor-hook.mjs`。
3. **Cursor Settings → Tools & MCPs**：`openviking` 已连接。
## 故障排查
| 问题 | 处理 |
|---|---|
| 安装后没有触发 Hook | 完全退出并重新启动 Cursor，然后新建 Agent 会话。 |
| 出现重复召回 | 检查 Execution Log 是否导入了旧 Claude OpenViking Hook，并按安装器提示升级或移除旧插件。 |
| 连接或鉴权失败 | 检查 `~/.openviking/ovcli.conf`，然后重启 Cursor。 |
| Hook 没跑 | 完全退出 Cursor，重启，再建会话 |
| 连接 / 鉴权失败 | 检查 `~/.openviking/ovcli.conf`，重启 Cursor |
| 需要日志 | `OPENVIKING_DEBUG=1`，看 `~/.openviking/logs/cursor-hooks.log` |
## 参考
- 手动配置文档：[Cursor](https://docs.openviking.net/zh/agent-integrations/12-cursor)
- 源码：[examples/cursor-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/cursor-memory-plugin)
docs/images/agents/zh/deerflow-mcp.md
+2 -2
View File
@@ -2,7 +2,7 @@ DeerFlow 支持通过 MCP Server 接入 OpenViking。MCP 接入的核心价值
## 步骤 1：配置 OpenViking 鉴权信息
在 DeerFlow 项目根目录下编辑 `.env` 文件，添加 OpenViking USER API Key：
在 DeerFlow 项目根目录下编辑 `.env` 文件，把本页的 API Key 填进去：
```bash
OPENVIKING_API_KEY=[TODO]your-api-key
@@ -26,7 +26,7 @@ cp extensions_config.example.json extensions_config.json
"openviking": {
"enabled": true,
"type": "http",
"url": "[TODO]openviking-base-url/mcp",
"url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
"headers": {
"X-API-Key": "$OPENVIKING_API_KEY"
}
docs/images/agents/zh/deerflow-memory-manager.md
+3 -3
View File
@@ -2,7 +2,7 @@ DeerFlow 支持通过 MemoryManager 接入 OpenViking 作为长期记忆后端
## 步骤 1：配置 OpenViking 鉴权信息
在 DeerFlow 项目根目录下编辑 `.env` 文件，添加 OpenViking USER API Key：
在 DeerFlow 项目根目录下编辑 `.env` 文件，把本页的 API Key 填进去：
```bash
OPENVIKING_API_KEY=[TODO]your-api-key
@@ -20,7 +20,7 @@ memory:
manager_class: openviking
mode: middleware
backend_config:
base_url: [TODO]openviking-base-url
base_url: https://api.vikingdb.cn-beijing.volces.com/openviking
owner_user_id: default
api_key_env: OPENVIKING_API_KEY
startup_policy: fail_fast
@@ -57,7 +57,7 @@ grep -i "memory manager resolved\|openviking\|deermem" logs/gateway.log
```text
Memory manager resolved: OpenVikingMemoryManager (manager_class='openviking')
HTTP Request: GET [TODO]openviking-base-url/health "HTTP/1.1 200 OK"
HTTP Request: GET https://api.vikingdb.cn-beijing.volces.com/openviking/health "HTTP/1.1 200 OK"
```
## 步骤 5：验证写入与召回
docs/images/agents/zh/hermes.md
+15 -21
View File
@@ -1,33 +1,27 @@
[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) 内置 OpenViking 记忆提供方。无需安装插件——把 Hermes 指向你的 OpenViking 服务即可，记忆存储、召回和抽取均原生支持。
## 步骤 1：运行 Hermes 记忆配置向导：
## 安装
```bash
hermes memory setup
hermes memory setup openviking
```
## 步骤 2：复制 Base URL 和 鉴权管理
执行 setup 命令后会依次提示输入 Base URL 和 鉴权管理，可复制后粘贴到你的 Hermes：
保持 **OpenViking Service (VolcEngine Cloud)**，把本页 API Key 贴进去。
- Base URL: 复制以下 Base URL 到你的 Hermes：
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
- 鉴权管理: 复制页面中展示的 鉴权管理 到你的 Hermes 终端
- 租户 account / user / agent ID：多租户部署时使用
配置保存在 Hermes 的 `config.yaml` 和 `.env` 文件中。
## 步骤 3：验证 Hermes 记忆状态
## 验证
```bash
hermes memory status
```
配置完成后，Hermes 会通过 OpenViking memory provider 自动注入上下文、预取相关记忆，并在会话后同步和抽取记忆。可用工具包括 `viking_search`、`viking_read`、`viking_browse`、`viking_remember`、`viking_forget` 和 `viking_add_resource`。
应看到 `Provider: openviking` 且 `Status: available`。然后开一轮新会话。
## 参考文档
## 故障排查
- [Hermes — OpenViking memory provider 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 完整配置指南
| 问题 | 处理 |
|---|---|
| Provider 不是 openviking | 重跑 `hermes memory setup openviking` |
| Status 不是 available | 检查本页 API Key |
## 参考
- 手动配置文档：[Hermes](https://docs.openviking.net/zh/agent-integrations/05-hermes)
- 原理说明：[OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking)
docs/images/agents/zh/index.json
+2 -2
View File
@@ -1,6 +1,6 @@
{
"version": 1,
"updatedAt": "2026-08-12",
"updatedAt": "2026-08-18",
"cdnBaseUrl": "https://docs.openviking.net/",
"accessMethods": [
{
@@ -53,7 +53,7 @@
"name": "Hermes Agent",
"tags": ["Provider"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",
"summary": "Hermes 官方内置 OpenViking 作为记忆提供方。无需安装插件——直接把 Hermes 指向你的 OpenViking 服务即可，记忆存储、召回和抽取均原生支持",
"summary": "Hermes 官方内置 OpenViking。跑 hermes memory setup openviking，默认选火山云，再贴上本页 API Key 即可",
"detailPath": "https://docs.openviking.net/agents/zh/hermes.md"
},
{
docs/images/agents/zh/openclaw.md
+21 -18
View File
@@ -1,22 +1,25 @@
## 步骤 1：安装 OpenViking
在你的 OpenClaw 的机器终端，执行以下命令以安装 OpenViking Plugin
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup
```
## 步骤 2：复制 Base URL 和 API Key
执行安装命令后会依次提示输入 Base URL 和 API Key，可复制后粘贴到你的 Agent 终端
- Base URL: 复制以下 Base URL 到你的 Agent 终端
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
- API Key: 复制页面中展示的 API Key 到你的 Agent 终端
## 步骤 3：重启 OpenClaw
复制以下指令到 Agent 终端以重启 OpenClaw，重启后控制台将自动判断 Agent 接入状态
## 安装
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <本页的-API-Key>
openclaw gateway restart
```
## 验证
```bash
openclaw openviking status
```
## 故障排查
| 问题 | 处理 |
|---|---|
| 插件未生效 | 重跑安装，再执行 `openclaw gateway restart` |
| 401 / 403 | 重新粘贴本页 API Key |
## 参考
- 手动配置文档：[OpenClaw](https://docs.openviking.net/zh/agent-integrations/03-openclaw)
- 源码：[examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin)
docs/images/agents/zh/opencode.md
+13 -45
View File
@@ -1,56 +1,24 @@
为 [OpenCode](https://opencode.ai/) 提供跨会话长期记忆和已索引仓库上下文。安装一次后，插件会在每次 prompt 前自动召回记忆、把对话逐轮捕获进 OpenViking session，并在 compact 前自动 commit。模型可调用工具来自 Claude Code / Codex 插件同款的 OpenViking MCP proxy。
源码：[examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
## 步骤 1：安装
## 安装
```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness opencode --dist tos
```
OpenCode 与 Claude Code、Codex 共用这一个安装器。它会询问要安装的工具、下载源（GitHub 或 TOS 镜像）、语言（English/中文）和 OpenViking 凭据；每一步都是幂等的，重复运行完全安全。TOS 渠道以本地文件方式安装插件——更新时重跑安装器即可。
选 **火山引擎 OpenViking 云服务**，把本页 API Key 贴进去。
<details>
<summary><b>手动安装</b></summary>
## 验证
前置条件：OpenCode、Node.js 18+，以及可达的 OpenViking server（`curl http://localhost:1933/health`）。
1. **配置连接**——写入 `~/.openviking/ovcli.conf`（`url`、`api_key`，可选 `account`/`user`），或安装后运行内置向导 `node <plugin-dir>/scripts/setup.mjs`。
2. **注册 npm 插件**（需要 npm registry 可达）——把 `"@openviking/opencode-plugin"` 合并进 `~/.config/opencode/opencode.json` 的 `plugin` 数组：
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
```
OpenCode 启动时会自动下载该包，插件会自动注册它的 `openviking` MCP server。
</details>
## 步骤 2：验证
重启 OpenCode。插件会暴露带 `openviking_` 前缀的 MCP 工具，例如 `openviking_search`、`openviking_read`、`openviking_remember`、`openviking_health`。可以让 OpenCode 搜索或浏览 OpenViking memory。
行为旋钮（召回上限、commit 阈值等）在 `~/.config/opencode/openviking-config.json`；凭据来自 `~/.openviking/ovcli.conf` 或 `OPENVIKING_*` 环境变量。运行时日志：
```bash
~/.config/opencode/openviking/openviking-memory.log
~/.config/opencode/openviking/openviking-session-state.json
```
重启 OpenCode，让它搜索 OpenViking 记忆。工具名类似 `openviking_search`、`openviking_read`、`openviking_remember`。
## 故障排查
| 现象 | 修复 |
|------|------|
| 插件没有加载 | 确认 `~/.config/opencode/opencode.json` 引用了 `@openviking/opencode-plugin`；文件安装时确认 `~/.config/opencode/plugins/openviking.js` 存在 |
| MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`，或设置 `OPENVIKING_*` 环境变量 / `OPENVIKING_PLUGIN_CONFIG` |
| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还需要 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| recall 为空 | 确认 OpenViking 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |
| 问题 | 处理 |
|---|---|
| 插件没加载 | 检查 `~/.config/opencode/opencode.json` 是否包含 `@openviking/opencode-plugin` |
| 连错服务 / 401 | 检查 `~/.openviking/ovcli.conf` 和本页 API Key |
| 召回为空 | 确认云端实例里已有记忆 |
## 参考文档
## 参考
- [插件 README](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin) - 完整 tools、配置字段和运行时说明
- [部署指南](https://docs.openviking.ai/zh/guides/03-deployment) - OpenViking server 与 CLI 配置
- 手动配置文档：[OpenCode](https://docs.openviking.net/zh/agent-integrations/10-opencode)
- 源码：[examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
docs/images/agents/zh/trae.md
+11 -16
View File
@@ -1,6 +1,4 @@
## 安装 TRAE 集成
需要 macOS/Linux 和 Node.js 18+。运行与客户端对应的安装命令，Hook 和 MCP 会同时配置：
## 安装
```bash
# TRAE
@@ -8,26 +6,23 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
# TRAE CN
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae-cn --dist tos
# 同时安装
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae,trae-cn --dist tos
```
安装器询问连接方式时，请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。只有本机已运行 OpenViking 服务时才选择 **自建 / 本地**。
选 **火山引擎 OpenViking 云服务**，把本页 API Key 贴进去。
## 验证
1. 安装后重启 TRAE。
2. 在 TRAE 设置中确认 `openviking` 已连接。
3. 新建会话并提问一个与过往项目或个人偏好相关的问题。
4. 告诉 Agent 一个临时偏好；下一会话再次询问，验证捕获和提交。
完整说明见 [TRAE 接入文档](https://docs.openviking.ai/zh/agent-integrations/13-trae)。
重启 TRAE。在设置里确认 `openviking` 已连接。
## 故障排查
| 问题 | 处理 |
|---|---|
| 安装后没有自动召回 | 完全退出并重新启动 TRAE，然后新建 Agent 会话。 |
| 新会话无法回忆上一轮 | 查看 `~/.openviking/logs/trae-hooks.log` 或 `trae-cn-hooks.log`，确认 Stop 提交成功。 |
| 连接或鉴权失败 | 检查 `~/.openviking/ovcli.conf`，然后重启 TRAE。 |
| 没有自动召回 | 完全退出 TRAE，重启，再建会话 |
| 连接 / 鉴权失败 | 检查 `~/.openviking/ovcli.conf`，重启 TRAE |
| 需要日志 | `~/.openviking/logs/trae-hooks.log` 或 `trae-cn-hooks.log` |
## 参考
- 手动配置文档：[TRAE](https://docs.openviking.net/zh/agent-integrations/13-trae)
- 源码：[examples/trae-memory-hooks](https://github.com/volcengine/OpenViking/tree/main/examples/trae-memory-hooks)
docs/zh/agent-integrations/05-hermes.md
+4 -12
View File
@@ -13,19 +13,13 @@ Python 环境中。请在独立的虚拟环境或容器中运行 OpenViking 服
## 配置
运行 Hermes 记忆配置向导：
```bash
hermes memory setup
hermes memory setup openviking
```
向导会询问：
- **OpenViking 服务 URL** — 自托管服务器（默认 `http://127.0.0.1:1933`）或 OpenViking Service（火山引擎云）
- **API Key** — 本地开发模式留空
- **租户 account / user / peer ID** — 多租户部署时使用。迁移期的旧 `agent_id` 配置会映射为请求的 actor peer。
配置保存在 Hermes 的 `config.yaml` 和 `.env` 文件中。
- 云：保持 **OpenViking Service (VolcEngine Cloud)**，粘贴 API Key
- 自托管：填 URL（默认 `http://127.0.0.1:1933`）和 API Key；本地免鉴权可留空
- 向导若发现已有 `ovcli.conf`，直接复用即可
## 验证
@@ -33,8 +27,6 @@ hermes memory setup
hermes memory status
```
配置完成后，Hermes 会通过 OpenViking memory provider 自动注入上下文、预取相关记忆，并在会话后同步和抽取记忆。可用工具包括 `viking_search`、`viking_read`、`viking_browse`、`viking_remember`、`viking_forget` 和 `viking_add_resource`。
## 参见
- [Hermes — OpenViking memory provider 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 完整配置指南