Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: review agent integration guides and setup panels (#5507)
Zayn Jarvisdcca08fbd56f
diff --git a/docs/en/agent-integrations/01-overview.md b/docs/en/agent-integrations/01-overview.mdindex 94d849d28..63f2e0e28 100644--- a/docs/en/agent-integrations/01-overview.md+++ b/docs/en/agent-integrations/01-overview.md@@ -35,28 +35,17 @@ Every integration on this page connects to a running OpenViking server. If you d## Low-latency recall-Query expansion and recall-result compression are two independent, optional model calls. Disable both in the Agent plugin when response latency matters most; semantic retrieval, budgeting, tier degradation, and cross-turn dedup continue to work.--The same environment variables apply to both the Claude Code and Codex memory plugins. Query expansion is switchable in every memory plugin that resolves its settings through the shared loader; compression is Claude Code and Codex only.+Query expansion and recall compression add model calls. Disable both when response time takes priority; retrieval, budgets, and cross-turn deduplication remain enabled:```bashexport OPENVIKING_RECALL_QUERY_EXPANSION=offexport OPENVIKING_RECALL_COMPRESS=off```-Both plugins have a local compression path, but expose it differently:--- Claude Code defaults to `recallCompress=auto`: it prefers local `claude -p` (Sonnet with low effort) and falls back to an OpenViking server digest when the local CLI is unavailable. `client` forces local-only compression, while `server` forces server-only compression.-- Codex calls local `codex exec` by default, trying `gpt-5.3-codex-spark` first and then `gpt-5.6-luna` with low effort. It does not enable server-side compression.--The shared default is `recallCompress=auto`. `OPENVIKING_RECALL_COMPRESS=off` disables compression in both plugins; Codex interprets `auto` or `client` as enabling its local compressor. The old Claude Code variable `OPENVIKING_RECALL_REWRITE` remains supported for compatibility, but new configurations should use the unified name.--The same settings can live in `~/.openviking/ovcli.conf`:+Or configure them in `~/.openviking/ovcli.conf`:```json{- "url": "https://openviking.example.com",- "api_key": "your-api-key","plugin": {"recallQueryExpansion": "off","recallCompress": "off"@@ -64,8 +53,23 @@ The same settings can live in `~/.openviking/ovcli.conf`:}```-Environment variables take precedence over `ovcli.conf`. Restart the Agent after changing these settings so its hook processes reload the configuration. These are plugin-client settings; the server's `ov.conf` does not need to change.+### Choose a compression mode++| Value | Behavior |+| --- | --- |+| `off` | Do not compress recall results |+| `server` | Request compression on the OpenViking server |+| `client` | Use a local compressor only; supported by Claude Code and Codex |+| `auto` | Prefer a local compressor when available; otherwise request automatic server processing |++Claude Code and Codex default to `auto`. Their local compressors are `claude -p` and `codex exec`; see [§3.2.5](./16-capability-reference.md#_3-2-5-recall-digest). Other integrations that support cloud compression retain `off` as their default and require explicit opt-in. Server compression is supported by Claude Code, Codex, OpenCode, DSH, pi, Cursor, TRAE, TRAE CN, ZCode, OpenClaw, and Hermes. It requires a server with context-search rewrite support.++These settings control automatic recall. Explicit MCP `search` calls use the arguments supplied in that call. See the [shared plugin documentation](https://github.com/volcengine/OpenViking/blob/main/examples/memory-plugin-shared/README.md#cloud-recall-compression) for details and older-server fallback behavior.++Shared plugins read the `plugin` section in `ovcli.conf`; `plugin.<harness>` overrides a setting for one client. Environment variables take precedence; the older `OPENVIKING_RECALL_REWRITE` still works as an alias for `OPENVIKING_RECALL_COMPRESS`. See [Plugin settings](../configuration/02-client.md#plugin-settings). Restart the agent after changing settings so its hooks load the new configuration. These are plugin-client settings; the server's `ov.conf` does not need to change.++### Request timeout-The `plugin` section is read by every memory plugin — claude-code, codex, cursor, trae, trae-cn, zcode, kimicode, opencode, dsh and pi — and a `plugin.<harness>` object overrides the shared keys for one of them, under either spelling (`claude_code` or `claude-code`, `trae_cn` or `trae-cn`). Compression is the exception: the other harnesses honour `recallQueryExpansion` but ignore `recallCompress` and its companions, since none of them requests a server digest.+Query expansion, retrieval, and digest compression run in sequence. Query expansion defaults to a 5-second timeout (`retrieval.recall_intent_timeout_s`); digest rewriting defaults to 30 seconds (`retrieval.recall_rewrite_timeout_s`).-A context request waits longer than an ordinary request, because aborting it client-side discards the whole response rather than just the stage that ran long. The server pipeline is serial and each optional stage has its own fuse: query expansion (`retrieval.recall_intent_timeout_s`, 5s) runs first, then retrieval, body reads and budgeting, and only then the digest rewrite (`retrieval.recall_rewrite_timeout_s`, 30s). The deadline therefore follows what the request actually asks for — 15s once it carries a session and can spend the expansion fuse, 45s when it also asks for a digest, and the plugin's ordinary timeout when it asks for neither. Set `OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS` (or `plugin.recallContextTimeoutMs`) to pin it — keep it above the fuses the request will spend and below the Agent's own hook timeout.+`OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS` or `plugin.recallContextTimeoutMs` sets the client's timeout for the entire context request. When unset, the client waits the plugin's ordinary timeout, raised to at least 15 seconds when the request carries a session and query expansion is not `off` and at least 45 seconds when it asks for a digest. An override should exceed the server timeouts the request will spend and stay below the host's hook timeout. Ending the request early discards the entire response.diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.mdindex 83e2637ae..b42c2ccf0 100644--- a/docs/en/agent-integrations/02-claude-code.md+++ b/docs/en/agent-integrations/02-claude-code.md@@ -17,7 +17,7 @@ curl -fsSL https://openviking.ai/install | bashNo shell wrapper is needed anymore: the plugin ships a stdio MCP proxy that reads `~/.openviking/ovcli.conf` (or `OPENVIKING_*` env vars) at runtime, same as the hooks.-After using it for a while, try starting a new conversation and asking about something you mentioned earlier—it will remember.+After a session has been captured and processed, start a new conversation and ask about a specific fact from it to check cross-session recall.<details><summary><b>Manual setup</b></summary>@@ -66,7 +66,7 @@ The plugin hooks into the Claude Code lifecycle:- **For each subagent** — assigns an isolated memory session- **Before a native file tool touches a `viking://` path** — blocks the call and names the OpenViking MCP tool to use instead; a `Write` or `Edit` on a skill path is pointed to `add_skill`-All write operations run asynchronously, ensuring they never block your conversation.+Capture runs in a detached worker and does not block the conversation turn. PreCompact and SessionEnd wait for the session commit, within their hook timeouts.The skill catalog is an `<available-skills>` block that lists the skills stored in OpenViking: your own under `viking://~/skills` first, then the ones shared with your account under `viking://agent/skills`, each with a short description. Before following a listed skill, Claude reads its `SKILL.md` with the OpenViking `read` tool. The catalog has its own token budget: when the descriptions do not fit, it lists names only, and when not even one name fits, it shrinks to a one-line count. The bundled `openviking-skills` skill tells Claude how to find and use OpenViking skills, create, install, and share them with the `add_skill` MCP tool, delete them, and move local skills such as `~/.claude/skills` into OpenViking when you ask.@@ -97,7 +97,7 @@ Most of these knobs can also live in `ovcli.conf` under `plugin` — see [PluginIf recall latency matters most, see [Low-latency recall](./01-overview.md#low-latency-recall) for the environment-variable and `ovcli.conf` settings that disable query expansion and result compression.-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).+With a user/admin key, the server derives identity from the key. Set `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` only for trusted mode, using values supplied by your administrator. 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>@@ -119,7 +119,7 @@ The plugin renders an OpenViking status indicator beneath your Claude Code input| 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 | `~/.openviking/ovcli.conf` has no `url` (the proxy falls back to the local default) | Fix `ovcli.conf` (or run `node <plugin-dir>/scripts/setup.mjs`), then restart Claude Code || MCP tool calls fail with an auth error | The active ovcli config has no valid `api_key` for an authenticated server | Update the `api_key` in `ovcli.conf`; the stdio proxy re-reads it after auth failures |-| 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` |+| Remote auth 401 / 403 | Invalid credentials or insufficient permission | Check the active user/admin key and resource access. Only trusted mode requires administrator-supplied account/user headers; these headers cannot change a user key’s identity. |## See alsodiff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.mdindex af0045016..02a49983a 100644--- a/docs/en/agent-integrations/03-openclaw.md+++ b/docs/en/agent-integrations/03-openclaw.md@@ -29,7 +29,7 @@ bash cleanup-memory-openviking.sh```bashopenclaw plugins install clawhub:@openviking/openclaw-plugin-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --jsonopenclaw gateway restart```@@ -42,7 +42,7 @@ If ClawHub is unavailable:```bashnpm install -g openclaw-openviking-setup-helper-ov-install --base-url http://your-server:1933+ov-install --base-url https://openviking.example.com```Key parameters:@@ -74,10 +74,10 @@ For example:```bash# Alice is the OpenViking user; separate memories by OpenClaw assistant.-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role assistant --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --peer-role assistant --json# support-agent is the OpenViking user; separate memories by human sender.-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --peer-role sender --json```Setup and the installer accept only `sender`; existing `peer_role=person` configurations remain compatible and are treated as `sender`. OpenViking initializes the managed `peers/` container for every user, so `none` means that no concrete `peers/<peer_id>/memories` subtree is used. Actor-peer recall includes shared user memory plus the current peer memory, and changing the scope does not move existing memories.@@ -136,7 +136,7 @@ openclaw config get plugins.slots.contextEngine# expect: openviking```-For an end-to-end pipeline test:+From the OpenViking checkout, run the end-to-end test below after enabling the Gateway `/v1/responses` endpoint described in HEALTHCHECK.md. It sends real model requests and writes test conversations:```bashpython examples/openclaw-plugin/health_check_tools/ov-healthcheck.py@@ -160,7 +160,7 @@ Plugin config lives under `plugins.entries.openviking.config`. Setup usually wri| `autoRecallTimeoutMs` | `5000` | Outer timeout (ms) for the whole auto-recall flow; increase for slow local embedding hardware (clamped 1000–300000) |```bash-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.baseUrl https://openviking.example.comopenclaw config set plugins.entries.openviking.config.apiKey your-api-key```diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex c7a5194a5..40e5db45b 100644--- a/docs/en/agent-integrations/04-codex.md+++ b/docs/en/agent-integrations/04-codex.md@@ -1,6 +1,6 @@# Codex Memory Plugin-Equip [Codex](https://developers.openai.com/codex) with persistent memory across sessions. Install it once, and your OpenViking profile, memory index, and skill catalog are loaded at session start, relevant memories are recalled with every prompt, new turns are captured after each response, and sessions are committed before compaction. The plugin also connects Codex to OpenViking's `/mcp` endpoint, enabling the model to call tools such as `find`, `search`, `read`, and `remember` directly.+Give [Codex](https://developers.openai.com/codex) cross-session memory. Hooks handle automatic recall, capture, and session commits; MCP tools let the model search, read, and manage memories.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/)@@ -23,7 +23,7 @@ codex### First launch: trust the hooks-The plugin's hooks are new to Codex, so startup stops on a trust prompt. Pick **Trust all and continue**, or Review hooks first if you want to read the commands:+Installing the plugin does not automatically trust its hooks. On first launch Codex shows a review prompt similar to the one below; the exact layout varies by Codex version. Pick **Trust all and continue**, or **Review hooks** to read the commands first. *Continue without trusting* leaves the hooks off until you enable them in `/hooks`.```textHooks need review@@ -35,14 +35,9 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-A fresh install lists all 6 hooks the plugin registers. After that, any plugin update that touches a hook stops startup again, with the count of what changed this time (`1 hook is new or changed`, say) — pick Trust all and continue there too.+You can also open `/hooks`, review the OpenViking commands, and trust and enable the hooks you intend to use. In `/plugins`, also confirm that `openviking-memory` is enabled. The plugin currently declares six hooks. New or changed definitions require another review. See the [official hook trust documentation](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks).-Pick the third option, or skip past the prompt, and the hooks never run: MCP tools still work, but automatic recall and capture are both dead. Recovering means switching on two independent things:--- `/hooks` — hook trust and on/off state. Trust and enable the entries marked *New hook - review required* or *Modified since last trusted*.-- `/plugins` — the plugin's own enabled state. Confirm `openviking-memory` is enabled.--If either side is off, nothing is recalled or captured.+MCP tools can work while hooks are disabled. Automatic recall requires `UserPromptSubmit`; capture requires `Stop`, with lifecycle commits handled by the other hooks listed below. If setup was skipped, return to `/hooks` to enable the relevant entries.<details><summary><b>Manual setup</b></summary>@@ -69,7 +64,18 @@ For TraeCode CLI 2.0, launch `trae-cli` and use `trae-cli plugin list` to confir## How it works-The plugin integrates with Codex's lifecycle by hooking into key events. On `SessionStart` (`startup`, `clear`, or `resume`), it injects `profile.md`, URI and abstract indexes for `preferences/` and `entities/`, and an `<available-skills>` catalog of your OpenViking skills, all through the same shared, CJK-aware profile builder used by the other coding-agent integrations. It then searches OpenViking and injects relevant memories before every prompt (`UserPromptSubmit`), appends new turns to the session after each response (`Stop`), commits the full transcript before compaction (`PreCompact`), and commits the session when the thread shuts down (`SessionEnd`) so memory extraction processes the entire conversation. Before a shell command runs (`PreToolUse` on `Bash`), it looks for a `viking://` URI in the command: the command still runs, and the model gets a notice suggesting the OpenViking MCP tools, which it can ignore when the URI is intentional data such as an `ov` argument. Upon starting a fresh session, it also sweeps any orphaned sessions left by previous runs. A resumed session may combine the fixed profile block with its latest archive digest.+The plugin handles memory at these Codex lifecycle events:++| Codex event | Plugin behavior |+| --- | --- |+| `SessionStart` (`startup`, `clear`, `resume`) | Inject `profile.md`, URI and abstract indexes for `preferences/` and `entities/`, and the `<available-skills>` catalog. It uses the shared CJK-aware profile builder; resumed sessions may also receive the latest archive digest. |+| `UserPromptSubmit` | Retrieve and inject memories relevant to the current prompt. |+| `Stop` | Append new conversation turns to the OpenViking session. |+| `PreCompact` | Capture remaining turns and commit the complete transcript before compaction. |+| `SessionEnd` | Commit the session on graceful exit for subsequent memory extraction. |+| `PreToolUse` (`Bash`) | Detect `viking://` URIs in shell commands and suggest the OpenViking MCP tools. The command still runs; the model can ignore the notice when the URI is intentional data, such as an `ov` argument. |++Starting a new session also sweeps orphaned sessions from earlier runs once their idle TTL has expired.> **Known limitation**: `SessionEnd` requires Codex 0.145 or newer, and it only fires on a graceful exit (`/quit`, `/exit`, double `Ctrl-C`, EOF, end of a `codex exec` run). It does not fire on `SIGTERM`, a closed terminal, `kill -9`, or a crash, and it is deferred when the TUI runs against a `codex app-server` daemon. Those sessions — and every session on Codex older than 0.145, and any TraeCode CLI build without it — are recovered by the idle-TTL sweep (30 minutes) at the next `SessionStart`.@@ -120,8 +126,8 @@ Change it with `OPENVIKING_PEER_SOURCE`, with `plugin.peerSource` in `ovcli.conf|---------|-------|-----|| MCP tool calls fail with an auth error | The active ovcli config has no valid `api_key` for an authenticated server | Fix `~/.openviking/ovcli.conf` (or run `node <plugin-dir>/scripts/setup.mjs`) and restart Codex; the stdio proxy re-reads it on launch and after auth failures. || MCP tool calls fail with a connection error | Server unreachable or the URL is wrong | Check the endpoint: `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |-| `6 hooks need review`, or the plugin is installed but no hook fires | A fresh install trusts all 6 hooks at once, and every later update that touches a hook asks again; choosing *Continue without trusting* or skipping it leaves the hooks off for good | Trust and enable the entries in `/hooks`, and confirm `openviking-memory` is enabled in `/plugins` — two independent switches, both have to be on. |-| Plugin still targets an old server after `ov config switch` | Codex keeps the proxy process from the previous session | Restart Codex; the proxy resolves credentials at startup. |+| Hook review warning, or installed plugin with no recall/capture | Required hooks are untrusted, disabled, or the plugin is disabled | Review and enable the relevant entries in `/hooks`, then confirm `openviking-memory` in `/plugins`. |+| Plugin still targets an old server after `ov config switch` | The existing proxy retains its connection, or credential env vars override the selected config | Restart Codex and check credential env vars and `OPENVIKING_CLI_CONFIG_FILE`. Remote calls reload changed files after an auth failure, not on every successful request. || Hooks use one server, MCP another | Stale `OPENVIKING_*` credential env vars in one context (env vars override ovcli.conf by default) | Unset the stale env vars (ovcli.conf then drives both), set `OPENVIKING_CREDENTIAL_SOURCE=cli`, or make the env vars consistent. |## See alsodiff --git a/docs/en/agent-integrations/06-mcp-clients.md b/docs/en/agent-integrations/06-mcp-clients.mdindex b56199491..450378d61 100644--- a/docs/en/agent-integrations/06-mcp-clients.md+++ b/docs/en/agent-integrations/06-mcp-clients.md@@ -1,10 +1,10 @@# MCP Clients-Any [MCP](https://modelcontextprotocol.io/)-compatible client can connect to OpenViking's built-in `/mcp` endpoint — no plugin installation or extra processes needed. This covers Cursor, Trae, Manus, Claude Desktop, ChatGPT, and others.+Clients supporting [MCP](https://modelcontextprotocol.io/) Streamable HTTP can connect directly to OpenViking's `/mcp` endpoint. Clients that support only stdio can use the proxy in the [Agent Plugins package](./15-agent-plugins.md).## Quick setup-Most MCP clients use the standard `mcpServers` format:+Clients accepting `mcpServers` and custom headers can use this example. For other clients, follow the platform-specific instructions below:```json{@@ -19,7 +19,7 @@ Most MCP clients use the standard `mcpServers` format:}```-No authentication is needed when connecting to a local server without `root_api_key` configured (dev mode).+No authentication is needed for a server running in `dev` mode. Keep it bound to loopback; an authenticated server still requires credentials when accessed locally.## Platform-specific notes@@ -37,9 +37,13 @@ Add `--scope user` to make the config global across all projects.> For auto-recall and auto-capture without manual tool calls, use the [Claude Code Memory Plugin](./02-claude-code.md) instead.-### Trae / Cursor / ChatGPT+### Trae / Cursor-Standard `mcpServers` config as shown above — all verified with API key auth.+Add the service URL and API key shown above to the client's MCP configuration.++### ChatGPT++Create a custom App in developer mode and complete OAuth authorization. See the [OAuth guide](../guides/11-oauth.md#chatgpt-codex-plus-enterprise).### Codex@@ -67,9 +71,9 @@ Use OpenCode's native `mcp` config in `~/.config/opencode/opencode.json`:### Claude Desktop / Claude.ai (OAuth)-These clients require OAuth 2.1 — API keys cannot be passed directly. OpenViking ships a native OAuth 2.1 implementation, so no external proxy is needed.+For the hosted remote-connector flow, use OpenViking’s native OAuth implementation. At the authorization page, sign in with an existing OpenViking User/Admin key. Claude Desktop’s local stdio configuration is a separate connection path.-If you already have HTTPS configured for your OpenViking server, just connect to `https://your-server.com/mcp` — the client will walk you through the OAuth authorization flow automatically.+Enable `oauth.enabled` on the server and configure HTTPS, then connect the client to `https://your-server.com/mcp` and complete authorization in the browser.See the [OAuth 2.1 Guide](../guides/11-oauth.md) and [Public Access Guide](../guides/12-public-access.md) for HTTPS setup, deployment templates, and the full authorization flow.@@ -82,7 +86,7 @@ Once connected, OpenViking exposes retrieval, memory, resource, watch, filesyste| Symptom | Fix ||---------|-----|| Connection refused | Verify `openviking-server` is running: `curl http://localhost:1933/health` |-| Authentication errors | Ensure the API key in your client config matches the server. See [Authentication Guide](../guides/04-authentication.md) |+| Authentication errors | Check that the client uses a valid user/admin key. See [Authentication Guide](../guides/04-authentication.md) |## See alsodiff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.mdindex 8d051b90c..f67157839 100644--- a/docs/en/agent-integrations/07-langchain-langgraph.md+++ b/docs/en/agent-integrations/07-langchain-langgraph.md@@ -221,7 +221,7 @@ docs = retriever.invoke("What did the user decide about deployment?")### Context backend```python-from langchain_core.messages import AIMessage+from langchain_core.messages import AIMessage, HumanMessagefrom langchain_core.runnables import RunnableLambdafrom langchain_openviking import with_openviking_context@@ -230,7 +230,10 @@ with with_openviking_context(url="http://localhost:1933",api_key="...",) as chain:- result = chain.invoke(...)+ result = chain.invoke(+ [HumanMessage(content="Remember that I prefer short answers")],+ config={"configurable": {"session_id": "support-thread-1"}},+ )```### Agent toolsdiff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.mdindex fc09f20da..57f2eb7be 100644--- a/docs/en/agent-integrations/08-community-plugins.md+++ b/docs/en/agent-integrations/08-community-plugins.md@@ -85,11 +85,13 @@ Provides auto-capture of group/DM conversations, semantic recall before each LLM**Install**: In AstrBot WebUI, search **OpenViking Memory** in the Plugin Marketplace; or install from URL: `https://github.com/t0saki/astrbot_plugin_openviking_memory.git`+The current plugin requires AstrBot 4.23.1+ and a compatible OpenViking server. Use a User key for `global`; `venue` needs an Admin key to create users. Check the linked plugin README before migrating an older configuration.+**Key features**:- Auto-recall and auto-capture via hooks — the model doesn't need to invoke tools-- Three isolation modes: `venue_user` (per-group/DM), `venue_user_fanout` (cross-venue sharing), `global_user` (single user)-- Four auto-commit triggers: message count, token threshold, idle timeout, and process-exit flush+- `self_scope=global` shares one bot identity; `venue` creates a separate user per group/DM. People are represented as peers. Legacy `isolation_mode` values are mapped to these scopes.+- Automatic commit by message count, token threshold, or idle timeout- Backfills platform message history on first venue encounter## Open WebUI tool serverdiff --git a/docs/en/agent-integrations/09-log-ingestion.md b/docs/en/agent-integrations/09-log-ingestion.mdindex 1e4694fa2..4589485d6 100644--- a/docs/en/agent-integrations/09-log-ingestion.md+++ b/docs/en/agent-integrations/09-log-ingestion.md@@ -1,8 +1,8 @@# Import Local Agent Logs (openviking-server ingest)-`openviking-server ingest` parses the conversation logs that AI coding / agent harnesses (Claude Code, Codex, WorkBuddy, OpenCode, MiMo, Hermes, OpenClaw) already leave on your machine, then "replays" them through OpenViking's existing session pipeline (`create session → batch add messages → commit`, where commit triggers memory extraction). This turns both your historical and newly written conversations into long-term memory. It complements the per-harness memory plugins: a plugin captures **while a conversation is happening**, whereas this tool is for **importing existing logs** and **watching for new logs offline** — no plugin required and no change to the harness itself.+`openviking-server ingest` reads local agent conversation logs, imports the messages into OpenViking sessions, and commits them for memory extraction. It supports one-time historical imports and ongoing log monitoring without changing the agent or installing a memory plugin.-Key difference from the plugins: this tool is an OpenViking **client**. It runs where the logs live and points at a local or remote server via the SDK, and it is **off by default** — installing OpenViking does not silently scan your local files.+Run it on the machine that holds the logs. It connects to a local or remote OpenViking server through the SDK. Ingestion is disabled by default, so installing OpenViking does not scan local logs; enable both the main switch and the configuration for each chosen agent.Source: [openviking/ingest](https://github.com/volcengine/OpenViking/tree/main/openviking/ingest)@@ -98,7 +98,7 @@ openviking-server ingest runopenviking-server ingest status```-`--reset` deletes and recreates the OV session before replaying. Without `--reset`, re-running is idempotent — the cursor store guarantees nothing is appended twice.+`--reset` deletes and recreates the OV session before replaying; it does not remove memories already extracted from earlier imports. Normal reruns resume from the persisted cursor and reconcile interrupted batches against the server message count. Keep the cursor database, avoid simultaneous replay processes or other writers to imported sessions, and do not reuse one cursor database for a different server or user.## peer_id@@ -123,13 +123,13 @@ Each harness has a thin adapter that parses its logs into normalized messages an- **Backfill** enumerates every session, replays from the cursor to the end, then commits once per session.- **Watch** mirrors OpenViking's own `WatchScheduler`: it uses **interval polling** (not filesystem events) driven by durable cursors, so a missed tick, a sleep, or a restart just reads cursor→end on the next tick and self-heals. JSONL uses a byte-offset cursor (with partial-line / truncation / rotation handling); SQLite uses a `(time, id)` cursor read read-only (WAL-aware).-Cursor state persists in `~/.openviking/ingest/state.db`, so both backfill and watch resume across restarts without re-ingesting.+Cursor state persists in `~/.openviking/ingest/state.db`, so backfill and watch can resume after a restart under the same connection identity.## Cost and privacy- Commit triggers memory extraction (an LLM call). Backfilling months of history at once can produce many calls — prefer `--dry-run` first, narrow with `--since`, and enable harnesses in batches.- Logs may contain sensitive content (credentials, file contents). Use this in a trusted deployment and confirm `server_url` points at the server you intend.-- Tool-call inputs/outputs are dropped as low-value by default; only user / assistant text is ingested.+- The default import keeps user/assistant text and drops tool-call inputs and outputs. Use a runtime plugin when you need structured tool capture.## See alsodiff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex 8a94f1ff7..440837cbd 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -10,13 +10,13 @@ Source: [examples/pi-coding-agent-extension](https://github.com/volcengine/OpenV- **Every prompt** runs semantic recall against the OpenViking server and injects matching memories as hidden context.- **Every turn** captures user and assistant messages (including structured tool calls) into an OpenViking session; takeover mode commits once synced-token pressure crosses the threshold and then keeps only the recent live tail in model context.- **Context takeover** is enabled by default. The `context` hook injects `[OpenViking Session Context]` from the latest archive overview before recall is added to the latest user turn.-- **Model-callable tools** are whatever the server's MCP `tools/list` returns, each registered under an `openviking_` prefix — the same 15 tools the other memory plugins expose: `openviking_find`, `openviking_search`, `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`, `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`, `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`. The extension keeps no tool catalogue of its own, so a server that adds or drops a tool changes pi's tool surface at the next session, with no extension release. The shared `mcpEnabled: false` turns the tool surface off and leaves recall, capture, and takeover running.+- **Model-callable tools** are whatever the server's MCP `tools/list` returns, each registered under an `openviking_` prefix, including `openviking_find`, `openviking_search`, `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`, `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`, `openviking_add_skill`, `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`. The extension keeps no tool catalogue of its own, so a server that adds or drops a tool changes pi's tool surface at the next session, with no extension release. The shared `mcpEnabled: false` turns the tool surface off and leaves recall, capture, and takeover running.- **Skills**: the extension ships `openviking-memory`, `openviking-skills`, and `ov-experience-memory` from its `skills/` directory and adds them through pi's `resources_discover` event, so the model knows when to use which OpenViking tool. They are left out when `mcpEnabled` is `false`.-- The tool handshake never fails startup. When it fails — server down, credentials rejected, no `/mcp` endpoint — the session keeps recall, capture, and takeover and simply has no OpenViking tools; the bridge retries on a later turn, so a server started after pi is picked up without a restart.+- The tool handshake never fails startup. If only the MCP handshake fails, REST recall, capture, and takeover can still work. If the server is unavailable or authentication fails, those features also fail or fall back; the bridge retries on a later turn, so a server started after pi is picked up without a restart.- A footer status segment (`OV ✓ …`) shows connection and capture state, plus `tools ✗` when the handshake failed; the `/viking` command prints status, including the registered tool count or the last handshake error, and `/viking commit` forces a commit.- Accidental `read`/`grep`/`find`/`ls`/`write`/`edit` calls whose path is a `viking://` URI are blocked with a hint pointing to the matching `openviking_*` tool. A `bash` command that carries a `viking://` URI still runs, and its result ends with a notice suggesting `openviking_read` / `openviking_search`.-Extension 0.4.0 replaced the seven hand-written `viking_*` REST tools with this mirrored surface, with no alias period: a `--tools` / `--exclude-tools` allowlist that pins the old names must be updated by hand, or those tools silently disappear. Some semantics moved with the names — `openviking_remember` writes through its own session that the server commits immediately, `openviking_read` returns full text only (the old `level="abstract"` / `"overview"` tiers are gone; use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)` for the condensed views), and `openviking_forget` deletes the URI you give it instead of the strongest match of a query. Context takeover still injects the archive overview itself over REST, so that path is unchanged.+Extension 0.4.0 replaced the seven hand-written `viking_*` REST tools with this mirrored surface, with no alias period: a `--tools` / `--exclude-tools` allowlist that pins the old names must be updated by hand, or those tools silently disappear. Some semantics moved with the names — `openviking_remember` writes through its own session that the server commits immediately, `openviking_read` reads file content, with line pagination (the old `level="abstract"` / `"overview"` tiers are gone; use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)` for the condensed views), and `openviking_forget` deletes the URI you give it instead of the strongest match of a query. Context takeover still injects the archive overview itself over REST, so that path is unchanged.Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).diff --git a/docs/en/agent-integrations/12-cursor.md b/docs/en/agent-integrations/12-cursor.mdindex b3308139e..822535776 100644--- a/docs/en/agent-integrations/12-cursor.md+++ b/docs/en/agent-integrations/12-cursor.md@@ -6,7 +6,7 @@ Give Cursor long-term memory across projects and sessions. After installation, OPrerequisites: macOS or Linux, Node.js 18+, and preferably the latest stable Cursor release. The installer guides you through the OpenViking connection settings.-When prompted for the connection, Volcengine Cloud users should select **Volcengine OpenViking Cloud** and enter their API key. Select **Self-hosted / local** only when an OpenViking server is running locally.+When prompted for the connection, Volcengine Cloud users should select **Volcengine OpenViking Cloud** and enter their API key. Select **Self-hosted / local** for a server on this machine (`http://127.0.0.1:1933`); for a remote self-hosted server, select **Custom URL / keep current** and enter its URL.```bashcurl -fsSL https://openviking.ai/install | bash@@ -28,7 +28,7 @@ Quit Cursor completely and restart it after installation.2. Open **Cursor Settings → Hooks** and confirm that the OpenViking lifecycle Hooks execute `scripts/hook.mjs` and its URI protection Hook executes `scripts/uri-guard.mjs`.3. Check that the `beforeSubmitPrompt` output contains `additional_context`. This confirms that recall reaches the Agent without requiring an MCP call first.4. Open **Cursor Settings → Tools & MCPs** and confirm that `openviking` is connected.-5. Tell Cursor a temporary preference, wait for the response to finish, then create a new session and ask for that preference to verify capture and cross-session recall.+5. Tell Cursor a test preference, end the session normally, and confirm capture and commit in the Hook log. After memory extraction completes, start a new session in the same workspace and ask about it.## How it worksdiff --git a/docs/en/agent-integrations/13-trae.md b/docs/en/agent-integrations/13-trae.mdindex de1c3f5bf..d2f01199c 100644--- a/docs/en/agent-integrations/13-trae.md+++ b/docs/en/agent-integrations/13-trae.md@@ -6,7 +6,7 @@ Give TRAE, TRAE CN, and TraeCode CLI 2.0 long-term memory across projects and sePrerequisites: macOS or Linux, Node.js 18+, and a TRAE/TRAE CN release that supports the `SessionStart`, `UserPromptSubmit`, `PreToolUse`, and `Stop` Hooks. TraeCode CLI 2.0 uses the Codex-compatible plugin format directly. The installer guides you through the OpenViking connection settings.-When prompted for the connection, Volcengine Cloud users should select **Volcengine OpenViking Cloud** and enter their API key. Select **Self-hosted / local** only when an OpenViking server is running locally.+When prompted for the connection, Volcengine Cloud users should select **Volcengine OpenViking Cloud** and enter their API key. Select **Self-hosted / local** for a server on this machine (`http://127.0.0.1:1933`); for a remote self-hosted server, select **Custom URL / keep current** and enter its URL.```bashcurl -fsSL https://openviking.ai/install | bash@@ -17,7 +17,7 @@ When the installer asks which harnesses to install, select **TRAE**, **TRAE CN**### TraeCode CLI 2.0: trust the hooks on first launch-TraeCode CLI 2.0 hooks only run once you trust them. Starting `trae-cli` stops on this prompt — pick **Trust all and continue**, or Review hooks first if you want to read the commands:+TraeCode CLI 2.0 uses the Codex-format plugin. Starting `trae-cli` shows a hook review prompt similar to the one below; the exact layout varies by version. Pick **Trust all and continue**; *Continue without trusting* leaves the hooks off.```textHooks need review@@ -29,22 +29,17 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-A fresh install lists all 6 hooks the plugin registers. After that, any plugin update that touches a hook stops startup again, with the count of what changed this time (`1 hook is new or changed`, say) — pick Trust all and continue there too.+You can also use `/hooks` to review the OpenViking commands and trust and enable the hooks you want to use. Confirm `openviking-memory` is enabled in `/plugins`. Modified definitions may need review again. MCP connectivity alone does not verify recall or capture; see the [Codex hook setup](04-codex.md#first-launch-trust-the-hooks).-Pick the third option, or skip past the prompt, and the hooks never run: MCP tools still work, but automatic recall and capture are both dead. Recovering means switching on two independent things:--- `/hooks` — hook trust and on/off state. Trust and enable the entries marked *New hook - review required* or *Modified since last trusted*.-- `/plugins` — the plugin's own enabled state. Confirm `openviking-memory` is enabled.--TRAE and TRAE CN read `hooks.json` directly and need no such approval — restarting the client is enough.+TRAE and TRAE CN use the installed `hooks.json` and need no hook approval; restart the corresponding client after installation.## What gets installed- `SessionStart` loads your profile, current project memory, and an `<available-skills>` catalog of your OpenViking skills.- `UserPromptSubmit` recalls and injects context for the current request, including your own skills and those shared with your account under `viking://agent/skills`.- `PreToolUse` on TRAE and TRAE CN denies `Read`, `Glob`, and `Grep` calls whose path is a `viking://` URI and points to OpenViking MCP tools; a `Bash` or `RunCommand` command that carries a `viking://` URI still runs, with a notice suggesting those tools. TraeCode CLI 2.0 uses the Codex plugin, whose `PreToolUse` matches only `Bash`: it adds the same notice and never denies a call.-- `Stop` captures and immediately commits the completed turn, including short sessions.-- The OpenViking MCP server transparently exposes the full server MCP tool set (16 tools): `find`, `search`, `read`, `list`, `tree`, `remember`, `write`, `edit`, `add_resource`, `add_skill`, `list_watches`, `cancel_watch`, `grep`, `glob`, `forget`, and `health`. `search` with `mode="context"` returns assembled context.+- TRAE/TRAE CN `Stop` captures and commits the completed turn. TraeCode CLI 2.0 follows the Codex plugin’s capture and lifecycle commit policy.+- The OpenViking MCP server transparently exposes the full server MCP tool set (20 tools): `find`, `search`, `read`, `list`, `tree`, `remember`, `write`, `edit`, `add_resource`, `add_skill`, `list_watches`, `cancel_watch`, `grep`, `glob`, `forget`, `health`, `list_users`, `list_groups`, `get_acl`, and `set_acl`. `search` with `mode="context"` returns assembled context.The skill catalog lists your own skills before those shared with your account, with each description cut to about 40 tokens. Its budget, `skillCatalogTokenBudget` (default `1200` tokens), is separate from the profile budget; when not every description fits, the catalog lists names only. Set `skillCatalog` to `false` or the budget to `0` to turn it off, either in the `plugin` section of `~/.openviking/ovcli.conf` ([Plugin Settings](../configuration/02-client.md#plugin-settings)) or through `OPENVIKING_SKILL_CATALOG` and `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`.## Verify@@ -52,7 +47,7 @@ The skill catalog lists your own skills before those shared with your account, w1. Restart TRAE, TRAE CN, or TraeCode CLI 2.0 and create a new Agent session.2. Confirm that `openviking` is connected in the client's MCP settings.3. Ask about an existing project or preference and confirm that the answer uses stored memory.-4. Tell the Agent a temporary preference, wait for the response to finish, then create a new session and ask for it again to verify capture, commit, and cross-session recall.+4. Tell the Agent a temporary preference, confirm capture and commit in the logs, then wait for memory extraction before asking about it in a new session in the same workspace.5. For TraeCode CLI 2.0, run `trae-cli plugin list` to confirm that `openviking-memory` is enabled, then run `/hooks` in the session and confirm the OpenViking entries are trusted and switched on.For Hook diagnostics, start the client with `OPENVIKING_DEBUG=1` and inspect:diff --git a/docs/en/agent-integrations/15-agent-plugins.md b/docs/en/agent-integrations/15-agent-plugins.mdindex 90c143456..1c24c4427 100644--- a/docs/en/agent-integrations/15-agent-plugins.md+++ b/docs/en/agent-integrations/15-agent-plugins.md@@ -36,7 +36,7 @@ OpenViking already speaks streamable HTTP at `/mcp`, but a `streamable-http` ent## Credential resolution-Highest to lowest priority — the same chain as the `ov` CLI and the other OpenViking plugins:+This package resolves credentials from the following sources, highest to lowest priority. It shares credential files with the CLI; plugin-specific fallbacks are listed explicitly:1. Environment variables: `OPENVIKING_URL` (or `OPENVIKING_BASE_URL`), `OPENVIKING_MCP_URL`, `OPENVIKING_API_KEY` (or `OPENVIKING_BEARER_TOKEN`), `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_PEER_ID`, `OPENVIKING_AUTH_MODE`2. `~/.openviking/ovcli.conf` (`url`, `api_key`, `account` / `account_id`, `user` / `user_id`, `actor_peer_id` / `peer_id`), then its `plugin.agent_plugins` and shared `plugin` keys (`apiKey`, `accountId`, `userId`, `authMode`) — override the path with `OPENVIKING_CLI_CONFIG_FILE`@@ -57,6 +57,8 @@ Highest to lowest priority — the same chain as the `ov` CLI and the other Open}```+Use a User/Admin key for `/mcp`. The legacy `server.root_api_key` fallback does not make a root key valid for MCP access.+Config file changes are picked up by the running proxy without a restart.Debugging: set `OPENVIKING_DEBUG=1` to write JSON lines to `~/.openviking/logs/agent-plugins.log` (override the path with `OPENVIKING_DEBUG_LOG`). Set `OPENVIKING_TIMEOUT_MS` to change the 15s per-request timeout.@@ -71,7 +73,7 @@ The bundled `ov-experience-memory` skill has the model search `viking://~/memoriThe bundled `openviking-skills` skill covers the skills stored in OpenViking itself: finding one with `find(context_type="skill")`, reading and following its `SKILL.md`, creating or replacing one with `add_skill`, installing one from Git or a local folder, sharing one with the account, and moving local skill folders into OpenViking. Without a session-start hook there is no `<available-skills>` catalog here, so the skill has the model search for a skill rather than read it off a list.-**If your harness has its own hook system, prefer the dedicated plugin.** Hook-driven recall and capture happen without the model spending tool calls or deciding to remember, which is both cheaper and more reliable than the skill-driven loop. Use this Agent Plugins package for harnesses that have no hooks, or when you want one package that works across many clients.+**If your harness has its own hook system, prefer the dedicated plugin.** Hook-driven recall and capture happen without the model spending tool calls or deciding to remember. Use this Agent Plugins package for harnesses that have no hooks, or when you want one package that works across many clients.One installer covers Claude Code, Codex, Cursor, TRAE / TRAE CN, ZCode, OpenCode, and pi. It asks which harnesses to install and for your OpenViking credentials, and every step is idempotent:diff --git a/docs/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex e2ee2a615..3ab1f09f7 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -26,21 +26,21 @@ precedence while present; use the [normal setup guide](./05-hermes.md) for it.## 1.1 Active tool surface (agentic calls)-- **MCP-based harnesses (claude-code, codex/trae-cli, cursor, trae/trae-cn, zcode, kimicode, opencode, dsh, pi) share an identical active tool surface comprising 16 tools.** The server centrally defines these tools. The plugins read `~/.openviking/ovcli.conf` and connect to the server-defined MCP tools. pi uses the official MCP client inside its extension and registers the discovered tools as native pi tools.+- **MCP-based harnesses (claude-code, codex/trae-cli, cursor, trae/trae-cn, zcode, kimicode, opencode, dsh, pi) share an identical active tool surface comprising 20 tools.** The server centrally defines these tools. The plugins read `~/.openviking/ovcli.conf` and connect to the server-defined MCP tools. pi uses the official MCP client inside its extension and registers the discovered tools as native pi tools.- `trae-cli` means TraeCode CLI 2.0 (2.0 only). It is installed via a `codex` plugin alias and maintains format compatibility with `codex`. Therefore, it is consolidated into the `codex` row in the matrices below.| harness | tool surface | tools (enabled by default) | search memory | search resource | search skill | write memory | write resource | write skill | delete type boundary ||---|---|---|---|---|---|---|---|---|---|-| claude-code | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| codex / trae-cli | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| cursor | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| trae / trae-cn | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| zcode | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| kimicode | MCP passthrough | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| opencode | MCP passthrough (host adds an `openviking_` prefix) | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| dsh | MCP passthrough (`@deepseek-ai/dsh-mcp-client` → the shared stdio proxy; host adds an `mcp__openviking__` prefix) | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |-| pi | MCP mirror (official client; extension adds an `openviking_` prefix) | 16, i.e. whatever `tools/list` returns (registration has preconditions³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| claude-code | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| codex / trae-cli | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| cursor | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| trae / trae-cn | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| zcode | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| kimicode | MCP passthrough | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| opencode | MCP passthrough (host adds an `openviking_` prefix) | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| dsh | MCP passthrough (`@deepseek-ai/dsh-mcp-client` → the shared stdio proxy; host adds an `mcp__openviking__` prefix) | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² |+| pi | MCP mirror (official client; extension adds an `openviking_` prefix) | 20, i.e. whatever `tools/list` returns (registration has preconditions³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² || openclaw | native registration (15 × `memory_*`/`ov_*` and friends) | 15 (14 on by default⁴) | ✅ `memory_recall` | ✅ `ov_search` (both scopes by default) | ✅ `ov_search` | ✅ `memory_store` | off by default⁴ | ✅ `add_skill` | memory-only allowlist + auto-delete only for a single candidate with score≥0.85 || hermes | native registration (6 × `viking_*`) | 6 (all on once the provider is active) | ✅ | ✅ | ✅ | ✅ `viking_remember` (dedicated session and asynchronous extraction) | ✅ multi-protocol ingest (HTTP/Git/SSH/local file/directory zip) | ❌ | memory-only + `.md` leaf check || ov CLI | CLI commands | ~40 command groups | ✅ `ov find` | ✅ `ov find` | ✅ `ov find` | ✅ `ov add-memory` | ✅ `ov add-resource` | ✅ `ov add-skill` | `ov rm` executes directly (TUI deletion asks for confirmation and blocks root/scope deletes) |@@ -54,10 +54,10 @@ precedence while present; use the [normal setup guide](./05-hermes.md) for it.## 1.2 Automatic hook surface (driven by the harness)-| harness | how it plugs in | auto-recall | recall carries session_id | digest (client)* | profile injection | takes over host compaction | offline compensation (pending queue) | statusline |+| harness | how it plugs in | auto-recall | recall carries session_id | digest (client)* | profile injection | takes over host compaction | offline compensation | statusline ||---|---|---|---|---|---|---|---|---|| claude-code | 9 hooks + MCP proxy + slash + statusline + skill | ✅ | ✅ | ✅ local `claude -p` / server-side rewrite (auto by default) | ✅ (10000) + `<available-skills>` (1200) | ❌ (PreCompact only commits) | ✅ | ✅ |-| codex / trae-cli | 6 hooks + MCP proxy + skill | ✅ | ✅ | ✅ local `codex exec` (on by default) | ✅ (10000) + `<available-skills>` (1200) | ❌ | ✅ | ❌ |+| codex / trae-cli | 6 hooks + MCP proxy + skill | ✅ | ✅ | ✅ local `codex exec` (on by default) | ✅ (10000) + `<available-skills>` (1200) | ❌ | ✅ transcript + cursor | ❌ || cursor | 6 hooks + MCP proxy + rule + skill | ✅ | ✅ | ❌ | ✅ (10000) + `<available-skills>` (1200) | ❌ | ✅ | ❌ || trae / trae-cn | 4 hooks + MCP proxy | ✅ | ✅ | ❌ | ✅ (10000) + `<available-skills>` (1200) | ❌ | ✅ | ❌ || zcode | 4 hooks + MCP proxy | ✅ | ✅ | ❌ | ✅ (10000) + `<available-skills>` (1200) | ❌ | ✅ | ❌ |@@ -91,7 +91,7 @@ In the profile injection column, the first number is the default `profileTokenBuThe individual harness sections (profile cards) focus exclusively on differences and specific implementations. All shared capabilities and universal behaviors are documented once in this section.## 2.1 Server-side MCP tool surface-These tools are defined on the server side, and future updates will be centrally published there. Harnesses only need to proxy the MCP to obtain the latest `~/.openviking/ovcli.conf`.+Tool definitions come from the server through `tools/list`. The proxy reads connection settings from the local `~/.openviking/ovcli.conf`, then connects to discover tools. After a server update, reconnect or refresh the tool list. Counts on this page describe the current repository implementation; the connected server determines the actual list.| # | Tool | What it does | Key parameters (definition line) ||---|---|---|---|@@ -109,13 +109,17 @@ These tools are defined on the server side, and future updates will be centrally| 12 | `cancel_watch` | Cancel by `to_uri`; not yet supported on the commercial edition | Deliberately does not expose pause/resume/trigger/update (`:1653`) || 13 | `grep` | Regex content search | Multiple patterns run concurrently (semaphore of 10), `node_limit=10` (`:1696`) || 14 | `glob` | Filename glob | `node_limit=100` (`:1765`) |-| 15 | `forget` | Permanently deletes a URI (unrecoverable) | `recursive=False` by default; type boundaries in [§3.5](#_3-5-type-boundaries-for-writes-and-deletes) (`:1791`) |+| 15 | `forget` | Permanently deletes a URI (irreversible) | `recursive=False` by default; type boundaries in [§3.5](#_3-5-type-boundaries-for-writes-and-deletes) (`:1791`) || 16 | `health` | Health check | No parameters (`:1808`) |+| 17 | `list_users` | List account user IDs; credentials are opt-in, require ADMIN/ROOT, and are unavailable in trusted mode | `query`, `limit`, `page`, `include_credentials` (`mcp_endpoint.py:356`) |+| 18 | `list_groups` | List account group IDs without membership | No user parameters (`mcp_endpoint.py:394`) |+| 19 | `get_acl` | Read a resource ACL; requires manage permission or account ADMIN | `uri` (`mcp_endpoint.py:408`) |+| 20 | `set_acl` | Set a resource ACL; requires manage permission or account ADMIN | `uri`, `acl` (`mcp_endpoint.py:418`) |Supporting mechanisms:- **Portable schema rewriting** (`:1149-1218`): At module import time, every tool's `anyOf` / `$ref` is flattened into a plain type to ensure compatibility with clients that only support the OpenAPI 3.0 subset (such as Gemini). Runtime validation still relies on the original Python signature (for instance, `read` advertises an array schema but continues to accept a bare string). All MCP clients receive the exact same server-produced schema; there are no client-specific variants.-- **Identity middleware** (`:149-233`): Shares `resolve_identity` with REST endpoints. It reads headers in the following order: `x-api-key`, `authorization`, `x-openviking-account`, `x-openviking-user`, and `x-openviking-actor-peer`. If absent, the account and user fields fall back to `"default"`.+- **Identity middleware** (`:149-233`): Shares `resolve_identity` with REST endpoints. Identity depends on the authentication mode: API key mode resolves the account and user from the key, trusted mode accepts identity headers from a trusted gateway, and dev mode accepts account/user headers and defaults missing values to `default`. Actor peer is resolved separately and cannot override authentication. See [Authentication](../guides/04-authentication.md).## 2.2 The memory-plugin-shared layer@@ -158,7 +162,7 @@ Core modules at a glance (detailed further in the per-dimension sections):- **Server-side auto-commit is disabled by default unless an explicit or deployment-default policy enables it**:- `memory.session_auto_commit.enabled = false` (`memory_config.py`). Auto-commit is disabled for sessions lacking a storage policy (`session_service.py`). Furthermore, the idle scanner isn't even instantiated when `enabled=false` (`core.py`), effectively acting as a double gate.- The `auto_create` path triggered by `POST /messages` accepts no policy arguments, but it inherits `server.user_config_defaults.auto_commit_policy` when configured. `POST /sessions` and `PATCH /sessions/{id}/config` remain the explicit per-session controls.- - Currently, no plugin sends an `auto_commit_policy`. Among first-party clients, only the **ov CLI** does this (`ov session new --auto-commit-policy-json` / `--no-auto-commit`, `ov session config set`).+ - Current memory plugins do not explicitly send an `auto_commit_policy`. Set it through the Python SDK’s `create_session` / `update_session_config`, the HTTP API, or the **ov CLI** (`ov session new --auto-commit-policy-json` / `--no-auto-commit`, `ov session config set`).- When a policy is explicitly enabled, the server defaults are: `pending_token_threshold=150000` (strictly greater than), `message_count_threshold=100`, `idle_timeout_seconds=86400`, `keep_recent_count=0`, and `min_commit_interval_seconds=0`. Note that this set of server defaults operates independently of the plugin clients' configuration (which is typically 20000/10).- **Consequence**: Plugins can rely on `server.user_config_defaults.auto_commit_policy` for new-session token/message thresholds; idle-timeout recovery additionally requires `memory.session_auto_commit.enabled=true`. Without that fallback, clients must still arrange their own commit path ([§3.3](#_3-3-session-and-commit-lifecycle)).- **Externalized tool output**: The server sets `tool_output_externalization.enabled=True` with `threshold_chars=20000` (`server/config.py:257-258`). Clients commonly raise `captureToolMaxChars` to 1000000 purely as a fallback mechanism, since the actual truncation and externalization occur on the server. Externalized results are then referenced via `tool_output_ref` (for context, openclaw provides three dedicated tools specifically for reading these references).@@ -251,7 +255,7 @@ For `openclaw`, the peer is derived from `peer_role`/`peer_prefix` (note that if|---|---|---|| env `OPENVIKING_*` | Per family, see above; behavior knobs are listed on each profile card | The only layer that spans every JS-based integration. || Workspace layers: the per-machine registry `~/.openviking/workspaces/<slot>.json` > `<repo-root>/.openviking/config.local.json` (private, gitignored) > `<repo-root>/.openviking/config.json` (committed, shared by the team) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | Schema v1; `version: 1` is required and a file declaring another version is skipped with a warning. Keys: `peer.source`, `peer.id`, `recall.{enabled,peer_scope,dedup_turns,max_items,score_threshold}`, `capture.{enabled,commit_token_threshold}`, `bypass.session_patterns`, `labels`. Lists union across layers, and a leading `"!reset"` clears what was inherited; unknown keys are kept and ignored. These files are trusted without a prompt because a hook is non-interactive, so the refusals are structural instead: connection and credential keys (`url`, `api_key`, `account`, `user`, `extra_headers`, …) are stripped with a warning and `${VAR}` is never expanded. Nothing writes the registry today: an entry is created by hand, and `ov-memory-doctor` prints the slot path to put it at. What a committed file switches off is announced in `ov-memory-doctor` rather than blocked. |-| ovcli.conf `plugin` section (shared scalars, overridden by a `plugin.<harness>` object) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | A per-harness key takes either spelling — `claude_code` or `claude-code`, `trae_cn` or `trae-cn`. Note: `ov config add/edit` rewrites the entire file from the Rust Config struct, thereby dropping any `plugin` sections it does not recognize; however, `ov config switch` simply copies bytes and remains unaffected. |+| ovcli.conf `plugin` section (shared scalars, overridden by a `plugin.<harness>` object) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | A per-harness key takes either spelling — `claude_code` or `claude-code`, `trae_cn` or `trae-cn`. CLI edits and renames preserve extra top-level fields such as `plugin`. Switching uses fields explicitly supplied by the incoming profile and retains omitted extra fields from the active file. || ov.conf harness sections (`<harness>.*`, legacy) | Every harness, for the section named after it | Both the credential fields (`apiKey`, `accountId`, `userId`, `peerId`) and the tuning knobs resolve from the calling harness's own section. Either spelling of the name reaches the same block. || The harness's own config file | dsh cordis patch (which the `plugin` section outranks), openclaw `openclaw.json`, hermes `config.yaml`+`.env` | |@@ -259,7 +263,7 @@ For `openclaw`, the peer is derived from `peer_role`/`peer_prefix` (note that if- `OPENVIKING_COMMIT_TURN_THRESHOLD`: cursor only (`trae`, `trae-cn`, and `zcode` commit on every Stop and ignore this threshold).- `OPENVIKING_WRITE_PATH_ASYNC`: claude-code / codex / zcode.-- Recall digest settings (`OPENVIKING_RECALL_COMPRESS`, `OPENVIKING_RECALL_REWRITE`, and their companions): claude-code / codex (note that the server-side `rewrite` parameter is available to all callers, see [§3.2.5](#_3-2-5-recall-digest)).+- Recall digest: `OPENVIKING_RECALL_COMPRESS=server` is supported across memory integrations; local `client` mode is limited to Claude Code / Codex. See [§3.2.5](#_3-2-5-recall-digest) for modes and defaults.- `OPENVIKING_RECALL_DEDUP_TURNS`, `OPENVIKING_RECALL_QUERY_EXPANSION`, `OPENVIKING_PEER_SOURCE`, `OPENVIKING_SKILL_CATALOG`, `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`, the workspace config files and the ovcli.conf `plugin` section: every harness that resolves through the shared loader — claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi. openclaw and hermes have configuration systems of their own.## 3.2 Automatic recall and injection@@ -283,6 +287,8 @@ On the server side, `session_id` handling diverges into two distinct execution p### 3.2.2 Decision matrix+The table shows default recall paths. Enabling server compression changes the request path as described in §3.2.5.+| harness | trigger | query construction | session_id | server path | injection format / location | digest (client)* ||---|---|---|---|---|---|---|| claude-code | every `UserPromptSubmit` | prompt verbatim, trimmed | ✅ `cc-` | A (context face) | `<openviking-context>` → `hookSpecificOutput.additionalContext` | ✅ local/server (default auto, [§3.2.5](#_3-2-5-recall-digest)) |@@ -296,7 +302,7 @@ On the server side, `session_id` handling diverges into two distinct execution p| openclaw | context-engine transformContext assemble (7 passthrough gates) | plain text of the last user message, cleaned and cut to 4000 characters | ❌ (`/find` has no such field) | `/find` | prepended into the last user message as `<relevant-memories>` + `Source: openviking-auto-recall` | ❌ || hermes | `prefetch` runs synchronously before every API call | raw user input, with two layers of skill scaffolding stripped; skipped under 5 characters | partial (only on the preferred `search/search` path, which lands in B; omitted when degrading to `/find`) | B / find | `<memory-context>` fenced block appended to the current user message (request body only, never written back to storage) | ❌ |-\* As in [§1.2](#_1-2-automatic-hook-surface-driven-by-the-harness), "digest" in this column refers to client-side local compression, while the server digest is available to every caller ([§3.2.5](#_3-2-5-recall-digest)). The `ov` CLI has no automatic recall and is not included in this table.+\* The digest column describes local compression. All memory integrations can opt into server compression through context-search rewrite; see [§3.2.5](#_3-2-5-recall-digest). The `ov` CLI does not provide automatic recall.### 3.2.3 Profile / opening injection@@ -336,12 +342,12 @@ On the server side, `session_id` handling diverges into two distinct execution p### 3.2.4 Timeout and budget chain-- **Family A client derivation**: With rewrite, the timeout is `max(timeoutMs, 45000)`; with expansion, it is `max(timeoutMs, 15000)`. The corresponding server-side fuses are 5s (expansion) and 30s (rewrite). By design, the client budget accommodates every server stage, ensuring the client never aborts early and loses the entire response.+- **Family A client derivation**: With rewrite, the timeout is `max(timeoutMs, 45000)`; with expansion, it is `max(timeoutMs, 15000)`. The corresponding server-side fuses are 5s (expansion) and 30s (rewrite). By design, the client budget accommodates every server stage, reducing premature client timeouts; an outer host deadline can still terminate the hook.- **Actual timeout values**:- **claude-code (cc)**: 15s (against a 60s hook budget).- **codex**: Recall enforces a hard 120s deadline for the entire hook, plus a 110s compression subprocess.- **cursor / trae×2 / zcode**: 15s (against a 20s host hook budget).- - **opencode / dsh / pi**: 15s (`dsh` blocks the pre-step).+ - **opencode**: 30s. **dsh**: 10s configured HTTP default, raised to at least 15s for context expansion (`dsh` blocks the pre-step). **pi**: 15s.- **openclaw**: Imposes a 5s hard timeout around the entire recall flow (including a 500ms health precheck). Since the default `recallPreferAbstract=false` means every leaf memory costs one extra read, this budget allows at most 1 find + 6 reads + 1 health check.- **hermes**: 4s total / 3s per request (configurable).- **Injection budget**: The server's `max_tokens` defaults to 1600 (Family A harnesses do not send this by default, allowing the server to dictate the limit). Both `openclaw` and `hermes` utilize a 4000-character budget, opting to "skip an entry that does not fit" rather than truncating it.@@ -350,11 +356,23 @@ On the server side, `session_id` handling diverges into two distinct execution p**Server implementation (available to all callers)**: The context retrieval face (covering REST `mode="context"` and legacy `/recall`) accepts a `rewrite` parameter—which can be `false`, `true`, or `"auto"` (defaulting to `false`)—alongside `rewrite_max_bullets` (defaulting to 6, with a range of 1-20). When enabled, the server leverages the `query_planner` model to rewrite recall results into a digest with citations. (If `rewrite=true` but `query_planner` is unconfigured, it falls back to the main `vlm`; `"auto"` only takes effect if `query_planner` is explicitly configured). The digest features an `OpenViking memory digest:` header followed by bullet points (`- `). Each bullet must be ≤500 characters and must cite a valid `viking://` URI from the hit set (bullets with missing or out-of-range citations are dropped). If the model determines there are no relevant memories, it emits a sentinel value and clears the injection block, ensuring that turn is not recorded in the deduplication ledger. This model call is protected by a fuse (`retrieval.recall_rewrite_timeout_s=30s`). On timeout, it falls back to providing the un-rewritten, rendered block (`rewrite.py:78-141`, `pipeline.py:122-130`, `search.py:195-196`).-**Client-side status**:+**Client configuration**: Automatic recall uses `OPENVIKING_RECALL_COMPRESS`, corresponding to `recallCompress` in shared configuration (`recallRewrite` remains a compatibility alias).++| Mode | Behavior |+| --- | --- |+| `off` | Do not request a digest. |+| `server` | Send `rewrite: true` and prefer the server digest. |+| `client` | Use a local compressor; supported by Claude Code and Codex. |+| `auto` | Claude Code and Codex prefer an available local compressor, otherwise sending `rewrite: "auto"`. Integrations without a local compressor send `rewrite: "auto"` directly. |++Claude Code and Codex default to `auto`; other integrations default to `off`. Claude Code, Codex, OpenCode, DSH, Pi, Cursor, TRAE, TRAE CN, ZCode, OpenClaw, and Hermes can all opt into server compression. Legacy boolean values `1` / `0` mean `auto` / `off`. A `stats.rewrite="no_relevant"` result suppresses injection; it must not fall back to the raw block.-- **claude-code**: `recallRewrite` supports four states: `off`, `client`, `server`, and `auto` (defaulting to **auto**). It initially probes for a local compressor via `claude --version` (caching the result for 7 days). If available, compression runs in a local subprocess: `claude -p --model sonnet --effort low --strict-mcp-config`. This subprocess has a 30s timeout, skips compression for inputs under 1500 characters, uses per-digest caching, and force-degrades its environment to prevent recursion. Subprocess failures fall back to the uncompressed block. URIs are snapped back to valid URIs using edit distance, and any irreparably broken bullets are dropped. If no local compressor is found, it sends `rewrite:"auto"`, deferring to the server. Notably, this is the *only* harness actively wired to the server-side rewrite.-- **codex**: The boolean `recallCompress` defaults to **true** and relies entirely on local compression (it does not utilize the server rewrite). The model profile is read from `~/.codex/models_cache.json` (candidates range from `gpt-5.3-codex-spark` to `gpt-5.6-luna`, cached for 7 days). The execution command is `codex --sandbox read-only --ask-for-approval never exec --ephemeral --ignore-user-config --skip-git-repo-check --output-last-message <tmp> -`, with a 110s timeout. If a runtime failure occurs, compression is disabled for the remainder of the session and re-probed at the next `SessionStart`. Outputs are normalized and truncated to 4000 characters. When compression is turned off or fails, a deterministic `fallbackDigest` takes over.-- **Other harnesses**: None of the other harnesses send the `rewrite` flag or compress locally; they simply inject the raw recall block returned by the server. Third-party applications directly calling the API can pass `rewrite` themselves to leverage the server digest.+Local compressor details:++- **claude-code**: Probes for a local compressor with `claude --version` (result cached for 7 days). If found, it runs `claude -p --model sonnet --effort low --strict-mcp-config` with a default subprocess timeout of 110s (`recallTimeoutMs - 10s`; the host’s 60s prompt-hook budget can end it earlier), skips inputs under 1500 characters (`recallCompressMinInputChars`), caches per digest, and snaps cited URIs back to valid hit URIs by edit distance, dropping bullets it cannot repair. A failed subprocess falls back to locally formatted recall entries, or the rendered block when no entries are available.+- **codex**: Picks a model from `~/.codex/models_cache.json` (`gpt-5.3-codex-spark` first, then `gpt-5.6-luna` with low effort; cached for 7 days) and runs `codex --sandbox read-only --ask-for-approval never exec --ephemeral --ignore-user-config --skip-git-repo-check --output-last-message <tmp> -`, with a default timeout of `recallTimeoutMs - 10s` (110s). A runtime failure disables local compression for the rest of the session until the next `SessionStart` re-probes. Output is normalized and capped at 4000 characters; when local compression fails, locally formatted recall entries are used, or the rendered block if no entries are available. With compression off, the server digest or rendered block is used directly.++These settings affect automatic recall. Explicit MCP calls retain their caller-supplied arguments. Cloud compression requires context-search rewrite support on the server. See the [shared plugin documentation](https://github.com/volcengine/OpenViking/blob/main/examples/memory-plugin-shared/README.md#cloud-recall-compression) and individual integration pages for older-server fallbacks, compressor discovery, and host time budgets.### 3.2.6 Injection backflow protection@@ -371,7 +389,7 @@ To prevent injected content from being captured a second time, the injection pro- **Write path**: The JS family routes all writes through `batch-send.mjs` (endpoint `POST /messages/batch`, capped at 100 messages per batch to match the server's `max_length=100` limit; on a 404/405 error, it gracefully degrades to sending one message at a time). Incremental cursors are implemented per integration (e.g., `cc` and `codex` compute a cursor from the transcript turn index; `cursor` uses `sha256(index+role+content)`; `zcode` relies on the rollout `turn_id`; OpenCode v1 uses an event-stream Map while v2 reads context at execution boundaries and advances by message ID; `dsh` uses an event allowlist; `pi` uses the branch entry watermark; and `hermes` slices by the current turn).- **Commits are client-triggered** (see [§2.3](#_2-3-server-side-session-and-commit-semantics)): The server does not auto-commit by default. Any "threshold/trigger" condition mentioned in the tables below refers strictly to client-side logic.- **Differences in `keep_recent_count`** (determining how much of a "live tail" a commit leaves for the host): The server default is 0. Here is what each integration passes: `cc`/`codex` pass 10 on threshold commits; `cursor`, `trae×2`, and `zcode` send an empty body `{}`, meaning 0 (every commit acts as a full archive); `opencode` and `dsh` pass 10; `pi` passes 10 outside takeover mode and 3 within it (locally, this means "keep 3 user turns," but the server interprets it as a raw message count, so fewer messages are actually retained); `openclaw` passes 10 on an `afterTurn` threshold trigger and 0 on `compact`/`reset`/`memory_store` operations; `hermes` always passes 0.-- **Write-path detachment** (`async-writer.mjs`, enabled by default for `cc`/`codex`/`zcode` on `Stop`): The execution flow is drain stdin → spawn detached worker → approve → write payload → unref. *(Note: If spawning fails, approval has not yet occurred, ensuring the synchronous fallback executes exactly once).* The detached worker forms its own process group, immunizing it against terminal signals. This is the crucial mechanism that makes `cc` reliable during shutdown and prevents `zcode` from losing writes upon `Ctrl+C`. **Side effect:** Once detachment is active, `Stop` no longer prints the `appended N turn(s)` notice (to restore this, set `OPENVIKING_WRITE_PATH_ASYNC=0`).+- **Write-path detachment** (`async-writer.mjs`, enabled by default for `cc`/`codex`/`zcode` on `Stop`): The execution flow is drain stdin → spawn detached worker → approve → write payload → unref. *(Note: If spawning fails, approval has not yet occurred, ensuring the synchronous fallback executes exactly once).* The detached worker forms its own process group and can continue after the terminal exits. It must already have started; network errors, system termination, or server failures can still leave the write incomplete. **Side effect:** Once detachment is active, `Stop` no longer prints the `appended N turn(s)` notice (to restore this, set `OPENVIKING_WRITE_PATH_ASYNC=0`).### 3.3.2 Regular commit triggers@@ -394,7 +412,7 @@ To prevent injected content from being captured a second time, the injection pro### 3.3.3 Shutdown method × harness outcome matrix-Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **—** = does not commit (messages already POSTed stay in the server's live area: the message bodies are not lost, they wait for a later trigger to archive and extract them); **n/a** = not applicable. The server-side behavior is **—** on every row ([§2.3](#_2-3-server-side-session-and-commit-semantics)).+Legend: **C** = the exit event attempts to trigger a commit; **C\*** = additional conditions apply; **—** = this event does not trigger a commit; **n/a** = not applicable. A trigger does not guarantee completed archiving or memory extraction: network errors, host exit budgets, or process termination can interrupt the request. Successfully written messages remain in the server’s live area until a later commit. This table assumes server auto-commit is disabled; configured policies add the [server behavior](#_2-3-server-side-session-and-commit-semantics).| harness | normal exit | Ctrl+C | SIGTERM | SIGHUP / close terminal / close window·tab | kill -9 / crash | recovery path ||---|---|---|---|---|---|---|@@ -406,7 +424,7 @@ Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **| zcode | **—** (no session-end-style event) | **C\*** | **—** | **—** | **—** | C\* precondition: The Stop for that turn had already fired when Ctrl+C arrived (the detached worker finishes writing as usual); every Stop has already committed, and missed turns are recovered by the rollout cursor on the next Stop in the same session || opencode | **C\*** (v1 ≥1.15.11 `dispose` or v2 cleanup calls `flushAll({commit:true})`) | **C\*** | **C\*** | **C\*** | **—** | C\* precondition: host cleanup time is finite, so slow requests or serial commits across several sessions may be cut off; v2 cleanup runs after 60 minutes of inactivity, service shutdown, and local-plugin hot reload || dsh | **C** (Cordis teardown triggers one 3s-timeout commit per session, no threshold) | **C** (the first one; a second Ctrl+C force-quits → —) | **C** | **—** (no SIGHUP listener) | **—** | The teardown commit and the threshold commit share a serial write chain, meaning it may not fit inside the 5s process grace period if a slow request precedes it; in the web form, closing the browser tab does not trigger a teardown |-| pi (takeover default) | **—** (`session_shutdown` fires on every shutdown path and is awaited, but the handler persists local takeover state and does not commit) | **—** | **—** | **—** | **—** | The next run accumulating 30000, or a manual `/viking commit` |+| pi (takeover default) | **—** (supported graceful shutdown paths await `session_shutdown`, but the handler persists local takeover state and does not commit) | **—** | **—** | **—** | **—** | The next run accumulating 30000, or a manual `/viking commit` || pi (takeover off) | **C** (`await sync.commit()`, failures go to the pending queue) | **C** | **C** | **C** | **—** | — || openclaw | **—** (upstream sends an awaited `session_end(reason=shutdown\|restart)`; the handler caches agentId and returns without triggering a commit; `gateway_stop` is not registered; no signal handling) | **—** | **—** | **—** | **—** | Explicit `/new` `/reset` and the ~50% threshold; sessions below the threshold rely on these two paths for archiving || hermes | **C\*** (atexit `_run_cleanup` → 10s flush → on_session_end) | **C\*** (both interactive and non-interactive trigger atexit) | **C\*** (`_signal_handler`, grace period defaults to 1.5s → clean exit → atexit) | **C\*** (SIGHUP follows the same path as SIGTERM) | **—** (atexit does not run) | If the drain does not finish, this round aborts the commit (avoiding a half-written commit); the Hermes exit watchdog can interrupt a slow commit |@@ -424,7 +442,8 @@ Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **| harness | mechanism | notes ||---|---|---|-| cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi | On-disk queue `~/.openviking/pending` (0700/0600) | Only retryable failures are queued (4xx errors, including 401/403, are considered non-retryable and are not queued, though they appear in debug logs); replay runs at session start: ≤50 entries per run, ≤3 attempts per entry, TTL 7 days; `.processing` claims entries atomically, with a 10min stale reclaim; an addMessage failure breaks execution immediately to preserve order |+| cc / cursor / trae×2 / zcode / opencode / dsh / pi | On-disk queue `~/.openviking/pending` (0700/0600) | Only retryable failures are queued (4xx errors, including 401/403, are considered non-retryable and are not queued, though they appear in debug logs); replay runs at session start: ≤50 entries per run, ≤3 attempts per entry, TTL 7 days; `.processing` claims entries atomically, with a 10min stale reclaim; an addMessage failure breaks execution immediately to preserve order |+| codex / trae-cli | Transcript + persisted cursor | New captures do not enter the pending queue. The cursor advances only for successfully sent messages; later capture or the SessionStart sweep resends the remaining tail. SessionStart also replays existing shared pending entries. || openclaw | No local queue | An addSessionMessage failure is caught, and that turn's messages are not replayed || hermes | In-process upload threads; pending-commit markers under `$HERMES_HOME/openviking/pending_sessions/` | On POSIX, startup recovery commits sessions left pending by dead runs. Unsent messages are not replayed from disk. || LangChain | In-process `_pending_commit_sessions` set | A failed commit is retried automatically during the next record; nothing is written to disk. On partial success, it raises an `OpenVikingPartialWriteError` (carrying `messages_written`, `input_messages_consumed`, and `context_attached`, allowing the caller to slice by position and retry the suffix) — making this the only protocol across all integrations that reports partial success |@@ -434,7 +453,7 @@ Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **| harness | handling ||---|---|-| claude-code | Offers the most complete isolation: SubagentStart derives a separate `cc-<sid>__subagent-<agent_id>` session, and SubagentStop reads the subagent transcript, pushes it, commits unconditionally, and clears the state |+| claude-code | Separate subagent sessions: SubagentStart derives a separate `cc-<sid>__subagent-<agent_id>` session, and SubagentStop reads the subagent transcript, pushes it, commits unconditionally, and clears the state || codex / trae-cli | No separate session: Subagent output (`agent_message` / `sub_agent_activity`) is folded into the main session's assistant/tool components || opencode | `oc-<parent>__subagent-<child>` hangs under the parent namespace; session-start injection skips subagents (recall does not); v2 maps `parentID` from `session.created`, then reads context when execution ends || dsh | Each subagent operates as a separate `dsh-<id>` session, preserving no parent-child relationship; N subagents = N profile injections + N separate sessions |@@ -509,7 +528,7 @@ There are three primary guards on MCP `write` and REST `content/write` (`content| harness | When the server is unreachable | Negative cache | HTTP retry | Failure blocks the host ||---|---|---|---|---|| claude-code | All hooks catch exceptions → approve (never blocks); at session-start, even pending replays are skipped | context-face 6h + host-cli probe 7d + health 5s | None (relies on pending replay); `peer_scope` degrades once; batch falls back to sequential | No (`uri-guard` deny is by design) |-| codex / trae-cli | All hooks catch exceptions → noop | context-face 6h + compressor runtime_failed (until the next startup) | Same as above (pending replay, triggered at SessionStart) | No |+| codex / trae-cli | All hooks catch exceptions → noop | context-face 6h + compressor runtime_failed (until the next startup) | Capture retries use the transcript/cursor; SessionStart also replays existing pending entries | No || cursor/trae×2/zcode | Fetch errors are swallowed as `status:0`, and catch returns an empty injection; silently skips if the lock isn't acquired within 5s | context-face 6h (no negative cache for unreachable servers; every turn waits the full 15s) | None | No || opencode | Recall, context, after-tool, event-loop, and cleanup failures are caught and logged; intentional URI-guard denials still reach the model | context-face 6h only; `/health` is uncached | No synchronous retry; the MCP proxy retries once each for 401/403 and 400/404 | No (URI-guard denial is intentional) || dsh | The client swallows all exceptions; `ensureState` failures are not cached (when the server is unreachable, each pre-step makes two 5s health calls) | context-face 6h + an in-process user-space cache that never expires | None; pending queue replays 3 times across processes | Yes (pre-step runs profile+recall serially; session/flush blocks) |@@ -547,10 +566,10 @@ Each card serves as a quick-reference entry point. It records only the facts and## claude-code- **Integration docs**: [Claude Code Memory Plugin](./02-claude-code.md)-- **Form**: A Claude Code plugin (marketplace) featuring a four-in-one architecture: 9 hooks, an MCP proxy (passing through 16 tools), a slash command, a statusline, and 4 skills (`openviking-memory`, `openviking-skills`, `ov-experience-memory`, `ov-memory-doctor`). Version 0.6.1.+- **Form**: A Claude Code plugin (marketplace) featuring a four-in-one architecture: 9 hooks, an MCP proxy (passing through 20 tools), a slash command, a statusline, and 4 skills (`openviking-memory`, `openviking-skills`, `ov-experience-memory`, `ov-memory-doctor`). Version 0.6.1.- **Capability highlights**: The harness with the broadest hook coverage — `SessionStart` (120s) / `UserPromptSubmit` (60s) / `PostToolUse:Read` (5s, the skill-experience hook, off by default) / `PreToolUse:Read|Glob|Grep|Edit|Write|Bash` (5s, `uri-guard`: denies a file tool whose path is a `viking://` URI, pointing a Write/Edit on a skill URI to `add_skill`, and adds a notice to a Bash command that carries one) / `Stop` (45s) / `PreCompact` (30s) / `SessionEnd` (30s) / `SubagentStart` (10s) / `SubagentStop` (45s). Recall digesting is enabled by default (local `claude -p`, falling back to the server-side rewrite automatically when the local CLI is unavailable, [§3.2.5](#_3-2-5-recall-digest)). Provides full sub-session isolation via `SubagentStart`/`Stop` ([§3.3.5](#_3-3-5-subagent-session-comparison)), along with a statusline, slash command, and `uri-guard`. All shutdown paths except `kill -9` trigger a commit ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)).- **Behavior notes**: The session ID format is `cc-<raw_CC_session_id>`, while subagents use `…__subagent-<agent_id>`. `Stop` commits at a threshold of 20000 (keep 10), and `PreCompact` commits synchronously. Automatic recall excludes resources ([§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths)). The incremental cursor is stored in `/tmp` (if cleared by the system, the entire session is pushed again).-- **Configuration**: Configured via environment variables, `ovcli.conf` (`plugin.claude_code`), and `ov.conf` (`claude_code` as per [§3.1.4](#_3-1-4-configuration-layers)), offering roughly 70 tunable parameters. The compressor command and model are hardcoded to `claude`/`sonnet`/`low`/30s.+- **Configuration**: Configured via environment variables, `ovcli.conf` (`plugin.claude_code`), and `ov.conf` (`claude_code` as per [§3.1.4](#_3-1-4-configuration-layers)), offering roughly 70 tunable parameters. The compressor defaults to `claude`/`sonnet`/`low`; its timeout comes from `recallCompressTimeoutMs` (110s by default), subject to the host hook budget.- **Dimension index**: tool surface [§2.1](#_2-1-server-side-mcp-tool-surface) | recall [§3.2](#_3-2-automatic-recall-and-injection) | commit [§3.3.2](#_3-3-2-regular-commit-triggers)/[§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix) | compaction [§3.4](#_3-4-compaction-takeover) | degradation [§3.6](#_3-6-degradation-and-fault-tolerance) | UX [§3.7](#_3-7-additional-ux-comparison).## codex@@ -558,7 +577,7 @@ Each card serves as a quick-reference entry point. It records only the facts and- **Integration docs**: [Codex Memory Plugin](./04-codex.md)- **Form**: A Codex plugin (marketplace). Features 6 hooks (`SessionStart` 70s / `UserPromptSubmit` 130s / `Stop` 30s / `SessionEnd` 3s / `PreCompact` 60s / `PreToolUse:Bash` 5s), an MCP proxy, and the same 4 skills as claude-code. Version 0.10.1.- **Capability highlights**: A local recall-compression pipeline (`codex exec`, [§3.2.5](#_3-2-5-recall-digest)). `SessionEnd` (Codex ≥ 0.145) commits the session on a graceful exit, catching up any turns `Stop` missed, and a `SessionStart` fallback sweep reclaims messages left unarchived by exits that never fired it ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). `PreToolUse:Bash` (`uri-guard`) lets a shell command that carries a `viking://` URI run and adds a notice suggesting the OpenViking MCP tools. Codex edits files through `apply_patch`, whose input has no path argument, so the guard never denies a call.-- **Behavior notes**: The session ID format is `cx-<safeId>` (derived deterministically without reading state). `SessionEnd` fires only on a graceful exit and only on Codex 0.145+, so signals, crashes, older builds and `codex app-server` deferral fall to the sweep. Has no on-disk pending queue (while offline, the cursor simply doesn't advance, and the next turn resends to compensate, [§3.3.4](#_3-3-4-pending-queue-offline-compensation-comparison)). Idle-TTL is 1800000ms, lock wait 120000ms (configured via env). `Stop` and `SessionEnd` detach by default (the `appended N turn(s)` notice is hidden by default); a per-session mkdir lock serializes the Stop worker, PreCompact, the SessionEnd worker and the sweep. A newly registered hook has no Codex trust record, so after an upgrade `/hooks` must approve each hook the upgrade added (`SessionEnd`, `PreToolUse`).+- **Behavior notes**: The session ID format is `cx-<safeId>` (derived deterministically without reading state). `SessionEnd` fires only on a graceful exit and only on Codex 0.145+, so signals, crashes, older builds and `codex app-server` deferral fall to the sweep. New captures do not enter the on-disk pending queue (the transcript/cursor owns retries, while SessionStart also replays existing pending entries, [§3.3.4](#_3-3-4-pending-queue-offline-compensation-comparison)). Idle-TTL is 1800000ms, lock wait 120000ms (configured via env). `Stop` and `SessionEnd` detach by default (the `appended N turn(s)` notice is hidden by default); a per-session mkdir lock serializes the Stop worker, PreCompact, the SessionEnd worker and the sweep. A newly registered hook has no Codex trust record, so after an upgrade `/hooks` must approve each hook the upgrade added (`SessionEnd`, `PreToolUse`).- **Configuration**: Configured via environment variables, `ovcli.conf` (`plugin.codex`), and `ov.conf` (`codex`). Hooks authenticate with `Authorization: Bearer` alone ([§3.1.3](#_3-1-3-credential-systems)).- **Dimension index**: tool surface [§2.1](#_2-1-server-side-mcp-tool-surface) | recall [§3.2](#_3-2-automatic-recall-and-injection) | commit [§3.3.2](#_3-3-2-regular-commit-triggers)/[§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix) | degradation [§3.6](#_3-6-degradation-and-fault-tolerance).@@ -591,7 +610,7 @@ Each card serves as a quick-reference entry point. It records only the facts and- **Integration docs**: [Community Integrations → ZCode](./08-community-plugins.md)- **Form**: Config-driven (merged into `~/.zcode/cli/config.json`, forcing `hooks.enabled=true`) utilizing an MCP proxy. It features 4 hooks: SessionStart(30s) / UserPromptSubmit(20s) / PreToolUse:Read\|Glob\|Grep(5s) / Stop(30s). It vendors nothing: the installer assembles its shared runtime the same way it does for cursor and trae. Version 0.5.0.-- **Capability highlights**: The rollout file `~/.zcode/cli/rollout/model-io-<sid>.jsonl` serves as the source of truth for increments (a `lastTurnId` diff backfills any missed Stop events). Stop detaches by default, meaning Ctrl+C does not result in lost writes.+- **Capability highlights**: The rollout file `~/.zcode/cli/rollout/model-io-<sid>.jsonl` serves as the source of truth for increments (a `lastTurnId` diff backfills any missed Stop events). Stop detaches by default. An already-started worker can continue after the terminal receives Ctrl+C, but network errors or process termination can still interrupt the write.- **Behavior notes**: Commits on every Stop (keep 0). The capture path only strips the three types of injection blocks without performing any further text cleanup ([§3.2.6](#_3-2-6-injection-backflow-protection)). The initial capture reads the entire rollout at once, meaning that installing it into a long-running session will produce a single large push.- **Configuration**: Configured via environment variables, `ovcli.conf` (`plugin.zcode`), and the workspace files; `OPENVIKING_WRITE_PATH_ASYNC` takes effect for zcode.- **Dimension index**: tool surface [§2.1](#_2-1-server-side-mcp-tool-surface) | recall [§3.2](#_3-2-automatic-recall-and-injection) | commit [§3.3.2](#_3-3-2-regular-commit-triggers)/[§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix).@@ -616,6 +635,8 @@ Each card serves as a quick-reference entry point. It records only the facts and## dsh (DeepSeek Harness)+- **Integration docs**: [DSH Plugin](./17-dsh.md)+- **Form**: This is the only in-process, native Cordis plugin (`export function apply`). Its tool surface is the server's MCP surface, mounted through `@deepseek-ai/dsh-mcp-client` and the shared stdio proxy (published as `mcp__openviking__*`), while its hooks call REST directly. It features 6 events: agent/session-start (emit) / agent/pre-step (waterfall) / session/event / session/flush / tools/pre-execute / tools/post-execute. Version 0.5.1.- **Capability highlights**: `ctx.provide("openvikingMemory")` allows other Cordis plugins to build upon it. Pre-step injection is transmitted as a user message, aligning with the `complete:true` rendering mode of the DSH persona.- **Behavior notes**: The unified installer covers dsh and installs into the `web` profile unless `--dsh-profile` names another; npm is the bundle's only distribution channel, so every mode except `dev` installs the published package; `dev` packs the checkout first, because `dsh plugin` forwards to pnpm and a linked source tree cannot resolve the dsh peers the bundle imports. The teardown commit is allocated 3 seconds with no threshold, and it does not trigger on SIGHUP or a consecutive Ctrl+C ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). Compaction remains invisible to the plugin: injected content shrinks alongside the host's compaction, and the profile is not re-injected. Each subagent is assigned its own session ([§3.3.5](#_3-3-5-subagent-session-comparison)). The tool surface is the server's own MCP surface, reached through the same stdio proxy the other integrations use and published under `mcp__openviking__*`, so a server upgrade adds tools without a bundle release; the trade-off is that the proxy runs once per profile, so tool calls carry a process-level actor peer and `remember` is not session-scoped (recall, capture, and commit still resolve a peer per session). The bundle also ships the shared `openviking-memory`, `openviking-skills`, and `ov-experience-memory` skills; tool results are captured by default (`captureToolResults: true`) so `ov-experience-memory` runs the full Experience loop; turning it off leaves the skill retrieving and applying Experience only. `uri-guard` lowercases tool names before matching: `tools/pre-execute` denies a file tool whose path is a `viking://` URI (a write or edit on a skill URI is pointed to `mcp__openviking__add_skill`), and `tools/post-execute` adds a notice (`form: "notice"`) when a `bash` command carries one.@@ -625,9 +646,9 @@ Each card serves as a quick-reference entry point. It records only the facts and## pi (pi Coding Agent Extension)- **Integration docs**: [pi Coding Agent Extension](./11-pi.md)-- **Form**: Operates as a native pi extension (loaded from a directory and dynamically transpiled from TS by jiti). The extension uses the official MCP client and republishes every descriptor from the server's `tools/list` as a pi tool named `openviking_<tool>`: 16 today ([§2.1](#_2-1-server-side-mcp-tool-surface)). Nothing in the extension enumerates tools, so a server that gains or drops one changes pi's surface at the next session with no plugin release. Recall, session sync, profile injection and takeover still go over REST. It features 9 events + a `/viking` command; `tool_call` blocks read/grep/find/ls/write/edit calls whose path is a `viking://` URI, and `tool_result` appends a notice to the result of a `bash` command that carries one. Ships 3 skills (`openviking-memory`, `openviking-skills`, `ov-experience-memory`) through `resources_discover`, left out when `mcpEnabled` is `false`. Version 0.4.1.-- **Highlights**: Features takeover compaction (enabled by default, [§3.4.2](#_3-4-2-pi-takeover)). Employs a two-stage recall system: it queues at `before_agent_start` and performs synchronous retrieval during the context event, ensuring the current turn's prompt receives its corresponding memories. It also includes a status line. The `session_shutdown` event triggers across all shutdown paths and is properly awaited.-- **Behavior**: When takeover is enabled, exiting does not trigger a commit. Instead, the handler persists local state, and archiving waits either for the next resumed run to hit the threshold or for a manual `/viking commit` command ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). The takeover threshold is set to 30000 tokens while keeping the last 3 turns (keep 3, which the server interprets as a message count). When takeover is disabled, the threshold is 20000 tokens (keep 10), and exiting triggers an unconditional commit. Tool registration requires `health`, `ensureSession` and a `/mcp` handshake ([§1.1](#_1-1-active-tool-surface-agentic-calls)); a root API key is refused on `/mcp` with a 403, so a credential chain ending at `ov.conf`'s `server.root_api_key` produces a session with no tools — before 0.4.0 the REST tools registered and quietly answered "No results found." instead. `openviking_remember` runs on the MCP surface, meaning its own one-shot session committed immediately rather than a write folded into pi's session ([§2.1](#_2-1-server-side-mcp-tool-surface)). `openviking_add_resource` ingests a remote URL directly; for a local path the server returns an upload instruction whose URL the model has to POST the bytes to with `bash`, as on every other MCP harness. `openviking_read` returns full text only: a directory URI comes back as `Cannot render …: URI points to a directory`, and the old `level="abstract"/"overview"` tiers have no MCP equivalent — use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)`, while takeover keeps injecting the archive overview itself over REST. A tool call is bounded by the shared `timeoutMs` (15000ms, `OPENVIKING_TIMEOUT_MS`), which a `write`/`edit` with `wait=true` or a synchronous `add_resource` ingest can outlast; a timeout or ESC fails the call locally only, so the request it already sent runs to completion and a write may have landed anyway. Upgrading from 0.3.x renames every tool with no alias period, so a `--tools` / `--exclude-tools` allowlist that pinned `viking_*` has to be rewritten or the tools silently disappear. If takeover is off, resuming via `pi -c` will re-report the entire branch.+- **Form**: Operates as a native pi extension (loaded from a directory and dynamically transpiled from TS by jiti). The extension uses the official MCP client and republishes every descriptor from the server's `tools/list` as a pi tool named `openviking_<tool>`: 20 today ([§2.1](#_2-1-server-side-mcp-tool-surface)). Nothing in the extension enumerates tools, so a server that gains or drops one changes pi's surface at the next session with no plugin release. Recall, session sync, profile injection and takeover still go over REST. It features 9 events + a `/viking` command; `tool_call` blocks read/grep/find/ls/write/edit calls whose path is a `viking://` URI, and `tool_result` appends a notice to the result of a `bash` command that carries one. Ships 3 skills (`openviking-memory`, `openviking-skills`, `ov-experience-memory`) through `resources_discover`, left out when `mcpEnabled` is `false`. Version 0.4.1.+- **Highlights**: Features takeover compaction (enabled by default, [§3.4.2](#_3-4-2-pi-takeover)). Employs a two-stage recall system: it queues at `before_agent_start` and performs synchronous retrieval during the context event, ensuring the current turn's prompt receives its corresponding memories. It also includes a status line. Supported graceful shutdown paths await `session_shutdown`; forced termination such as `kill -9` cannot run the handler.+- **Behavior**: When takeover is enabled, exiting does not trigger a commit. Instead, the handler persists local state, and archiving waits either for the next resumed run to hit the threshold or for a manual `/viking commit` command ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). The takeover threshold is set to 30000 tokens while keeping the last 3 turns (keep 3, which the server interprets as a message count). When takeover is disabled, the threshold is 20000 tokens (keep 10), and exiting triggers an unconditional commit. Tool registration requires `health`, `ensureSession` and a `/mcp` handshake ([§1.1](#_1-1-active-tool-surface-agentic-calls)); a root API key is refused on `/mcp` with a 403, so a credential chain ending at `ov.conf`'s `server.root_api_key` produces a session with no tools — before 0.4.0 the REST tools registered and quietly answered "No results found." instead. `openviking_remember` runs on the MCP surface, meaning its own one-shot session committed immediately rather than a write folded into pi's session ([§2.1](#_2-1-server-side-mcp-tool-surface)). `openviking_add_resource` ingests a remote URL directly; for a local path the server returns an upload instruction whose URL the model has to POST the bytes to with `bash`, as on every other MCP harness. `openviking_read` reads file content with line pagination (`offset`/`limit`): a directory URI comes back as `Cannot render …: URI points to a directory`, and the old `level="abstract"/"overview"` tiers have no MCP equivalent — use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)`, while takeover keeps injecting the archive overview itself over REST. A tool call is bounded by the shared `timeoutMs` (15000ms, `OPENVIKING_TIMEOUT_MS`), which a `write`/`edit` with `wait=true` or a synchronous `add_resource` ingest can outlast; a timeout or ESC fails the call locally only, so the request it already sent runs to completion and a write may have landed anyway. Upgrading from 0.3.x renames every tool with no alias period, so a `--tools` / `--exclude-tools` allowlist that pinned `viking_*` has to be rewritten or the tools silently disappear. If takeover is off, resuming via `pi -c` will re-report the entire branch.- **Config**: Configured via environment variables, `ovcli.conf` (`plugin.pi`), and the workspace files (credentials always pass through the credential chain, [§3.1.3](#_3-1-3-credential-systems)). Bypass goes through the shared `isBypassed` glob matcher under the key `bypassSessionPatterns`; the older `bypassPatterns` still reads. The shared `mcpEnabled: false` now takes effect here as well: no bridge, no tools, and `/viking` reports that as a setting rather than a fault.- **Dimension index**: tool surface [§1.1](#_1-1-active-tool-surface-agentic-calls) | recall [§3.2](#_3-2-automatic-recall-and-injection) | takeover [§3.4.2](#_3-4-2-pi-takeover) | commit [§3.3.2](#_3-3-2-regular-commit-triggers)/[§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix).@@ -653,14 +674,14 @@ Each card serves as a quick-reference entry point. It records only the facts and- **Integration docs**: [Deployment Guide → CLI](../guides/03-deployment.md#cli)- **Form**: A native Rust binary that wraps the server's REST API into a command-line interface. It operates without host events, automatic recall, or compaction takeover.-- **Highlights**: The only first-party client capable of sending an `auto_commit_policy` (`ov session new --auto-commit-policy-json`, `ov session config set`). It also offers multi-profile management, admin tools, privacy controls, snapshot management, and TUI capabilities unavailable in any plugin (see [§5.3](#_5-3-capabilities-only-the-cli-has)).+- **Highlights**: Provides command-line entry points for `auto_commit_policy` (`ov session new --auto-commit-policy-json`, `ov session config set`). It also offers multi-profile management, admin tools, privacy controls, snapshot management, and TUI capabilities unavailable in any plugin (see [§5.3](#_5-3-capabilities-only-the-cli-has)).- **Dimension index**: See [§5](#_5-ov-cli-command-reference) for the comprehensive command reference.---# 5. ov CLI Command Reference-`ov` (internally identified as `openviking` in clap) is a Rust-based HTTP client. Because all core capabilities reside on the server, the CLI's role is strictly to assemble parameters, pack and upload local files, render output, and manage multiple profiles. It is a standalone tool rather than a harness integration—meaning it does not handle host events, automatic recall, or compaction takeover. This chapter details its complete command surface for using OV directly (either manually or via scripts) and highlights features exclusive to the CLI (such as the TUI, multi-profile management, admin tools, `--sudo`, privacy controls, and snapshots).+`ov` (internally identified as `openviking` in clap) is a Rust-based HTTP client. Most data operations call the server’s REST API. The CLI also packages local uploads, validates configuration, generates keys, renders output, and manages profiles. It is a standalone tool rather than a harness integration—meaning it does not handle host events, automatic recall, or compaction takeover. This chapter details its complete command surface for using OV directly (either manually or via scripts) and highlights additional CLI entry points (such as the TUI, multi-profile management, admin tools, `--sudo`, privacy controls, and snapshots).> Version note: This guide reflects the HEAD source (with the HEAD tag at `[email protected]`); notable differences from older versions, such as 0.4.10, are explicitly mentioned. Please note that `ov doctor` is not included in the native Rust binary. Instead, the Python wrapper installed via pip intercepts `argv[1]=="doctor"` and routes it to `openviking_cli.doctor`, reading the server's `ov.conf` rather than `ovcli.conf`. The pure Rust `ov` binary distributed via npm/cargo does not include this subcommand.@@ -672,9 +693,9 @@ Doc-comment prefixes like `[Data]`, `[Interactive]`, `[Admin]`, or `[Experimenta**Reading/retrieval**: `ls` (alias: list) | `tree` (`-L` defaults to 3) | `stat` / `attrs get` | `read` / `abstract` / `overview` (L2/L0/L1 respectively) | `get` (download) | `find` (requires at least one non-empty query or `--image`; `--image` accepts local paths, data URIs, HTTP URLs, and viking:// schemas) | `search` (experimental; adds `--session-id` on top of find capabilities) | `grep` | `glob`-**Skills**: `skills add` (supports local paths, Git, and GitHub tree URLs; use `-s` to select or `*` for all; prompts for interactive confirmation) | `skills list/find/show/update/remove` | `skills validate` (the only fully offline command)+**Skills**: `skills add` (supports local paths, Git, and GitHub tree URLs; use `-s` to select or `*` for all; prompts for interactive confirmation) | `skills list/find/show/update/remove` | `skills validate` (local validation without a server request)-**Sessions/memory**: `session new` (`--auto-commit-policy-json` and `--no-auto-commit` are mutually exclusive—this is the only first-party client that sends a policy) | `session list/get/delete` | `session get-session-context` (`--token-budget` defaults to 128000) | `session get-session-archive` | `session add-message(s)` | `session config set` (modifies mutable configurations) | `session commit`+**Sessions/memory**: `session new` (`--auto-commit-policy-json` and `--no-auto-commit` are mutually exclusive; the SDK and HTTP API also support setting the policy) | `session list/get/delete` | `session get-session-context` (`--token-budget` defaults to 128000) | `session get-session-archive` | `session add-message(s)` | `session config set` (modifies mutable configurations) | `session commit`**Import/export & snapshots**: `export` / `backup` / `import` / `restore` (.ovpack formats) | `snapshot commit/restore/show/log/diff/ignore-*` (workspace snapshots; rollbacks are achieved by committing forward)@@ -689,14 +710,14 @@ Doc-comment prefixes like `[Data]`, `[Interactive]`, `[Admin]`, or `[Experimenta## 5.2 Global options and unique mechanisms- `-o/--output table|json` (defaults to `output` in the config file) | `-c/--compact` (defaults to true) | `--account`/`--user`/`--actor-peer-id` | `--sudo` (utilizes the `root_api_key`; permitted only for admin, system, reindex, task status, and task list commands) | `--profile` (hidden).-- **Multi-profile**: The active profile is stored at `~/.openviking/ovcli.conf`, with alternative profiles named `ovcli.conf.<name>`. The `switch` command performs a direct byte copy (preserving the `plugin` section). Conversely, `add` and `edit` rewrite the file via serde, which drops any keys unrecognized by the Rust Config structure (including the `plugin` section, as detailed in [§3.1.4](#_3-1-4-configuration-layers)).+- **Multi-profile**: The active profile is `~/.openviking/ovcli.conf`; named profiles use `ovcli.conf.<name>`. Edits and renames preserve extra top-level fields such as `plugin`. Switching replaces connection settings. An incoming `plugin` section takes precedence; if it is absent, the active file’s existing `plugin` section is retained.- **Language gate**: A display language must be configured before executing any commands (if unconfigured in a non-interactive environment, the CLI exits with code 2). As of the HEAD version, `--help` bypasses this gate (unlike version 0.4.10, which lacked this exemption), though `--version` still requires a configured language to run.- **Three JSON output shapes, categorized by command group**: Under compact mode, standard commands emit `{"ok":true,"result":…}` upon success, a bare payload when `-c false` is passed, and `{"ok":false,"error":…}` upon failure. The configuration command family outputs `{"status":"ok","result":…}`. When a profile is active, `"profile":[…]` is appended to the response. These variations require careful handling when parsing outputs in scripts. Additionally, `echo_command` defaults to true and is not suppressed by `-o json` (meaning the first line of stdout will typically be `cmd: …`).- **Environment variables**: `OPENVIKING_CLI_CONFIG_FILE`, `OPENVIKING_UPLOAD_MODE` (local/shared), `OPENVIKING_ASSETS_CREDENTIALS_FILE`, `OPENVIKING_LANG`/`LC_*`/`LANG`, along with `VIKINGBOT_ENDPOINT`/`VIKINGBOT_API_KEY`/`OPENVIKING_URL` for chat functionality.-## 5.3 Capabilities only the CLI has+## 5.3 Additional CLI capabilities {#_5-3-capabilities-only-the-cli-has}-The following operations are inaccessible via the plugin surface and remain exclusive to the CLI/TUI: multi-profile switching and the configuration wizard, the complete `admin` account and user management suite, root operations via `--sudo`, `privacy` policy CRUD and versioning, data movement commands (`snapshot`/`backup`/`restore`/`export`/`import`), index rebuilds via `reindex`, root key generation via `system crypto init-key`, interactive browsing with `ov tui`, VikingBot-dependent features like `ov chat` and `ov compile`, and `ov session config set` for explicitly defining the `auto_commit_policy` (this serves as the only first-party entry point capable of enabling server-side auto-commits).+Compared with memory plugins, the CLI/TUI also provides the following entry points. Server-side operations can also be called through their HTTP APIs or SDK methods: multi-profile switching and the configuration wizard, the complete `admin` account and user management suite, root operations via `--sudo`, `privacy` policy CRUD and versioning, data movement commands (`snapshot`/`backup`/`restore`/`export`/`import`), index rebuilds via `reindex`, root key generation via `system crypto init-key`, interactive browsing with `ov tui`, VikingBot-dependent features like `ov chat` and `ov compile`, and `ov session config set` for explicitly defining the `auto_commit_policy` (the SDK and HTTP API can also set this policy).---@@ -708,13 +729,14 @@ If your preferred agent or harness is not among the 11 listed previously, you ca| Path | Effort | Agent-initiated tool surface | Auto recall/capture hooks | Session/commit | Compaction takeover ||---|---|---|---|---|---|-| ① [Direct MCP connection](./06-mcp-clients.md) | Minutes (fill in one config block) | ✅ All 16 tools | ❌ The model calls them itself | Only `remember` creates a temporary session | ❌ |-| ② HTTP API / SDK / [LangChain](./07-langchain-langgraph.md) | Hours (requires code) | Flexible (call REST as needed) | Custom implementation | Custom implementation (or use the LangChain middleware) | ❌ |-| ③ Reuse shared-core / the [Agent Plugins portable package](./15-agent-plugins.md) | Days (requires hook adapters) | ✅ 16 tools (through the MCP proxy) | ✅ Full recall/capture/commit/pending set | ✅ | Depends on which events you wire up |+| ① [Direct MCP connection](./06-mcp-clients.md) | Minutes: configure endpoint, credentials, and transport | ✅ All 20 tools | ❌ The model calls them itself | Only `remember` creates a temporary session | ❌ |+| ② HTTP API / SDK / [LangChain](./07-langchain-langgraph.md) | Hours: implement calls and lifecycle handling | Flexible (call REST as needed) | Custom implementation | Custom implementation (or use the LangChain middleware) | ❌ |+| ③ Reuse shared-core | Days: adapt and validate host lifecycle events | ✅ 20 tools (through the MCP proxy) | ✅ Full recall/capture/commit/pending set | ✅ | Depends on which events you wire up |+| [Agent Plugins portable package](./15-agent-plugins.md) | Minutes: install MCP and skill configuration | ✅ Server MCP tools | ❌ Model follows the skill and calls tools | Only `remember` creates a temporary session | ❌ |## 6.2 Path ①: Direct MCP connection (recommended starting point)-Any MCP-capable agent simply needs to point its `mcpServers` configuration to the server's `/mcp` endpoint (refer to [MCP Clients](./06-mcp-clients.md) to locate this configuration for each client). Doing so instantly unlocks all 16 tools ([§2.1](#_2-1-server-side-mcp-tool-surface)). The minimal configuration looks like this:+MCP clients that support Streamable HTTP can connect to the server’s `/mcp` endpoint. This example is for clients using `mcpServers`, `url`, and `headers`; other clients use different fields and formats, as documented in [MCP Clients](./06-mcp-clients.md). The connection discovers the tools provided by the server ([§2.1](#_2-1-server-side-mcp-tool-surface)).```json{@@ -722,17 +744,14 @@ Any MCP-capable agent simply needs to point its `mcpServers` configuration to th"openviking": {"url": "http://127.0.0.1:1933/mcp","headers": {- "Authorization": "Bearer <api_key>",- "X-OpenViking-Account": "<account>",- "X-OpenViking-User": "<user>",- "X-OpenViking-Actor-Peer": "<workspace-peer>"+ "Authorization": "Bearer <api_key>"}}}}```-The last three headers are optional; however, omitting them disables workspace peer isolation and tenant routing. For `stdio`-only clients, you can utilize the portable proxy (Path ③) to bridge `stdio` to streamable HTTP. This path provides a pure tool surface—meaning it does not include automatic recall, capture, or commits (unless the model explicitly invokes the `remember` tool).+Use a user or admin API key; the server resolves the account and user from that key. `X-OpenViking-Account` and `X-OpenViking-User` belong to trusted identity mode and cannot override an ordinary key’s identity. Add `X-OpenViking-Actor-Peer` when workspace peer context is needed; see [Authentication](../guides/04-authentication.md) for visibility rules. For stdio-only clients, use the [Agent Plugins portable proxy](./15-agent-plugins.md) to bridge to Streamable HTTP. Direct MCP connections do not include automatic recall, capture, or session commits. Calling `remember` creates and commits a one-shot session.## 6.3 Path ②: Programmatic integration@@ -741,12 +760,12 @@ The last three headers are optional; however, omitting them disables workspace p- **Open WebUI** (OpenAPI tool server): Running `python -m openviking_openwebui` launches a standalone process. By adding the resulting Tool Server URL to Open WebUI, you gain access to 7 tools (note that deletion and hooks are unsupported). See [§7](#_7-appendix-non-coding-integrations-at-a-glance) A for more details.## 6.4 Path ③: Reuse a Reference Implementation for Automatic Hooks-If you need the full spectrum of automation—recall, capture, commit, and pending state management—there is no need to build it from scratch. Consider studying and reusing one of these two existing implementations:+If you need the full spectrum of automation—recall, capture, commit, and pending state management—there is no need to build it from scratch. Choose the implementation that matches the host. The portable package supplies MCP and skills, without automatic hooks:-- **`examples/memory-plugin-shared/lib/`** (Node): This provides a complete set of core modules. These include `recall-core` (three-tier degradation recall), `profile-inject`, `capture-utils` (message normalization and injection-echo protection), `pending-queue` (offline replay), `batch-send`, `mcp-proxy-core` (stdio↔HTTP proxy), `session-model` (session ID derivation), and `credentials`. To build a lightweight integration harness, you only need to implement an adapter layer that maps host lifecycle events to these modules. For example, `agent-hook-runtime.mjs` is a ready-made, all-in-one runtime shared by Cursor, Trae, and zcode. Wiring up a new host is usually just a matter of parsing its stdin JSON field names.+- **`examples/memory-plugin-shared/lib/`** (Node): This provides a complete set of core modules. These include `recall-core` (three-tier degradation recall), `profile-inject`, `capture-utils` (message normalization and injection-echo protection), `pending-queue` (offline replay), `batch-send`, `mcp-proxy-core` (stdio↔HTTP proxy), `session-model` (session ID derivation), and `credentials`. To build a lightweight integration harness, map host lifecycle events to these modules and validate ordering, retries, timeouts, and exit behavior. For example, `agent-hook-runtime.mjs` is a ready-made, all-in-one runtime shared by Cursor, Trae, and zcode. Its stdin event parsing provides a starting point for another host adapter.- **The Agent Plugins 1.0 Portable Package** (under `agent-plugins/`): This offers a standardized portable format comprising `plugin.json`, the `skills/` directory, and `mcp.json` (stdio→HTTP proxy). It intentionally excludes automatic hooks—instead, recall and persistence rely on a skill that teaches the model to invoke the tools autonomously. This design makes it highly suitable for clients that follow the Agent Plugins specification for direct loading. Additionally, `plugin.test.mjs` defines spec-conformance checks (such as schema URL validation, naming rules, ensuring no secrets in static headers, and preventing `mcp.json` references from escaping the plugin root), which you can use as a linting baseline when packaging your own plugin.-**Three conventions you must follow** (to ensure behavior remains consistent with existing harnesses): ① The recall call site must forward the `session_id`, which enables server-side expansion and cross-turn deduplication (see [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths)); ② Do not allow the adapter's own timeout to override the deadline dictated by the helper; ③ You must arrange a commit path at shutdown. Otherwise, any remaining conversation tail that falls below the threshold will remain unarchived until a subsequent trigger occurs (see [§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). If the host has no shutdown event, enable `memory.session_auto_commit.enabled` and provide a per-session or deployment-default policy. These three rules are exactly what `recall-session-wiring.test.mjs` enforces using cross-plugin regexes.+**Three conventions you must follow** (to ensure behavior remains consistent with existing harnesses): ① The recall call site must forward the `session_id`, which enables server-side expansion and cross-turn deduplication (see [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths)); ② Do not allow the adapter's own timeout to override the deadline dictated by the helper; ③ You must arrange a commit path at shutdown. Otherwise, any remaining conversation tail that falls below the threshold will remain unarchived until a subsequent trigger occurs (see [§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). If the host has no shutdown event, enable `memory.session_auto_commit.enabled` and provide a per-session or deployment-default policy. `recall-session-wiring.test.mjs` checks wiring such as session ID and timeout forwarding. Validate exit events and completed writes in the target host as well.---@@ -754,10 +773,10 @@ If you need the full spectrum of automation—recall, capture, commit, and pendi| Integration | Form | Tool Surface | Session/Commit | Fault Tolerance | Default State ||---|---|---|---|---|---|-| **A. [Open WebUI](./08-community-plugins.md)** | Standalone FastAPI OpenAPI tool server | 7 local OpenAPI routes (`ov_search`/`ov_recall_memories`/`ov_add_memory`/`ov_list_memories`/`ov_read_resource`/`ov_add_resource`/`ov_session_status`), no deletion tool | No session concept | Most lightweight: bare `httpx`, no retries or negative caching; `/health` only echoes the config and does not probe OpenViking. | Inactive until the process is explicitly started. |-| **B. [LangChain/LangGraph](./07-langchain-langgraph.md)** | Python SDK adapter layer (retriever/tools/store/middleware/recorder) | `create_openviking_tools()` provides 12 StructuredTools (`viking_forget` is not in the agent profile by default) | `thread_id`/`session_id` come from the caller; `CommitPolicy` defaults to `never` | Most robust in this group: read-only methods automatically retry once, writes never retry (to prevent duplicates), and partial successes raise a structured exception that can be retried as a slice. | Requires explicit construction before taking effect. |-| **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | Portable package: `plugin.json` + `skills/` + `mcp.json` (stdio→HTTP proxy) | MCP passthrough for all 16 tools; intentionally excludes hooks (recall relies on a skill instructing the model). | Only `remember` creates a temporary session | Retries handled at the MCP proxy layer (401/403 triggers credential swap, 400/404 triggers re-initialization; max 1 retry each). | Active as soon as loaded by the client. |-| **D. [Direct MCP Connection](./06-mcp-clients.md)** | No local components, connects straight to `/mcp` | Same as C (16 tools) | Same as C | Depends entirely on the client. | `/mcp` is always on. |+| **A. [Open WebUI](./08-community-plugins.md)** | Standalone FastAPI OpenAPI tool server | 7 local OpenAPI routes (`ov_search`/`ov_recall_memories`/`ov_add_memory`/`ov_list_memories`/`ov_read_resource`/`ov_add_resource`/`ov_session_status`), no deletion tool | No session concept | Transport: bare `httpx`, no retries or negative caching; `/health` only echoes the config and does not probe OpenViking. | Inactive until the process is explicitly started. |+| **B. [LangChain/LangGraph](./07-langchain-langgraph.md)** | Python SDK adapter layer (retriever/tools/store/middleware/recorder) | `create_openviking_tools()` provides 12 StructuredTools (`viking_forget` is not in the agent profile by default) | `thread_id`/`session_id` come from the caller; `CommitPolicy` defaults to `never` | Retry behavior: read-only methods automatically retry once, writes never retry (to prevent duplicates), and partial successes raise a structured exception that can be retried as a slice. | Requires explicit construction before taking effect. |+| **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | Portable package: `plugin.json` + `skills/` + `mcp.json` (stdio→HTTP proxy) | MCP passthrough for all 20 tools; intentionally excludes hooks (recall relies on a skill instructing the model). | Only `remember` creates a temporary session | Retries handled at the MCP proxy layer (401/403 triggers credential swap, 400/404 triggers re-initialization; max 1 retry each). | Active as soon as loaded by the client. |+| **D. [Direct MCP Connection](./06-mcp-clients.md)** | No local components, connects straight to `/mcp` | Same as C (20 tools) | Same as C | Depends entirely on the client. | `/mcp` is always on. || **E. [Log Ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI (runs on the machine hosting the logs, importing them in reverse) | None (write-only, no recall) | Session ID `{prefix}__{harness}__{sanitized native id}`; commit token 6000 / idle 5s / keep 0 | Crash recovery: utilizes a SQLite cursor store, single-instance locking, and a reconciliation process to verify batch delivery. | Disabled by default on two levels (`ingest.enabled` and each harness's individual `enabled` flag are both false); adapters available for claude_code, codex, hermes, opencode, openclaw, and cursor. || **F. [OpenViking Helper](./14-openviking-helper.md)** | Closed-source desktop app | — | — | — | Outside the scope of this codebase. |diff --git a/docs/en/agent-integrations/17-dsh.md b/docs/en/agent-integrations/17-dsh.mdindex d1a182d46..6813fef93 100644--- a/docs/en/agent-integrations/17-dsh.md+++ b/docs/en/agent-integrations/17-dsh.md@@ -15,7 +15,7 @@ curl -fsSL https://openviking.ai/install | bashThe installer puts the plugin into the `web` profile. To use another profile, pass `--dsh-profile <name>`: `curl -fsSL https://openviking.ai/install | bash -s -- --dsh-profile <name>`.-After using it for a while, start a new conversation and ask about something you mentioned earlier—it will remember.+After installation, use the verification steps below to check tool access and cross-session recall.<details><summary><b>Manual setup</b></summary>@@ -56,7 +56,7 @@ The bundle runs inside DSH as a Cordis plugin rather than as external hooks, soEach DSH session maps to `dsh-<session-id>` in OpenViking, and every subagent gets its own session.-The model-facing surface is the OpenViking MCP tool set, reached through the same stdio proxy the other memory integrations use and published under an `mcp__openviking__` prefix. Because that proxy runs once per profile, `mcp__openviking__remember` stores into a short-lived server-side session rather than the current one—automatic capture still records the conversation itself—and tool calls carry the actor peer resolved at startup. Set `OPENVIKING_PEER_ID` when one process serves several workspaces and tool calls need exact attribution. The bundle also ships three shared skills: `openviking-memory`, so the model knows when to search, read, and write; `openviking-skills`, which covers finding, using, creating, sharing, and migrating skills stored in OpenViking; and `ov-experience-memory`, which retrieves and applies prior task Experience before executable work. Tool results are captured by default (`captureToolResults: true`), which lets the server link the skill's reads back to the Experience they used; with `false` the skill only retrieves and applies Experience.+The model-facing surface is the OpenViking MCP tool set, reached through the same stdio proxy the other memory integrations use and published under an `mcp__openviking__` prefix. Because that proxy runs once per profile, `mcp__openviking__remember` stores into a short-lived server-side session rather than the current one—automatic capture still records the conversation itself. With `OPENVIKING_RECALL_PEER_SCOPE=actor`, a fixed `OPENVIKING_PEER_ID` attributes that profile’s tool calls to one peer; the default `all` scope omits the actor-peer header. Use separate profiles/processes when workspaces need different tool identities. The bundle also ships three shared skills: `openviking-memory`, so the model knows when to search, read, and write; `openviking-skills`, which covers finding, using, creating, sharing, and migrating skills stored in OpenViking; and `ov-experience-memory`, which retrieves and applies prior task Experience before executable work. Tool results are captured by default (`captureToolResults: true`), which lets the server link the skill's reads back to the Experience they used; with `false` the skill only retrieves and applies Experience.A filesystem tool call whose path is a `viking://` URI is blocked with a hint pointing at the right OpenViking tool. For a write or edit under a skill directory such as `viking://~/skills/<name>/`, that tool is `mcp__openviking__add_skill`, which creates or replaces a whole skill from its `SKILL.md` text. A shell command that carries a `viking://` URI still runs, and the model gets a notice suggesting the OpenViking tools, which it can ignore when the URI is intentional data.@@ -88,7 +88,7 @@ Behavior knobs live in the profile's Cordis patch entry:commitTokenThreshold: 20000```-`syncTurns: false`, in that same block, makes the integration read-only: it still injects your profile and recalls memories, but sends nothing back — no captured turns, no commits, and no replay of writes an earlier session queued, which stay on the queue until a session that still writes drains them.+`syncTurns: false` in that block disables automatic capture, commit, and replay of pending writes. Profile injection and recall continue; queued writes remain for a later writing session. This does not revoke the model’s MCP write tools or change server permissions.`peerSource`, in that same `config` block, decides how the workspace peer is derived. The default `"git"` uses the repository's normalized `origin` URL (`[email protected]:volcengine/OpenViking.git` becomes `github.com-volcengine-openviking`), falling back to the repository root path, so every clone, worktree, and subdirectory of one repository shares a single peer; outside a repository no peer is sent at all, and what is remembered there goes to your user-level space at `viking://user/<you>/memories`. `"cwd"` restores the earlier behavior — the working directory with every non-alphanumeric character replaced by `-` — and `"none"` sends no peer at all. To give a directory outside a repository its own memory, set `OPENVIKING_PEER_ID` for it ([Give a Directory Its Own Peer](../configuration/02-client.md#give-a-directory-its-own-peer)).@@ -104,11 +104,11 @@ Credentials given in the patch win over the environment. Behavior knobs resolve|-------|---------------|| Nothing injected, no OpenViking tools | `dsh --profile web --dump-config` should list `openviking-memory-runtime`; re-run the installer or `dsh plugin --profile web add …` || Installed into the wrong profile | The installer defaults to `web`; re-run it with `--dsh-profile <name>` |-| `ERESOLVE` during install | The `@deepseek-ai/dsh-*` prerelease tags drift apart; install `@deepseek-ai/[email protected]` exactly |-| Install says the package is "not in the npm registry" | pnpm refuses releases younger than 24 hours by default (`minimumReleaseAge`). Wait it out, or add the exact version to `minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml` |-| Recall is empty | `curl http://localhost:1933/health`; check the endpoint and that the prompt is longer than the minimum query length (3 characters) |+| `ERESOLVE` during install | Use a supported `@deepseek-ai/dsh` version: `0.1.0-rc.6`, `0.1.5-rc.1`, `0.1.5-rc.2`, `0.1.7-rc.2`, or a stable `0.1.x` (peer range `>=0.1.0-rc.6 <0.2.0 \|\| ^0.1.5-rc.1 \|\| ^0.1.7-rc.2`), and keep all `@deepseek-ai/dsh-*` host packages on the same version. |+| Install says the package is "not in the npm registry" | The profile may have a pnpm minimum release age of 24 hours; check its configuration (`minimumReleaseAge`). Wait it out, or add the exact version to `minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml` |+| Recall is empty | `curl "<your OpenViking URL>/health"`; check the endpoint and that the prompt is longer than the minimum query length (3 characters) || 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |-| Memories from other projects leak in | Set `OPENVIKING_RECALL_PEER_SCOPE=actor` |+| Memories from other projects leak in | Set `OPENVIKING_RECALL_PEER_SCOPE=actor` to limit peer memories to the active peer; user-level memories remain shared || Nothing committed after a crash | Commit runs on a token threshold and at teardown; queued writes replay at the next session start |## See alsodiff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 89da37b3a..771ee2bdb 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -1,45 +1,44 @@# MCP Integration Guide-OpenViking server has a built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoint, allowing any MCP-compatible client to access its memory and resource capabilities over HTTP — no additional processes needed.+OpenViking Server includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoint. Clients supporting Streamable HTTP can connect directly. Clients supporting only stdio can use the proxy in the [Agent Plugins package](../agent-integrations/15-agent-plugins.md).> **Quick setup?** See [MCP Clients](../agent-integrations/06-mcp-clients.md) for client configuration snippets and platform-specific notes. This page covers the full tool reference and advanced configuration.## Prerequisites-1. OpenViking installed (`pip install openviking` or from source)-2. A valid configuration file (see [Configuration Guide](01-configuration.md))-3. `openviking-server` running (see [Deployment Guide](03-deployment.md))+Use a running OpenViking service and credentials for that service. For a new self-hosted deployment, follow the [Quick Start](../getting-started/02-quickstart.md) first. A managed or existing service does not require a local server installation.The MCP endpoint is at `http://<server>:1933/mcp`, sharing the same process and port as the REST API.-## Verified Platforms+## Client Connections-The following platforms have been successfully integrated with OpenViking MCP:+The following table links the available connection configurations. Verify tool discovery and a permitted data read with your client version:| Platform | Integration Method ||----------|-------------------|| **Claude Code** | `type: http` || **Trae** | Standard MCP config || **Cursor** | Standard MCP config |-| **ChatGPT & Codex** | Standard MCP config |+| **ChatGPT** | Custom App with OAuth; see the [OAuth guide](11-oauth.md) |+| **Codex** | MCP configuration in the [Codex integration](../agent-integrations/04-codex.md) || **OpenCode** | Native OpenCode `mcp` config || **Manus** | Standard MCP config || **Claude.ai / Claude Desktop** | Native OAuth 2.1 (see [11-oauth](11-oauth.md)) |## Authentication-The MCP endpoint shares the same API-Key authentication system as the OpenViking REST API. Pass either header:+MCP uses the server authentication configuration. In API Key mode, use a User/Admin key with either header:- `X-Api-Key: <your-key>`- `Authorization: Bearer <your-key>`-No authentication is required in local dev mode (server bound to localhost).+Only `dev` mode disables authentication; binding to localhost alone does not. OAuth clients follow the authorization flow below; see [Authentication](04-authentication.md) for other server modes.## Client Configuration### Generic MCP Clients-Most MCP-compatible platforms (Trae, Manus, Cursor, etc.) use the standard `mcpServers` format:+Clients accepting `mcpServers` and custom headers can use the following example. Check the client documentation for its field names and transport settings:```json{@@ -104,17 +103,16 @@ Configure `~/.config/opencode/opencode.json`:### Claude.ai / Claude Desktop (OAuth)-These clients only accept OAuth 2.1 — API Keys cannot be passed directly.+For remote connectors configured through the Claude.ai / Claude Desktop connector UI, use the OAuth flow below.OpenViking ships a native OAuth 2.1 implementation (DCR + PKCE + opaquetokens, backed by SQLite, with a Studio consent screen for authorization) sono external proxy is needed.-If you already have HTTPS configured, just connect to `https://your-server.com/mcp` — the client will walk you through the authorization flow automatically.+Enable `oauth.enabled` on the server and configure HTTPS as described in the OAuth guide. Then connect the client to `https://your-server.com/mcp` and complete authorization in the browser.**See the [OAuth 2.1 Guide](11-oauth.md)** and **[Public Access Guide](12-public-access.md)** for:-- End-to-end flow (device-flow style: page displays a 6-character code,- user confirms in the OpenViking console)+- Studio consent flow and the optional 6-character-code fallback for cross-device authorization- HTTP (local) and HTTPS (production) deployment, including Caddy and nginxreverse-proxy templates plus a docker-compose example- Connecting Claude.ai / Claude Desktop step by step@@ -122,20 +120,18 @@ If you already have HTTPS configured, just connect to `https://your-server.com/m- Token model (`ovat_` / `ovrt_` / `ovac_` prefixes) and revocation> The community [MCP-Key2OAuth](https://github.com/t0saki/MCP-Key2OAuth)-> Cloudflare Worker proxy is still around and remains a valid third-party-> option, but the native flow is recommended now: no extra deployment unit,-> no third-party trust boundary on the API key.+> Cloudflare Worker proxy is a separate third-party project. The native flow above needs no extra deployment unit and does not pass your API key through a third party; deployments choosing the proxy should review its configuration and credential handling.## Available MCP Tools-Once connected, OpenViking exposes 20 tools:+The built-in MCP tools are listed below. Use the connected server's `tools/list` response to determine which tools are available:| Tool | Description | Key Parameters ||------|-------------|----------------|| `find` | Fast semantic retrieval without session context. `context_type="skill"` on its own switches to package-level skill retrieval: one hit per skill package, its URI pointing at that package's `SKILL.md` and its summary taken from the skill itself, even when an auxiliary file inside the package is what matched. Without `target_uri` it searches both your own skills and the account-shared `viking://agent/skills`. Mixing `skill` with another context type keeps the generic retrieval path | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional), `context_type` (optional), `read_content` (optional — inline each hit's content), `events_time_decay_protection` (optional) || `search` | Deep semantic retrieval; `mode="context"` assembles injection-ready context and replaces the former `recall` tool. `list` mode also returns one hit per skill package, its URI pointing at `SKILL.md` and its summary taken from the package itself, but `limit` applies before that merge, so a package matching in several files takes several slots and fewer than `limit` results come back | `query`, `mode` (`list` or `context`), `target_uri` (list mode only), `session_id` (optional), `limit`, `min_score`, `level` (list mode), `context_type` (optional), `events_time_decay_protection` (optional in both modes), plus context-mode `quotas`, `purpose`, `max_tokens`, `detail` or `detail_by_category`, `dedup_turns`, `exclude_uris`, `peer_scope`, scalar `other_peer_penalty` or `other_peer_penalties` by category, and `rewrite` (`off` or `auto`) |-| `read` | Read one or more `viking://` URIs. PNG, JPEG, GIF, and WebP return native MCP image content; WAV, MP3, FLAC, OGG, and M4A return native audio content. Video is not supported because MCP has no standard video content block | `uris` (single string or array) |+| `read` | Read one or more `viking://` URIs. PNG, JPEG, GIF, and WebP return native MCP image content; WAV, MP3, FLAC, OGG, and M4A return native audio content. Video is not supported because MCP has no standard video content block | `uris` (single string or array), `offset`, `limit` (text lines) || `list` | List entries under a `viking://` directory | `uri`, `recursive`, `offset`, `limit`, `sort_by`, `sort_order` (optional) || `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `offset`, `limit`, `include_abstract` (optional — also show each directory's summary; for a skill directory that is its name and description) || `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |@@ -216,7 +212,7 @@ The `add_resource` tool accepts both **remote URLs** and **local file paths**, hIn `api_key` auth mode, the token retains the role of the issuing MCP call, for both API-key and OAuth callers. Uploads are rejected if the user no longer exists, the identity is being deleted, or the role has been downgraded. A later promotion does not expand an existing token's permissions. Trusted-mode upload tokens continue to use the USER role.-This lets any MCP client — including sandboxed environments without a local filesystem (Claude web, Manus, etc.) — push files into OpenViking without pre-installing the `ov` CLI. The token upload reuses the authenticated `temp_upload` route (API key first, otherwise the one-shot `?token=`) and its `TempUploadStore` persistence, so the same `local` / `shared` upload modes apply. Note: the one-shot token is held in-process, so in a multi-worker deployment the `add_resource` call and the follow-up upload POST must reach the same worker (or run single-worker) for the token to resolve.+A client that can read the source bytes and send a multipart HTTP request can upload without the `ov` CLI. A sandbox must provide those capabilities; an inaccessible local path alone cannot transfer a file. The token upload reuses the authenticated `temp_upload` route (API key first, otherwise the one-shot `?token=`) and its `TempUploadStore` persistence, so the same `local` / `shared` upload modes apply. Note: the one-shot token is held in-process, so in a multi-worker deployment the `add_resource` call and the follow-up upload POST must reach the same worker (or run single-worker) for the token to resolve.#### When you must set `OPENVIKING_PUBLIC_BASE_URL`@@ -260,12 +256,14 @@ curl http://localhost:1933/health### Authentication errors-**Likely cause:** API key mismatch between client config and server config.+**Likely cause:** The client key is invalid, expired, or not valid for tenant data access.-**Fix:** Ensure the API key in your MCP client configuration matches the one in your OpenViking server configuration. See [Authentication Guide](04-authentication.md).+**Fix:** Use a valid user/admin key for the target account. In `api_key` mode, root keys are reserved for administration. See [Authentication Guide](04-authentication.md).## References- [MCP Specification](https://modelcontextprotocol.io/)- [OpenViking Configuration](01-configuration.md)- [OpenViking Deployment](03-deployment.md)++Client configuration references: [Claude Code MCP](https://code.claude.com/docs/en/mcp), [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/).diff --git a/docs/images/agents/en/agent-cli.md b/docs/images/agents/en/agent-cli.mdindex adeb49ce3..3b1bf63ab 100644--- a/docs/images/agents/en/agent-cli.md+++ b/docs/images/agents/en/agent-cli.md@@ -1,9 +1,9 @@-Copy the following prompt to your AI assistant (Claude Code, Codex, Cursor, Trae, and so on). It will automatically complete OpenViking CLI installation, configuration, and usage learning:+Copy the following prompt to your AI assistant (Claude Code, Codex, Cursor, Trae, and so on). Ask it to install and configure the CLI, then verify the connection:```textFirst ask the user for the OpenViking API Key and store it as OPENVIKING_API_KEY.-Write the following content to ~/.openviking/ovcli.conf, replacing ${OPENVIKING_API_KEY} with the actual value provided by the user:+Write the following content to ~/.openviking/ovcli.conf, replacing ${OPENVIKING_API_KEY} with the actual value provided by the user. The CLI does not expand environment variables in this file:{"url": "{{OPENVIKING_BASE_URL}}","api_key": "${OPENVIKING_API_KEY}"@@ -15,7 +15,9 @@ Install OpenViking CLI:npm i -g @openviking/cliAfter installation, run:+ov config validate+ov healthov --help-Explore the CLI usage and write the OpenViking CLI workflow into your long-term memory.+Read ov --help and the help for individual commands, then summarize common operations. Save the workflow in long-term memory, including only usage notes, not the API key or raw config file.```diff --git a/docs/images/agents/en/api.md b/docs/images/agents/en/api.mdindex 87af806f1..206ba1cda 100644--- a/docs/images/agents/en/api.md+++ b/docs/images/agents/en/api.md@@ -1,6 +1,6 @@## Step 1: Add a resource-Refer to the resource write example from GitHub and fill in the API Key and domain automatically:+Install `requests` in your Python environment (`python -m pip install requests`). Replace the local file path and use an unused complete target URI; the page supplies the service URL and API key.```pythonimport json@@ -56,16 +56,11 @@ print(json.dumps(result, ensure_ascii=False, indent=2))## Step 2: Add memory-Refer to the memory write example from GitHub and fill in the API Key and domain automatically:+Reuse the imports, connection settings, and `post_json` helper from Step 1. Add a message to a new session and submit memory extraction:```pythontext = "[TODO]your-message-text" # e.g. I am a developer-def post_json(path: str, payload: dict, timeout: float):- response = requests.post(f"{url}{path}", headers=headers, json=payload, timeout=timeout)- response.raise_for_status()- return response.json()-# Create a session.session = post_json("/api/v1/sessions", {}, 360.0)session_id = session["result"]["session_id"]@@ -88,3 +83,5 @@ result = post_json()print(json.dumps(result, ensure_ascii=False, indent=2))```++Resource import and session commit may return before processing finishes. If `result["result"]` contains a `task_id`, query `GET /api/v1/tasks/{task_id}` with the same authorization header until it is `completed`, `failed`, or `cancelled`. Handle failures before reading or searching the result. A no-op commit may return no task.diff --git a/docs/images/agents/en/claude-code.md b/docs/images/agents/en/claude-code.mdindex 0a32d3304..4a9b01bca 100644--- a/docs/images/agents/en/claude-code.md+++ b/docs/images/agents/en/claude-code.md@@ -33,11 +33,11 @@ Because Claude Code may block installation scripts from unknown sources, automat└ openviking MCP · ✔ connected```-3. Run `/mcp` and confirm it shows:+3. Run `/mcp` and confirm OpenViking is connected. The tool count depends on the server version:```textBuilt-in MCPs (always available)- ❯ plugin:openviking-memory:openviking · ✔ connected · 10 tools+ ❯ plugin:openviking-memory:openviking · ✔ connected```4. Run `/openviking-memory:ov` and confirm the service status is healthy:diff --git a/docs/images/agents/en/cli.md b/docs/images/agents/en/cli.mdindex 51a4e5b59..4f5958cb2 100644--- a/docs/images/agents/en/cli.md+++ b/docs/images/agents/en/cli.md@@ -20,5 +20,7 @@ npm i -g @openviking/cli && ov config### Step 3: After configuration, run the following command to view CLI usage:```bash+ov config validate+ov healthov --help```diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.mdindex 8585c8c00..ac6a24589 100644--- a/docs/images/agents/en/codex.md+++ b/docs/images/agents/en/codex.md@@ -15,7 +15,7 @@## Step 2: Verify-1. Start Codex. The first launch stops on a hook trust prompt — pick **Trust all and continue**:+1. Start Codex. The first launch shows a hook review prompt similar to this (exact layout varies by version); pick **Trust all and continue**:```textHooks need review@@ -27,20 +27,9 @@3. Continue without trusting (hooks won't run)```- The six hooks OpenViking registers are (an older Codex may show fewer):-- ```text- SessionStart- UserPromptSubmit- PreToolUse- Stop- SessionEnd- PreCompact- ```--2. If you miss the prompt or pick the third option, the hooks never run. Enter `/hooks` to trust and enable the entries, and check `/plugins` shows `openviking-memory` as enabled — two independent switches, both have to be on. A plugin update that touches a hook asks for trust again.--3. Verify Profile loading: once trusted, submit your first Prompt. Any prompt is fine. The plugin should load your Profile automatically. If the beginning of the conversation contains recalled memory context, the integration is working:+ If you skipped it or picked option 3, open `/hooks`. Review the OpenViking commands, then trust and enable the hooks you intend to use. In `/plugins`, confirm that `openviking-memory` is enabled. New or changed hooks require another review.+2. Confirm that OpenViking MCP tools are available, then ask Codex to call `health` and `list`. This verifies tool access; automatic recall also requires `UserPromptSubmit`, and capture requires `Stop`.+3. In a workspace with saved memories, ask about previously stored information and check the hook output or debug log. Recalled context looks similar to this:```text• UserPromptSubmit hook (completed)@@ -48,6 +37,8 @@OpenViking memory digest:```+ An empty new account may have no profile or relevant memories to inject. See the full guide for lifecycle commits and a complete memory check.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/deepseek-harness.md b/docs/images/agents/en/deepseek-harness.mdindex 88ca026ec..eba224d0c 100644--- a/docs/images/agents/en/deepseek-harness.md+++ b/docs/images/agents/en/deepseek-harness.md@@ -29,7 +29,7 @@ The installer asks for the harness and OpenViking credentials:| Package reported missing from npm | pnpm rejects releases younger than 24 hours by default; wait and retry, or add the exact version to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` || Recall returns no history | Run `curl http://localhost:1933/health` to confirm the server is healthy, then check the endpoint and make sure the prompt is at least 3 characters long || OpenViking returns 401 / 403 | Check the API key; trusted-mode deployments must also check `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |-| Memories from other projects appear | Set `OPENVIKING_RECALL_PEER_SCOPE=actor` |+| Memories from other projects appear | Set `OPENVIKING_RECALL_PEER_SCOPE=actor` to limit peer memories to the active peer; user-level memories remain shared || Nothing committed after a crash | Commits run at the token threshold and session teardown; queued writes replay at the next session start |## Referencesdiff --git a/docs/images/agents/en/deerflow-memory-manager.md b/docs/images/agents/en/deerflow-memory-manager.mdindex 15236923b..3e5e2ca8e 100644--- a/docs/images/agents/en/deerflow-memory-manager.md+++ b/docs/images/agents/en/deerflow-memory-manager.md@@ -1,5 +1,7 @@DeerFlow can use OpenViking as a long-term memory backend through MemoryManager. After the integration is enabled, DeerFlow writes conversation messages to OpenViking, recalls relevant memories before model calls, and injects them into the context.+This setup supports one DeerFlow user with an ordinary OpenViking USER API key in `api_key` mode. `owner_user_id: default` applies when DeerFlow authentication is disabled; otherwise set the authenticated DeerFlow user's ID. It does not provision separate credentials for multiple users. Remove old trusted-mode identity defaults before switching. See [DeerFlow's authentication and migration notes](https://github.com/bytedance/deer-flow/blob/main/docs/OPENVIKING.md#authentication-boundary).+## Step 1: Configure OpenViking credentialsEdit the `.env` file in the DeerFlow project root and add the API key:@@ -60,7 +62,7 @@ HTTP Request: GET {{OPENVIKING_BASE_URL}}/health "HTTP/1.1 200 OK"## Step 5: Verify memory write and recall-Use the following logs to confirm that write and recall are working:+These logs show accepted requests and injected context. After extraction finishes, start another conversation as the same user and ask about a distinctive fact from the previous session to verify memory recall:```bashgrep -Ei "messages/batch|commit|search/find|has_memory" logs/gateway.log | tail -100diff --git a/docs/images/agents/en/mcp.md b/docs/images/agents/en/mcp.mdindex 62965995f..34afbd229 100644--- a/docs/images/agents/en/mcp.md+++ b/docs/images/agents/en/mcp.md@@ -15,7 +15,4 @@### Step 2: Test MCP tool connectivity-Enter `ov health` to check the OpenViking version and connection status.-```bash-ov health-```+Reconnect the MCP service in your client and confirm that its tools are listed. Ask the assistant to call OpenViking's `health` tool, then use `list` to check the directories accessible to your account. `ov health` checks the CLI connection; it does not verify this client's MCP connection.diff --git a/docs/images/agents/en/openclaw.md b/docs/images/agents/en/openclaw.mdindex b8f027191..ed08d72e8 100644--- a/docs/images/agents/en/openclaw.md+++ b/docs/images/agents/en/openclaw.md@@ -6,13 +6,19 @@openclaw plugins install clawhub:@openviking/openclaw-plugin```-2. Connect OpenClaw to the VolcEngine-hosted OpenViking service:+2. Run the setup wizard. Enter `{{OPENVIKING_BASE_URL}}` as the service URL and the API key provided on this page:```bash- openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>+ openclaw openviking setup```-3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `sender` represents human participants. After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:+ Or configure it in one step, with the key in `OPENVIKING_API_KEY`:++ ```bash+ openclaw openviking setup --base-url {{OPENVIKING_BASE_URL}} --api-key "$OPENVIKING_API_KEY"+ ```++3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `sender` represents message senders (the legacy value `person` remains an alias). After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:```bashopenclaw openviking setup --reconfigurediff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.mdindex cf5d3823e..ea9c732c2 100644--- a/docs/images/agents/en/opencode.md+++ b/docs/images/agents/en/opencode.md@@ -17,7 +17,7 @@1. Restart OpenCode.2. Run `/mcps` and confirm the list shows `openviking connected`.-3. Ask OpenCode to recall related memories in a conversation, and verify that it can automatically call tools such as `openviking_search`, `openviking_read`, and `openviking_remember`.+3. Explicitly ask OpenCode to call `openviking_search` and `openviking_read` to verify tool access. Automatic recall runs through hooks without those model tool calls; check it separately by asking about stored information in a new session.## Troubleshootdiff --git a/docs/images/agents/en/sdk.md b/docs/images/agents/en/sdk.mdindex c76152dc0..fa6f43011 100644--- a/docs/images/agents/en/sdk.md+++ b/docs/images/agents/en/sdk.md@@ -1,14 +1,14 @@-## Step 1: Install OpenViking+## Step 1: Install the Python SDK-Run the following command to install OpenViking:+Install the standalone SDK in the Python environment that runs your code:```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking-sdk```## Step 2: Initialize the client-Refer to the standard write example from GitHub and fill in the API Key and domain automatically:+Create a client with the service URL and API key. Reuse it in the following steps:```pythonfrom openviking_sdk import SyncHTTPClient, TextPart@@ -26,15 +26,15 @@ client.initialize()## Step 3: Add a resource-Refer to the standard resource write example from GitHub and fill in the API Key and domain automatically:+Replace the local file path and target URI. `to` specifies the complete target URI; use an unused path:```pythonfile_path = "[TODO]your-file-path"-resource_to = "[TODO]your-resource-path" # e.g. viking://resources+resource_to = "[TODO]your-resource-path" # e.g. viking://resources/my-documentreason = "[TODO]your-reason" # e.g. External API documentation# Reuse the initialized client.-client.add_resource(+result = client.add_resource(path=file_path,to=resource_to,options={"reason": reason},@@ -43,7 +43,7 @@ client.add_resource(## Step 4: Add memory-Refer to the memory write example from GitHub and fill in the API Key and domain automatically:+Create a session, add a message, and submit it for memory extraction:```pythontext = "[TODO]your-message-text" # e.g. I am a developer@@ -58,3 +58,5 @@ client.add_message()result = client.commit_session(session_id=session_id)```++Resource imports and memory extraction run in the background. When a response contains a `task_id`, save it and check it with `client.get_task(result["task_id"])`. A no-op commit may return no task. Wait for `completed` before checking results; inspect the task error if it is `failed` or `cancelled`. Call `client.close()` when finished.diff --git a/docs/images/agents/en/trae.md b/docs/images/agents/en/trae.mdindex ea01ded2b..71337d1bb 100644--- a/docs/images/agents/en/trae.md+++ b/docs/images/agents/en/trae.md@@ -17,7 +17,7 @@**TRAE / TRAE CN**: open **Settings → MCP → Configured MCP Servers** and confirm that the `openviking` entry is visible.-**TraeCode CLI 2.0**: hooks only run once you trust them. Start `trae-cli` and pick **Trust all and continue** at the prompt:+**TraeCode CLI 2.0**: start `trae-cli` and pick **Trust all and continue** at the hook review prompt (exact layout varies by version):```textHooks need review@@ -29,7 +29,9 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-Then run `trae-cli plugin list` and confirm that `openviking-memory` is enabled. If you miss the prompt or pick the third option, the hooks never run: enter `/hooks` to trust and enable the entries, and check `/plugins` shows the plugin as enabled — two independent switches, both have to be on. A plugin update that touches a hook asks for trust again.+If you skipped it or picked option 3, review and enable the OpenViking hooks in `/hooks`. Confirm the plugin is enabled with `trae-cli plugin list`. New or changed hooks need another review. See the full guide for version-specific lifecycle support.++An MCP entry only confirms configuration. Ask the assistant to call OpenViking `health` and `list`, then check automatic recall separately using a new conversation in the same workspace after a previous session has been committed and processed.## Troubleshootdiff --git a/docs/images/agents/en/workbuddy.md b/docs/images/agents/en/workbuddy.mdindex 026ed8edf..224404c36 100644--- a/docs/images/agents/en/workbuddy.md+++ b/docs/images/agents/en/workbuddy.md@@ -15,7 +15,7 @@{"mcpServers": {"OpenViking": {- "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",+ "url": "{{OPENVIKING_BASE_URL}}/mcp","headers": {"Authorization": "Bearer {{OPENVIKING_API_KEY}}"}diff --git a/docs/images/agents/zh/agent-cli.md b/docs/images/agents/zh/agent-cli.mdindex 644dd8a15..48ee1e15e 100644--- a/docs/images/agents/zh/agent-cli.md+++ b/docs/images/agents/zh/agent-cli.md@@ -1,10 +1,10 @@-将下方提示词复制给你的 AI 助手(Claude Code、Codex、Cursor、Trae 等),它会自动完成 OpenViking CLI 安装、配置和用法学习:+将下方提示词复制给你的 AI 助手(Claude Code、Codex、Cursor、Trae 等),让它完成 OpenViking CLI 安装、配置和连接验证:```text请先向用户询问 OpenViking API Key,并记为 OPENVIKING_API_KEY。-请在 ~/.openviking/ovcli.conf 写入以下内容:+请在 ~/.openviking/ovcli.conf 写入以下内容,将 ${OPENVIKING_API_KEY} 替换为用户提供的实际 key;CLI 不会在此文件中展开环境变量:{"url": "{{OPENVIKING_BASE_URL}}","api_key": "${OPENVIKING_API_KEY}"@@ -16,7 +16,9 @@npm i -g @openviking/cli安装完成后,请运行:+ov config validate+ov healthov --help-请探索 CLI 用法,并把 OpenViking CLI 的使用方式写入你的长期记忆。+请查阅 ov --help 和具体命令的 --help,再总结常用操作。把常用操作写入长期记忆,只记录用法,不记录 API Key 或原始配置文件。```diff --git a/docs/images/agents/zh/api.md b/docs/images/agents/zh/api.mdindex 5a7af4cc4..36332c532 100644--- a/docs/images/agents/zh/api.md+++ b/docs/images/agents/zh/api.md@@ -1,6 +1,6 @@## 步骤 1: 写入资源-参考 GitHub 提供的资源写入示例,自动填入 API Key 和域名+在运行代码的 Python 环境中安装 `requests`(`python -m pip install requests`)。替换本地文件路径和完整目标 URI,目标需尚未占用;服务地址和 API Key 由页面填入。```pythonimport json@@ -56,16 +56,11 @@ print(json.dumps(result, ensure_ascii=False, indent=2))```## 步骤 2: 写入记忆-参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名+复用步骤 1 的导入、连接配置和 `post_json` 函数。创建会话、写入消息,再提交记忆提取:```pythontext = "[TODO]your-message-text" # e.g. I am a developer-def post_json(path: str, payload: dict, timeout: float):- response = requests.post(f"{url}{path}", headers=headers, json=payload, timeout=timeout)- response.raise_for_status()- return response.json()-# Create a session.session = post_json("/api/v1/sessions", {}, 360.0)session_id = session["result"]["session_id"]@@ -88,3 +83,5 @@ result = post_json()print(json.dumps(result, ensure_ascii=False, indent=2))```++资源导入和会话提交可能在后台处理完成前返回。若 `result["result"]` 中包含 `task_id`,用相同鉴权头请求 `GET /api/v1/tasks/{task_id}`,直到状态为 `completed`、`failed` 或 `cancelled`;先处理失败,再读取或检索结果。无待处理内容的 commit 可能不返回任务。diff --git a/docs/images/agents/zh/claude-code.md b/docs/images/agents/zh/claude-code.mdindex 94b06168d..42e9f897b 100644--- a/docs/images/agents/zh/claude-code.md+++ b/docs/images/agents/zh/claude-code.md@@ -33,11 +33,11 @@└ openviking MCP · ✔ connected```-3. 执行 `/mcp` 命令,确认显示如下信息:+3. 执行 `/mcp`,确认 OpenViking 显示为 connected。工具数量随服务端版本变化:```textBuilt-in MCPs (always available)- ❯ plugin:openviking-memory:openviking · ✔ connected · 10 tools+ ❯ plugin:openviking-memory:openviking · ✔ connected```4. 执行 `/openviking-memory:ov` 命令,确认服务状态正常:diff --git a/docs/images/agents/zh/cli.md b/docs/images/agents/zh/cli.mdindex 18b858cf6..81811d862 100644--- a/docs/images/agents/zh/cli.md+++ b/docs/images/agents/zh/cli.md@@ -22,5 +22,7 @@ npm i -g @openviking/cli && ov config### 步骤3:配置完成后,可运行以下命令查看 CLI 用法:```bash+ov config validate+ov healthov --help```diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.mdindex d9c43b888..1d9039df2 100644--- a/docs/images/agents/zh/codex.md+++ b/docs/images/agents/zh/codex.md@@ -15,7 +15,7 @@## 步骤2:验证-1. 启动 Codex。首次启动会停在 Hook 信任确认上,选 **Trust all and continue**:+1. 启动 Codex。首次启动会显示类似下面的 hook 审阅提示(具体界面随版本变化),选 **Trust all and continue**:```textHooks need review@@ -27,20 +27,9 @@3. Continue without trusting (hooks won't run)```- OpenViking 注册的 6 个 Hook 是(Codex 版本较旧时可能少几个):-- ```text- SessionStart- UserPromptSubmit- PreToolUse- Stop- SessionEnd- PreCompact- ```--2. 错过这个提示,或当时选了第 3 项,Hook 就不会运行。输入 `/hooks` 补上信任并开启条目,`/plugins` 里确认 `openviking-memory` 已启用——两个开关相互独立,都要是开着的。插件更新动了 Hook 时会再要求信任一次。--3. 验证 Profile 加载:信任完成后,提交第一条 Prompt(内容随意即可)。此时插件应自动加载 Profile——若对话开头出现记忆召回内容,则表明接入成功:+ 如果跳过了提示或选了第 3 项,打开 `/hooks`,检查 OpenViking 的命令,再信任并开启需要使用的 hooks。在 `/plugins` 中确认 `openviking-memory` 已启用。新增或变更的 hooks 需要重新检查。+2. 确认 OpenViking MCP 工具可用,让 Codex 调用 `health` 和 `list`。这一步验证工具连接;自动召回还需开启 `UserPromptSubmit`,对话采集需开启 `Stop`。+3. 在已有记忆的工作目录中询问之前保存的信息,检查 hook 输出或调试日志。召回内容类似:```text• UserPromptSubmit hook (completed)@@ -48,6 +37,8 @@OpenViking memory digest:```+ 新账号可能还没有 profile 或相关记忆可注入。会话提交时机和完整验证步骤见下方文档。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/deepseek-harness.md b/docs/images/agents/zh/deepseek-harness.mdindex e882ab6c3..b6a1c9540 100644--- a/docs/images/agents/zh/deepseek-harness.md+++ b/docs/images/agents/zh/deepseek-harness.md@@ -29,7 +29,7 @@ curl -fsSL https://openviking.ai/install | bash| 安装时提示包不在 npm registry 中 | pnpm 默认拒绝发布不满 24 小时的版本;可稍后重试,或把精确版本加入 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` || 无法召回历史记忆 | 先执行 `curl http://localhost:1933/health` 确认服务端正常;再检查端点配置,并确认 prompt 不少于 3 个字符 || OpenViking 返回 401 / 403 | 检查 API Key;可信模式部署还需检查 `OPENVIKING_ACCOUNT` 与 `OPENVIKING_USER` |-| 召回结果混入其他项目的记忆 | 设置 `OPENVIKING_RECALL_PEER_SCOPE=actor` |+| 召回结果混入其他项目的记忆 | 设置 `OPENVIKING_RECALL_PEER_SCOPE=actor`,将 peer 记忆限定为当前 peer;用户级记忆仍会共享 || 异常退出后没有 commit | commit 由 token 阈值和会话 teardown 触发;排队的写入会在下次会话开始时重放 |## 参考diff --git a/docs/images/agents/zh/deerflow-memory-manager.md b/docs/images/agents/zh/deerflow-memory-manager.mdindex dda1715b1..51f0aabba 100644--- a/docs/images/agents/zh/deerflow-memory-manager.md+++ b/docs/images/agents/zh/deerflow-memory-manager.md@@ -1,5 +1,7 @@DeerFlow 支持通过 MemoryManager 接入 OpenViking 作为长期记忆后端。接入后,DeerFlow 会将对话消息写入 OpenViking,并在模型调用前通过 OpenViking 进行记忆召回,再注入到上下文中。+本配置支持一个 DeerFlow 用户,使用 OpenViking `api_key` 模式下的普通 USER API Key。`owner_user_id: default` 适用于未开启 DeerFlow 登录认证的场景;已开启时填写对应的 DeerFlow 用户 ID。此接入不会为多用户自动分配凭据,切换前还需移除旧的 trusted 身份默认值。详见 [DeerFlow 的认证与迁移说明](https://github.com/bytedance/deer-flow/blob/main/docs/OPENVIKING.md#authentication-boundary)。+## 步骤 1:配置 OpenViking 鉴权信息在 DeerFlow 项目根目录下编辑 `.env` 文件,把 API Key 填进去:@@ -60,7 +62,7 @@ HTTP Request: GET {{OPENVIKING_BASE_URL}}/health "HTTP/1.1 200 OK"## 步骤 5:验证写入与召回-可通过以下日志确认写入和召回是否正常:+下列日志可确认请求已接收、上下文已注入。等提取完成后,以同一用户另开会话,询问上一会话中一条容易识别的信息,验证记忆是否能召回:```bashgrep -Ei "messages/batch|commit|search/find|has_memory" logs/gateway.log | tail -100diff --git a/docs/images/agents/zh/mcp.md b/docs/images/agents/zh/mcp.mdindex 86c47fa8b..25dcc0527 100644--- a/docs/images/agents/zh/mcp.md+++ b/docs/images/agents/zh/mcp.md@@ -15,7 +15,4 @@### 步骤 2:测试 MCP 工具连通性-输入 `ov health` 检查 ov 的版本和连接状态-```bash-ov health-```+重新连接客户端中的 MCP 服务,确认工具列表可见,再让助手调用 OpenViking 的 `health` 工具。工具调用成功后,再用 `list` 查看当前账号可访问的目录。`ov health` 只验证 CLI 连接,不能证明这个客户端的 MCP 已接通。diff --git a/docs/images/agents/zh/openclaw.md b/docs/images/agents/zh/openclaw.mdindex 904075ba8..019432141 100644--- a/docs/images/agents/zh/openclaw.md+++ b/docs/images/agents/zh/openclaw.md@@ -6,13 +6,19 @@openclaw plugins install clawhub:@openviking/openclaw-plugin```-2. 将 OpenClaw 连接至火山引擎托管的 OpenViking 服务:+2. 运行配置向导,服务地址填 `{{OPENVIKING_BASE_URL}}`,API Key 填当前页面提供的 key:```bash- openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>+ openclaw openviking setup```-3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`sender` 表示不同的人类参与者。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:+ 也可以一步完成配置,key 放在 `OPENVIKING_API_KEY` 中:++ ```bash+ openclaw openviking setup --base-url {{OPENVIKING_BASE_URL}} --api-key "$OPENVIKING_API_KEY"+ ```++3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`sender` 表示不同的消息发送者(旧值 `person` 仍兼容)。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:```bashopenclaw openviking setup --reconfigurediff --git a/docs/images/agents/zh/opencode.md b/docs/images/agents/zh/opencode.mdindex 0833fd84d..c6499b862 100644--- a/docs/images/agents/zh/opencode.md+++ b/docs/images/agents/zh/opencode.md@@ -17,7 +17,7 @@1. 重启 OpenCode。2. 输入 `/mcps` 命令,确认列表中显示 `openviking connected`。-3. 在对话中请求 OpenCode 召回相关记忆,验证是否会自动调用 `openviking_search`、`openviking_read`、`openviking_remember` 等工具。+3. 在对话中明确要求调用 `openviking_search` 和 `openviking_read`,验证工具可用。自动召回由 hook 完成,不需要模型调用这些工具;可另开会话,询问已保存的信息来检查。## 故障排查diff --git a/docs/images/agents/zh/sdk.md b/docs/images/agents/zh/sdk.mdindex 5746bfc28..80ac126b4 100644--- a/docs/images/agents/zh/sdk.md+++ b/docs/images/agents/zh/sdk.md@@ -1,12 +1,12 @@-## 步骤 1 安装 OpenViking-执行以下命令以安装 OpenViking+## 步骤 1:安装 Python SDK+在运行代码的 Python 环境中安装独立 SDK:```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking-sdk```## 步骤 2 初始化客户端-参考 GitHub 提供的规范写入示例,自动填入 API Key 和域名+使用当前服务地址和 API Key 创建客户端,后续步骤复用该客户端:```pythonfrom openviking_sdk import SyncHTTPClient, TextPart@@ -24,15 +24,15 @@ client.initialize()## 步骤 3:写入资源-参考 GitHub 提供的规范写入示例,自动填入 API Key 和域名+将本地文件路径和目标 URI 替换为实际值。`to` 是完整目标 URI,请使用尚未占用的路径:```pythonfile_path = "[TODO]your-file-path"-resource_to = "[TODO]your-resource-path" # e.g. viking://resources+resource_to = "[TODO]your-resource-path" # e.g. viking://resources/my-documentreason = "[TODO]your-reason" # e.g. External API documentation# Reuse the initialized client.-client.add_resource(+result = client.add_resource(path=file_path,to=resource_to,options={"reason": reason},@@ -40,7 +40,7 @@ client.add_resource(```## 步骤 4:写入记忆-参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名+创建会话、写入消息,再提交记忆提取任务:```pythontext = "[TODO]your-message-text" # e.g. I am a developer@@ -55,3 +55,5 @@ client.add_message()result = client.commit_session(session_id=session_id)```++资源导入和记忆提取都在后台处理。响应包含 `task_id` 时,保存它并用 `client.get_task(result["task_id"])` 查询;无待处理内容的 commit 可能不返回任务。等待 `completed` 后再检查结果,遇到 `failed` 或 `cancelled` 时先处理任务错误。用完后调用 `client.close()`。diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.mdindex 1e6671549..7db9e23a7 100644--- a/docs/images/agents/zh/trae.md+++ b/docs/images/agents/zh/trae.md@@ -17,7 +17,7 @@**TRAE / TRAE CN**:在「设置 → MCP → 已配置的 MCP Servers」中确认能够看到 `openviking` 条目即表示接入成功。-**TraeCode CLI 2.0**:Hook 要先信任才会运行。启动 `trae-cli`,在信任确认上选 **Trust all and continue**:+**TraeCode CLI 2.0**:启动 `trae-cli`,在 hook 审阅提示中选 **Trust all and continue**(具体界面随版本变化):```textHooks need review@@ -29,7 +29,9 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-再执行 `trae-cli plugin list`,确认 `openviking-memory` 已启用。错过这个提示,或当时选了第 3 项,Hook 就不会运行:输入 `/hooks` 补上信任并开启条目,`/plugins` 里确认插件已启用——两个开关相互独立,都要是开着的。插件更新动了 Hook 时会再要求信任一次。+如果跳过了提示或选了第 3 项,在 `/hooks` 中检查并开启 OpenViking hooks。执行 `trae-cli plugin list` 确认插件已启用。新增或变更的 hooks 需要重新检查;不同版本支持的会话生命周期见完整文档。++MCP 条目可见只说明配置存在。让助手调用 OpenViking 的 `health` 和 `list` 验证连接;自动召回需另行检查:等之前的会话提交并处理完成后,在同一工作目录中新建会话,询问已保存的信息。## 故障排查diff --git a/docs/images/agents/zh/workbuddy.md b/docs/images/agents/zh/workbuddy.mdindex 64ff2029a..b5d6e2db7 100644--- a/docs/images/agents/zh/workbuddy.md+++ b/docs/images/agents/zh/workbuddy.md@@ -15,7 +15,7 @@{"mcpServers": {"OpenViking": {- "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",+ "url": "{{OPENVIKING_BASE_URL}}/mcp","headers": {"Authorization": "Bearer {{OPENVIKING_API_KEY}}"}diff --git a/docs/zh/agent-integrations/01-overview.md b/docs/zh/agent-integrations/01-overview.mdindex 6e9319f57..2c651e190 100644--- a/docs/zh/agent-integrations/01-overview.md+++ b/docs/zh/agent-integrations/01-overview.md@@ -35,28 +35,17 @@ OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端## 低延迟召回-查询扩展和召回结果压缩是两个独立的可选模型调用。需要优先保证响应速度时,可以在 Agent 插件端同时关闭它们;语义检索、预算控制、档位降级和跨轮去重仍会正常工作。--下面这组环境变量同时适用于 Claude Code 和 Codex。查询扩展在所有经共享加载器解析配置的记忆插件上都可以关闭;压缩只有 Claude Code 和 Codex 支持。+查询扩展和召回压缩都会增加模型调用。优先考虑响应速度时,可以关闭这两项;检索、预算控制和跨轮去重仍然保留:```bashexport OPENVIKING_RECALL_QUERY_EXPANSION=offexport OPENVIKING_RECALL_COMPRESS=off```-两个插件都有本地压缩逻辑,但配置模型不同:--- Claude Code 默认使用 `recallCompress=auto`:优先调用本地 `claude -p`(Sonnet + low),本地 CLI 不可用时回落到 OpenViking 服务端生成 digest。`client` 强制只用本地,`server` 强制只用服务端。-- Codex 默认调用本地 `codex exec`,模型顺序为 `gpt-5.3-codex-spark`,其次 `gpt-5.6-luna` + low。它不会启用服务端压缩。--两端的共同默认配置是 `recallCompress=auto`。`OPENVIKING_RECALL_COMPRESS=off` 会同时关闭两端压缩;Codex 将 `auto` 或 `client` 解释为启用本地压缩。旧的 Claude Code 变量 `OPENVIKING_RECALL_REWRITE` 仍可兼容,但新配置请使用统一名称。--也可以把同样的设置写进 `~/.openviking/ovcli.conf`:+也可以在 `~/.openviking/ovcli.conf` 中配置:```json{- "url": "https://openviking.example.com",- "api_key": "your-api-key","plugin": {"recallQueryExpansion": "off","recallCompress": "off"@@ -64,8 +53,23 @@ export OPENVIKING_RECALL_COMPRESS=off}```-环境变量优先于 `ovcli.conf`。修改后重启对应的 Agent,让 hook 进程重新加载配置。上述设置属于插件客户端,不需要修改服务端的 `ov.conf`。+### 选择压缩方式++| 值 | 行为 |+| --- | --- |+| `off` | 不压缩召回结果 |+| `server` | 请求 OpenViking 服务端压缩 |+| `client` | 只用本地压缩器,适用于 Claude Code 和 Codex |+| `auto` | 有本地压缩器时优先使用,否则请求服务端自动处理 |++Claude Code 和 Codex 默认使用 `auto`,本地压缩器分别是 `claude -p` 和 `codex exec`,见 [§3.2.5](./16-capability-reference.md#_3-2-5-召回再摘要)。其他支持云端压缩的集成默认保持 `off`,需要显式开启。服务端压缩适用于 Claude Code、Codex、OpenCode、DSH、pi、Cursor、TRAE、TRAE CN、ZCode、OpenClaw 和 Hermes,要求服务端支持 context-search rewrite。++这些设置控制自动召回。模型主动调用 MCP `search` 时,使用该次调用传入的参数。完整规则与旧服务端回退行为见[共享插件说明](https://github.com/volcengine/OpenViking/blob/main/examples/memory-plugin-shared/README.md#cloud-recall-compression)。++共享插件读取 `ovcli.conf` 的 `plugin` 段;`plugin.<harness>` 可覆盖某个客户端的配置。环境变量优先级更高;旧变量 `OPENVIKING_RECALL_REWRITE` 仍可作为 `OPENVIKING_RECALL_COMPRESS` 的别名使用,详见[插件配置](../configuration/02-client.md#插件配置)。修改后重启对应 Agent,使 hook 进程加载新配置。这些都是插件客户端配置,不需要修改服务端的 `ov.conf`。++### 请求超时-`plugin` 段由每个记忆插件读取——claude-code、codex、cursor、trae、trae-cn、zcode、kimicode、opencode、dsh 和 pi;`plugin.<harness>` 对象只覆盖其中某一个 harness 的共享键,两种写法都认(`claude_code` 或 `claude-code`、`trae_cn` 或 `trae-cn`)。压缩是例外:其余 harness 认 `recallQueryExpansion`,但忽略 `recallCompress` 及其配套项——它们都不会请求服务端 digest。+查询扩展、检索和 digest 压缩依次执行。查询扩展默认超时为 5 秒(`retrieval.recall_intent_timeout_s`),digest 默认超时为 30 秒(`retrieval.recall_rewrite_timeout_s`)。-context 请求的等待时间比普通请求更长,因为客户端提前中断会丢掉整个响应,而不只是超时的那一段。服务端流水线是串行的,每个可选阶段各有保险丝:先是查询扩展(`retrieval.recall_intent_timeout_s`,5 秒),然后是检索、正文读取和预算规划,最后才是 digest 重写(`retrieval.recall_rewrite_timeout_s`,30 秒)。因此这个上限按请求实际启用的阶段决定——带 session、会走查询扩展时取 15 秒,同时还要 digest 时取 45 秒,两者都不涉及时沿用插件自身的普通超时。可以用 `OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS`(或 `plugin.recallContextTimeoutMs`)指定这个上限,取值应高于该请求会用到的保险丝、低于 Agent 自身的 hook 超时。+`OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS` 或 `plugin.recallContextTimeoutMs` 控制客户端等待整个 context 请求的上限。未设置时沿用插件的普通超时;请求带 session 且未将 query expansion 设为 `off` 时至少 15 秒,请求 digest 时至少 45 秒。自定义值应高于该请求会用到的服务端超时,并低于宿主 hook 的超时;客户端提前结束会丢失整个响应。diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.mdindex 3db726c06..f8be416fa 100644--- a/docs/zh/agent-integrations/02-claude-code.md+++ b/docs/zh/agent-integrations/02-claude-code.md@@ -17,12 +17,12 @@ curl -fsSL https://openviking.ai/install | bash现在不再需要任何 shell wrapper:插件自带的 stdio MCP 代理会在运行时读取 `~/.openviking/ovcli.conf`(或 `OPENVIKING_*` 环境变量),与 hooks 使用同一套配置链。-使用一段时间后,即便在全新的对话中提及过往的话题,Claude Code 也能准确回忆起来。+可以在新会话中询问已保存的信息,验证跨会话召回是否生效。<details><summary><b>手动安装</b></summary>-如果您倾向于手动安装:+如果你倾向于手动安装:1. **配置连接** — 手写 `~/.openviking/ovcli.conf`(`url`、`api_key`,可选 `account`/`user`),或装完后运行插件自带向导 `node <插件目录>/scripts/setup.mjs`。@@ -39,7 +39,7 @@ curl -fsSL https://openviking.ai/install | bash> 尚未创建 `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 版本?安装脚本会跳过它并提示升级。如需用 `claude mcp add` + hooks 合并手动接入,见 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。@@ -50,7 +50,7 @@ curl -fsSL https://openviking.ai/install | bash启动 `claude`,随后:- 输入 `/plugins` → 在 Installed 列表中应能找到 **openviking-memory**(其子项 **openviking** MCP 应显示为已连接状态)。-- 输入 `/mcp` → OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。+- 输入 `/mcp` → OpenViking 对应的条目应显示你的服务器 URL 及有效的认证信息。- 输入 `/openviking-memory:ov` → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。若插件未正常工作,可设置环境变量 `OPENVIKING_DEBUG=1`,并查看日志文件 `~/.openviking/logs/cc-hooks.log` 以排查问题。@@ -66,7 +66,7 @@ curl -fsSL https://openviking.ai/install | bash- **启动子代理(subagent)时** — 为其分配相互隔离的记忆会话。- **原生文件工具访问 `viking://` 路径前** — 拦截该调用,并提示改用对应的 OpenViking MCP 工具;对 skill 路径的 `Write` 或 `Edit` 会被引导到 `add_skill`。-所有数据写入操作均为异步执行,不会阻塞当前的对话进程。+捕获在独立后台进程中执行,不阻塞当前对话轮次。PreCompact 和 SessionEnd 会在 hook 超时范围内等待会话提交完成。skill 清单就是 `<available-skills>` 块,列出存放在 OpenViking 中的 skill:先列你自己在 `viking://~/skills` 下的,再列账号内共享在 `viking://agent/skills` 下的,每个附一句简短描述。要照清单里的 skill 执行前,Claude 会先用 OpenViking 的 `read` 工具读取它的 `SKILL.md`。清单有独立的 Token 预算:放不下描述时只列名称,连一个名称都放不下时缩成一行总数。插件自带的 `openviking-skills` skill 告诉 Claude 如何查找和使用 OpenViking 中的 skill,如何用 `add_skill` MCP 工具创建、安装和共享 skill,如何删除 skill,以及在你要求时如何把 `~/.claude/skills` 等本地 skill 迁入 OpenViking。@@ -93,11 +93,11 @@ skill 清单就是 `<available-skills>` 块,列出存放在 OpenViking 中的| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启或关闭插件 || `OPENVIKING_DEBUG` | `false` | 将调试日志输出至 `~/.openviking/logs/cc-hooks.log` |-这些旋钮大多也可以写在 `ovcli.conf` 的 `plugin` 段下——见[插件配置](../configuration/02-client.md#插件配置)。两个过滤器 knob 尤其建议写在那里,用 JSON 数组,因为环境变量形式会按逗号切分。+这些配置大多也可以写在 `ovcli.conf` 的 `plugin` 段下——见[插件配置](../configuration/02-client.md#插件配置)。两个过滤器建议使用 JSON 数组,避免环境变量中的逗号被当作分隔符。如果更看重召回响应速度,请参阅[低延迟召回](./01-overview.md#低延迟召回),其中说明了如何通过环境变量或 `ovcli.conf` 关闭查询扩展与结果压缩。-在多租户场景下,请额外配置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整的环境变量列表请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。+使用 user/admin key 时,服务端从密钥解析身份;仅在 trusted 模式下按管理员提供的信息设置 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`。完整的环境变量列表请参阅 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。</details>@@ -119,7 +119,7 @@ skill 清单就是 `<available-skills>` 块,列出存放在 OpenViking 中的| 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 || MCP 工具调用报认证错误 | 当前 ovcli 配置没有 authenticated server 所需的有效 `api_key` | 更新 `ovcli.conf` 中的 `api_key`;stdio 代理在认证失败后会重新读取配置 |-| 远程认证失败 (401 / 403) | API Key 错误或缺少租户 Header | 检查 `OPENVIKING_API_KEY` 是否正确;多租户环境下还需核对 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |+| 远程认证失败 (401 / 403) | 凭据无效或权限不足 | 检查当前 user/admin key 和资源权限。仅 trusted 模式需要管理员提供的 account/user Header;这些 Header 不能改变用户 Key 绑定的身份。 |## 参见diff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.mdindex a79e30370..2f3d635ca 100644--- a/docs/zh/agent-integrations/03-openclaw.md+++ b/docs/zh/agent-integrations/03-openclaw.md@@ -29,7 +29,7 @@ bash cleanup-memory-openviking.sh```bashopenclaw plugins install clawhub:@openviking/openclaw-plugin-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --jsonopenclaw gateway restart```@@ -42,7 +42,7 @@ openclaw gateway restart```bashnpm install -g openclaw-openviking-setup-helper-ov-install --base-url http://your-server:1933+ov-install --base-url https://openviking.example.com```常用参数:@@ -74,10 +74,10 @@ ov-install --base-url http://your-server:1933```bash# Alice 是 OpenViking user;按 OpenClaw 助手分开 peer 记忆。-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role assistant --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --peer-role assistant --json# support-agent 是 OpenViking user;按给它发消息的人分开 peer 记忆。-openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json+openclaw openviking setup --base-url https://openviking.example.com --api-key sk-xxx --peer-role sender --json```安装和 setup 只接受 `sender`;已有的 `peer_role=person` 配置仍兼容,并按 `sender` 处理。OpenViking 会为每个用户初始化受管的 `peers/` 容器,因此 `none` 的含义是不使用具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆;切换 scope 不会搬迁已有记忆。@@ -136,7 +136,7 @@ openclaw config get plugins.slots.contextEngine# 期望输出:openviking```-全链路健康检查:+先按 HEALTHCHECK.md 启用 Gateway 的 `/v1/responses` 端点,再从 OpenViking 源码目录执行全链路检查。该命令会发起真实模型请求并写入测试对话:```bashpython examples/openclaw-plugin/health_check_tools/ov-healthcheck.py@@ -160,7 +160,7 @@ python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py| `autoRecallTimeoutMs` | `5000` | 整个 auto-recall 流程的外层超时(毫秒);本地嵌入硬件较慢时可调大(取值范围 1000–300000) |```bash-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.baseUrl https://openviking.example.comopenclaw config set plugins.entries.openviking.config.apiKey your-api-key```diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex 1ccdab493..f85e79dcf 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)记忆功能。只需安装一次,即可实现:在会话开始时加载 OpenViking profile、记忆索引和 skill 清单,在每次用户输入前自动召回相关记忆,在每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将完整记录提交给记忆抽取器。同时,该插件将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 `find`、`search`、`read`、`remember` 等工具来主动管理记忆。+为 [Codex](https://developers.openai.com/codex) 提供跨会话记忆。插件通过 hooks 自动召回、捕获和提交对话,通过 MCP 提供检索、读取和记忆管理工具。源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)@@ -23,7 +23,7 @@ codex### 首次启动:信任 hooks-插件的 hooks 对 Codex 是新的,启动时会先停在一次信任确认上,选 **Trust all and continue**;想先看一眼 hook 命令就选 Review hooks:+安装插件不会自动信任它的 hooks。首次启动时 Codex 会显示类似下面的审阅提示,具体界面随 Codex 版本变化。选 **Trust all and continue**,或先选 **Review hooks** 查看命令。选 *Continue without trusting* 后 hooks 不会运行,直到在 `/hooks` 中开启。```textHooks need review@@ -35,14 +35,9 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-全新安装会一次列出插件注册的全部 6 个 hook。之后每次插件更新只要动了 hook,Codex 都会再拦一次,数字是这次新增或改动的条数(比如只改了一个就是 `1 hook is new or changed`),同样选 Trust all and continue。+也可以在 `/hooks` 中检查 OpenViking 命令,信任并启用准备使用的条目;同时在 `/plugins` 中确认 `openviking-memory` 已启用。当前插件声明了 6 个 hook,新增或修改定义后需要重新审阅,规则见[官方 hook 信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。-选第 3 项或错过这一步,hooks 就不会运行:MCP 工具仍能调用,但自动召回和捕获全部停摆。要恢复,得让两个彼此独立的开关都处于开启状态:--- `/hooks` — hook 的信任与开关,把标着 *New hook - review required* 或 *Modified since last trusted* 的条目信任并打开。-- `/plugins` — 插件本身的启用状态,确认 `openviking-memory` 是 enabled。--任何一边是关着的,自动召回和捕获都不会发生。+Hook 关闭时,MCP 工具仍可能正常使用。自动召回需要 `UserPromptSubmit`,捕获需要 `Stop`,其余生命周期提交见下表。之前跳过设置的,可以回到 `/hooks` 启用相关条目。<details><summary><b>手动安装</b></summary>@@ -69,7 +64,18 @@ TraeCode CLI 2.0 用户启动 `trae-cli`,并可用 `trae-cli plugin list` 确## 工作原理-本插件深度挂载于 Codex 的生命周期之中:在 `SessionStart`(`startup`、`clear` 或 `resume`)阶段,它会复用其他 coding-agent 集成共用的 CJK-aware profile 构建逻辑,注入 `profile.md`、`preferences/` 与 `entities/` 的 URI 和摘要索引,以及列出你的 OpenViking skill 的 `<available-skills>` 清单;在每次用户输入前,它会搜索 OpenViking 并注入相关的记忆(触发 `UserPromptSubmit`);在每轮对话结束后,会将新的对话追加至当前会话(触发 `Stop`);在上下文压缩前,补齐并提交(commit)完整的对话记录(触发 `PreCompact`);在线程正常退出时提交整段会话(触发 `SessionEnd`),以确保记忆抽取器能够在完整的上下文环境中运行。shell 命令执行前(`Bash` 上的 `PreToolUse`),插件会检查命令里是否带 `viking://` URI:命令照常执行,模型会收到一条提示,建议改用 OpenViking MCP 工具;如果该 URI 是有意传入的数据(例如 `ov` 命令参数),模型可以忽略这条提示。此外,在启动新会话时,插件还会清扫前次运行遗留的孤儿会话(orphan session)。恢复已有会话时,固定 profile 背景还会与最新的 archive digest 合并注入。+插件按以下事件处理记忆:++| Codex 事件 | 插件行为 |+| --- | --- |+| `SessionStart`(`startup`、`clear`、`resume`) | 注入 `profile.md`、`preferences/` 和 `entities/` 的 URI 与摘要索引,以及 `<available-skills>` 清单。复用支持中日韩文本的公共 profile 构建逻辑;恢复会话时还可注入最新 archive digest。 |+| `UserPromptSubmit` | 搜索并注入与当前输入相关的记忆。 |+| `Stop` | 将新增对话追加到 OpenViking 会话。 |+| `PreCompact` | 补齐并提交压缩前的完整对话记录。 |+| `SessionEnd` | 正常退出时提交会话,触发后续记忆提取。 |+| `PreToolUse`(`Bash`) | 检查命令中的 `viking://` URI,并提示模型使用 OpenViking MCP 工具。命令仍会执行;URI 是 `ov` 参数等有意传入的数据时,可以忽略提示。 |++新会话启动时还会清理上次运行遗留、已超过闲置 TTL 的孤儿会话。> **已知局限**:`SessionEnd` 需要 Codex 0.145 及以上版本,且只在正常退出时触发(`/quit`、`/exit`、连按两次 `Ctrl-C`、EOF、`codex exec` 运行结束)。`SIGTERM`、直接关闭终端、`kill -9` 或崩溃都不会触发;当 TUI 挂在 `codex app-server` 守护进程上时,该事件会被延后。这些会话——以及 Codex 低于 0.145 的所有会话(以及没有该事件的 TraeCode CLI 版本)——由下一次 `SessionStart` 的闲置 TTL(生存时间,默认为 30 分钟)清扫回收。@@ -100,7 +106,7 @@ TraeCode CLI 2.0 用户启动 `trae-cli`,并可用 `trae-cli plugin list` 确| `OPENVIKING_CAPTURE_FILTERS` | `""` | CSV 格式的 sed 风格正则规则,作用于每个被捕获的回合(同一套语法) || `OPENVIKING_DEBUG` | `false` | 是否将日志写入 `~/.openviking/logs/codex-hooks.log` |-这些旋钮大多也可以写在 `ovcli.conf` 的 `plugin` 段下——见[插件配置](../configuration/02-client.md#插件配置)。两个过滤器 knob 尤其建议写在那里,用 JSON 数组,因为环境变量形式会按逗号切分。+这些配置大多也可以写在 `ovcli.conf` 的 `plugin` 段下——见[插件配置](../configuration/02-client.md#插件配置)。两个过滤器建议使用 JSON 数组,避免环境变量中的逗号被当作分隔符。如果更看重召回响应速度,请参阅[低延迟召回](./01-overview.md#低延迟召回),其中说明了如何通过环境变量或 `ovcli.conf` 关闭查询扩展与 Codex 本地结果压缩。@@ -120,8 +126,8 @@ TraeCode CLI 2.0 用户启动 `trae-cli`,并可用 `trae-cli plugin list` 确|------|------|------|| MCP 工具调用报认证错误 | 当前 ovcli 配置没有 authenticated server 所需的有效 `api_key` | 修正 `~/.openviking/ovcli.conf`(或运行 `node <插件目录>/scripts/setup.mjs`)后重启 Codex;stdio 代理会在启动时和认证失败后重新读取配置 || MCP 工具调用报连接错误 | 服务器不可达或 URL 配置错误 | 执行 `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` 检查服务器状态 |-| `6 hooks need review`,或插件已装但 hook 不生效 | 全新安装要信任全部 6 个 hook,之后每次插件更新改动到 hook 时还会再问一次;当时选了 *Continue without trusting* 或直接跳过,hooks 就一直不会运行 | `/hooks` 里信任并开启相关条目,`/plugins` 里确认 `openviking-memory` 已启用——两个开关相互独立,都要是开着的 |-| `ov config switch` 后插件仍指向旧服务器 | 上个会话的代理进程仍在运行 | 重启 Codex;代理在启动时解析凭据 |+| 提示审阅 hook,或插件已装但没有自动召回/捕获 | 相关 hook 未信任、未启用,或插件被禁用 | 在 `/hooks` 审阅并启用相关条目,再到 `/plugins` 确认插件已启用。 |+| `ov config switch` 后插件仍指向旧服务器 | 原代理仍保留连接,或凭据环境变量覆盖了选中的配置 | 重启 Codex,并检查凭据环境变量与 `OPENVIKING_CLI_CONFIG_FILE`。远程调用会在认证失败后检查文件变化,不会在每次成功请求时重载 || Hook 与 MCP 指向不同服务器 | 某一侧残留了过期的 `OPENVIKING_*` 凭据环境变量(默认环境变量优先于 ovcli.conf) | 清除过期环境变量(让 ovcli.conf 同时驱动两者)、设置 `OPENVIKING_CREDENTIAL_SOURCE=cli`,或保证环境变量一致 |## 参见diff --git a/docs/zh/agent-integrations/06-mcp-clients.md b/docs/zh/agent-integrations/06-mcp-clients.mdindex 8d768991e..4cbb4dc89 100644--- a/docs/zh/agent-integrations/06-mcp-clients.md+++ b/docs/zh/agent-integrations/06-mcp-clients.md@@ -1,10 +1,10 @@# MCP 客户端-任何兼容 [MCP](https://modelcontextprotocol.io/) 的客户端都可以直接连接 OpenViking 内置的 `/mcp` 端点——无需安装插件或启动额外进程。适用于 Cursor、Trae、Manus、Claude Desktop、ChatGPT 等。+支持 [MCP](https://modelcontextprotocol.io/) Streamable HTTP 的客户端可直接连接 OpenViking 的 `/mcp` 端点。仅支持 stdio 的客户端可使用 [Agent Plugins 包](./15-agent-plugins.md)中的代理。## 快速配置-大多数 MCP 客户端使用标准 `mcpServers` 格式:+以下示例适用于接受 `mcpServers` 和自定义请求头的客户端。其他客户端按下方对应说明配置:```json{@@ -19,7 +19,7 @@}```-本地服务未配置 `root_api_key` 时(dev 模式)无需认证。+服务运行在 `dev` 模式时无需认证,应仅监听本机回环地址。认证模式下,即使从本机访问也需要凭据。## 各平台注意事项@@ -37,9 +37,13 @@ claude mcp add --transport http openviking \> 如果你需要免工具调用的自动召回与自动捕获,请使用 [Claude Code 记忆插件](./02-claude-code.md)。-### Trae / Cursor / ChatGPT+### Trae / Cursor-使用上面的标准 `mcpServers` 配置即可——均已通过 API Key 鉴权验证。+在客户端的 MCP 配置中添加上述服务 URL 和 API Key。++### ChatGPT++通过开发者模式创建自定义 App,再完成 OAuth 授权,见 [OAuth 指南](../guides/11-oauth.md#chatgpt-codex-plus-enterprise)。### Codex@@ -67,9 +71,9 @@ Codex 请使用 [Codex 记忆插件](./04-codex.md)。插件通过 manifest 提### Claude Desktop / Claude.ai (OAuth)-这些客户端要求 OAuth 2.1——无法直接传 API Key。OpenViking 自带原生 OAuth 2.1 实现,无需外部代理。+托管的远程连接器流程使用 OpenViking 原生 OAuth;在授权页填写已有的 OpenViking User/Admin Key。Claude Desktop 的本地 stdio 配置是另一种接入方式。-如果你已经为 OpenViking 服务配好了 HTTPS,直接连接 `https://your-server.com/mcp` 端点即可——客户端会自动引导你完成 OAuth 授权流程。+在服务端启用 `oauth.enabled` 并配置 HTTPS 后,让客户端连接 `https://your-server.com/mcp`,在浏览器中完成授权。HTTPS 配置、部署模板和完整授权流程详见 [OAuth 2.1 指南](../guides/11-oauth.md) 和 [公网访问指南](../guides/12-public-access.md)。@@ -82,7 +86,7 @@ HTTPS 配置、部署模板和完整授权流程详见 [OAuth 2.1 指南](../gui| 现象 | 修复 ||------|------|| 连接被拒绝 | 确认 `openviking-server` 正在运行:`curl http://localhost:1933/health` |-| 认证错误 | 确保客户端配置中的 API Key 与服务端一致。见 [鉴权指南](../guides/04-authentication.md) |+| 认证错误 | 检查客户端是否使用有效的 user/admin key。见 [鉴权指南](../guides/04-authentication.md) |## 参见diff --git a/docs/zh/agent-integrations/07-langchain-langgraph.md b/docs/zh/agent-integrations/07-langchain-langgraph.mdindex 7452086f7..f46d83a06 100644--- a/docs/zh/agent-integrations/07-langchain-langgraph.md+++ b/docs/zh/agent-integrations/07-langchain-langgraph.md@@ -209,7 +209,7 @@ docs = retriever.invoke("用户之前对部署方案做了什么决定?")### Context backend```python-from langchain_core.messages import AIMessage+from langchain_core.messages import AIMessage, HumanMessagefrom langchain_core.runnables import RunnableLambdafrom langchain_openviking import with_openviking_context@@ -218,7 +218,10 @@ with with_openviking_context(url="http://localhost:1933",api_key="...",) as chain:- result = chain.invoke(...)+ result = chain.invoke(+ [HumanMessage(content="Remember that I prefer short answers")],+ config={"configurable": {"session_id": "support-thread-1"}},+ )```### Agent toolsdiff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.mdindex 79bfa5a1d..94a774c05 100644--- a/docs/zh/agent-integrations/08-community-plugins.md+++ b/docs/zh/agent-integrations/08-community-plugins.md@@ -82,11 +82,13 @@ curl -fsSL https://openviking.ai/install | bash -s -- --uninstall --yes --harnes**安装**:在 AstrBot WebUI → 插件市场搜索 **OpenViking Memory** 并安装;或从链接安装:`https://github.com/t0saki/astrbot_plugin_openviking_memory.git`+当前插件要求 AstrBot 4.23.1+ 和兼容的 OpenViking 服务。`global` 使用 User Key;`venue` 需要 Admin Key 创建用户。迁移旧配置前,先核对上方插件 README。+**主要特性**:- 基于 hooks 的自动召回与捕获,模型不需要主动调用工具-- 三档隔离模式:`venue_user`(群/私聊各自独立)、`venue_user_fanout`(跨群共享)、`global_user`(全局共享)-- 四触发器自动 commit:消息计数、token 阈值、空闲超时、进程退出 flush+- `self_scope=global` 共用一个 Bot 身份,`venue` 为群/私聊分别创建用户;每个人以 peer 表示。旧版 `isolation_mode` 会映射到这两种范围。+- 按消息数、token 阈值或空闲超时自动 commit- 首次接入群聊时自动拉取平台历史消息入库## Open WebUI tool serverdiff --git a/docs/zh/agent-integrations/09-log-ingestion.md b/docs/zh/agent-integrations/09-log-ingestion.mdindex 5e1d982ec..e81d7e7db 100644--- a/docs/zh/agent-integrations/09-log-ingestion.md+++ b/docs/zh/agent-integrations/09-log-ingestion.md@@ -1,8 +1,8 @@# 导入本地 Agent 日志(openviking-server ingest)-`openviking-server ingest` 把你本地已有的 AI 编码 / agent harness 的对话日志(Claude Code、Codex、WorkBuddy、OpenCode、MiMo、Hermes、OpenClaw)解析成标准消息,再通过 OpenViking 既有的会话管线“重放”进去(`创建会话 → 批量追加消息 → 提交`,提交时触发记忆抽取),从而把这些历史与新增对话沉淀为长期记忆。它与各 harness 的“记忆插件”互补:插件在对话**进行时**实时挂载捕获,而本工具用于**导入既有日志**与**离线监听新增日志**,无需插件、也无需改动对应 harness。+`openviking-server ingest` 读取本地 Agent 对话日志,将消息导入 OpenViking 会话并提交,触发记忆提取。它支持一次性导入历史日志,也支持持续监听新增日志,无需修改对应 Agent 或安装记忆插件。-与插件方案的关键区别:本工具是 OpenViking 的**客户端**,跑在日志所在的机器上,通过 SDK 指向本地或远端 server;它默认**完全关闭**,不会“装上就扫你本地文件”。+命令运行在日志所在机器,通过 SDK 连接本地或远程 OpenViking 服务。导入默认关闭,安装 OpenViking 不会扫描本地日志;需要显式启用总开关和指定 Agent 的配置。源码:[openviking/ingest](https://github.com/volcengine/OpenViking/tree/main/openviking/ingest)@@ -98,7 +98,7 @@ openviking-server ingest runopenviking-server ingest status```-`--reset` 会在重放前删除并重建对应的 OV 会话;不加 `--reset` 时,重复运行是幂等的(游标保证不会重复追加)。+`--reset` 会在重放前删除并重建对应的 OV 会话,不会删除此前已提取的记忆。正常重跑会从持久化游标续传,并用服务端消息数核对中断的批次。保留游标数据库,避免多个进程同时重放或其他程序写入导入会话;切换服务或用户时不要沿用同一份游标数据库。## peer_id@@ -121,13 +121,13 @@ openviking-server ingest status- **存量回填**:枚举所有会话,从游标读到末尾后逐会话提交一次。- **监听增量**:参照 OpenViking 自身的 `WatchScheduler`,用**定时轮询**(非文件系统事件)+ 持久游标驱动;漏一拍、休眠或重启后,下一拍从游标读到末尾即可自愈。JSONL 用字节偏移游标(含半行/截断/轮转处理),SQLite 用 `(time, id)` 游标只读读取(兼容 WAL)。-游标状态持久化在 `~/.openviking/ingest/state.db`,因此回填与监听都能在重启后续传,且不会重复入库。+游标状态持久化在 `~/.openviking/ingest/state.db`,在连接身份不变时,回填与监听可以在重启后续传。## 成本与隐私- 提交会触发记忆抽取(LLM 调用)。一次性回填数月历史可能产生大量调用,建议先 `--dry-run`、用 `--since` 收窄时间窗、按 harness 分批开启。- 日志中可能含敏感内容(凭据、文件内容)。请在受信任的部署中使用,并确认 `server_url` 指向你期望的 server。-- tool 调用的输入/输出默认按低价值丢弃,仅入库 user / assistant 文本。+- 默认只导入 user/assistant 文本,不保留工具调用的输入和输出。需要结构化工具记录时,使用对应运行时的记忆插件。## 参见diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.mdindex 704ebdcd0..d0286a485 100644--- a/docs/zh/agent-integrations/10-opencode.md+++ b/docs/zh/agent-integrations/10-opencode.md@@ -1,6 +1,6 @@# OpenCode 插件-为 [OpenCode](https://opencode.ai/) 提供跨项目、跨会话的长期记忆和已索引仓库上下文。安装后,每次对话都会通过 OpenCode plugin hooks 自动召回相关记忆并捕获新内容;模型可调用工具来自 Claude Code / Codex 记忆插件同款的 OpenViking stdio MCP proxy。+为 [OpenCode](https://opencode.ai/) 提供跨项目、跨会话的长期记忆和已索引仓库上下文。安装后,每次对话都会通过 OpenCode plugin hooks 自动召回相关记忆并捕获新内容;模型可调用工具来自 Claude Code / Codex 记忆插件同款的 OpenViking stdio MCP 代理。源码:[examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)@@ -102,7 +102,7 @@ node examples/memory-plugin-shared/sync.mjsnode examples/opencode-plugin/scripts/setup.mjs```-行为旋钮写在 `~/.openviking/ovcli.conf` 的 `plugin` 段,与向导写入的连接字段同一个文件。共享键对所有记忆插件生效;`plugin.opencode` 下的键只对本插件生效,并覆盖共享键:+行为配置写在 `~/.openviking/ovcli.conf` 的 `plugin` 段,与向导写入的连接字段同一个文件。共享键对所有记忆插件生效;`plugin.opencode` 下的键只对本插件生效,并覆盖共享键:```json{diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex 1910c0501..a3b5f2efa 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -10,13 +10,13 @@- **每个 prompt** 向 OpenViking server 做语义召回,把命中的记忆作为隐藏上下文注入。- **每个 turn** 把用户与助手消息(含结构化工具调用)捕获进 OpenViking session;takeover 模式会在 synced token 压力超过阈值后 commit,并在模型上下文中只保留近期 live tail。- **Context takeover** 默认开启。`context` hook 会先注入来自最新 archive overview 的 `[OpenViking Session Context]`,再把 recall 结果插入最新用户消息。-- **模型可调用工具**就是服务端 MCP `tools/list` 返回的工具,注册时统一加 `openviking_` 前缀——与其他记忆插件同一套 15 个工具:`openviking_find`、`openviking_search`、`openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`、`openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`、`openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`。扩展自己不再维护工具清单,服务端增删工具后,下一次 pi 会话即生效,无需发布新版扩展。共享键 `mcpEnabled: false` 可关掉整个工具面,召回、捕获和 takeover 不受影响。+- **模型可调用工具**就是服务端 MCP `tools/list` 返回的工具,注册时统一加 `openviking_` 前缀,包括:`openviking_find`、`openviking_search`、`openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`、`openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`、`openviking_add_skill`、`openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`。扩展自己不再维护工具清单,服务端增删工具后,下一次 pi 会话即生效,无需发布新版扩展。共享键 `mcpEnabled: false` 可关掉整个工具面,召回、捕获和 takeover 不受影响。- **Skill**:扩展从自己的 `skills/` 目录提供 `openviking-memory`、`openviking-skills` 和 `ov-experience-memory`,通过 pi 的 `resources_discover` 事件加入,让模型知道什么时候该用哪个 OpenViking 工具。`mcpEnabled` 为 `false` 时不会加入。-- 工具握手失败不会影响启动。服务端不可达、凭据被拒、没有 `/mcp` 端点时,召回、捕获和 takeover 照常工作,只是这次会话没有 OpenViking 工具;桥接会在后续 turn 重试,所以 pi 启动之后才拉起的服务端不必重启 pi 也能接上。+- 工具握手失败不会影响启动。仅 MCP 握手失败时,REST 召回、捕获和 takeover 仍可使用;整个服务不可达或认证失败时,这些功能也会失败或降级。桥接会在后续 turn 重试,所以 pi 启动之后才拉起的服务端不必重启 pi 也能接上。- 底部状态栏显示 `OV ✓ …` 连接与捕获状态,握手失败时还会追加 `tools ✗`;`/viking` 命令查看状态,包括已注册的工具数量或最近一次握手错误,`/viking commit` 强制 commit。- 模型用本地 `read`/`grep`/`find`/`ls`/`write`/`edit` 访问 `viking://` URI 路径时,调用会被拦截,并提示改用对应的 `openviking_*` 工具;`bash` 命令带 `viking://` URI 时照常执行,结果末尾附一条提示,建议改用 `openviking_read` / `openviking_search`。-扩展 0.4.0 用这套镜像工具面替换了原先手写的 7 个 `viking_*` REST 工具,且不保留别名:`--tools` / `--exclude-tools` 白名单里写死旧名字的,必须手动改过来,否则这些工具会静默消失。部分语义也随之改变——`openviking_remember` 写入独立 session 并由服务端立即 commit,`openviking_read` 只返回全文(旧的 `level="abstract"` / `"overview"` 两档已移除,需要精简视图改用 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`),`openviking_forget` 直接删除给定 URI,而不是删除某个 query 的最强匹配。Context takeover 的归档 overview 仍由扩展经 REST 注入,这条路径不变。+扩展 0.4.0 用这套镜像工具面替换了原先手写的 7 个 `viking_*` REST 工具,且不保留别名:`--tools` / `--exclude-tools` 白名单里写死旧名字的,必须手动改过来,否则这些工具会静默消失。部分语义也随之改变——`openviking_remember` 写入独立 session 并由服务端立即 commit,`openviking_read` 读取文件正文,支持按行分页(旧的 `level="abstract"` / `"overview"` 两档已移除,需要精简视图改用 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`),`openviking_forget` 直接删除给定 URI,而不是删除某个 query 的最强匹配。Context takeover 的归档 overview 仍由扩展经 REST 注入,这条路径不变。工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。@@ -58,7 +58,7 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scriptsnode ~/.pi/agent/extensions/openviking/scripts/setup.mjs```-行为与 peer 作用域旋钮写在 `~/.openviking/ovcli.conf` 的 `plugin` 段,与其他记忆插件共用。`plugin.pi` 下的键只对本扩展生效,并覆盖共享键;连接和认证凭据仍来自上面的配置源:+行为与 peer 作用域配置写在 `~/.openviking/ovcli.conf` 的 `plugin` 段,与其他记忆插件共用。`plugin.pi` 下的键只对本扩展生效,并覆盖共享键;连接和认证凭据仍来自上面的配置源:```json{diff --git a/docs/zh/agent-integrations/12-cursor.md b/docs/zh/agent-integrations/12-cursor.mdindex d465eaf08..397c3194a 100644--- a/docs/zh/agent-integrations/12-cursor.md+++ b/docs/zh/agent-integrations/12-cursor.md@@ -6,7 +6,7 @@前置条件:macOS 或 Linux、Node.js 18+,并建议使用最新稳定版 Cursor。安装过程中会引导配置 OpenViking 连接信息。-安装器询问连接方式时,火山引擎云服务用户请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。只有本机已运行 OpenViking 服务时才选择 **自建 / 本地**。+安装器询问连接方式时,火山引擎云服务用户请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。服务运行在本机时选择 **自建 / 本地**(`http://127.0.0.1:1933`);远程自建服务请选择 **自定义 URL / 保持当前** 并填写其 URL。```bashcurl -fsSL https://openviking.ai/install | bash@@ -28,7 +28,7 @@ curl -fsSL https://openviking.ai/install | bash2. 打开 **Cursor Settings → Hooks**,确认 OpenViking 生命周期 Hook 执行了 `scripts/hook.mjs`,URI 保护 Hook 执行了 `scripts/uri-guard.mjs`。3. 查看 `beforeSubmitPrompt` 输出,确认存在 `additional_context`;这表示当前问题的召回结果已直接交给 Agent,无需先调用 MCP。4. 打开 **Cursor Settings → Tools & MCPs**,确认 `openviking` 已连接。-5. 告诉 Cursor 一个临时偏好,等待本轮回复完成;新建会话后询问该偏好,确认捕获和跨会话召回均生效。+5. 告诉 Cursor 一个测试偏好,正常结束会话,并在 Hook 日志中确认捕获和提交。等待记忆提取完成后,在同一工作区新建会话并询问该偏好。## 工作原理diff --git a/docs/zh/agent-integrations/13-trae.md b/docs/zh/agent-integrations/13-trae.mdindex 9d78ac2d4..e64b9edf0 100644--- a/docs/zh/agent-integrations/13-trae.md+++ b/docs/zh/agent-integrations/13-trae.md@@ -6,7 +6,7 @@前置条件:macOS 或 Linux、Node.js 18+,以及支持 `SessionStart`、`UserPromptSubmit`、`PreToolUse`、`Stop` Hook 的 TRAE/TRAE CN 版本。TraeCode CLI 2.0 直接使用兼容 Codex 的插件格式。安装过程中会引导配置 OpenViking 连接信息。-安装器询问连接方式时,火山引擎云服务用户请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。只有本机已运行 OpenViking 服务时才选择 **自建 / 本地**。+安装器询问连接方式时,火山引擎云服务用户请选择 **火山引擎 OpenViking 云服务** 并填写 API Key。服务运行在本机时选择 **自建 / 本地**(`http://127.0.0.1:1933`);远程自建服务请选择 **自定义 URL / 保持当前** 并填写其 URL。```bashcurl -fsSL https://openviking.ai/install | bash@@ -17,7 +17,7 @@ curl -fsSL https://openviking.ai/install | bash### TraeCode CLI 2.0:首次启动信任 hooks-TraeCode CLI 2.0 的 hooks 要先信任才会运行。启动 `trae-cli` 时会停在这个确认上,选 **Trust all and continue**;想先看一眼 hook 命令就选 Review hooks:+TraeCode CLI 2.0 使用 Codex 格式插件。启动 `trae-cli` 时会显示类似下面的 hook 审阅提示,具体界面随版本变化。选 **Trust all and continue**;选 *Continue without trusting* 后 hooks 不会运行。```textHooks need review@@ -29,22 +29,17 @@ Hooks can run outside the sandbox after you trust them.3. Continue without trusting (hooks won't run)```-全新安装会一次列出插件注册的全部 6 个 hook。之后每次插件更新只要动了 hook,启动时都会再拦一次,数字是这次新增或改动的条数(比如只改了一个就是 `1 hook is new or changed`),同样选 Trust all and continue。+也可以在 `/hooks` 中检查 OpenViking 命令,信任并启用准备使用的条目;同时在 `/plugins` 确认插件已启用。定义变化后可能需要重新审阅。MCP 连通不能证明自动召回和捕获已生效,详见 [Codex hook 设置](04-codex.md#首次启动-信任-hooks)。-选第 3 项或错过这一步,hooks 就不会运行:MCP 工具仍能调用,但自动召回和捕获全部停摆。要恢复,得让两个彼此独立的开关都处于开启状态:--- `/hooks` — hook 的信任与开关,把标着 *New hook - review required* 或 *Modified since last trusted* 的条目信任并打开。-- `/plugins` — 插件本身的启用状态,确认 `openviking-memory` 是 enabled。--TRAE 和 TRAE CN 走 `hooks.json`,重启客户端后直接生效,没有这一步。+TRAE 和 TRAE CN 使用安装后的 `hooks.json`,不需要审阅 hook,安装后重启对应客户端。## 安装内容- `SessionStart`:加载用户画像、当前项目记忆,以及 OpenViking skill 清单 `<available-skills>`。- `UserPromptSubmit`:根据当前问题召回并注入相关内容,召回范围包括你自己的 skill 和账号内共享在 `viking://agent/skills` 下的 skill。- `PreToolUse`:在 TRAE 和 TRAE CN 上,`Read`、`Glob`、`Grep` 的路径是 `viking://` URI 时拒绝调用,并提示改用 OpenViking MCP 工具;`Bash` 或 `RunCommand` 命令带 `viking://` URI 时照常执行,同时附加改用建议。TraeCode CLI 2.0 使用 Codex 插件,它的 `PreToolUse` 只匹配 `Bash`,只附加同样的提示,不拒绝调用。-- `Stop`:捕获本轮消息并立即提交,使短会话也能进入记忆抽取流程。-- OpenViking MCP Server:透传服务端完整 MCP 工具集(16 个工具):`find`、`search`、`read`、`list`、`tree`、`remember`、`write`、`edit`、`add_resource`、`add_skill`、`list_watches`、`cancel_watch`、`grep`、`glob`、`forget`、`health`。其中 `search` 的 `mode="context"` 可返回组装后的上下文。+- TRAE/TRAE CN 的 `Stop` 捕获并提交本轮消息;TraeCode CLI 2.0 遵循 Codex 插件的捕获与生命周期提交策略。+- OpenViking MCP Server:透传服务端完整 MCP 工具集(20 个工具):`find`、`search`、`read`、`list`、`tree`、`remember`、`write`、`edit`、`add_resource`、`add_skill`、`list_watches`、`cancel_watch`、`grep`、`glob`、`forget`、`health`、`list_users`、`list_groups`、`get_acl`、`set_acl`。其中 `search` 的 `mode="context"` 可返回组装后的上下文。skill 清单先列你自己的 skill,再列账号内共享的 skill,每条描述截到约 40 token。清单的预算 `skillCatalogTokenBudget`(默认 `1200` token)独立于画像预算;描述放不下时只列名称。把 `skillCatalog` 设为 `false` 或把预算设为 `0` 即可关闭,既可以写在 `~/.openviking/ovcli.conf` 的 `plugin` 段(见[插件配置](../configuration/02-client.md#插件配置)),也可以用环境变量 `OPENVIKING_SKILL_CATALOG` 和 `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`。## 验证@@ -52,7 +47,7 @@ skill 清单先列你自己的 skill,再列账号内共享的 skill,每条1. 重启 TRAE、TRAE CN 或 TraeCode CLI 2.0,并新建 Agent 会话。2. 在客户端的 MCP 设置中确认 `openviking` 已连接。3. 提问一个与已有项目或个人偏好相关的问题,确认回答使用了已有记忆。-4. 告诉 Agent 一个临时偏好,等待回复完成;新建会话后再次询问,确认捕获、提交和跨会话召回均生效。+4. 告诉 Agent 一个临时偏好,在日志中确认捕获和提交,等待记忆提取完成后,在同一工作区新建会话并再次询问。5. 对 TraeCode CLI 2.0,运行 `trae-cli plugin list` 确认 `openviking-memory` 已启用,并在会话里输入 `/hooks`,确认 OpenViking 的条目已信任且处于开启状态。需要排查 Hook 时,设置 `OPENVIKING_DEBUG=1` 后启动客户端,并查看:diff --git a/docs/zh/agent-integrations/15-agent-plugins.md b/docs/zh/agent-integrations/15-agent-plugins.mdindex 52b1c0f2e..1f11ac5c7 100644--- a/docs/zh/agent-integrations/15-agent-plugins.md+++ b/docs/zh/agent-integrations/15-agent-plugins.md@@ -36,7 +36,7 @@ OpenViking 服务端本身在 `/mcp` 上就是 streamable HTTP,但 `mcp.json`## 凭据解析顺序-从高到低 —— 与 `ov` CLI 及其他 OpenViking 插件完全一致:+该包按以下来源解析凭据,优先级从高到低,与 CLI 共用凭据文件;插件专用的回退规则列在下面:1. 环境变量:`OPENVIKING_URL`(或 `OPENVIKING_BASE_URL`)、`OPENVIKING_MCP_URL`、`OPENVIKING_API_KEY`(或 `OPENVIKING_BEARER_TOKEN`)、`OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、`OPENVIKING_PEER_ID`、`OPENVIKING_AUTH_MODE`2. `~/.openviking/ovcli.conf`(`url`、`api_key`、`account` / `account_id`、`user` / `user_id`、`actor_peer_id` / `peer_id`),其后是它的 `plugin.agent_plugins` 与共享 `plugin` 键(`apiKey`、`accountId`、`userId`、`authMode`)—— 可用 `OPENVIKING_CLI_CONFIG_FILE` 覆盖路径@@ -57,6 +57,8 @@ OpenViking 服务端本身在 `/mcp` 上就是 streamable HTTP,但 `mcp.json`}```+`/mcp` 应使用 User/Admin Key。保留 `server.root_api_key` 的兼容回退,不代表 root Key 可以访问 MCP。+配置文件的改动会被运行中的代理自动读取,无需重启。调试:设置 `OPENVIKING_DEBUG=1`,日志以 JSON Lines 写入 `~/.openviking/logs/agent-plugins.log`(路径可用 `OPENVIKING_DEBUG_LOG` 覆盖)。`OPENVIKING_TIMEOUT_MS` 可调整默认 15s 的单请求超时。@@ -71,7 +73,7 @@ Agent Plugins 1.0 只覆盖 skills 和 MCP servers;hooks、commands、agents内置的 `openviking-skills` 技能覆盖存放在 OpenViking 里的 skill 本身:用 `find(context_type="skill")` 查找、读取并按 `SKILL.md` 执行、用 `add_skill` 新建或替换、从 Git 或本地文件夹安装、共享给整个账号,以及把本地 skill 目录迁入 OpenViking。这里没有会话启动 hook,也就没有 `<available-skills>` 清单,所以该技能让模型自己检索 skill,而不是从清单里读。-**如果你的 harness 支持 hooks 机制,推荐使用专属插件。** hook 驱动的召回与捕获不需要模型花费工具调用、也不依赖模型「想起来要记」,比技能驱动的闭环更省 token、也更可靠。本 Agent Plugins 包适用于没有 hooks 的 harness,或你希望用同一个包覆盖多个客户端的场景。+**如果你的 harness 支持 hooks 机制,推荐使用专属插件。** hook 驱动的召回与捕获不需要模型调用工具,也不依赖模型「想起来要记」。本 Agent Plugins 包适用于没有 hooks 的 harness,或你希望用同一个包覆盖多个客户端的场景。Claude Code、Codex、Cursor、TRAE / TRAE CN、ZCode、OpenCode、pi 共用同一个安装脚本。它会询问要安装的 harness 和 OpenViking 凭据,所有步骤幂等,重复运行安全:diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex bbb23f608..54a8d3ecd 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -26,21 +26,21 @@## 1.1 主动工具面(Agentic 调用能力)-- **MCP 型 harness(claude-code、codex/trae-cli、cursor、trae/trae-cn、zcode、kimicode、opencode、dsh、pi)的主动工具面完全一致,共 16 个工具**:这些工具由服务端统一定义,各插件读取 `~/.openviking/ovcli.conf` 并连接服务端 MCP 工具;pi 在扩展中使用官方 MCP 客户端,再把发现的工具注册成 pi 原生工具。+- **MCP 型 harness(claude-code、codex/trae-cli、cursor、trae/trae-cn、zcode、kimicode、opencode、dsh、pi)的主动工具面完全一致,共 20 个工具**:这些工具由服务端统一定义,各插件读取 `~/.openviking/ovcli.conf` 并连接服务端 MCP 工具;pi 在扩展中使用官方 MCP 客户端,再把发现的工具注册成 pi 原生工具。- trae-cli 指 TraeCode CLI 2.0(仅支持 2.0),经 codex 插件别名安装,插件与 codex 格式兼容,下文矩阵并入 codex 行。| harness | 工具面形态 | 工具数(默认开) | 搜 memory | 搜 resource | 搜 skill | 写 memory | 写 resource | 写 skill | 删除类型边界 ||---|---|---|---|---|---|---|---|---|---|-| claude-code | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| codex / trae-cli | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| cursor | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| trae / trae-cn | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| zcode | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| kimicode | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| opencode | MCP 透传(宿主加 `openviking_` 前缀) | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| dsh | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |-| pi | MCP 镜像(官方客户端;扩展加 `openviking_` 前缀) | 16,即 `tools/list` 返回什么就是什么(注册有前置条件³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| claude-code | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| codex / trae-cli | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| cursor | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| trae / trae-cn | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| zcode | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| kimicode | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| opencode | MCP 透传(宿主加 `openviking_` 前缀) | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| dsh | MCP 透传 | 20 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² |+| pi | MCP 镜像(官方客户端;扩展加 `openviking_` 前缀) | 20,即 `tools/list` 返回什么就是什么(注册有前置条件³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² || openclaw | 原生注册(15 个 `memory_*`/`ov_*` 等) | 15(默认开 14⁴) | ✅ `memory_recall` | ✅ `ov_search`(默认双 scope) | ✅ `ov_search` | ✅ `memory_store` | 默认关⁴ | ✅ `add_skill` | memory-only 白名单 + 单候选 score≥0.85 才自动删 || hermes | 原生注册(6 个 `viking_*`) | 6(provider 激活即全开) | ✅ | ✅ | ✅ | ✅ `viking_remember`(独立会话提交,异步抽取) | ✅ 多协议摄取(HTTP/Git/SSH/本地文件/目录 zip) | ❌ | memory-only + `.md` 叶子校验 || ov CLI | CLI 命令 | ~40 命令组 | ✅ `ov find` | ✅ `ov find` | ✅ `ov find` | ✅ `ov add-memory` | ✅ `ov add-resource` | ✅ `ov add-skill` | `ov rm` 直接执行(TUI 删除有确认 + root/scope 禁删) |@@ -54,10 +54,10 @@## 1.2 自动 hook 面(通过 Harness 自动实现)-| harness | 接入方式 | 自动召回 | 召回带 session_id | 再摘要(客户端)* | profile 注入 | 接管宿主压缩 | 离线补偿(pending queue) | statusline |+| harness | 接入方式 | 自动召回 | 召回带 session_id | 再摘要(客户端)* | profile 注入 | 接管宿主压缩 | 离线补偿 | statusline ||---|---|---|---|---|---|---|---|---|| claude-code | 9 hook + MCP 代理 + slash + statusline + skill | ✅ | ✅ | ✅ 本地 `claude -p` / 服务端 rewrite(默认 auto) | ✅(10000)+ `<available-skills>`(1200) | ❌(PreCompact 只 commit) | ✅ | ✅ |-| codex / trae-cli | 6 hook + MCP 代理 + skill | ✅ | ✅ | ✅ 本地 `codex exec`(默认开) | ✅(10000)+ `<available-skills>`(1200) | ❌ | ✅ | ❌ |+| codex / trae-cli | 6 hook + MCP 代理 + skill | ✅ | ✅ | ✅ 本地 `codex exec`(默认开) | ✅(10000)+ `<available-skills>`(1200) | ❌ | ✅ transcript + 游标 | ❌ || cursor | 6 hook + MCP 代理 + rule + skill | ✅ | ✅ | ❌ | ✅(10000)+ `<available-skills>`(1200) | ❌ | ✅ | ❌ || trae / trae-cn | 4 hook + MCP 代理 | ✅ | ✅ | ❌ | ✅(10000)+ `<available-skills>`(1200) | ❌ | ✅ | ❌ || zcode | 4 hook + MCP 代理 | ✅ | ✅ | ❌ | ✅(10000)+ `<available-skills>`(1200) | ❌ | ✅ | ❌ |@@ -92,7 +92,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章## 2.1 服务端 MCP 工具面-这些工具定义在服务端,后续更新也会在服务端统一发布,Harness 只需通过插件代理 MCP 拿到最新的 `~/.openviking/ovcli.conf` 即可。+工具定义来自服务端的 `tools/list`。插件代理读取本地 `~/.openviking/ovcli.conf` 中的连接配置,再连接服务端发现工具;服务端增加工具后,客户端需重新连接或刷新工具列表。本页的工具数量对应当前仓库实现,实际以所连服务端返回的列表为准。| # | 工具名 | 功能 | 参数要点(定义行号) ||---|---|---|---|@@ -110,13 +110,17 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章| 12 | `cancel_watch` | 按 `to_uri` 取消,商业版尚未支持 | 刻意不暴露 pause/resume/trigger/update(`:1653`) || 13 | `grep` | 正则内容检索 | 多 pattern 并发(信号量 10),`node_limit=10`(`:1696`) || 14 | `glob` | 文件名 glob | `node_limit=100`(`:1765`) |-| 15 | `forget` | 删除 URI(不可恢复) | 默认 `recursive=False`;类型边界详见 [§3.5](#_3-5-写入与删除的类型边界)(`:1791`) |+| 15 | `forget` | 永久删除 URI(不可恢复) | 默认 `recursive=False`;类型边界详见 [§3.5](#_3-5-写入与删除的类型边界)(`:1791`) || 16 | `health` | 健康检查 | 无参(`:1808`) |+| 17 | `list_users` | 列出账户内用户 ID;凭据需显式请求并具有 ADMIN/ROOT 权限,trusted 模式禁用 | `query`、`limit`、`page`、`include_credentials`(`mcp_endpoint.py:356`) |+| 18 | `list_groups` | 列出账户内组 ID,不返回成员 | 无用户参数(`mcp_endpoint.py:394`) |+| 19 | `get_acl` | 读取资源 ACL;需 manage 权限或账户 ADMIN | `uri`(`mcp_endpoint.py:408`) |+| 20 | `set_acl` | 设置资源 ACL;需 manage 权限或账户 ADMIN | `uri`、`acl`(`mcp_endpoint.py:418`) |配套机制:- **可移植 schema 重写**(`:1149-1218`):模块导入时把所有工具的 `anyOf`/`$ref` 折成扁平类型,以兼容 Gemini 等 OpenAPI 3.0 子集客户端;运行时校验仍用原始 Python 签名(例如 `read` 广播的 schema 是 array,但仍接受裸字符串)。所有 MCP 客户端拿到的 schema 都由服务端统一产出,客户端无差异。-- **身份中间件**(`:149-233`):与 REST 共用 `resolve_identity`,依次读 `x-api-key` / `authorization` / `x-openviking-account` / `x-openviking-user` / `x-openviking-actor-peer`;account/user 缺省回落 `"default"`。+- **身份中间件**(`:149-233`):与 REST 共用 `resolve_identity`,按认证模式解析凭据和身份:API key 模式从 key 确定账户与用户,trusted 模式接受可信网关传入的账户/用户头,dev 模式接受账户/用户头,缺省字段使用 `default`。actor peer 另行解析,不能覆盖认证身份。见[认证指南](../guides/04-authentication.md)。## 2.2 memory-plugin-shared 共享层@@ -147,8 +151,8 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章| `workspace-config.mjs` | 分层 workspace 配置:读 `<root>/.openviking/config.json` 与 `config.local.json`,带来源(provenance)合并各层,剥离连接与凭据类 key | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi || `workspace-registry.mjs` | 每机注册表 `~/.openviking/workspaces/<slot>.json`——一个 workspace 一个文件,由人工创建、插件只读,优先级高于任何已提交的文件 | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi || `uri-guard.mjs` | 文件工具的路径参数是 `viking://` URI 时拒绝调用;shell 命令带 `viking://` URI 时照常执行,并给模型附加提示;grep 的 `pattern` 是搜索文本,不当作路径;目标是 skill URI(`isSkillUri()`)时,write 与 edit 的提示改为 `add_skill`,不再指向 `write` / `edit` | 拒绝:各 harness 的 PreToolUse/tool.execute.before 类 hook;提示:PreToolUse,或执行后的 hook(dsh `tools/post-execute`、pi `tool_result`、opencode `tool.execute.after`) |-| `config-schema.mjs` | 全部旋钮的唯一声明:规范名、类型、默认值、取值范围、`OPENVIKING_*` 变量、可接受的旧拼写、workspace 键。doctor 的已知键集合与 workspace 文件的点分键映射都是它的投影 | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi |-| `plugin-config.mjs` | 按层解析全部已声明旋钮:env → workspace 各层 → ovcli.conf `plugin.<harness>` → ovcli.conf `plugin` → ov.conf 的 harness 段 → 默认值 | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi |+| `config-schema.mjs` | 全部配置项的唯一声明:规范名、类型、默认值、取值范围、`OPENVIKING_*` 变量、可接受的旧拼写、workspace 键。doctor 的已知键集合与 workspace 文件的点分键映射都是它的投影 | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi |+| `plugin-config.mjs` | 按层解析全部已声明配置项:env → workspace 各层 → ovcli.conf `plugin.<harness>` → ovcli.conf `plugin` → ov.conf 的 harness 段 → 默认值 | cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi || `setup-wizard.mjs` | 交互式写 ovcli.conf | cc / codex / opencode / pi 暴露入口 || `retryable.mjs` | 可重试判定:status 0/408/429/≥500,或 409 且 `error.details.retryable===true`;4xx(含 401/403)不重试 | 全部 JS 系 |@@ -159,7 +163,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章- **服务端自动 commit 默认关闭,除非显式策略或部署级默认策略将其启用**:- `memory.session_auto_commit.enabled = false`(`memory_config.py`);无存储 policy 的会话自动 commit 关闭(`session_service.py`);idle 扫描器在 `enabled=false` 时根本不创建(`core.py`),构成双重门控。- `POST /messages` 的 auto_create 不接受 policy 参数,但配置后会继承 `server.user_config_defaults.auto_commit_policy`;`POST /sessions`(create)与 `PATCH /sessions/{id}/config` 仍是显式的 Session 级控制面。- - 当前没有插件下发 `auto_commit_policy`;第一方客户端中会下发该字段的是 **ov CLI**(`ov session new --auto-commit-policy-json` / `--no-auto-commit`、`ov session config set`)。+ - 当前记忆插件不主动下发 `auto_commit_policy`。可通过 Python SDK 的 `create_session` / `update_session_config`、HTTP API 或 **ov CLI** 设置(`ov session new --auto-commit-policy-json` / `--no-auto-commit`、`ov session config set`)。- policy 显式启用时,服务端默认阈值是 `pending_token_threshold=150000(严格大于)/ message_count_threshold=100 / idle_timeout_seconds=86400 / keep_recent_count=0 / min_commit_interval_seconds=0`。注意这组服务端默认值与各插件客户端的 20000/10 是相互独立的两层配置。- **由此**:插件可通过 `server.user_config_defaults.auto_commit_policy` 继承新 Session 的 token/message 阈值;idle timeout 兜底还需开启 `memory.session_auto_commit.enabled=true`。未配置该 fallback 时,客户端仍需自行安排 commit 路径([§3.3](#_3-3-会话与-commit-生命周期))。- **tool output 外置**:服务端 `tool_output_externalization.enabled=True`、`threshold_chars=20000`(`server/config.py:257-258`)——客户端普遍把 `captureToolMaxChars` 设到 1000000 仅作兜底,真正的截断/外置在服务端做,externalized 结果通过 `tool_output_ref` 引用(openclaw 有三个专门工具读它)。@@ -222,7 +226,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章6. 统一请求头:`Authorization: Bearer` + `X-OpenViking-Account/User`(仅 trusted 模式)+ `X-OpenViking-Actor-Peer` + `User-Agent: openviking-memory-<harness>/<version>`。`api_key` 模式的服务端从 key 里取身份、忽略这两个头,所以那里不发,免得把身份报给链路上的每一层代理。模式解析顺序:`OPENVIKING_AUTH_MODE`(任何模式下都读)→ `ovcli` `plugin.<harness>.authMode` → `plugin.authMode` → `ov.conf` `<harness>.authMode` → `ov.conf` `server.auth_mode` → 只要解析出了 account 或 user 就算 trusted。7. **hook 与 MCP 共用一份连接**:以上规则都由 `credentials.mjs` 的 `resolveConnection()` 实现。hook 的 loader(`buildPluginConfig()`)和每个 MCP proxy(经各自 harness 的 loader,agent-plugins 经 `buildProxyConnection()`)都调用它,而且它不读当前目录,所以从插件目录启动的 proxy 与 hook 解析结果相同。跨进程边界只有两种做法:Codex 只把 `.mcp.json` `env_vars` 列出的变量交给 MCP 进程,这份名单必须包含 `MCP_PROXY_ENV_VARS`;dsh 直接转发解析好的连接,每个凭据变量都显式写出(空值也写),并带上 `OPENVIKING_CREDENTIAL_SOURCE=env`,所以文件和子进程继承到的变量都改变不了它。`mcp-hook-parity.test.mjs` 断言两边发出的 URL、key 和身份一致。-**workspace peer**(家族 A 各 harness 均适用;agent-plugins 包既不派生 workspace peer,也不转发任何 peer——它没有能把 `recallPeerScope` 设成 `actor` 的旋钮层,代理始终不发这个头):无显式 peerId 且 `OPENVIKING_WORKSPACE_PEER≠0` 时由 workspace 派生,随 `X-OpenViking-Actor-Peer` 发送(服务端会对该头校验,含 `/` 或 `\` 返回 400)。派生规则由 `peer.source` 决定,**默认 `git`**:先取归一化后的 `origin` URL,取不到回落到仓库根路径;不在仓库中则什么都不发送,在那里记下的内容进入用户级空间 `viking://user/<you>/memories`。例如在 `/Users/x/Dev/OpenViking/examples/codex-memory-plugin` 下、origin 为 `[email protected]:volcengine/OpenViking.git` 时,peer 是 `github.com-volcengine-openviking`——任意子目录、任意 worktree、任意机器、任意 clone 都是同一个值。`peer.source` 的读取层为 env `OPENVIKING_PEER_SOURCE`、ovcli.conf `plugin.peerSource` / `plugin.<harness>.peerSource`、workspace 文件的 `peer.source`;家族 A 的每个 harness 都会读这几层。+**workspace peer**(家族 A 各 harness 均适用;agent-plugins 包既不派生 workspace peer,也不转发任何 peer——它没有能把 `recallPeerScope` 设成 `actor` 的配置项层,代理始终不发这个头):无显式 peerId 且 `OPENVIKING_WORKSPACE_PEER≠0` 时由 workspace 派生,随 `X-OpenViking-Actor-Peer` 发送(服务端会对该头校验,含 `/` 或 `\` 返回 400)。派生规则由 `peer.source` 决定,**默认 `git`**:先取归一化后的 `origin` URL,取不到回落到仓库根路径;不在仓库中则什么都不发送,在那里记下的内容进入用户级空间 `viking://user/<you>/memories`。例如在 `/Users/x/Dev/OpenViking/examples/codex-memory-plugin` 下、origin 为 `[email protected]:volcengine/OpenViking.git` 时,peer 是 `github.com-volcengine-openviking`——任意子目录、任意 worktree、任意机器、任意 clone 都是同一个值。`peer.source` 的读取层为 env `OPENVIKING_PEER_SOURCE`、ovcli.conf `plugin.peerSource` / `plugin.<harness>.peerSource`、workspace 文件的 `peer.source`;家族 A 的每个 harness 都会读这几层。| `peer.source` | 展开为 | 得到的 peer ||---|---|---|@@ -251,17 +255,17 @@ openclaw 的 peer 由 `peer_role`/`peer_prefix` 推导(`peer_role=sender` 时| 配置层 | 生效范围 | 备注 ||---|---|---|-| env `OPENVIKING_*` | 各家族见上;行为旋钮见各档案卡 | 唯一横跨所有 JS 系的层 |+| env `OPENVIKING_*` | 各家族见上;行为配置项见各档案卡 | 唯一横跨所有 JS 系的层 || workspace 层:每机注册表 `~/.openviking/workspaces/<slot>.json` > `<repo-root>/.openviking/config.local.json`(私有,gitignore)> `<repo-root>/.openviking/config.json`(提交进仓库、团队共享) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | schema v1,必须写 `version: 1`,声明其他版本的文件会被跳过并告警。可用 key:`peer.source`、`peer.id`、`recall.{enabled,peer_scope,dedup_turns,max_items,score_threshold}`、`capture.{enabled,commit_token_threshold}`、`bypass.session_patterns`、`labels`。列表类跨层取并集,首元素写 `"!reset"` 可清空继承来的内容;不认识的 key 原样保留但不生效。hook 是非交互的,这些文件因此无提示直接信任,换来的是结构性的拒绝:连接与凭据类 key(`url`、`api_key`、`account`、`user`、`extra_headers` 等)一律剥离并告警,这些文件里的 `${VAR}` 永不展开。注册表目前没有写入方:条目由人工创建,`ov-memory-doctor` 会打印该放到哪个 slot 路径。提交进仓库的文件关掉了什么,由 `ov-memory-doctor` 播报而不是拦截 |-| ovcli.conf `plugin` 段(共享标量,可被 `plugin.<harness>` 对象覆盖) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | 每个 harness 键两种写法都认——`claude_code` 或 `claude-code`、`trae_cn` 或 `trae-cn`。注意:`ov config add/edit` 会以 Rust Config 结构重写整个文件,从而丢弃其不识别的 `plugin` 段;而 `ov config switch` 为字节复制,不受影响 |-| ov.conf harness 段(`<harness>.*`,legacy) | 每个 harness 读与自己同名的那段 | 凭据字段(`apiKey`/`accountId`/`userId`/`peerId`)与调优旋钮都按调用方 harness 取自己的段。两种写法指向同一段 |+| ovcli.conf `plugin` 段(共享标量,可被 `plugin.<harness>` 对象覆盖) | claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi | 每个 harness 键两种写法都认——`claude_code` 或 `claude-code`、`trae_cn` 或 `trae-cn`。`ov config` 编辑和重命名会保留 `plugin` 等额外顶层字段;切换时以新配置显式提供的字段为准,缺省的额外字段沿用 active 文件 |+| ov.conf harness 段(`<harness>.*`,legacy) | 每个 harness 读与自己同名的那段 | 凭据字段(`apiKey`/`accountId`/`userId`/`peerId`)与调优配置项都按调用方 harness 取自己的段。两种写法指向同一段 || harness 自有配置文件 | dsh cordis patch(会被 `plugin` 段压过)、openclaw `openclaw.json`、hermes `config.yaml`+`.env` | |-**配置项生效范围速查**(这些旋钮只在列出的 harness 上生效):+**配置项生效范围速查**(这些配置项只在列出的 harness 上生效):- `OPENVIKING_COMMIT_TURN_THRESHOLD`:仅 cursor(trae×2/zcode 每 Stop 必 commit,不走该阈值)。- `OPENVIKING_WRITE_PATH_ASYNC`:claude-code / codex / zcode。-- 召回再摘要相关(`OPENVIKING_RECALL_COMPRESS` / `OPENVIKING_RECALL_REWRITE` 及配套项):claude-code / codex(服务端 `rewrite` 参数本身对所有调用方可用,[§3.2.5](#_3-2-5-召回再摘要))。+- 召回再摘要:`OPENVIKING_RECALL_COMPRESS` 的 `server` 模式适用于各记忆集成,本地 `client` 模式仅 Claude Code / Codex 支持。默认值和模式见 [§3.2.5](#_3-2-5-召回再摘要)。- `OPENVIKING_RECALL_DEDUP_TURNS`、`OPENVIKING_RECALL_QUERY_EXPANSION`、`OPENVIKING_PEER_SOURCE`、`OPENVIKING_SKILL_CATALOG`、`OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`、workspace 配置文件与 ovcli.conf `plugin` 段:经共享加载器解析配置的每个 harness——claude-code / codex / cursor / trae / trae-cn / zcode / opencode / dsh / pi;openclaw 与 hermes 各有自己的配置体系。## 3.2 自动召回与注入@@ -272,7 +276,7 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处1. **context face**:调用 `POST /api/v1/search/search`,参数设定为 `mode:"context"` 且 `purpose:"coding"`。其核心设计原则为"只声明意图,机制交服务端":对于 `quotas`/`max_tokens`/`query_expansion`/`rewrite_max_bullets` 等参数,仅在用户显式配置时(带有 configured 哨兵字段)才会发送,否则直接采用服务端的默认设定。2. **legacy `/recall`**:若 context face 请求返回 400/422 错误,且响应报文包含 `extra`/`mode`/`unexpected` 等特征字段,则判定对接了旧版服务端。此时会在本地写入 6 小时的负缓存(路径为 `~/.openviking/state/context-face.json`,该文件全机共享,一旦被任一 harness 标记,同机所有 JS 系 harness 均会跳过 context face 阶段)。随后降级调用已弃用的 `/api/v1/search/recall` 接口;若 `peer_scope` 被拒,则去掉该参数重试一次。-3. **raw find 兜底**:并发请求 `viking://~/memories` 与 `viking://~/skills`,调用两次 `POST /search/find`(注意:resources 被刻意排除在自动召回之外,资源类文档由模型主动调用 `search` 获取)。客户端收到结果后进行本地重排(权重规则为:leaf +0.12 / 时间意图 +0.10 / 偏好意图 +0.08 / 词面重叠 ≤0.2)、去重,最后按客户端 token 预算装填。`recallTokenBudget`、`recallMaxContentChars` 与 `recallPreferAbstract` 三个旋钮只在这一级生效;而在 context face 下,注入预算由服务端 `max_tokens`(默认 1600)决定。+3. **raw find 兜底**:并发请求 `viking://~/memories` 与 `viking://~/skills`,调用两次 `POST /search/find`(注意:resources 被刻意排除在自动召回之外,资源类文档由模型主动调用 `search` 获取)。客户端收到结果后进行本地重排(权重规则为:leaf +0.12 / 时间意图 +0.10 / 偏好意图 +0.08 / 词面重叠 ≤0.2)、去重,最后按客户端 token 预算装填。`recallTokenBudget`、`recallMaxContentChars` 与 `recallPreferAbstract` 三个配置项只在这一级生效;而在 context face 下,注入预算由服务端 `max_tokens`(默认 1600)决定。服务端在处理 session_id 时,分为两条截然不同的执行路径:@@ -283,6 +287,8 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处### 3.2.2 判定矩阵+下表描述默认召回路径。显式开启服务端压缩后,请求路径按 §3.2.5 调整。+| harness | 触发点 | query 构造 | session_id | 服务端路径 | 注入格式 / 位置 | 再摘要(客户端)* ||---|---|---|---|---|---|---|| claude-code | 每轮 `UserPromptSubmit` | prompt 原文 trim | ✅ `cc-` | A(context face) | `<openviking-context>` → `hookSpecificOutput.additionalContext` | ✅ 本地/服务端(默认 auto,[§3.2.5](#_3-2-5-召回再摘要)) |@@ -296,7 +302,7 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处| openclaw | context-engine transformContext assemble(设有 7 道 passthrough 门) | 最后一条 user 消息纯 text,清洗后截 4000 字符 | ❌(`/find` 无该字段) | `/find` | 以 `<relevant-memories>` + `Source: openviking-auto-recall` 格式前置进最后一条 user 消息 | ❌ || hermes | 每轮 API 调用前同步执行 `prefetch` | 原始用户输入,双层剥 skill 脚手架;<5 字符跳过 | 部分携带(仅 `search/search` 首选路径,落 B;降级 `/find` 时不带) | B / find | `<memory-context>` fenced 块追加到当轮 user 消息(只进 API 请求体,不写回持久化) | ❌ |-\* 同 [§1.2](#_1-2-自动-hook-面-通过-harness-自动实现):此列的"再摘要"特指客户端本地压缩,而服务端 digest 对所有调用方均可用([§3.2.5](#_3-2-5-召回再摘要))。ov CLI 无自动召回,不在本表。+\* 本表的再摘要列描述本地压缩能力。各集成都可显式开启服务端压缩;开启后会使用 context-search rewrite,见 [§3.2.5](#_3-2-5-召回再摘要)。`ov` CLI 不提供自动召回。### 3.2.3 profile / 开场注入@@ -326,18 +332,30 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处### 3.2.4 超时与预算链- 家族 A 客户端推导:带 rewrite → `max(timeoutMs, 45000)`;带 expansion → `max(timeoutMs, 15000)`;对应服务端熔断 5s(expansion)/30s(rewrite)——设计上让客户端预算覆盖服务端各阶段,防止客户端提前 abort 丢掉整个响应。-- 实际值:cc 15s(hook 预算 60s);codex 召回整 hook 120s 硬截止 + 压缩子进程 110s;cursor/trae×2/zcode 15s(宿主 hook 预算 20s);opencode 30s;dsh 15s(阻塞 pre-step);pi 15s;openclaw 整个召回流程外层 5s 硬超时(500ms health precheck;默认 `recallPreferAbstract=false` 时每条 leaf 记忆多一次 read,预算内最多 1 find + 6 read + 1 health);hermes 总预算 4s / 单请求 3s(可配)。+- 实际值:cc 15s(hook 预算 60s);codex 召回整 hook 120s 硬截止 + 压缩子进程 110s;cursor/trae×2/zcode 15s(宿主 hook 预算 20s);opencode 30s;dsh HTTP 默认 10s,context expansion 请求至少 15s(阻塞 pre-step);pi 15s;openclaw 整个召回流程外层 5s 硬超时(500ms health precheck;默认 `recallPreferAbstract=false` 时每条 leaf 记忆多一次 read,预算内最多 1 find + 6 read + 1 health);hermes 总预算 4s / 单请求 3s(可配)。- 注入体预算:服务端 `max_tokens` 默认 1600(家族 A 默认不发、由服务端决定);openclaw / hermes 用字符预算 4000(两家都是"装不下整条跳过"而非截断)。### 3.2.5 召回再摘要**服务端实现(对所有调用方可用)**:context 检索面(涵盖 REST 的 `mode="context"` 与 legacy 的 `/recall`)支持传入 `rewrite` 参数——可选值为 `false | true | "auto"`,默认为 `false`;并配套提供 `rewrite_max_bullets`(默认 6,1-20)。开启后,服务端会用 `query_planner` 模型(`rewrite=true` 时未配置则回落主 `vlm`;`"auto"` 仅在显式配置了 `query_planner` 时生效)把召回结果改写成带引用的 digest:`OpenViking memory digest:` 头 + `- ` bullets,每条 ≤500 字符且必须引用一条本次命中的 `viking://` URI(无引用或引用越界的 bullet 被丢弃);判定无相关记忆时输出哨兵并清空注入块(该轮不记入去重台账)。模型调用受 `retrieval.recall_rewrite_timeout_s=30s` 熔断,超时回落未改写的 rendered 块(`rewrite.py:78-141`、`pipeline.py:122-130`、`search.py:195-196`)。-**客户端侧现状**:+**客户端配置**:自动召回统一使用 `OPENVIKING_RECALL_COMPRESS`,共享配置文件中对应 `recallCompress`(`recallRewrite` 为兼容别名)。++| 模式 | 行为 |+| --- | --- |+| `off` | 不请求再摘要。 |+| `server` | 发送 `rewrite: true`,优先使用服务端 digest。 |+| `client` | 仅 Claude Code 和 Codex 支持,使用本地压缩器。 |+| `auto` | Claude Code 和 Codex 优先使用可用的本地压缩器,否则发送 `rewrite: "auto"`;没有本地压缩器的集成直接请求服务端自动判断。 |++Claude Code 和 Codex 默认 `auto`,其他集成默认 `off`。Claude Code、Codex、OpenCode、DSH、Pi、Cursor、TRAE、TRAE CN、ZCode、OpenClaw 和 Hermes 均可显式启用服务端压缩;旧布尔值 `1` / `0` 分别对应 `auto` / `off`。`stats.rewrite="no_relevant"` 表示本轮不注入,不能再回退到原始块。-- **claude-code**:`recallRewrite` 四态 `off|client|server|auto`,默认 **auto**——先探测本地压缩器是否可用(`claude --version` 探测,缓存 7 天),若可用则在本地起 `claude -p --model sonnet --effort low --strict-mcp-config` 子进程压缩(30s 超时,输入 <1500 字不压缩,digest 单条缓存;子进程环境强制降级防递归;失败回落未压缩块;URI 编辑距离吸附回真实 URI,修不回的整条丢弃)。若本地不可用,则下发 `rewrite:"auto"` 交服务端。这是唯一接入服务端 rewrite 的 harness。-- **codex**:布尔 `recallCompress` 默认 **true**,完全依赖本地压缩(不使用服务端 rewrite):模型 profile 从 `~/.codex/models_cache.json` 读,候选 `gpt-5.3-codex-spark` → `gpt-5.6-luna`,缓存 7 天;命令 `codex --sandbox read-only --ask-for-approval never exec --ephemeral --ignore-user-config --skip-git-repo-check --output-last-message <tmp> -`,超时 110s;运行期失败后同一会话内跳过压缩、下次 SessionStart 自愈重测;输出规范化截 4000 字符;压缩关闭或失败时用确定性 `fallbackDigest` 兜底。-- **其余 harness**:均不发送 `rewrite`、无本地压缩,而是直接注入服务端返回的原始召回块。直连 API 的第三方可自行传 `rewrite` 获得服务端 digest。+本地压缩器细节:++- **claude-code**:用 `claude --version` 探测本地压缩器(结果缓存 7 天)。可用时执行 `claude -p --model sonnet --effort low --strict-mcp-config`,子进程默认超时 110s(`recallTimeoutMs - 10s`;宿主 60s prompt-hook 预算可提前结束它);输入少于 1500 字符时跳过(`recallCompressMinInputChars`);按 digest 缓存;引用的 URI 按编辑距离修正为本次命中的有效 URI,无法修复的 bullet 会被丢弃。子进程失败时回退到本地格式化的召回条目;没有条目时使用 rendered 块。+- **codex**:从 `~/.codex/models_cache.json` 选模型(先 `gpt-5.3-codex-spark`,其次 `gpt-5.6-luna` + low,缓存 7 天),执行 `codex --sandbox read-only --ask-for-approval never exec --ephemeral --ignore-user-config --skip-git-repo-check --output-last-message <tmp> -`,默认超时为 `recallTimeoutMs - 10s`(110s)。运行失败后本会话不再做本地压缩,下次 `SessionStart` 重新探测。输出经规范化并截断到 4000 字符;本地压缩失败时使用本地格式化的召回条目,没有条目时使用 rendered 块;关闭压缩时直接使用服务端 digest 或 rendered 块。++这些设置只控制自动召回,显式 MCP 调用使用调用方传入的参数。服务端需支持 context-search rewrite;旧服务回退行为、压缩器探测和宿主时间预算见 [共享插件说明](https://github.com/volcengine/OpenViking/blob/main/examples/memory-plugin-shared/README.md#cloud-recall-compression)及各集成页。### 3.2.6 注入回流防护@@ -350,7 +368,7 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处- **写入路径**:JS 系统一通过 `batch-send.mjs` 处理(对应接口 `POST /messages/batch`,每批最多 100 条,与服务端的 `max_length=100` 限制保持一致;若遇 404/405 错误则降级为逐条发送)。增量游标由各家自行实现(cc 按 transcript turn 序号计算,codex 机制相同;cursor 采用 `sha256(index+role+content)`;zcode 基于 rollout 的 `turn_id`;opencode v1 依赖事件流 Map,v2 在 execution 结束时读取 context 并按 message id 推进游标;dsh 基于事件白名单;pi 依据 branch 条目水位;hermes 则按当前轮切片)。- **commit 是客户端触发的**(详见 [§2.3](#_2-3-服务端会话与-commit-语义)):服务端默认不自动 commit。下表所有的"阈值/触发"条件,均指客户端逻辑。- **keep_recent_count 差异**(即 commit 后给宿主留多少 live tail):服务端默认值为 0。各家传参如下:cc/codex 阈值提交传 10;cursor、trae×2、zcode 发空 body `{}`,即传 0(每次均为全量归档);opencode 传 10;dsh 传 10;pi 在非 takeover 模式传 10,takeover 模式传 3(本地含义是"保留 3 个用户轮",而服务端按消息条数解释,实际保留更少);openclaw 在 afterTurn 阈值触发时传 10,在 compact/reset/memory_store 操作时传 0;hermes 恒定传 0。-- **写路径 detach**(`async-writer.mjs`,cc/codex/zcode 的 Stop 默认开):drain stdin → spawn detached worker → approve → write payload → unref(注:spawn 失败时尚未 approve,回落同步恰好只输出一次)。detached worker 自成进程组,不受终端信号波及——这是保证 cc 在关闭链路时具有高可靠性、zcode 在按下 Ctrl+C 时不丢失写入数据的关键机制。附带效果:执行 detach 后,Stop 的 `appended N turn(s)` 提示将不再展示(设置 `OPENVIKING_WRITE_PATH_ASYNC=0` 可恢复该提示)。+- **写路径 detach**(`async-writer.mjs`,cc/codex/zcode 的 Stop 默认开):drain stdin → spawn detached worker → approve → write payload → unref(注:spawn 失败时尚未 approve,回落同步恰好只输出一次)。detached worker 自成进程组,可在终端退出后继续处理已交给它的写入。但 worker 必须已经启动,网络错误、系统终止或服务端失败仍可能导致写入未完成。附带效果:执行 detach 后,Stop 的 `appended N turn(s)` 提示将不再展示(设置 `OPENVIKING_WRITE_PATH_ASYNC=0` 可恢复该提示)。### 3.3.2 常规 commit 触发条件@@ -373,7 +391,7 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处### 3.3.3 关闭方式 × harness 终局矩阵-图例:**C** = 会 commit;**C\*** = 会 commit 但有前提(见注);**—** = 不 commit(已 POST 的消息仍留在服务端 live 区:不丢消息本体,等待后续触发归档与抽取);**n/a** = 无此形态。所有行的服务端侧行为一律为 **—**([§2.3](#_2-3-服务端会话与-commit-语义))。+图例:**C** = 对应退出事件会尝试触发 commit;**C\*** = 还需满足表中前提;**—** = 该事件不触发 commit;**n/a** = 不适用。触发不代表归档和记忆抽取完成:网络错误、宿主退出预算或进程终止都可能中断请求。已成功写入的消息仍在服务端 live 区,等待后续提交。本表假设服务端自动提交未启用;配置了自动提交策略时,还需计入[服务端行为](#_2-3-服务端会话与-commit-语义)。| harness | 正常退出 | Ctrl+C | SIGTERM | SIGHUP/关终端/关窗口·tab | kill -9/崩溃 | 补救路径 ||---|---|---|---|---|---|---|@@ -385,7 +403,7 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处| zcode | **—**(无 session-end 类事件) | **C\*** | **—** | **—** | **—** | C\* 前提:Ctrl+C 时该轮 Stop 已触发(detached worker 照常写完);每 Stop 已 commit,漏掉的轮次靠 rollout 游标在同一会话的下个 Stop 补回 || opencode | **C\***(v1 ≥1.15.11 的 `dispose` 或 v2 cleanup → `flushAll({commit:true})`) | **C\*** | **C\*** | **C\*** | **—** | C\* 前提:宿主给 cleanup 的时间有限,慢请求或多个会话串行提交可能被截断;v2 会在无活动 60 分钟、服务停止和本地插件热重载时触发 cleanup || dsh | **C**(Cordis teardown → 每 session 一次 3s 超时 commit,无阈值) | **C**(第一次;第二次 Ctrl+C 强退 → —) | **C** | **—**(无 SIGHUP 监听) | **—** | teardown commit 与阈值 commit 共享同一条串行写链,5s 进程 grace 内前方有慢请求时可能挤不进;web 形态关浏览器 tab 不触发 teardown |-| pi(takeover 默认) | **—**(`session_shutdown` 全关闭方式都触发且被 await,handler 持久化本地 takeover 状态,不 commit) | **—** | **—** | **—** | **—** | 下次续跑攒满 30000,或手动 `/viking commit` |+| pi(takeover 默认) | **—**(正常退出路径会 await `session_shutdown`,handler 持久化本地 takeover 状态,不 commit) | **—** | **—** | **—** | **—** | 下次续跑攒满 30000,或手动 `/viking commit` || pi(takeover off) | **C**(`await sync.commit()`,失败入 pending 队列) | **C** | **C** | **C** | **—** | — || openclaw | **—**(上游发 awaited `session_end(reason=shutdown\|restart)`,handler 缓存 agentId 后返回,不触发 commit;`gateway_stop` 未注册;无信号处理) | **—** | **—** | **—** | **—** | 显式 `/new` `/reset` 与 ~50% 阈值;低于阈值的会话依赖这两条路径归档 || hermes | **C\***(atexit `_run_cleanup` → flush 10s → on_session_end) | **C\***(交互与非交互最终都走 atexit) | **C\***(`_signal_handler`,grace 默认 1.5s → 干净退出 → atexit) | **C\***(SIGHUP 同 SIGTERM 路径) | **—**(atexit 不执行) | drain 不净时本次不 commit(避免提交半截数据);Hermes 退出看门狗可能中断慢 commit |@@ -403,7 +421,8 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处| harness | 机制 | 要点 ||---|---|---|-| cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi | 磁盘队列 `~/.openviking/pending`(0700/0600) | 仅可重试的失败入队(4xx 含 401/403 判为不可重试,不入队,debug 日志可见);重放在会话启动时执行:≤50 条/次、≤3 次/条、TTL 7 天;`.processing` 原子认领,10min 陈旧回收;addMessage 失败即 break 保序 |+| cc / cursor / trae×2 / zcode / opencode / dsh / pi | 磁盘队列 `~/.openviking/pending`(0700/0600) | 仅可重试的失败入队(4xx 含 401/403 判为不可重试,不入队,debug 日志可见);重放在会话启动时执行:≤50 条/次、≤3 次/条、TTL 7 天;`.processing` 原子认领,10min 陈旧回收;addMessage 失败即 break 保序 |+| codex / trae-cli | transcript + 持久化游标 | 新捕获的消息不进入 pending queue;成功发送多少条,游标才推进多少条,后续捕获或 SessionStart 扫描补发未发送的尾部。SessionStart 仍会重放已有的共享 pending 条目。 || openclaw | 无本地队列 | addSessionMessage 失败被 catch,该轮消息不重放 || hermes | 进程内上传线程;`$HERMES_HOME/openviking/pending_sessions/` 保存待提交标记 | POSIX 上启动时可提交已退出进程遗留的待提交会话;未上传消息不会从磁盘重放。 || LangChain | 进程内 `_pending_commit_sessions` 集合 | commit 失败下次 record 自动重试;不落盘。部分成功时抛 `OpenVikingPartialWriteError`(携带 `messages_written`、`input_messages_consumed`、`context_attached`,调用方可按位置切片重试后缀)——全部集成里唯一的部分成功上报协议 |@@ -490,7 +509,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可| harness | 服务端不可达时 | 负缓存 | HTTP 重试 | 失败阻塞宿主 ||---|---|---|---|---|| claude-code | 各 hook catch→approve,不阻塞;session-start 时连 pending 重放都跳过 | context-face 6h + host-cli 探测 7d + health 5s | 无(靠 pending 重放);peer_scope 降级 1 次;batch→逐条 | 否(uri-guard deny 是设计意图) |-| codex / trae-cli | 各 hook catch→noop | context-face 6h + 压缩器 runtime_failed(至下次启动) | 同上(靠 pending 重放,SessionStart 触发) | 否 |+| codex / trae-cli | 各 hook catch→noop | context-face 6h + 压缩器 runtime_failed(至下次启动) | 捕获失败靠 transcript/游标补发;SessionStart 也重放已有 pending 条目 | 否 || cursor/trae×2/zcode | fetch 吞成 status:0,catch 返回空注入;锁 5s 拿不到则静默跳过 | context-face 6h(服务端整体不可达时无负缓存,每轮等满 15s) | 无 | 否 || opencode | recall、context、after-tool、事件循环与 cleanup 失败均 catch→WARN;URI guard 的预期拒绝仍会返回给模型 | 仅 context-face 6h;`/health` 无缓存 | 无同步重试;MCP 代理 401/403、400/404 各一次 | 否(URI guard deny 是设计意图) || dsh | client 全吞异常;`ensureState` 失败不缓存(服务端不可达时每 pre-step 两次 health 各 5s) | context-face 6h + user-space 缓存进程内不过期 | 无;pending 跨进程重放 3 次 | 是(pre-step 串行 profile+recall;session/flush 阻塞) |@@ -528,10 +547,10 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## claude-code- **集成文档**:[Claude Code 记忆插件](./02-claude-code.md)-- **形态**:CC 插件(marketplace),采用四合一架构:9 hook + MCP 代理(16 工具透传)+ slash command + statusline + 4 个 skill(`openviking-memory`、`openviking-skills`、`ov-experience-memory`、`ov-memory-doctor`)。版本 0.6.1。+- **形态**:CC 插件(marketplace),采用四合一架构:9 hook + MCP 代理(20 工具透传)+ slash command + statusline + 4 个 skill(`openviking-memory`、`openviking-skills`、`ov-experience-memory`、`ov-memory-doctor`)。版本 0.6.1。- **能力亮点**:hook 覆盖最全的 harness——SessionStart(120s) / UserPromptSubmit(60s) / PostToolUse:Read(5s,默认关的 skill-experience) / PreToolUse:Read\|Glob\|Grep\|Edit\|Write\|Bash(5s,uri-guard:文件工具的路径是 `viking://` URI 时拒绝,针对 skill URI 的 Write/Edit 会被引导到 `add_skill`;Bash 命令带 `viking://` URI 时附加提示) / Stop(45s) / PreCompact(30s) / SessionEnd(30s) / SubagentStart(10s) / SubagentStop(45s);默认启用召回再摘要(本地 `claude -p`,本地不可用时自动回落服务端 rewrite,[§3.2.5](#_3-2-5-召回再摘要));支持 SubagentStart/Stop 的完整子会话隔离([§3.3.5](#_3-3-5-subagent-会话对照));statusline + slash + uri-guard;关闭链路除 kill -9 外全部 commit([§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))。- **行为要点**:session id 为 `cc-<CC session_id 原文>`,subagent 为 `…__subagent-<agent_id>`;Stop 阈值 commit 20000/keep 10,PreCompact 同步 commit;自动召回排除 resources([§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径));增量游标存于 `/tmp`(被系统清理后,同一会话会整段重推)。-- **配置**:env + ovcli.conf `plugin.claude_code` + ov.conf `claude_code`([§3.1.4](#_3-1-4-配置体系分层)),约 70 个旋钮;压缩器命令与模型固定为 `claude`/`sonnet`/`low`/30s。+- **配置**:env + ovcli.conf `plugin.claude_code` + ov.conf `claude_code`([§3.1.4](#_3-1-4-配置体系分层)),约 70 个配置项;压缩器默认使用 `claude`/`sonnet`/`low`;超时来自 `recallCompressTimeoutMs`(默认 110s),仍受宿主 hook 预算约束。- **维度索引**:工具面 [§2.1](#_2-1-服务端-mcp-工具面) |召回 [§3.2](#_3-2-自动召回与注入) |commit [§3.3.2](#_3-3-2-常规-commit-触发条件)/[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵) |压缩 [§3.4](#_3-4-压缩-compaction-接管) |降级 [§3.6](#_3-6-降级与容错) |UX [§3.7](#_3-7-附加-ux-对照)。## codex@@ -539,7 +558,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可- **集成文档**:[Codex 记忆插件](./04-codex.md)- **形态**:Codex 插件(marketplace),6 hook(SessionStart 70s / UserPromptSubmit 130s / Stop 30s / SessionEnd 3s / PreCompact 60s / PreToolUse:Bash 5s)+ MCP 代理 + 与 claude-code 相同的 4 个 skill。版本 0.10.1。- **能力亮点**:本地召回压缩管线(`codex exec`,[§3.2.5](#_3-2-5-召回再摘要));SessionEnd(Codex ≥ 0.145)在正常退出时补齐 Stop 漏掉的轮次并 commit,SessionStart 的兜底扫描回收那些没触发 SessionEnd 的退出所遗留的未归档消息([§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵));PreToolUse:Bash(uri-guard)放行带 `viking://` URI 的 shell 命令,并附加提示,建议改用 OpenViking MCP 工具;Codex 通过 `apply_patch` 编辑文件,输入里没有路径参数,因此 guard 不会拒绝任何调用。-- **行为要点**:session id 为 `cx-<safeId>`(确定性推导,不读 state);SessionEnd 只在正常退出、且 Codex 0.145+ 时触发,信号、崩溃、旧版本以及 `codex app-server` 延后的场景都落到扫描路径;不使用磁盘 pending queue(离线靠游标不推进、下一轮重发补偿,[§3.3.4](#_3-3-4-pending-queue-离线补偿对照));idle-TTL 1800000ms、锁等待 120000ms(env 配置);Stop 与 SessionEnd 默认 detach(`appended N turn(s)` 提示默认不展示);单会话 mkdir 锁串行化 Stop worker、PreCompact、SessionEnd worker 与扫描。新增的 hook 在 Codex 侧没有信任记录,升级后需在 `/hooks` 中批准这次升级新增的 hook(SessionEnd、PreToolUse)。+- **行为要点**:session id 为 `cx-<safeId>`(确定性推导,不读 state);SessionEnd 只在正常退出、且 Codex 0.145+ 时触发,信号、崩溃、旧版本以及 `codex app-server` 延后的场景都落到扫描路径;新捕获的消息不进入磁盘 pending queue(离线靠 transcript/游标补发,SessionStart 仍重放已有 pending 条目,[§3.3.4](#_3-3-4-pending-queue-离线补偿对照));idle-TTL 1800000ms、锁等待 120000ms(env 配置);Stop 与 SessionEnd 默认 detach(`appended N turn(s)` 提示默认不展示);单会话 mkdir 锁串行化 Stop worker、PreCompact、SessionEnd worker 与扫描。新增的 hook 在 Codex 侧没有信任记录,升级后需在 `/hooks` 中批准这次升级新增的 hook(SessionEnd、PreToolUse)。- **配置**:env + ovcli.conf `plugin.codex` + ov.conf `codex`;hooks 只用 `Authorization: Bearer` 认证([§3.1.3](#_3-1-3-凭据体系))。- **维度索引**:工具面 [§2.1](#_2-1-服务端-mcp-工具面) |召回 [§3.2](#_3-2-自动召回与注入) |commit [§3.3.2](#_3-3-2-常规-commit-触发条件)/[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵) |降级 [§3.6](#_3-6-降级与容错)。@@ -573,7 +592,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可- **集成文档**:[社区插件 → ZCode](./08-community-plugins.md)- **形态**:配置驱动(合并进 `~/.zcode/cli/config.json`,强制 `hooks.enabled=true`)+ MCP 代理。4 hook:SessionStart(30s) / UserPromptSubmit(20s) / PreToolUse:Read\|Glob\|Grep(5s) / Stop(30s)。自身不 vendoring 任何共享模块:安装器按 cursor / trae 同样的方式为它拼装共享运行时。版本 0.5.0。-- **能力亮点**:以 rollout 文件 `~/.zcode/cli/rollout/model-io-<sid>.jsonl` 为增量真相源(`lastTurnId` 差集补齐漏掉的 Stop);Stop 默认 detach(Ctrl+C 不丢写入)。+- **能力亮点**:以 rollout 文件 `~/.zcode/cli/rollout/model-io-<sid>.jsonl` 为增量真相源(`lastTurnId` 差集补齐漏掉的 Stop);Stop 默认 detach;已启动的 worker 可在终端收到 Ctrl+C 后继续写入,仍可能因网络错误或进程被终止而失败。- **行为要点**:每 Stop commit(keep 0);捕获路径仅剥离三类注入块(不做额外文本清洗,[§3.2.6](#_3-2-6-注入回流防护));首次捕获会一次性读取整个 rollout(长会话首装时单次推送量大)。- **配置**:env + ovcli.conf `plugin.zcode` + workspace 文件;`OPENVIKING_WRITE_PATH_ASYNC` 对 zcode 生效。- **维度索引**:工具面 [§2.1](#_2-1-服务端-mcp-工具面) |召回 [§3.2](#_3-2-自动召回与注入) |commit [§3.3.2](#_3-3-2-常规-commit-触发条件)/[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵)。@@ -598,6 +617,8 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## dsh(DeepSeek Harness)+- **集成文档**:[DSH 插件](./17-dsh.md)+- **形态**:唯一同进程 Cordis 原生插件(`export function apply`),工具面就是服务端的 MCP 面,经 `@deepseek-ai/dsh-mcp-client` 与共享 stdio 代理接入(以 `mcp__openviking__*` 发布),hook 侧 REST 直连。6 事件:agent/session-start(emit)/ agent/pre-step(waterfall)/ session/event / session/flush / tools/pre-execute / tools/post-execute。版本 0.5.1。- **能力亮点**:`ctx.provide("openvikingMemory")` 供其他 Cordis 插件二次开发;pre-step 注入走 user 消息,适配 DSH persona 的 `complete:true` 渲染模式。- **行为要点**:统一安装器已覆盖 dsh,默认装到 `web` profile,可用 `--dsh-profile` 指定其他 profile;npm 是该插件唯一的分发渠道,因此除 `dev` 外的模式一律装已发布的包;`dev` 会先把 checkout 打包再装——`dsh plugin` 转发给 pnpm,link 一个源码目录无法解析插件 import 的 dsh peer;teardown commit 3s 无阈值,SIGHUP/二次 Ctrl+C 不触发([§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵));compaction 不感知(注入内容随宿主压缩收缩,profile 不重投);subagent 各自独立会话([§3.3.5](#_3-3-5-subagent-会话对照));工具面即服务端自身的 MCP 面,经与其他集成同一个 stdio 代理接入、以 `mcp__openviking__*` 发布,服务端升级即可增加工具而无需发版;代价是代理每个 profile 只起一个进程,因此工具调用带的是进程级 actor peer、`remember` 也不绑当前会话(召回/捕获/commit 仍按会话解析 peer);另随包附带共享的 `openviking-memory`、`openviking-skills` 与 `ov-experience-memory` 三个 skill,默认捕获工具结果(`captureToolResults: true`),因此 `ov-experience-memory` 能跑完整 Experience 闭环,关闭后只检索和应用;uri-guard 先把工具名转成小写再匹配,tools/pre-execute 拒绝路径是 `viking://` URI 的文件工具(针对 skill URI 的 write/edit 会被引导到 `mcp__openviking__add_skill`),bash 命令带 `viking://` URI 时由 tools/post-execute 附加提示(`form: "notice"`)。@@ -607,9 +628,9 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## pi(pi Coding Agent Extension)- **集成文档**:[pi Coding Agent 扩展](./11-pi.md)-- **形态**:pi 原生扩展(目录装载,jiti 直译 TS)。扩展使用 `@modelcontextprotocol/client`,把服务端 `tools/list` 的每个描述符注册成名为 `openviking_<tool>` 的 pi 工具,当前 16 个([§2.1](#_2-1-服务端-mcp-工具面))。扩展里没有任何工具目录,服务端增删工具,pi 下一次会话即跟上,不需要发插件版本。召回、会话同步、profile 注入与 takeover 仍走 REST。9 事件 + `/viking` 命令;tool_call 拦截路径是 `viking://` URI 的 read/grep/find/ls/write/edit,bash 命令带 `viking://` URI 时,tool_result 在结果末尾追加提示。经 `resources_discover` 附带 3 个 skill(`openviking-memory`、`openviking-skills`、`ov-experience-memory`),`mcpEnabled` 为 `false` 时不加入。版本 0.4.1。-- **能力亮点**:takeover 压缩接管(默认开,[§3.4.2](#_3-4-2-pi-takeover));两段式召回(before_agent_start 排队 + context 事件同步检索,当前轮 prompt 拿当前轮记忆);statusline;`session_shutdown` 在所有关闭方式下都触发且被 await。-- **行为要点**:默认 takeover 下退出不 commit(handler 持久化本地状态,归档靠下次续跑攒满阈值或 `/viking commit`,[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵));takeover 阈值 30000 token + 保留 3 轮(keep 3,服务端按消息条数解释);非 takeover 阈值 20000/keep 10、退出无条件 commit;工具注册需 health、ensureSession 与 `/mcp` 握手三项前置([§1.1](#_1-1-主动工具面-agentic-调用能力)),ROOT 角色的 API key 访问 `/mcp` 会被 403 拒绝,凭据链最终落到 `ov.conf` 的 `server.root_api_key` 时本次会话就没有工具——0.4.0 之前是 REST 工具照常注册、每次调用静默返回 "No results found.";`openviking_remember` 走 MCP 面,即自建一次性会话并立即提交,不再并入 pi 的会话([§2.1](#_2-1-服务端-mcp-工具面));`openviking_add_resource` 可直接摄取远端 URL,本地路径则由服务端返回一条上传指引,需要模型用 `bash` 把文件 POST 上去,与其他 MCP harness 一致;`openviking_read` 只返回全文,目录 URI 会得到 `Cannot render …: URI points to a directory`,旧的 `level="abstract"/"overview"` 两档在 MCP 面没有对应工具,替代路径是 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`,takeover 的归档 overview 仍由扩展自己经 REST 注入;单次工具调用受共享的 `timeoutMs` 约束(15000ms,`OPENVIKING_TIMEOUT_MS` 可调),`write`/`edit` 带 `wait=true` 或 `add_resource` 同步 ingest 有可能超过,而超时或 ESC 只让本地调用失败,已经发出的请求会跑完,写入仍可能已经生效;从 0.3.x 升级时全部工具改名且没有别名期,`--tools` / `--exclude-tools` 白名单里写死的 `viking_*` 必须手工替换,否则工具会静默消失;非 takeover 模式下 `pi -c` 续跑会重新上报整条 branch。+- **形态**:pi 原生扩展(目录装载,jiti 直译 TS)。扩展使用 `@modelcontextprotocol/client`,把服务端 `tools/list` 的每个描述符注册成名为 `openviking_<tool>` 的 pi 工具,当前 20 个([§2.1](#_2-1-服务端-mcp-工具面))。扩展里没有任何工具目录,服务端增删工具,pi 下一次会话即跟上,不需要发插件版本。召回、会话同步、profile 注入与 takeover 仍走 REST。9 事件 + `/viking` 命令;tool_call 拦截路径是 `viking://` URI 的 read/grep/find/ls/write/edit,bash 命令带 `viking://` URI 时,tool_result 在结果末尾追加提示。经 `resources_discover` 附带 3 个 skill(`openviking-memory`、`openviking-skills`、`ov-experience-memory`),`mcpEnabled` 为 `false` 时不加入。版本 0.4.1。+- **能力亮点**:takeover 压缩接管(默认开,[§3.4.2](#_3-4-2-pi-takeover));两段式召回(before_agent_start 排队 + context 事件同步检索,当前轮 prompt 拿当前轮记忆);statusline;支持的正常退出路径会 await `session_shutdown`;`kill -9` 等强制终止不会执行 handler。+- **行为要点**:默认 takeover 下退出不 commit(handler 持久化本地状态,归档靠下次续跑攒满阈值或 `/viking commit`,[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵));takeover 阈值 30000 token + 保留 3 轮(keep 3,服务端按消息条数解释);非 takeover 阈值 20000/keep 10、退出无条件 commit;工具注册需 health、ensureSession 与 `/mcp` 握手三项前置([§1.1](#_1-1-主动工具面-agentic-调用能力)),ROOT 角色的 API key 访问 `/mcp` 会被 403 拒绝,凭据链最终落到 `ov.conf` 的 `server.root_api_key` 时本次会话就没有工具——0.4.0 之前是 REST 工具照常注册、每次调用静默返回 "No results found.";`openviking_remember` 走 MCP 面,即自建一次性会话并立即提交,不再并入 pi 的会话([§2.1](#_2-1-服务端-mcp-工具面));`openviking_add_resource` 可直接摄取远端 URL,本地路径则由服务端返回一条上传指引,需要模型用 `bash` 把文件 POST 上去,与其他 MCP harness 一致;`openviking_read` 读取文件正文,支持按行分页(`offset`/`limit`),目录 URI 会得到 `Cannot render …: URI points to a directory`,旧的 `level="abstract"/"overview"` 两档在 MCP 面没有对应工具,替代路径是 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`,takeover 的归档 overview 仍由扩展自己经 REST 注入;单次工具调用受共享的 `timeoutMs` 约束(15000ms,`OPENVIKING_TIMEOUT_MS` 可调),`write`/`edit` 带 `wait=true` 或 `add_resource` 同步 ingest 有可能超过,而超时或 ESC 只让本地调用失败,已经发出的请求会跑完,写入仍可能已经生效;从 0.3.x 升级时全部工具改名且没有别名期,`--tools` / `--exclude-tools` 白名单里写死的 `viking_*` 必须手工替换,否则工具会静默消失;非 takeover 模式下 `pi -c` 续跑会重新上报整条 branch。- **配置**:env + ovcli.conf `plugin.pi` + workspace 文件(凭据统一走凭据链,[§3.1.3](#_3-1-3-凭据体系));bypass 走共享 `isBypassed` 的 glob 匹配,键名 `bypassSessionPatterns`(旧名 `bypassPatterns` 仍可读);共享键 `mcpEnabled: false` 现在对 pi 也生效:不发起桥接、不注册工具,`/viking` 标注成配置而非故障。- **维度索引**:工具面 [§1.1](#_1-1-主动工具面-agentic-调用能力) |召回 [§3.2](#_3-2-自动召回与注入) |takeover [§3.4.2](#_3-4-2-pi-takeover) |commit [§3.3.2](#_3-3-2-常规-commit-触发条件)/[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵)。@@ -636,14 +657,14 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可- **集成文档**:[部署指南 → CLI](../guides/03-deployment.md#cli)- **形态**:Rust 原生二进制,把服务端 REST 包成命令行;无宿主事件、无自动召回、不接管压缩。-- **能力亮点**:唯一会下发 `auto_commit_policy` 的第一方客户端(`ov session new --auto-commit-policy-json`、`ov session config set`);提供多 profile、admin、privacy、snapshot、TUI 等插件面没有的能力(详见 [§5.3](#_5-3-cli-独有于插件面的能力))。+- **能力亮点**:提供 `auto_commit_policy` 的命令行入口(`ov session new --auto-commit-policy-json`、`ov session config set`);提供多 profile、admin、privacy、snapshot、TUI 等插件面没有的能力(详见 [§5.3](#_5-3-cli-独有于插件面的能力))。- **维度索引**:完整命令参考请见 [§5](#_5-ov-cli-命令参考)。---# 5. ov CLI 命令参考-`ov`(clap 内部名 `openviking`)是 Rust HTTP 客户端,所有能力都在服务端,CLI 只做参数拼装、本地打包上传、输出渲染与多 profile 管理。它不是 harness 集成——没有宿主事件、不自动召回、不接管压缩;本章覆盖它作为"人/脚本直接使用 OV"的完整命令面,以及它独有于插件面的能力(TUI、多 profile、admin、`--sudo`、privacy、snapshot 等)。+`ov`(clap 内部名 `openviking`)是 Rust HTTP 客户端,大多数数据操作通过服务端 REST API 完成;CLI 还负责本地打包上传、配置校验、密钥生成、输出渲染与多 profile 管理。它不是 harness 集成——没有宿主事件、不自动召回、不接管压缩;本章覆盖它作为"人/脚本直接使用 OV"的完整命令面,以及它独有于插件面的能力(TUI、多 profile、admin、`--sudo`、privacy、snapshot 等)。> 版本说明:以 HEAD 源码为准(HEAD tag 已到 `[email protected]`),0.4.10 等旧版本的差异处已标注。需要注意的是,`ov doctor` 不在 Rust 二进制里——pip 装的 Python wrapper 会拦截 `argv[1]=="doctor"` 并走 `openviking_cli.doctor`,读取的是服务端 `ov.conf` 而非 `ovcli.conf`;npm/cargo 装的纯 Rust `ov` 无该子命令。@@ -655,9 +676,9 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可**读取/检索**:`ls`(别名 list)|`tree`(`-L` 默认 3)|`stat`/`attrs get`|`read`/`abstract`/`overview`(分别对应 L2/L0/L1)|`get`(下载)|`find`(query 或 `--image` 至少一个非空;`--image` 支持本地路径、data URI、http、viking://)|`search`(实验性,比 find 多一个 `--session-id`)|`grep`|`glob`-**Skills**:`skills add`(支持本地路径、git 及 GitHub tree URL,`-s` 选装、`*` 全装,有交互确认)|`skills list/find/show/update/remove`|`skills validate`(唯一完全离线的命令)+**Skills**:`skills add`(支持本地路径、git 及 GitHub tree URL,`-s` 选装、`*` 全装,有交互确认)|`skills list/find/show/update/remove`|`skills validate`(本地校验,不请求服务端)-**会话/记忆**:`session new`(`--auto-commit-policy-json` 与 `--no-auto-commit` 互斥——唯一下发 policy 的第一方客户端)|`session list/get/delete`|`session get-session-context`(`--token-budget` 默认 128000)|`session get-session-archive`|`session add-message(s)`|`session config set`(改可变配置)|`session commit`+**会话/记忆**:`session new`(`--auto-commit-policy-json` 与 `--no-auto-commit` 互斥;SDK 和 HTTP API 也支持设置 policy)|`session list/get/delete`|`session get-session-context`(`--token-budget` 默认 128000)|`session get-session-archive`|`session add-message(s)`|`session config set`(改可变配置)|`session commit`**导入导出/快照**:`export`/`backup`/`import`/`restore`(.ovpack)|`snapshot commit/restore/show/log/diff/ignore-*`(工作区快照,前向 commit 回滚)@@ -672,14 +693,14 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## 5.2 全局选项与独有机制- `-o/--output table|json`(默认取 conf `output`)|`-c/--compact`(默认 true)|`--account`/`--user`/`--actor-peer-id`|`--sudo`(用 root_api_key,只允许 admin/system/reindex/task status/task list)|`--profile`(隐藏)-- **多 profile**:active 为 `~/.openviking/ovcli.conf`,命名规范为 `ovcli.conf.<name>`;`switch` 是字节复制(保留 `plugin` 段),而 `add/edit` 走 serde 重写(会丢弃 Rust Config 不识别的键,含 `plugin` 段,见 [§3.1.4](#_3-1-4-配置体系分层))。+- **多 profile**:active 为 `~/.openviking/ovcli.conf`,命名配置为 `ovcli.conf.<name>`。编辑和重命名保留 `plugin` 等额外顶层字段。切换时替换连接配置;新配置若显式提供 `plugin`,则采用该段,否则保留 active 文件原有的 `plugin`。- **语言门禁**:跑任何命令前要求先存显示语言(未存 + 非交互 → exit 2);HEAD 起 `--help` 在门禁前豁免(0.4.10 尚无此豁免),但 `--version` 仍需先过门禁。- **三种 JSON 输出格式(按命令组不同)**:普通命令 compact 下输出 `{"ok":true,"result":…}`,`-c false` 输出裸 payload,失败输出 `{"ok":false,"error":…}`;config 系为 `{"status":"ok","result":…}`;带 profile 时追加 `"profile":[…]`。脚本解析时需注意;此外 `echo_command` 默认 true 且不受 `-o json` 抑制(stdout 第一行是 `cmd: …`)。- **env**:`OPENVIKING_CLI_CONFIG_FILE`、`OPENVIKING_UPLOAD_MODE`(local/shared)、`OPENVIKING_ASSETS_CREDENTIALS_FILE`、`OPENVIKING_LANG`/`LC_*`/`LANG`,以及 chat 用的 `VIKINGBOT_ENDPOINT`/`VIKINGBOT_API_KEY`/`OPENVIKING_URL`。-## 5.3 CLI 独有于插件面的能力+## 5.3 CLI 提供的其他能力 {#_5-3-cli-独有于插件面的能力}-以下是插件面拿不到、只有 CLI/TUI 能做的:多 profile 切换与向导、`admin` 全套账号/用户管理、`--sudo` root 操作、`privacy` 隐私策略 CRUD + 版本、`snapshot`/`backup`/`restore`/`export`/`import` 数据搬运、`reindex` 重建索引、`system crypto init-key` 生成 root key、`ov tui` 交互浏览、依赖 VikingBot 能力的 `ov chat`/`ov compile`,以及 `ov session config set` 显式设 `auto_commit_policy`(唯一能开服务端自动 commit 的第一方入口)。+相比记忆插件,CLI/TUI 还提供以下操作入口;其中服务端能力也可通过相应的 HTTP API 或 SDK 调用:多 profile 切换与向导、`admin` 全套账号/用户管理、`--sudo` root 操作、`privacy` 隐私策略 CRUD + 版本、`snapshot`/`backup`/`restore`/`export`/`import` 数据搬运、`reindex` 重建索引、`system crypto init-key` 生成 root key、`ov tui` 交互浏览、依赖 VikingBot 能力的 `ov chat`/`ov compile`,以及 `ov session config set` 显式设 `auto_commit_policy`。SDK 和 HTTP API 也支持设置该策略。---@@ -691,13 +712,14 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可| 路径 | 投入 | agent 主动工具面 | 自动召回/捕获 hook | 会话/commit | 压缩接管 ||---|---|---|---|---|---|-| ① [通用 MCP 直连](./06-mcp-clients.md) | 分钟级(填写一段 config 即可) | ✅ 16 工具全量 | ❌ 由模型主动调用 | 仅 `remember` 建临时会话 | ❌ |-| ② HTTP API / SDK / [LangChain](./07-langchain-langgraph.md) | 小时级(需写代码) | 自选(按需调 REST) | 自己实现 | 自己实现(或用 LangChain middleware) | ❌ |-| ③ 复用 shared-core / [Agent Plugins 便携包](./15-agent-plugins.md) | 天级(需写 hook 适配) | ✅ 16 工具(经 MCP 代理) | ✅ 召回/捕获/commit/pending 全套 | ✅ | 视接入哪些事件而定 |+| ① [通用 MCP 直连](./06-mcp-clients.md) | 分钟级:配置连接地址、凭据与传输方式 | ✅ 20 工具全量 | ❌ 由模型主动调用 | 仅 `remember` 建临时会话 | ❌ |+| ② HTTP API / SDK / [LangChain](./07-langchain-langgraph.md) | 小时级:编写调用代码和生命周期处理 | 自选(按需调 REST) | 自己实现 | 自己实现(或用 LangChain middleware) | ❌ |+| ③ 复用 shared-core | 天级:适配并验证宿主生命周期事件 | ✅ 20 工具(经 MCP 代理) | ✅ 召回/捕获/commit/pending 全套 | ✅ | 视接入哪些事件而定 |+| [Agent Plugins 便携包](./15-agent-plugins.md) | 分钟级:安装 MCP 与 skill 配置 | ✅ 服务端 MCP 工具 | ❌ 依赖模型按 skill 调工具 | 仅 `remember` 建临时会话 | ❌ |## 6.2 路径①:通用 MCP 直连(推荐起步)-任何支持 MCP 的 agent,只需在其 `mcpServers` 配置里指向服务端 `/mcp`(各客户端的具体配置位置见 [MCP 客户端](./06-mcp-clients.md)),即可立刻获得全部 16 个工具([§2.1](#_2-1-服务端-mcp-工具面))。最小配置如下:+支持 Streamable HTTP 的 MCP 客户端可以连接服务端 `/mcp`。下面展示使用 `mcpServers`、`url` 和 `headers` 字段的客户端配置;其他客户端的字段和格式见 [MCP 客户端](./06-mcp-clients.md)。连接后可发现服务端提供的工具([§2.1](#_2-1-服务端-mcp-工具面))。```json{@@ -705,17 +727,14 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可"openviking": {"url": "http://127.0.0.1:1933/mcp","headers": {- "Authorization": "Bearer <api_key>",- "X-OpenViking-Account": "<account>",- "X-OpenViking-User": "<user>",- "X-OpenViking-Actor-Peer": "<workspace-peer>"+ "Authorization": "Bearer <api_key>"}}}}```-后三个 header 可选,缺省时没有 workspace peer 隔离与租户路由。stdio-only 的客户端可用便携代理(路径③)把 stdio 桥到 streamable-HTTP。该路径得到的是纯工具面——无自动召回、无捕获、无 commit(除非模型主动调 `remember`)。+示例使用用户或管理员 API key,账户和用户身份由服务端根据 key 确定。`X-OpenViking-Account` 与 `X-OpenViking-User` 用于可信身份模式,不能用来覆盖普通 key 的身份。需要 workspace peer 上下文时可另加 `X-OpenViking-Actor-Peer`,具体可见范围见[认证指南](../guides/04-authentication.md)。仅支持 stdio 的客户端可用 [Agent Plugins 便携代理](./15-agent-plugins.md)桥接 Streamable HTTP。直接接入 MCP 不含自动召回、捕获或会话提交;模型调用 `remember` 时会创建并提交一次性会话。## 6.3 路径②:程序化接入@@ -724,12 +743,12 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可- **Open WebUI**(OpenAPI 工具服务器):`python -m openviking_openwebui` 起独立进程,在 Open WebUI 里添加 Tool Server URL,即可得 7 个工具(无删除、无 hook)。参考 [§7](#_7-附录-非-coding-集成速览) A。## 6.4 路径③:要自动 hook 面时复用参考实现-如果希望实现召回、捕获、commit、pending 的全套自动化,完全不必从零开始编写。建议直接参考并复用以下两个现成的实现:+如果希望实现召回、捕获、commit、pending 的全套自动化,完全不必从零开始编写。可按宿主能力选择以下实现;便携包只提供 MCP 和 skill,不包含自动 hook:-- **`examples/memory-plugin-shared/lib/`**(Node):包含完整的核心功能模块,例如 `recall-core`(三级降级召回)、`profile-inject`、`capture-utils`(消息归一 + 注入回流防护)、`pending-queue`(离线重放)、`batch-send`、`mcp-proxy-core`(stdio↔HTTP 代理)、`session-model`(会话 id 派生)以及 `credentials`。构建瘦 harness 时,只需实现一个适配层,把宿主生命周期事件映射到这些模块即可(例如 `agent-hook-runtime.mjs` 就是 cursor、trae、zcode 共用的现成一体化运行时,接新宿主时的主要工作只是解析其 stdin JSON 字段名)。+- **`examples/memory-plugin-shared/lib/`**(Node):包含完整的核心功能模块,例如 `recall-core`(三级降级召回)、`profile-inject`、`capture-utils`(消息归一 + 注入回流防护)、`pending-queue`(离线重放)、`batch-send`、`mcp-proxy-core`(stdio↔HTTP 代理)、`session-model`(会话 id 派生)以及 `credentials`。构建新集成时,需要把宿主生命周期事件映射到这些模块,并验证消息顺序、重试、超时和退出行为(例如 `agent-hook-runtime.mjs` 就是 cursor、trae、zcode 共用的现成一体化运行时,可参考其 stdin 事件解析方式)。- **Agent Plugins 1.0 便携包**(位于 `agent-plugins/`):采用 `plugin.json` + `skills/` + `mcp.json`(stdio→HTTP 代理)的规范化便携格式。该方案刻意不含 hooks(召回/沉淀靠 skill 教模型自调工具),非常适合符合 Agent Plugins 规范的客户端直接加载;此外,`plugin.test.mjs` 定义了规范一致性校验(schema URL、name 规则、静态 headers 不含机密、`mcp.json` 引用不逃逸插件根等),可作为自行打包的 lint 依据。-**接入时务必对齐的三个约定**(与现有 harness 保持一致的行为):① 召回调用点必须转发 `session_id`,这样才有服务端 expansion + 跨轮去重(详见 [§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径));② 适配器不要用自己的超时压过 helper 下发的 deadline;③ 关闭时要安排一条 commit 路径,否则未达阈值的尾部对话需等待后续触发才能归档(详见 [§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))——若宿主没有关闭事件,需开启 `memory.session_auto_commit.enabled`,并提供 Session 级或部署级默认 policy。这三条正是 `recall-session-wiring.test.mjs` 用跨插件正则钉死的。+**接入时务必对齐的三个约定**(与现有 harness 保持一致的行为):① 召回调用点必须转发 `session_id`,这样才有服务端 expansion + 跨轮去重(详见 [§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径));② 适配器不要用自己的超时压过 helper 下发的 deadline;③ 关闭时要安排一条 commit 路径,否则未达阈值的尾部对话需等待后续触发才能归档(详见 [§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))——若宿主没有关闭事件,需开启 `memory.session_auto_commit.enabled`,并提供 Session 级或部署级默认 policy。`recall-session-wiring.test.mjs` 检查 session ID 和超时传递等接线;退出事件是否触发、写入是否完成,还需在目标宿主中验证。---@@ -739,8 +758,8 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可|---|---|---|---|---|---|| **A. [Open WebUI](./08-community-plugins.md)** | 独立的 FastAPI OpenAPI 工具服务器 | 7 个本地 OpenAPI 路由(`ov_search`/`ov_recall_memories`/`ov_add_memory`/`ov_list_memories`/`ov_read_resource`/`ov_add_resource`/`ov_session_status`),无删除工具 | 无会话概念 | 最薄:裸 httpx,无 retry/负缓存;`/health` 仅回显配置,不探测 OV | 进程不启动即不存在 || **B. [LangChain/LangGraph](./07-langchain-langgraph.md)** | Python SDK 适配层(retriever/tools/store/middleware/recorder) | `create_openviking_tools()` 提供 12 个 StructuredTool(`viking_forget` 默认不在 agent profile 中) | `thread_id`/`session_id` 由调用方给;`CommitPolicy` 默认 `never` | 本组最稳:只读方法自动重试 1 次、写方法不重试(防重复)、部分成功抛结构化异常可切片重试 | 需全部显式构造才生效 |-| **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | 便携包 `plugin.json` + `skills/` + `mcp.json`(stdio→HTTP 代理) | MCP 透传 16 工具;刻意无 hooks(召回靠 skill 教模型) | 仅 `remember` 建临时会话 | MCP 代理层重试(401/403 换凭据、400/404 重初始化各 1 次) | 客户端加载后工具即用 |-| **D. [通用 MCP 直连](./06-mcp-clients.md)** | 零本地组件,直连 `/mcp` | 同 C(16 工具) | 同 C | 由客户端自定 | `/mcp` 常驻 |+| **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | 便携包 `plugin.json` + `skills/` + `mcp.json`(stdio→HTTP 代理) | MCP 透传 20 工具;刻意无 hooks(召回靠 skill 教模型) | 仅 `remember` 建临时会话 | MCP 代理层重试(401/403 换凭据、400/404 重初始化各 1 次) | 客户端加载后工具即用 |+| **D. [通用 MCP 直连](./06-mcp-clients.md)** | 零本地组件,直连 `/mcp` | 同 C(20 工具) | 同 C | 由客户端自定 | `/mcp` 常驻 || **E. [log ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI(跑在日志所在机器,反向导入) | 无(只写不召回) | 会话 id `{prefix}__{harness}__{sanitized native id}`;commit token 6000/idle 5s/keep 0 | 崩溃恢复:SQLite 游标库 + 单实例锁 + reconcile 判定批次落地 | 双重默认关(`ingest.enabled` + 每 harness `enabled` 都 false);支持 claude_code/codex/hermes/opencode/openclaw/cursor 适配器 || **F. [OpenViking Helper](./14-openviking-helper.md)** | 闭源桌面 App | — | — | — | 不在本文代码基线内 |diff --git a/docs/zh/agent-integrations/17-dsh.md b/docs/zh/agent-integrations/17-dsh.mdindex 3c8fa0b09..9f29f1d66 100644--- a/docs/zh/agent-integrations/17-dsh.md+++ b/docs/zh/agent-integrations/17-dsh.md@@ -15,7 +15,7 @@ curl -fsSL https://openviking.ai/install | bash安装器会把插件装到 `web` profile。要装到其他 profile,用 `--dsh-profile <name>` 指定:`curl -fsSL https://openviking.ai/install | bash -s -- --dsh-profile <name>`。-用一段时间后,开一个新会话问问之前提过的事情——它会记得。+安装后按下方“验证”步骤检查工具接入和跨会话召回。<details><summary><b>手动安装</b></summary>@@ -56,7 +56,7 @@ curl -fsSL https://openviking.ai/install | bash每个 DSH 会话映射为 OpenViking 中的 `dsh-<session-id>`,子 agent 各自拥有独立会话。-模型看到的工具面就是 OpenViking 的 MCP 工具集,经由与其他记忆集成相同的 stdio 代理接入,以 `mcp__openviking__` 前缀发布。由于该代理每个 profile 只起一个进程,`mcp__openviking__remember` 写入的是服务端一个短生命周期的会话而不是当前会话(对话本身仍由自动捕获记录),工具调用带的也是启动时解析的 actor peer。若一个进程要服务多个工作区且需要精确归属工具调用,请显式设置 `OPENVIKING_PEER_ID`。插件同时附带三个共享技能:`openviking-memory` 让模型知道何时该检索、读取和写入,`openviking-skills` 讲如何查找、使用、创建、共享和迁移存放在 OpenViking 里的技能,`ov-experience-memory` 让模型在执行类任务前检索并应用以往任务的 Experience。插件默认捕获工具结果(`captureToolResults: true`),服务端据此把该技能的读取关联回所用的 Experience;设为 `false` 时,它只检索和应用 Experience。+模型看到的工具面就是 OpenViking 的 MCP 工具集,经由与其他记忆集成相同的 stdio 代理接入,以 `mcp__openviking__` 前缀发布。由于该代理每个 profile 只起一个进程,`mcp__openviking__remember` 写入的是服务端一个短生命周期的会话而不是当前会话(对话本身仍由自动捕获记录)。设置 `OPENVIKING_RECALL_PEER_SCOPE=actor` 后,固定的 `OPENVIKING_PEER_ID` 才会把该 profile 的工具调用归属到同一个 peer;默认 `all` 不发送 actor-peer 头。多个工作区需要不同工具身份时,使用独立 profile/进程。插件同时附带三个共享技能:`openviking-memory` 让模型知道何时该检索、读取和写入,`openviking-skills` 讲如何查找、使用、创建、共享和迁移存放在 OpenViking 里的技能,`ov-experience-memory` 让模型在执行类任务前检索并应用以往任务的 Experience。插件默认捕获工具结果(`captureToolResults: true`),服务端据此把该技能的读取关联回所用的 Experience;设为 `false` 时,它只检索和应用 Experience。文件工具误把 `viking://` URI 当本地路径时,调用会被拦截,并提示改用对应的 OpenViking 工具;写入或编辑的若是 `viking://~/skills/<name>/` 这类技能目录,提示的工具是 `mcp__openviking__add_skill`,它用完整的 `SKILL.md` 文本创建或替换整个技能。shell 命令带 `viking://` URI 时照常执行,模型会收到一条改用 OpenViking 工具的提示,URI 是有意传入的数据时可以忽略。@@ -88,13 +88,13 @@ curl -fsSL https://openviking.ai/install | bashcommitTokenThreshold: 20000```-同一个 `config` 块里的 `syncTurns: false` 让该集成变成只读:画像注入和记忆召回照常,但什么都不再写回——不捕获对话、不 commit,也不重放此前会话排入队列的写入,那些写入会一直留在队列里,直到某个仍在写入的会话把它们排空。+同一个 `config` 块里的 `syncTurns: false` 关闭自动捕获、commit 和待写队列重放,画像注入和召回照常。排队的写入保留到后续开启写入的会话处理;该开关不会撤销模型的 MCP 写工具或改变服务端权限。同一个 `config` 块里的 `peerSource` 决定工作区 peer 的派生方式。默认的 `"git"` 取仓库归一化后的 `origin` URL(`[email protected]:volcengine/OpenViking.git` 得到 `github.com-volcengine-openviking`),其次是仓库根路径,因此同一个仓库的每个 clone、worktree 和子目录共用同一个 peer;不在仓库中则完全不发送 peer,在那里记下的内容进入用户级空间 `viking://user/<you>/memories`。`"cwd"` 恢复此前的行为——把工作目录路径中的非字母数字字符全部替换成 `-`;`"none"` 则完全不发送 peer。要让仓库之外的目录拥有独立记忆,请为它设置 `OPENVIKING_PEER_ID`(见[让一个目录拥有独立记忆](../configuration/02-client.md#让一个目录拥有独立记忆))。同一个 `config` 块里的 `skillCatalog` 和 `skillCatalogTokenBudget` 控制会话开始时注入的技能清单。清单先列你自己的技能,再列账号内共享在 `viking://agent/skills` 下的技能,每条描述截到约 40 token;它有独立的预算(默认 `1200` token,不占用画像预算),描述放不下时只列名称。`skillCatalog: false` 或把预算设为 `0` 即可关闭;对应的环境变量是 `OPENVIKING_SKILL_CATALOG` 和 `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`。-patch 中写的凭证优先于环境变量。行为旋钮按优先级从高到低解析:`OPENVIKING_*` 环境变量、工作区的 `.openviking/config.json` 与 `config.local.json`、`ovcli.conf` 的 `plugin.dsh`、`ovcli.conf` 的 `plugin`,最后才是这个 patch 块。完整参数列表见[插件 README](https://github.com/volcengine/OpenViking/tree/main/examples/dsh-memory-plugin)。+patch 中写的凭证优先于环境变量。行为配置按优先级从高到低解析:`OPENVIKING_*` 环境变量、工作区的 `.openviking/config.json` 与 `config.local.json`、`ovcli.conf` 的 `plugin.dsh`、`ovcli.conf` 的 `plugin`,最后才是这个 patch 块。完整参数列表见[插件 README](https://github.com/volcengine/OpenViking/tree/main/examples/dsh-memory-plugin)。</details>@@ -104,11 +104,11 @@ patch 中写的凭证优先于环境变量。行为旋钮按优先级从高到|------|----------|| 没有注入,也没有 OpenViking 工具 | `dsh --profile web --dump-config` 里应能看到 `openviking-memory-runtime`;重新运行安装器或 `dsh plugin --profile web add …` || 装到了错误的 profile | 安装器默认 `web`;用 `--dsh-profile <name>` 重新运行 |-| 安装时报 `ERESOLVE` | `@deepseek-ai/dsh-*` 各包预发布 tag 不同步;请精确安装 `@deepseek-ai/[email protected]` |-| 安装时报包「不在 npm registry 中」 | pnpm 默认拒绝发布不满 24 小时的版本(`minimumReleaseAge`)。等一等,或把该精确版本加进 profile 的 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` |-| 召不回任何内容 | `curl http://localhost:1933/health`;检查端点配置,以及 prompt 是否长于最小查询长度(3 个字符) |+| 安装时报 `ERESOLVE` | 使用受支持的 `@deepseek-ai/dsh` 版本:`0.1.0-rc.6`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.7-rc.2` 或稳定版 `0.1.x`(peer 范围 `>=0.1.0-rc.6 <0.2.0 \|\| ^0.1.5-rc.1 \|\| ^0.1.7-rc.2`),并让所有 `@deepseek-ai/dsh-*` 宿主包保持同一版本。 |+| 安装时报包「不在 npm registry 中」 | 检查该 profile 的 pnpm 是否设置了 24 小时的最小发布年龄(`minimumReleaseAge`)。等一等,或把该精确版本加进 profile 的 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` |+| 召不回任何内容 | `curl "<OpenViking 服务地址>/health"`;检查端点配置,以及 prompt 是否长于最小查询长度(3 个字符) || OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;可信模式部署还要检查 `OPENVIKING_ACCOUNT` 与 `OPENVIKING_USER` |-| 串入了其他项目的记忆 | 设置 `OPENVIKING_RECALL_PEER_SCOPE=actor` |+| 串入了其他项目的记忆 | 设置 `OPENVIKING_RECALL_PEER_SCOPE=actor`,将 peer 记忆限定为当前 peer;用户级记忆仍会共享 || 崩溃后没有 commit | commit 由 token 阈值和 teardown 触发;排队的写入会在下次会话开始时重放 |## 延伸阅读diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex cd465b954..f60d81072 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -1,45 +1,44 @@# MCP 集成指南-OpenViking 服务器内置 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 端点,任何兼容 MCP 的客户端都可以通过 HTTP 直接访问其记忆和资源能力,无需部署额外进程。+OpenViking Server 内置 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 端点。支持 Streamable HTTP 的客户端可直接连接;只支持 stdio 的客户端可使用 [Agent Plugins 包](../agent-integrations/15-agent-plugins.md)提供的代理。> **快速接入?** 见 [MCP 客户端](../agent-integrations/06-mcp-clients.md) 获取各平台配置片段和注意事项。本页面覆盖完整的工具参考和高级配置。## 前提条件-1. 已安装 OpenViking(`pip install openviking` 或从源码安装)-2. 有效的配置文件(参见[配置指南](01-configuration.md))-3. `openviking-server` 正在运行(参见[部署指南](03-deployment.md))+准备可访问的 OpenViking 服务地址和对应凭证。需要自行部署时,先完成[快速开始](../getting-started/02-quickstart.md);使用托管服务或已有部署时,无需在本地安装服务端。MCP 端点位于 `http://<server>:1933/mcp`,与 REST API 同进程、同端口。-## 已验证的接入平台+## 客户端接入-以下平台已成功接入并使用 OpenViking MCP:+下表列出已有接入配置。连接后,用当前客户端版本确认能发现工具,并读取一项有权限的数据:| 平台 | 接入方式 ||------|----------|| **Claude Code** | `type: http` 接入 || **Trae** | 标准 MCP 配置 || **Cursor** | 标准 MCP 配置 |-| **ChatGPT & Codex** | 标准 MCP 配置 |+| **ChatGPT** | 通过自定义 App 接入 OAuth,见 [OAuth 指南](11-oauth.md) |+| **Codex** | 使用 [Codex 集成](../agent-integrations/04-codex.md)中的 MCP 配置 || **OpenCode** | OpenCode 原生 `mcp` 配置 || **Manus** | 标准 MCP 配置 || **Claude.ai / Claude Desktop** | 原生 OAuth 2.1(见 [11-oauth](11-oauth.md)) |## 鉴权方式-MCP 端点的鉴权与 OpenViking REST API 完全一致,复用同一套 API-Key 认证系统。传入以下任一 header 即可:+MCP 使用服务端认证配置。API Key 模式下,用 User/Admin key 传入以下任一 header:- `X-Api-Key: <your-key>`- `Authorization: Bearer <your-key>`-本地开发模式(服务器绑定 localhost)下无需认证。+只有 `dev` 模式无需认证,监听 localhost 本身不会关闭认证。OAuth 客户端使用下文授权流程,其他模式见[认证指南](04-authentication.md)。## 客户端配置### 通用 MCP 客户端-大多数支持 MCP 的平台(如 Trae、Manus、Cursor 等)使用标准的 `mcpServers` 配置格式:+支持 `mcpServers` 配置且允许自定义请求头的客户端,可参考以下示例。字段名和传输类型以客户端文档为准:```json{@@ -104,30 +103,30 @@ claude mcp add --transport http openviking \### Claude.ai / Claude Desktop(OAuth)-这些客户端只接受 OAuth 2.1,不接受 API Key。OpenViking 已经原生实现 OAuth 2.1(DCR + PKCE + opaque token,SQLite 后端,配合 Studio consent 授权页),不再需要外部代理。+通过 Claude.ai / Claude Desktop 的远程连接器界面接入时,使用下文 OAuth 流程。OpenViking 已经原生实现 OAuth 2.1(DCR + PKCE + opaque token,SQLite 后端,配合 Studio consent 授权页),不再需要外部代理。-如果你已经为 OpenViking 服务配好了 HTTPS,直接连接 `https://your-server.com/mcp` 端点即可——客户端会自动引导完成 OAuth 授权流程。+按 OAuth 指南在服务端启用 `oauth.enabled` 并配置 HTTPS,再让客户端连接 `https://your-server.com/mcp`,在浏览器中完成授权。**详见 [OAuth 2.1 接入指南](11-oauth.md)** 和 **[公网访问指南](12-public-access.md)**:-- 端到端流程(device-flow 风格:authorize 页显示 6 字符码,用户在 console 确认)+- Studio 授权确认流程,以及可选的 6 字符码跨设备授权- HTTP(本地)与 HTTPS(生产)两阶段部署,包含 Caddy / nginx 反代模板和 docker-compose 示例- Claude.ai / Claude Desktop 接入步骤- `OPENVIKING_PUBLIC_BASE_URL` 与 `oauth` 配置项- Token 模型(`ovat_` / `ovrt_` / `ovac_` 前缀)与撤销-> 社区项目 [MCP-Key2OAuth](https://github.com/t0saki/MCP-Key2OAuth) Cloudflare Worker 代理仍可作为第三方备选方案,但现在更推荐原生流程:无需额外部署单元,也不会引入第三方对 API Key 的信任面。+> 社区项目 [MCP-Key2OAuth](https://github.com/t0saki/MCP-Key2OAuth) Cloudflare Worker 代理是独立的第三方项目。上面的原生流程无需额外部署单元,也不会把 API Key 交给第三方;选择代理时,应单独核对其配置和凭证处理方式。## 可用的 MCP 工具-连接后,OpenViking MCP 端点暴露 20 个工具:+以下列出内置 MCP 工具。实际可用工具以所连接服务的 `tools/list` 响应为准:| 工具 | 说明 | 主要参数 ||------|------|----------|| `find` | 无 session 上下文的快速语义检索。只传 `context_type="skill"` 时改走包级 skill 检索:每个 skill 包只返回一条命中,URI 指向该包的 `SKILL.md`,摘要取自 skill 本身,即使命中的是包内辅助文件也是如此;不传 `target_uri` 时同时检索自己的 skill 和账户共享的 `viking://agent/skills`。`skill` 与其它 context_type 混用时仍走通用检索路径 | `query`, `target_uri`(可选), `limit`, `min_score`, `level`(可选), `context_type`(可选), `read_content`(可选——直接内联每条命中的内容), `events_time_decay_protection`(可选) || `search` | 深度语义检索;`mode="context"` 组装可直接注入的上下文,并替代原 `recall` 工具。`list` 模式下每个 skill 包也只出一条命中,URI 指向 `SKILL.md`、摘要取自包本身,但 `limit` 在合并之前生效,所以一个包在多个文件上命中时会占掉多个名额,返回条数少于 `limit` | `query`, `mode`(`list` 或 `context`), `target_uri`(仅 list 模式), `session_id`(可选), `limit`, `min_score`, `level`(list 模式), `context_type`(可选), `events_time_decay_protection`(两种模式均可选),以及 context 模式的 `quotas`, `purpose`, `max_tokens`, `detail` 或 `detail_by_category`, `dedup_turns`, `exclude_uris`, `peer_scope`, 标量 `other_peer_penalty` 或按类别设置的 `other_peer_penalties`, `rewrite`(`off` 或 `auto`) |-| `read` | 读取一个或多个 `viking://` URI 的内容。PNG、JPEG、GIF、WebP 返回 MCP 原生图片内容;WAV、MP3、FLAC、OGG、M4A 返回原生音频内容。MCP 没有标准视频内容块,因此暂不支持视频 | `uris`(单个字符串或数组) |+| `read` | 读取一个或多个 `viking://` URI 的内容。PNG、JPEG、GIF、WebP 返回 MCP 原生图片内容;WAV、MP3、FLAC、OGG、M4A 返回原生音频内容。MCP 没有标准视频内容块,因此暂不支持视频 | `uris`(单个字符串或数组), `offset`, `limit`(文本行数) || `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) || `tree` | 以缩进形式展示 `viking://` URI 下的递归目录树——当需要全面了解文件树结构时使用(单层列表用 `list`,按文件名查找用 `glob`) | `uri`(可选), `level_limit`(默认 3), `node_limit`(默认 1000), `include_abstract`(可选——同时展示每个目录的摘要;skill 目录的摘要就是它的名字和描述) || `remember` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |@@ -139,7 +138,7 @@ claude mcp add --transport http openviking \| `cancel_watch` | 按目标 URI 取消(删除)watch 任务。若需调整刷新周期或临时暂停,请取消后使用新的 `watch_interval` 重新添加 | `to_uri`(必须匹配 watch 任务的 `to` 值,例如 `viking://resources/...`) || `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive`, `node_limit` || `glob` | 按 glob 模式匹配文件 | `pattern`, `uri`(可选范围), `node_limit` |-| `forget` | 删除任意 `viking://` URI(先用 `search` 查找;删除目录需 `recursive=true`)。用它删 skill 目录会残留该 skill 的 privacy 配置,请改用 `ov skills remove` 或 `DELETE /api/v1/skills/{name}` | `uri`, `recursive`(可选) |+| `forget` | 删除任意 `viking://` URI(先用 `search` 查找;删除目录需 `recursive=true`)。用它删 skill 目录会残留该 skill 的 privacy 配置,请改用 `ov skills remove` 或 `DELETE /api/v1/skills/{name}` | `uri`, `recursive`(可选) || `health` | 检查 OpenViking 服务健康状态 | 无 || `list_users` | 查询当前 account 的用户 ID;默认不返回凭证,管理员也一样 | `query`(可选,ID 子串), `limit`(默认 100), `page`(默认 1), `include_credentials`(默认 false,仅 ADMIN/ROOT 可设为 true) || `list_groups` | 查询当前 account 的组 ID,不返回成员名单 | 无 |@@ -204,7 +203,7 @@ claude mcp add --transport http openviking \在 `api_key` 鉴权模式下,token 保留发起 MCP 调用时的角色,API Key 和 OAuth 调用均适用。上传时会检查用户是否仍存在、是否正在删除,以及角色是否已降级;不满足条件时拒绝上传。角色后来被提升也不会扩大旧 token 的权限。trusted 模式的 token 仍按 USER 身份处理。-这样设计是为了让任何 MCP 客户端(包括无本地文件系统的 Claude web、Manus 等沙箱环境)都能往 OpenViking 灌文件,而不需要客户端预装 `ov` CLI。token 上传复用认证版的 `temp_upload` 路由(API Key 优先,否则走一次性 `?token=`)及其 `TempUploadStore` 持久化,所以 `local` / `shared` 上传模式行为一致。注意:一次性 token 保存在进程内,因此多 worker 部署下 `add_resource` 调用与后续的上传 POST 必须落到同一个 worker(或以单 worker 运行),token 才能被解析。+客户端只要能读取源文件并发出 multipart HTTP 请求,就能上传,无需预装 `ov` CLI。沙箱也需要提供这两项能力,仅传入无法读取的本地路径不能完成文件传输。token 上传复用认证版的 `temp_upload` 路由(API Key 优先,否则走一次性 `?token=`)及其 `TempUploadStore` 持久化,所以 `local` / `shared` 上传模式行为一致。注意:一次性 token 保存在进程内,因此多 worker 部署下 `add_resource` 调用与后续的上传 POST 必须落到同一个 worker(或以单 worker 运行),token 才能被解析。#### 必须配置 `OPENVIKING_PUBLIC_BASE_URL` 的场景@@ -248,12 +247,14 @@ curl http://localhost:1933/health### 认证错误-**可能原因:** 客户端配置与服务器配置中的 API 密钥不匹配。+**可能原因:** 客户端的 API Key 无效、已过期,或不适用于租户数据访问。-**解决方案:** 确保 MCP 客户端配置中的 API 密钥与 OpenViking 服务器配置中的一致。参见[认证指南](04-authentication.md)。+**解决方案:** 确认客户端使用目标 account 的有效 user/admin key;`api_key` 模式下,root key 只用于管理接口。参见[认证指南](04-authentication.md)。## 参考- [MCP 规范](https://modelcontextprotocol.io/)- [OpenViking 配置](01-configuration.md)- [OpenViking 部署](03-deployment.md)++客户端配置参考:[Claude Code MCP](https://code.claude.com/docs/en/mcp)、[OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/)。