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: tighten setup, CLI and client configuration guidance (#5504)
Zayn Jarvisa0f3437740c2
diff --git a/docs/en/about/02-changelog.md b/docs/en/about/02-changelog.mdindex 964296cfd..f0b24a610 100644--- a/docs/en/about/02-changelog.md+++ b/docs/en/about/02-changelog.md@@ -3,6 +3,8 @@All notable changes to OpenViking will be documented in this file.This changelog is automatically generated from [GitHub Releases](https://github.com/volcengine/OpenViking/releases).+> Release entries describe behavior at that version, including commands and defaults that may since have changed. Use the current [deployment guide](../guides/03-deployment.md) for installation. Before any historical upgrade step that clears a workspace, stop writes and make a restorable backup; never apply those cleanup instructions to an unrelated upgrade.+## Unreleased- **Watch API migration (breaking change)**: Re-importing with `watch_interval > 0`@@ -19,7 +21,7 @@ This changelog is automatically generated from [GitHub Releases](https://github.extraction correctly. Existing boolean-like values remain temporarily compatible andemit deprecation warnings; use JSON booleans for new configurations.- **Workspace peer derivation**: The coding-agent plugins now derive a workspace's peer from git instead of from the working directory. The new default, `peer.source: "git"`, uses the repository's normalized `origin` URL (`github.com-volcengine-openviking`), falling back to the repository root path, so every clone, worktree, and subdirectory of one repository shares a single peer while a fork keeps its own. A directory that is not a git repository now gets no peer at all, and what is remembered there goes to the user-level space instead of a fresh namespace per folder. Give such a directory a memory of its own by creating `.openviking/config.json` with `{"version": 1, "peer": {"id": "my-project"}}`. No migration is required: the previous cwd-derived id can always be recomputed locally, and the default `peer_scope: "all"` recall already sweeps every peer, so memories written under it keep coming back (with `peer_scope: "actor"`, the Claude Code, Codex, OpenCode, and DSH plugins query that id as well). Set `peer.source: "cwd"` — or `OPENVIKING_PEER_SOURCE=cwd` — to keep the old behavior.-- **Pi extension tool surface (breaking change)**: The pi extension 0.4.0 replaces its seven hand-written `viking_*` REST tools with the server's own MCP tools through the official MCP client, so the tool list now follows whatever the server's `tools/list` returns instead of a catalogue shipped with the extension. Every tool is `openviking_` plus the server's name (`viking_search` → `openviking_search`), with no alias period, and pi matches `--tools` and `--exclude-tools` entries by exact name, so an allowlist that still says `viking_search` loses that tool silently and has to be renamed by hand. The tools now behave as they do on every other MCP harness: `remember` commits a session of its own rather than appending to the live pi session, `read` returns full text only (the `level="abstract"` and `level="overview"` tiers are gone — `openviking_search(mode="context", detail="overview")` is the substitute), `forget` deletes the URI it is handed, and `add_resource` answers a local path with a one-time upload URL to POST the file to. A root api key is refused on `/mcp` with 403 and now leaves the session with no tools at all, where before the tools registered and every call came back empty; create a user or admin key for it. The shared `mcpEnabled: false` switch now takes effect for pi as well, and tools turned off that way are not reported as a failure. Recall, session capture, and context takeover keep working in all of these cases, and no other harness is affected. The extension README's [Upgrading from 0.3.x](https://github.com/volcengine/OpenViking/blob/main/examples/pi-coding-agent-extension/README.md#upgrading-from-03x) has the full list.+- **Pi extension tool surface (breaking change)**: The pi extension 0.4.0 replaces its seven hand-written `viking_*` REST tools with the server's own MCP tools through the official MCP client, so the tool list now follows whatever the server's `tools/list` returns instead of a catalogue shipped with the extension. Every tool is `openviking_` plus the server's name (`viking_search` → `openviking_search`), with no alias period, and pi matches `--tools` and `--exclude-tools` entries by exact name, so an allowlist that still says `viking_search` loses that tool silently and has to be renamed by hand. The tools now behave as they do on every other MCP harness: `remember` commits a session of its own rather than appending to the live pi session, `read` returns text with line-based pagination (the `level="abstract"` and `level="overview"` tiers are gone — `openviking_search(mode="context", detail="overview")` is the substitute), `forget` deletes the URI it is handed, and `add_resource` answers a local path with a one-time upload URL to POST the file to. A root api key is refused on `/mcp` with 403 and now leaves the session with no tools at all, where before the tools registered and every call came back empty; create a user or admin key for it. The shared `mcpEnabled: false` switch now takes effect for pi as well, and tools turned off that way are not reported as a failure. Recall, session capture, and context takeover keep working in all of these cases, and no other harness is affected. The extension README's [Upgrading from 0.3.x](https://github.com/volcengine/OpenViking/blob/main/examples/pi-coding-agent-extension/README.md#upgrading-from-03x) has the full list.- **External peer identity migration**: Mixed-script log-ingestion identities now uselossless `ext-<base64>` ids. The `ext-` namespace is reserved, so ASCII identities thatwould otherwise enter it are encoded as well. Older lossy peer directories are not readdiff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.mdindex 09454356d..bd673ea03 100644--- a/docs/en/configuration/01-server.md+++ b/docs/en/configuration/01-server.md@@ -19,6 +19,8 @@ The server reads the file at startup. Restart the server after changing models,## Configuration Structure+This outline shows common top-level groups, not a runnable configuration. For a first deployment, start with the [minimal example](#minimal-example) and supply your models and credentials. Merge later snippets into the same `ov.conf`.+```json{"embedding": {},@@ -46,7 +48,7 @@ Optional sections use their defaults when omitted. Unknown fields in `ov.conf` a| `default_user` | string | `"default"` | Default user for the service context || `embedding` | object | built-in local dense model | Dense, sparse, and hybrid embedding; defaults to `local` / `bge-small-zh-v1.5-f16` || `vlm` | object | empty config | Content understanding, summaries, and memory extraction; configure a working model before using these capabilities |-| `query_planner` | object / `null` | `null` | Retrieval intent model; falls back to `vlm` |+| `query_planner` | object / `null` | `null` | Model for retrieval intent analysis and recall rewriting. Falls back to `vlm` when omitted or empty; recall rewrite in `auto` mode requires a configured cluster `query_planner` or an account-level `query_planner` or `vlm` override || `rerank` | object | disabled | Retrieval result reranking || `retrieval` | object | see below | Ranking and intent-analysis behavior || `grep` | object | built-in defaults | Text search engine |@@ -357,7 +359,7 @@ See [Encryption](../guides/08-encryption.md) for provider and key-management set| Field | Type / values | Default | Purpose ||---|---|---|---|-| `custom_templates_dir` | path | `""` | Additional memory template directory |+| `custom_templates_dir` | path | `""` | Custom memory template directory; a matching `memory_type` overrides the loaded template || `experimental_memory_switch` | boolean | `false` | Enable experimental templates || `eager_prefetch` | boolean | `true` | Search and read memories before extraction || `prefetch_search_topn` | integer, `>= 1` | `5` | Results read during prefetch |@@ -365,6 +367,8 @@ See [Encryption](../guides/08-encryption.md) for provider and key-management set| `session_skill_extraction_enabled` | boolean | `false` | Also extract reusable skills || `link_enabled` | boolean | `false` | Generate and resolve memory links |+Automatic commits require a separate policy; enabling memory extraction does not make sessions commit automatically. See `memory.session_auto_commit` in [Configuration](../guides/01-configuration.md) and the [Sessions API](../api/05-sessions.md). For template loading order and when changes take effect, see the [Prompt Guide](../guides/10-prompt-guide.md).+## Parser SettingsParsers live under `parsers`:diff --git a/docs/en/configuration/02-client.md b/docs/en/configuration/02-client.mdindex bc82e074e..e123f9332 100644--- a/docs/en/configuration/02-client.md+++ b/docs/en/configuration/02-client.md@@ -2,9 +2,9 @@`ovcli.conf` is the client configuration file for the `ov` CLI. It stores the server connection, authentication identity, and command defaults.-Agent plugins for Codex, Claude Code, OpenCode, and other clients also read their own `OPENVIKING_*` environment variables for Recall, Capture, diagnostics, and other behavior. Those variables are not part of `ovcli.conf`; configure them in the corresponding [Agent Integration](../agent-integrations/01-overview.md) documentation.+Agent plugins using the shared configuration loader also read the `plugin` section, workspace settings, and `OPENVIKING_*` environment variables for recall, conversation capture, and diagnostics. This page distinguishes CLI settings from plugin settings. See [Agent Integrations](../agent-integrations/01-overview.md) for host-specific support.-Use `ov config` to create and maintain configurations. Use `ov config show` to inspect the active configuration with secrets redacted.+Use `ov config` to manage CLI connections and `ov config show` to inspect the active configuration with secrets redacted. Editing or renaming a configuration preserves extra top-level fields such as `plugin`. On a switch, fields explicitly present in the incoming profile take precedence; if it omits `plugin`, the active file’s existing plugin settings are retained.Default path:@@ -25,8 +25,6 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf"url": "https://openviking.example.com","api_key": "<user-or-admin-key>","root_api_key": "<root-key>",- "account": "acme",- "user": "alice","actor_peer_id": "agent:research-assistant","timeout": 60,"output": "table",@@ -49,7 +47,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf}```-Omit fields you do not need. A local server in `dev` mode usually needs only `url`.+This example uses API key mode. Omit fields you do not need; a local server in `dev` mode usually needs only `url`. Trusted deployments additionally configure `account`, `user`, and the required credentials as described in [Authentication](../guides/04-authentication.md). In API key mode, the server takes identity from the key and ignores these fields.## Connection and Authentication@@ -58,8 +56,6 @@ Omit fields you do not need. A local server in `dev` mode usually needs only `ur"url": "https://openviking.example.com","api_key": "<user-or-admin-key>","root_api_key": "<root-key>",- "account": "acme",- "user": "alice","actor_peer_id": "agent:research-assistant","extra_headers": {"X-Tenant": "acme"@@ -136,7 +132,7 @@ Local directory uploads also honor `.gitignore`. Command-line `--include` and `-## Plugin Settings-Behaviour knobs for the memory plugins live under `plugin`. Keys directly under it apply to every harness; a nested object named after a harness — `claude_code` or `codex` — overrides them for that one.+Settings for memory plugins live under `plugin`. Keys directly under it provide defaults for plugins using the shared loader; a nested object named after a harness, such as `claude_code`, `codex`, or `opencode`, overrides them for that one.```json{@@ -152,11 +148,11 @@ Behaviour knobs for the memory plugins live under `plugin`. Keys directly under}```-Each key is the camelCase counterpart of an `OPENVIKING_*` tuning variable — `OPENVIKING_RECALL_LIMIT` is `recallLimit`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS` is `captureAssistantTurns`. The mapping does not go both ways: a few variables are deliberately environment-only, such as the one-shot `OPENVIKING_BYPASS_SESSION`. The full list lives in the plugin READMEs: [Claude Code](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration) and [Codex](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin). List-valued knobs — `bypassSessionPatterns`, `recallQueryFilters`, `captureFilters` — are JSON arrays here, while their environment counterparts are comma-separated strings, so a value containing a literal comma can only be written in the array.+Many settings have a corresponding `OPENVIKING_*` environment variable: `OPENVIKING_RECALL_LIMIT` is `recallLimit`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS` is `captureAssistantTurns`. `OPENVIKING_BYPASS_SESSION` also has a file setting, `plugin.bypassSession`; use the environment variable for a process-specific override. The full shared list is defined in `examples/memory-plugin-shared/lib/config-schema.mjs`. For usage, see the plugin READMEs: [Claude Code](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration) and [Codex](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin). List-valued knobs — `bypassSessionPatterns`, `recallQueryFilters`, `captureFilters` — are JSON arrays here, while their environment counterparts are comma-separated strings, so a value containing a literal comma can only be written in the array.-Resolution order, highest first: environment variables → the [workspace layers](#workspace-configuration) → `plugin.<harness>` → `plugin` → the legacy per-harness block in `ov.conf` → built-in defaults. Hook processes read the file on every invocation, so an edit takes effect on the next turn; changing an `OPENVIKING_*` variable instead needs the agent restarted, since hooks inherit its environment.+Resolution order, highest first: environment variables → the [workspace layers](#workspace-configuration) → `plugin.<harness>` → `plugin` → the legacy per-harness block in `ov.conf` → built-in defaults. Separately launched hook processes reread the file on each invocation. Reload behavior for persistent plugins depends on the host; restart the agent when uncertain. Environment changes also require a restart because hooks inherit the agent’s environment.-Only the Claude Code and Codex plugins read this section today, so an entry named after any other harness is inert. `ov-memory-doctor` prints what it resolved and warns about keys it does not recognise, naming the closest real one.+Memory plugins using the shared configuration loader read this section. See the corresponding [integration guide](../agent-integrations/01-overview.md) for supported fields and defaults. `ov-memory-doctor` prints what it resolved and warns about keys it does not recognise, naming the closest real one.## Workspace Configuration@@ -168,7 +164,7 @@ A repository can carry its own plugin settings, so the memory behavior of a proj~/.openviking/workspaces/<slot>.json # per-machine registry, one file per workspace```-The workspace root is the nearest ancestor directory holding a `.git`, or one holding `.openviking/config.json` (or `config.local.json`) — whichever the walk upward reaches first; `$HOME` and the filesystem root are never workspace roots. A directory that is neither is not a workspace at all: no configuration layer, no registry entry, and no peer of its own. The registry slot name combines the root's directory name with a hash of its full path, so two clones of one repository on one machine never share an entry. These layers are read by the Claude Code and Codex plugins, not by `ov` commands.+The workspace root is the nearest ancestor directory holding a `.git`, or one holding `.openviking/config.json` (or `config.local.json`) — whichever the walk upward reaches first; `$HOME` and the filesystem root are never workspace roots. A directory that is neither is not a workspace at all: no configuration layer, no registry entry, and no peer of its own. The registry slot name combines the root's directory name with a hash of its full path, so two clones of one repository on one machine never share an entry. Memory plugins using the shared configuration loader read these layers; `ov` commands do not.### Precedence@@ -217,7 +213,7 @@ No command writes the registry file. Create it by hand at the path `ov-memory-do| `bypass.session_patterns` | list of globs | A session whose id or working directory matches skips recall and capture || `labels` | object | Free-form metadata for humans; not read by the plugins |-An out-of-range number is clamped to the nearest bound and reported; an unrecognized enum value is ignored. Keys outside this list are kept in the file and ignored.+An out-of-range number is clamped to the nearest bound and reported; an unrecognized enum value is ignored. The table lists common fields; `config-schema.mjs` defines the full shared schema. Unrecognized keys do not take effect.### Workspace Peer@@ -233,13 +229,13 @@ Create `.openviking/config.json` in the directory:{"version": 1, "peer": {"id": "my-project"}}```-That directory and everything below it now writes to the peer `my-project`, repository or not. The id names no path, so it survives a move, a rename and a second machine — and two directories carrying the same id share one memory, which is how you merge them on purpose.+Unless a higher-priority peer setting or a nested workspace overrides it, memories captured by the plugin in that directory and its subdirectories are written under the peer `my-project`, whether or not it is a Git repository. The id names no path, so it survives a move, a rename and a second machine — and two directories using the same server, account, user, and peer id share the same memory scope, which is how you merge them on purpose.The other ways to set it, highest precedence first:| Where | What it does ||---|---|-| `OPENVIKING_PEER_ID=my-project` | Pins the peer for one process, whatever the files say |+| `OPENVIKING_PEER_ID=my-project` | Sets the peer for one process; ignored when credentials are pinned to `ovcli.conf`, and an explicit host peer takes precedence || `peer.id` in `.openviking/config.json` | Names this workspace's peer. The recommended way; `config.local.json` is the same key kept out of the commit || `peer.source` in the same file | Derives the peer instead of naming it — `"cwd"` for the directory path, `"team-{dir}"` for a template || `plugin.peerSource` in `ovcli.conf`, or `OPENVIKING_PEER_SOURCE` | The same choice for every directory on this machine; `"cwd"` restores the pre-`git` behavior everywhere |@@ -271,7 +267,7 @@ In `/Users/x/Dev/OpenViking/examples/codex-memory-plugin` with `origin` `git@git| A long-lived directory that is not a repository | Create `.openviking/config.json` with a `peer.id` || One subproject of a monorepo needing its own memory | Put a `config.json` in the subdirectory with `peer.source: "{git_remote}-{dir}"`. A marker file alone keeps the repository's peer, because `{git_remote}` resolves first || A throwaway task directory (a dated folder an app creates, an unpacked archive) | Nothing. Its memories go to your user-level space |-| Each agent keeping its own memory of one repository | `peer.source: "{git_remote}-{harness}"`. Not the default — one shared project memory across agents is usually what you want, so this one is opt-in |+| Each agent keeping its own memory of one repository | `peer.source: "{git_remote}-{harness}"`. Set this explicitly; the default shares project memory across agents || Several directories sharing one memory | Write the same `peer.id` in each || Not wanting per-project separation at all | `peer.source: "none"` (the same as `OPENVIKING_WORKSPACE_PEER=0`) |@@ -281,10 +277,10 @@ In `/Users/x/Dev/OpenViking/examples/codex-memory-plugin` with `origin` `git@git| `recall.peer_scope` | What recall reads ||---|---|-| `"all"` (default) | User-level memories and this workspace's peer at full weight, plus a sweep across the user's other peers whose hits are demoted by category — the server's `other_peer_penalty` defaults to 0.1 for events and entities, 0.02 for preferences, experiences, resources and skills. Another project can therefore only ever come last |+| `"all"` (default) | User-level memories and this workspace's peer at full weight, plus a sweep across the user's other peers whose hits are demoted by category — the server's `other_peer_penalty` defaults to 0.1 for events and entities, 0.02 for preferences, experiences, resources and skills. The penalty lowers other-project scores but does not guarantee that they always rank last || `"actor"` | User-level memories and this workspace's peer only. The plugin additionally asks once for the peer the pre-`git` rule would have derived here, so nothing written by an earlier release is lost |-User-level memories are read at full weight under both, and that is the cost of sending no peer outside a repository: what a throwaway task teaches is recalled in every project afterwards. For stronger separation, give such a directory a `peer.id` of its own, or switch to `"actor"`.+User-level memories are read at full weight under both, and that is the cost of sending no peer outside a repository: what a throwaway task teaches is recalled in every project afterwards. To separate future memories from such a directory, give it a `peer.id` and use `"actor"` to limit cross-peer recall. The actor scope still reads existing user-level memories; it does not reassign or hide them.Switching to the `git` default needs no migration and moves nothing: memories written under the earlier cwd-derived peer stay where they are, and recall keeps reaching them — through the cross-peer sweep under `"all"`, and through the extra query under `"actor"`. `peer_scope` is a per-request parameter; against a server too old to know it, the plugin records the downgrade once and warns rather than silently reading everything.@@ -318,7 +314,7 @@ The `ov` CLI directly uses only a small set of environment variables:The `--api-key-env <name>` and `--root-api-key-env <name>` options for `ov config add` and `ov config edit` read keys from a named environment variable and write them to the configuration.-Variables such as `OPENVIKING_AUTO_RECALL`, `OPENVIKING_RECALL_LIMIT`, `OPENVIKING_AUTO_CAPTURE`, and `OPENVIKING_DEBUG` are read by Agent plugin processes and are not `ovcli.conf` fields.+Agent plugins read environment variables such as `OPENVIKING_AUTO_RECALL`, `OPENVIKING_RECALL_LIMIT`, `OPENVIKING_AUTO_CAPTURE`, and `OPENVIKING_DEBUG`. Do not use the environment-variable names as JSON keys; supported file settings use their corresponding fields under `plugin`.## Multiple Serversdiff --git a/docs/en/getting-started/04-setup-for-agent.md b/docs/en/getting-started/04-setup-for-agent.mdindex 85357fa4a..4e5053a83 100644--- a/docs/en/getting-started/04-setup-for-agent.md+++ b/docs/en/getting-started/04-setup-for-agent.md@@ -9,8 +9,9 @@ This page is for OpenViking server setup. For client-only CLI setup, use the [Op## General Principles- Default to the normal end-user installation path; do not default to source builds-- Default to prebuilt packages; do not assume Go / Rust / C++ / CMake are required-- If configuration is uncertain, ask the user first; do not guess provider, model, api_base, api_key, or workspace+- Default to prebuilt packages; do not assume Rust / C++ / CMake are required+- Read existing configuration and supplied requirements first; ask the user about missing or uncertain values. Do not guess provider, model, api_base, api_key, or workspace+- Preserve existing configuration and unrelated fields; inspect the actual changes before updating it- Only move to the source-build path when installation clearly falls back to local compilation, or when the user explicitly asks for a source install## SOP@@ -40,9 +41,10 @@ Use this path if any of the following is true:- The user does not want to fill in many model settings manuallyExecution path:-1. Run `openviking-server init`-2. Run `openviking-server doctor`-3. Start `openviking-server`+1. Install the OpenViking Python package and make sure Ollama is running+2. Run `openviking-server init` and select local models+3. Run `openviking-server doctor`+4. Start `openviking-server`#### C. Docker installUse this path if any of the following is true:@@ -76,16 +78,15 @@ Only use this path if one of the following is true:- The user explicitly wants to modify or rebuild low-level native componentsOnly then explain the required toolchain:-- Go 1.22+- Rust 1.91.1+- A C++ compiler- CMake### 2. Ask questions-If the user has not provided a complete model configuration, ask first. Do not write the config file yet.+Check configuration files, environment variables, and choices already supplied. Use the following as an information checklist and ask only about missing values that affect installation. Have the user configure API keys locally or through an existing credential mechanism, rather than paste them into chat.-#### Required questions+#### Required information1. Which model provider do you want to use?- `openai`@@ -132,7 +133,7 @@ If the user has not provided a complete model configuration, ask first. Do not w- whether Ollama is already installed- which local embedding / VLM models they want to use-#### Extra required questions for Docker+#### Docker informationIf the user chooses Docker, also confirm:- whether they want `docker run` or `docker compose`@@ -140,7 +141,7 @@ If the user chooses Docker, also confirm:- whether they want to mount host `~/.openviking` to container `/app/.openviking`- whether they want to inject the full JSON config through `OPENVIKING_CONF_CONTENT`-#### Extra required questions for Windows+#### Windows informationIf the user is on Windows, also confirm:- whether they use PowerShell or cmd.exe@@ -149,7 +150,7 @@ If the user is on Windows, also confirm:### 3. Generate the config-Only write `~/.openviking/ov.conf` after the user has confirmed all required values.+Only write or update `~/.openviking/ov.conf` after the user has confirmed all required values, and keep a copy of existing configuration. The placeholder values below are not a working configuration.#### Minimal config shape@@ -195,8 +196,10 @@ Only add these when the provider requires them, when the README examples explici#### Path A: Standard minimal install+Use a Python 3.10+ virtual environment, or follow the [Quick Start](02-quickstart.md) with `uv tool install`. In an activated virtual environment:+```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking```After the user confirms the configuration, write `~/.openviking/ov.conf`, then run:@@ -208,6 +211,8 @@ openviking-server#### Path B: Local-model install (Ollama)+Complete the package installation from Path A and start Ollama, then run:+```bashopenviking-server initopenviking-server doctor@@ -222,7 +227,8 @@ If the user already has a local config directory, prefer:```bashdocker run --rm \- -p 1933:1933 \+ --name openviking \+ -p 127.0.0.1:1933:1933 \-v ~/.openviking:/app/.openviking \ghcr.io/volcengine/openviking:latest```@@ -252,20 +258,23 @@ docker compose up -dIf the user does not yet have `ov.conf`, there are two options:1. Generate it on the host first and mount it into the container-2. Start the container, then run:+2. Initialize the same mounted directory with a one-off container, then start the service using Option 1:```bash-docker exec -it openviking openviking-server init+docker run --rm -it \+ -v ~/.openviking:/app/.openviking \+ ghcr.io/volcengine/openviking:latest openviking-server init```The Dockerfile also supports injecting the full JSON config via `OPENVIKING_CONF_CONTENT` on first start. Only use that if the user explicitly wants it and all config values have already been confirmed.##### Docker validation-After startup, verify:+`/health` only confirms a responsive process; a container without configuration returns `503 pending_initialization`, so receiving a curl response alone does not establish health. Check logs and `/ready`:```bashcurl http://localhost:1933/health+curl http://localhost:1933/ready```#### Path D: Windows install@@ -273,7 +282,7 @@ curl http://localhost:1933/healthPrefer the prebuilt-wheel path first:```bat-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking```After the config file is ready, set environment variables using the user’s shell.@@ -313,7 +322,7 @@ set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"#### Path E: Source build-Only after you have confirmed that the source-build path is necessary should you ask the user to prepare Go / Rust / C++ / CMake.+Prepare Rust, C++, and CMake only when a source build is needed. See CONTRIBUTING.md in the repository for the full build steps.### 5. Triage@@ -373,7 +382,7 @@ Handling rule:- first try a standard reinstall:```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade --force-reinstall openviking```- if it still fails, then decide whether to move to the source-build path@@ -387,7 +396,7 @@ Confirm first whether this is because:- prebuilt artifacts are unavailableHandling rule:-- only after confirming the source-build path should you add Go / Rust / C++ / CMake+- only after confirming the source-build path should you add Rust / C++ / CMake- on Windows, local compilation usually means CMake and MinGW become relevant first- do not present source-build dependencies as the default install prerequisitesdiff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.mdindex b78502f7d..60db4cfa6 100644--- a/docs/en/getting-started/05-cli-setup.md+++ b/docs/en/getting-started/05-cli-setup.md@@ -13,7 +13,7 @@ The CLI evolves quickly. Use `ov --help` and `ov <command> --help` as the source## What This Configures-The CLI uses `~/.openviking/ovcli.conf` as the active client connection config.+The CLI defaults to `~/.openviking/ovcli.conf`. When `OPENVIKING_CLI_CONFIG_FILE` is set, normal commands read that file. Named configuration management still operates on the default directory, so check the effective path after switching.When you create named configs, `ov` stores them next to the active file as `~/.openviking/ovcli.conf.<name>`. Switching configs copies the chosen saved config into `~/.openviking/ovcli.conf`.@@ -53,7 +53,7 @@ Choose this only when the user wants to connect to a custom OpenViking server on- API key is usually not needed for a local unauthenticated server.- Agents should not probe local ports, curl local health endpoints, or start server commands unless the user chose local custom setup.-> **Note:** Recent CLI versions (v0.3.23+) require a saved display language before most commands will run. In an interactive terminal the CLI prompts you on first use; in a non-interactive shell (agent or CI) any non-exempt command exits `2` until you run `ov language en` or `ov language zh-CN`. Only `ov language`/`ov lang`, `ov config add|edit|delete|list`, and `ov config switch <name>` are exempt, so run `ov language <code>` before the `ov config validate`, `ov health`, and `ov status` checks below.+> **Note:** Recent CLI versions (v0.3.23+) require a saved display language before most commands will run. In an interactive terminal the CLI prompts you on first use; in a non-interactive shell (agent or CI) any non-exempt command exits `2` until you run `ov language en` or `ov language zh-CN`. In the current source, help requests, `ov language`/`ov lang`, `ov config add|edit|delete|list`, and `ov config switch <name>` bypass this gate, so run `ov language <code>` before the `ov config validate`, `ov health`, and `ov status` checks below.## Before You Start@@ -120,7 +120,7 @@ OpenViking CLI configs can hold a user key, a root key, or both.- User key: use this for normal data commands such as `ov add-resource`, `ov find`, and `ov tree`. The server derives the identity from the key, so you usually do not pass `--account` or `--user`. This is what most users want.- Root key: use this for admin work and commands that require `--sudo`. In `api_key` mode, root keys cannot access tenant data, even with `--account` and `--user`. Only a `trusted` server accepts those identity headers for root-key-authenticated data access.-- User key plus root key: use this when the same config should support daily data work and occasional admin work. Normal commands use the user key. `--sudo` commands use the root key with the configured account and user.+- User key plus root key: use this when the same config should support daily data work and occasional admin work. Normal commands use the user key. `--sudo` commands use the root key. Do not add `account` or `user` settings in API key mode.## Manual Setup@@ -159,13 +159,13 @@ Use this path when an agent is setting up `ov` for a user. The agent should read1. Ask which target the user wants unless it has already been specified: OpenViking Service (VolcEngine Cloud), remote custom, or local custom.2. Do not infer the intended setup from existing configs, active configs, local files, default ports, or running services.3. Ask before switching configs, replacing configs, probing local services, starting servers, or writing data.-4. Run `ov --help`, `ov config --help`, and the relevant config subcommand help before choosing commands.+4. Run `ov --help`, `ov config --help`, and the relevant config subcommand help before choosing commands. Select a display language with `ov language <code>` if none is saved.5. If you have long-term memory and the user permits it, store a short summary of the current `ov --help` command surface. Do not store API keys or other secrets.6. Use non-interactive `ov config` commands when the required values are known.7. Always pass `--name` for agent setup so retries target the same saved config.8. If the agent already holds the API key through a trusted channel, pass it with `--api-key-stdin` or `--root-api-key-stdin` and write only the key bytes to stdin. Use `--api-key-env` or `--root-api-key-env` only when that environment variable already exists. Do not ask the user to open a separate shell just to export a key for the agent.9. Use `-o json` and branch on the JSON result plus the process exit code.-10. Validate the active config with `ov config validate`, then check `ov health` and `ov status`.+10. Validate the active config with `ov config validate`, then check `ov health` and `ov status`. Inspect the result contents; a zero exit code alone does not mean the service is healthy.11. If non-interactive setup fails because values are missing, auth is unclear, or terminal input is safer, guide the user through `ov config` instead.### Inspect the Installed CLI@@ -307,7 +307,7 @@ Write the trusted deployment's root API key to stdin. The account and user identFor a custom server where the user has both a user key and a root key, store both in one config:```bash-ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --account <ACCOUNT-ID> --user <USER-ID> --activate -o json+ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --activate -o json```This keeps normal commands on the user key and lets `--sudo` commands use the root key. Because one command has only one stdin stream, the second key must come from an existing environment variable. If neither key is already available in the environment, use `ov config` and guide the user through the interactive flow.@@ -375,7 +375,7 @@ Do not print the raw config file unless you understand that it may contain secreIf a verification command says OpenViking needs a display language, run `ov language en`, or `ov language zh-CN` if the user wants Chinese, then rerun verification.-`ov status` includes broader server and data diagnostics. If `ov config validate` and `ov health` pass, a warning in `ov status` does not always mean CLI setup failed.+`ov status` includes broader server and data diagnostics. Confirm that `ov config validate` succeeds and inspect the `healthy` value from `ov health`. Currently, `ov health` and table-mode `ov status` can exit 0 while reporting an unhealthy state, so automation must inspect the result. A status warning unrelated to connectivity does not necessarily mean CLI setup failed.## Learn the Rest of the CLI@@ -387,7 +387,7 @@ ov config --helpov add-resource --help```-Agents should refresh this help before running unfamiliar commands. If an agent keeps long-term memory for the user and the user allows it, the agent may store a concise summary of the command surface for future sessions. It should not store secrets, raw config files, or private server details unless the user explicitly asks.+Check the relevant help before unfamiliar commands, especially ingestion targets, asynchronous waiting, and deletion options.## Credential Safety@@ -469,7 +469,7 @@ Use `ov config`. Do not use old or removed setup commands such as `ov config setOnce the CLI is configured, use `ov --help` and `ov <command> --help` to learn the rest of the CLI.-Adding a resource writes data into the active OpenViking server. If you want a small demo, use a resource you are comfortable storing. Agents must ask the user for permission before running this kind of demo command.+Adding a resource writes data into the active OpenViking server. If you want a small demo, use a resource you are comfortable storing. Agents must ask the user for permission before running this kind of demo command. Connection verification alone does not require writing a resource.```bashov add-resource https://github.com/volcengine/OpenVikingdiff --git a/docs/en/migration/01-user-peer-model.md b/docs/en/migration/01-user-peer-model.mdindex 2480622cd..535df0859 100644--- a/docs/en/migration/01-user-peer-model.md+++ b/docs/en/migration/01-user-peer-model.md@@ -2,6 +2,8 @@> **Version scope:** This page documents the historical 0.3.x-to-0.4.0 migration. Its Agent directory compatibility and migration instructions do not apply to current versions. `viking://agent/...` now denotes account-shared directories; Agent ID path compatibility, migration, and cleanup have been removed. The current `admin migrate` command handles legacy sessions only.+For current deployments, use [Administration API](../api/08-admin.md). Keep the source installation and its backup available until the historical migration has been verified; these commands are not a direct upgrade path from 0.3.x to the latest release.+This guide is for users already running OpenViking 0.3.x. It explains what to do before and after upgrading to 0.4.0, which legacy usage remains compatible, how to migrate data, and how to move application code to the new model.## Upgrade Decisiondiff --git a/docs/zh/about/02-changelog.md b/docs/zh/about/02-changelog.mdindex 6356ee1a4..714c0e30a 100644--- a/docs/zh/about/02-changelog.md+++ b/docs/zh/about/02-changelog.md@@ -3,6 +3,8 @@OpenViking 的所有重要变更都将记录在此文件中。此更新日志从 [GitHub Releases](https://github.com/volcengine/OpenViking/releases) 自动生成。+> 各版本条目记录发布时的行为,其中的命令和默认值可能已变更。安装请使用当前[部署指南](../guides/03-deployment.md)。历史升级步骤如需清空 workspace,应先停止写入并做好可恢复的备份;不要把旧版本的清理步骤套用到其他升级。+## 未发布- **Watch API 迁移(不兼容变更)**:使用 `watch_interval > 0` 重新导入不再更新或恢复已有 Watch。@@ -16,7 +18,7 @@ OpenViking 的所有重要变更都将记录在此文件中。- **Session policy 兼容性**:字符串 `"false"` 现在会正确关闭对应的记忆抽取开关。现有 boolean-like 值暂时保持兼容并产生弃用警告;新配置应使用 JSON 布尔值。- **工作区 peer 派生规则**:coding agent 插件不再按工作目录派生工作区 peer,改为按 git 派生。新的默认值 `peer.source: "git"` 取仓库归一化后的 `origin` URL(`github.com-volcengine-openviking`),其次回退到仓库根路径,因此同一个仓库的每个 clone、worktree 和子目录共用同一个 peer,而 fork 仍是独立的 peer。不在 git 仓库中的目录现在完全不发送 peer,在那里记下的内容进入用户级空间,而不是为每个目录新建一个命名空间。要让这样的目录拥有独立记忆,在其中创建 `.openviking/config.json`,写入 `{"version": 1, "peer": {"id": "my-project"}}`。无需任何迁移:此前按工作目录派生的 id 随时可以在本地重新算出,而默认的 `peer_scope: "all"` 召回本来就会扫描所有 peer,因此写在旧 id 下的记忆照常召回(`peer_scope: "actor"` 时,Claude Code、Codex、OpenCode 和 DSH 插件会额外查询该 id)。设置 `peer.source: "cwd"`(或 `OPENVIKING_PEER_SOURCE=cwd`)即可保持旧行为。-- **pi 扩展的工具面(不兼容变更)**:pi 扩展 0.4.0 移除自己手写的 7 个 `viking_*` REST 工具,改用官方 MCP 客户端连接服务端,因此工具清单由服务端 `tools/list` 的返回决定,不再来自扩展自带的目录。每个工具的名字是 `openviking_` 加服务端的工具名(`viking_search` → `openviking_search`),不保留旧名别名期;pi 的 `--tools` 和 `--exclude-tools` 按名字精确匹配,白名单里仍写 `viking_search` 的话,对应工具会静默消失,需要手动改名。这些工具的行为与其他 MCP harness 一致:`remember` 另开一个会话并立即提交,不再追加到当前 pi 会话;`read` 只返回全文(`level="abstract"` 和 `level="overview"` 两档已移除,替代路径是 `openviking_search(mode="context", detail="overview")`);`forget` 直接删除传入的 URI;`add_resource` 对本地路径返回一次性上传 URL,由模型把文件 POST 上去。root api key 在 `/mcp` 上被拒绝(403),现在会导致整个会话一个工具都没有,而此前是工具照常注册、每次调用都返回空结果,这类部署需要改用 user 或 admin key。共享开关 `mcpEnabled: false` 现在对 pi 同样生效,以这种方式关掉工具不计作故障。以上各种情况下,recall、会话采集和上下文接管都照常工作,其他 harness 不受影响。完整的改名对照和升级说明见扩展 README 的 [Upgrading from 0.3.x](https://github.com/volcengine/OpenViking/blob/main/examples/pi-coding-agent-extension/README.md#upgrading-from-03x)。+- **pi 扩展的工具面(不兼容变更)**:pi 扩展 0.4.0 移除自己手写的 7 个 `viking_*` REST 工具,改用官方 MCP 客户端连接服务端,因此工具清单由服务端 `tools/list` 的返回决定,不再来自扩展自带的目录。每个工具的名字是 `openviking_` 加服务端的工具名(`viking_search` → `openviking_search`),不保留旧名别名期;pi 的 `--tools` 和 `--exclude-tools` 按名字精确匹配,白名单里仍写 `viking_search` 的话,对应工具会静默消失,需要手动改名。这些工具的行为与其他 MCP harness 一致:`remember` 另开一个会话并立即提交,不再追加到当前 pi 会话;`read` 返回支持按行分页的文本(`level="abstract"` 和 `level="overview"` 两档已移除,替代路径是 `openviking_search(mode="context", detail="overview")`);`forget` 直接删除传入的 URI;`add_resource` 对本地路径返回一次性上传 URL,由模型把文件 POST 上去。root api key 在 `/mcp` 上被拒绝(403),现在会导致整个会话一个工具都没有,而此前是工具照常注册、每次调用都返回空结果,这类部署需要改用 user 或 admin key。共享开关 `mcpEnabled: false` 现在对 pi 同样生效,以这种方式关掉工具不计作故障。以上各种情况下,recall、会话采集和上下文接管都照常工作,其他 harness 不受影响。完整的改名对照和升级说明见扩展 README 的 [Upgrading from 0.3.x](https://github.com/volcengine/OpenViking/blob/main/examples/pi-coding-agent-extension/README.md#upgrading-from-03x)。- **外部 peer identity 迁移**:日志导入中的混合文字标识改用无损的`ext-<base64>` id。`ext-` 命名空间为编码身份保留,因此原本会进入该命名空间的ASCII 身份也会被编码。系统不会自动读取旧的有损 peer 目录,因为多个身份可能彼此冲突,diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.mdindex 5a9a225ae..f1e4b3883 100644--- a/docs/zh/configuration/01-server.md+++ b/docs/zh/configuration/01-server.md@@ -19,6 +19,8 @@ openviking-server --config /path/to/ov.conf## 配置结构+下面只展示常用顶层分组,不是可直接运行的完整配置。首次启动可从本页的[最小示例](#最小示例)开始,填写实际模型与凭据;后续示例中的片段应合并到同一个 `ov.conf`。+```json{"embedding": {},@@ -46,7 +48,7 @@ openviking-server --config /path/to/ov.conf| `default_user` | string | `"default"` | Service context 使用的默认用户 || `embedding` | object | 内置本地 Dense 模型 | 向量化模型和稀疏/混合检索配置;默认使用 `local` / `bge-small-zh-v1.5-f16` || `vlm` | object | 空配置 | 内容理解、摘要和记忆抽取使用的模型;使用相关能力前需要配置可用模型 |-| `query_planner` | object / `null` | `null` | 检索意图分析模型;未配置时回退到 `vlm` |+| `query_planner` | object / `null` | `null` | 检索意图分析和召回改写使用的模型。未配置或为空时回退到 `vlm`;`auto` 模式的召回改写要求配置集群级 `query_planner`,或账户级 `query_planner` / `vlm` 覆盖项 || `rerank` | object | disabled | 检索结果重排模型 || `retrieval` | object | 见下表 | 检索排序和意图分析策略 || `grep` | object | 内置默认值 | 文本搜索引擎配置 |@@ -356,7 +358,7 @@ Provider 和密钥管理配置见[加密指南](../guides/08-encryption.md)。| 字段 | 类型 / 可选值 | 默认值 | 作用 ||---|---|---|---|-| `custom_templates_dir` | path | `""` | 附加的自定义记忆模板目录 |+| `custom_templates_dir` | path | `""` | 自定义记忆模板目录;同名 `memory_type` 覆盖已加载模板 || `experimental_memory_switch` | boolean | `false` | 是否启用实验性记忆模板 || `eager_prefetch` | boolean | `true` | 是否在抽取前预取并读取记忆内容 || `prefetch_search_topn` | integer,`>= 1` | `5` | 预取时读取的检索结果数量 |@@ -364,6 +366,8 @@ Provider 和密钥管理配置见[加密指南](../guides/08-encryption.md)。| `session_skill_extraction_enabled` | boolean | `false` | 是否同时抽取可复用 Skill || `link_enabled` | boolean | `false` | 是否生成和解析记忆链接 |+自动提交还需要单独设置策略:记忆抽取开关不会让会话自动提交。详见[配置指南](../guides/01-configuration.md)的 `memory.session_auto_commit` 和[会话 API](../api/05-sessions.md)。模板目录的加载顺序和生效方式见 [Prompt 指南](../guides/10-prompt-guide.md)。+## 解析器配置解析器放在 `parsers` 下:diff --git a/docs/zh/configuration/02-client.md b/docs/zh/configuration/02-client.mdindex 37ba7f7e0..f59f0b6e3 100644--- a/docs/zh/configuration/02-client.md+++ b/docs/zh/configuration/02-client.md@@ -2,9 +2,9 @@`ovcli.conf` 是 `ov` CLI 的客户端配置文件,用于保存服务端连接、鉴权身份和命令默认行为。-Codex、Claude Code、OpenCode 等 Agent 插件还会读取各自的 `OPENVIKING_*` 环境变量,用于控制 Recall、Capture、调试等行为;这些不属于 `ovcli.conf`,请在对应的 [Agent 集成](../agent-integrations/01-overview.md)文档中配置。+采用共享配置加载器的 Agent 插件还会读取本文件的 `plugin` 段、工作区配置和 `OPENVIKING_*` 环境变量,控制召回、对话捕获和调试。下文分别说明 CLI 与插件的配置;各宿主的支持范围见 [Agent 集成](../agent-integrations/01-overview.md)。-建议使用 `ov config` 创建和维护配置;使用 `ov config show` 查看脱敏后的当前配置。+使用 `ov config` 管理 CLI 连接,使用 `ov config show` 查看脱敏后的当前配置。编辑或重命名配置时,CLI 会保留 `plugin` 等额外顶层字段。切换配置时,新配置显式包含的字段优先;若未包含 `plugin`,则保留 active 文件已有的插件配置。默认路径:@@ -25,8 +25,6 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf"url": "https://openviking.example.com","api_key": "<user-or-admin-key>","root_api_key": "<root-key>",- "account": "acme",- "user": "alice","actor_peer_id": "agent:research-assistant","timeout": 60,"output": "table",@@ -46,7 +44,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf}```-不需要的字段可以省略。本地 `dev` 模式通常只需要 `url`。+示例用于 API key 模式,不需要的字段可以省略。本地 `dev` 模式通常只需要 `url`。trusted 部署按[认证指南](../guides/04-authentication.md)另配 `account`、`user` 和对应凭据;API key 模式下,服务端按 key 确定身份,忽略这两个字段。## 连接与鉴权@@ -55,8 +53,6 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf"url": "https://openviking.example.com","api_key": "<user-or-admin-key>","root_api_key": "<root-key>",- "account": "acme",- "user": "alice","actor_peer_id": "agent:research-assistant","extra_headers": {"X-Tenant": "acme"@@ -133,7 +129,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf## 插件配置-记忆插件的行为旋钮写在 `plugin` 段下。直接挂在它下面的键对所有 harness 生效;以 harness 命名的嵌套对象(`claude_code` 或 `codex`)只覆盖那一个。+记忆插件的配置写在 `plugin` 段下。直接挂在它下面的键作为采用共享加载器的插件默认值;以 harness 命名的嵌套对象(如 `claude_code`、`codex` 或 `opencode`)只覆盖那一个。```json{@@ -149,11 +145,11 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf}```-每个键都是某个 `OPENVIKING_*` 调优变量的 camelCase 对应写法——`OPENVIKING_RECALL_LIMIT` 对应 `recallLimit`,`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 对应 `captureAssistantTurns`。反过来不成立:少数变量刻意只认环境变量,比如一次性的 `OPENVIKING_BYPASS_SESSION`。完整列表在插件 README 里:[Claude Code](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)、[Codex](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。取列表值的旋钮(`bypassSessionPatterns`、`recallQueryFilters`、`captureFilters`)在这里是 JSON 数组,而它们的环境变量对应物是逗号分隔的字符串,所以值里带字面逗号的只能写进数组。+许多配置项都有对应的 `OPENVIKING_*` 环境变量,例如 `OPENVIKING_RECALL_LIMIT` 对应 `recallLimit`,`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 对应 `captureAssistantTurns`。`OPENVIKING_BYPASS_SESSION` 也有文件配置项 `plugin.bypassSession`;仅需覆盖当前进程时可使用环境变量。完整共享列表由 `examples/memory-plugin-shared/lib/config-schema.mjs` 定义。用法见插件 README:[Claude Code](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)、[Codex](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。取列表值的配置项(`bypassSessionPatterns`、`recallQueryFilters`、`captureFilters`)在这里是 JSON 数组,而它们的环境变量对应物是逗号分隔的字符串,所以值里带字面逗号的只能写进数组。-优先级从高到低:环境变量 → [工作区各层](#工作区配置) → `plugin.<harness>` → `plugin` → `ov.conf` 里遗留的按 harness 分块 → 内置默认值。hook 每次触发都会重新读文件,所以改完下一轮就生效;改 `OPENVIKING_*` 变量则需要重启 agent,因为 hook 继承的是它的环境。+优先级从高到低:环境变量 → [工作区各层](#工作区配置) → `plugin.<harness>` → `plugin` → `ov.conf` 里遗留的按 harness 分块 → 内置默认值。独立启动的 hook 进程在每次触发时重新读文件;常驻插件何时重载取决于宿主,不确定时重启 Agent。环境变量改动也需要重启,因为 hook 继承的是 Agent 进程的环境。-目前只有 Claude Code 和 Codex 插件会读这一段,用其它 harness 名字建的条目不会生效。`ov-memory-doctor` 会打印它解析到的结果,并对不认识的键给出告警和最接近的正确键名。+采用共享配置加载器的记忆插件会读取这一段;各宿主支持的字段和默认值见对应的 [集成文档](../agent-integrations/01-overview.md)。`ov-memory-doctor` 会打印它解析到的结果,并对不认识的键给出告警和最接近的正确键名。## 工作区配置@@ -165,7 +161,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf~/.openviking/workspaces/<slot>.json # 本机注册表,每个工作区一个文件```-工作区根目录是向上查找时最先遇到的、包含 `.git` 或包含 `.openviking/config.json`(或 `config.local.json`)的目录;`$HOME` 和文件系统根目录永远不会被当作工作区根。两者都没有的目录不是工作区:没有配置层,没有注册表条目,也没有属于自己的 peer。注册表的槽位名由根目录名加上完整路径的哈希组成,因此同一台机器上同一仓库的两个 clone 不会共用同一条记录。这些层由 Claude Code 和 Codex 插件读取,`ov` 命令不读取。+工作区根目录是向上查找时最先遇到的、包含 `.git` 或包含 `.openviking/config.json`(或 `config.local.json`)的目录;`$HOME` 和文件系统根目录永远不会被当作工作区根。两者都没有的目录不是工作区:没有配置层,没有注册表条目,也没有属于自己的 peer。注册表的槽位名由根目录名加上完整路径的哈希组成,因此同一台机器上同一仓库的两个 clone 不会共用同一条记录。这些层由采用共享配置加载器的记忆插件读取,`ov` 命令不读取。### 优先级@@ -214,11 +210,11 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf| `bypass.session_patterns` | glob 列表 | 会话 id 或工作目录命中时跳过 Recall 与 Capture || `labels` | object | 给人看的自由元数据,插件不读取 |-超出范围的数值会被夹到最近的边界并给出提示;无法识别的枚举值会被忽略。表中之外的键会保留在文件里但不生效。+超出范围的数值会被夹到最近的边界并给出提示;无法识别的枚举值会被忽略。表格列出常用字段;完整字段由共享 `config-schema.mjs` 定义,未识别的键不会生效。### 工作区 peer-peer 是用户空间下的一段路径前缀——`viking://user/<you>/peers/<peer>/memories`——把一个项目的记忆归拢在一起。默认只有 git 仓库会有 peer:优先用归一化后的 `origin` URL,其次是仓库根路径。不在 git 仓库中的目录不发送任何 peer,在那里记下的内容进入用户级空间 `viking://user/<you>/memories`。这是有意为之:每个任务新建一个目录的应用,否则会为每个任务铸造一个全新的空 peer。+peer 是用户空间下的一段路径前缀——`viking://user/<you>/peers/<peer>/memories`——把一个项目的记忆归拢在一起。默认只有 git 仓库会有 peer:优先用归一化后的 `origin` URL,其次是仓库根路径。不在 git 仓库中的目录不发送任何 peer,在那里记下的内容进入用户级空间 `viking://user/<you>/memories`。这样,每个任务新建临时目录的应用就不会为每个目录创建一个空 peer。规则由 `peer.source` 决定。同一项配置在环境变量中写作 `OPENVIKING_PEER_SOURCE`,在 `ovcli.conf` 中写作 `plugin.peerSource` 或 `plugin.<harness>.peerSource`。@@ -230,13 +226,13 @@ peer 是用户空间下的一段路径前缀——`viking://user/<you>/peers/<pe{"version": 1, "peer": {"id": "my-project"}}```-这个目录及其下的一切从此写入 peer `my-project`,是不是仓库都一样。这个 id 不含路径,因此目录移动、改名、换一台机器都不会变;两个目录写同一个 id 就共享同一份记忆,这正是合并它们的方式。+没有更高优先级的 peer 设置或嵌套工作区覆盖时,插件在这个目录及其子目录中捕获的记忆会写入 peer `my-project`,无论它是否为 Git 仓库。这个 id 不含路径,因此目录移动、改名、换一台机器都不会变;连接同一服务端、使用同一账户和用户的两个目录,写同一个 peer id 就共享同一记忆范围,这正是合并它们的方式。其余写法,优先级从高到低:| 写在哪 | 作用 ||---|---|-| `OPENVIKING_PEER_ID=my-project` | 为单个进程钉住 peer,无视配置文件 |+| `OPENVIKING_PEER_ID=my-project` | 为单个进程指定 peer;凭据固定从 `ovcli.conf` 读取时忽略此变量,宿主显式指定的 peer 优先 || `.openviking/config.json` 的 `peer.id` | 指定本工作区的 peer。推荐做法;`config.local.json` 是同一个键,只是不提交 || 同一文件的 `peer.source` | 不直接指定,而是推导——`"cwd"` 用目录路径,`"team-{dir}"` 用模板 || `ovcli.conf` 的 `plugin.peerSource`,或 `OPENVIKING_PEER_SOURCE` | 对本机所有目录生效;`"cwd"` 可整体恢复 `git` 默认之前的行为 |@@ -268,7 +264,7 @@ peer 是用户空间下的一段路径前缀——`viking://user/<you>/peers/<pe| 长期使用但不是仓库的目录 | 创建 `.openviking/config.json`,写上 `peer.id` || monorepo 里某个子项目要单独记忆 | 在子目录放 `config.json`,写 `peer.source: "{git_remote}-{dir}"`。只放标记文件仍会沿用仓库 peer,因为 `{git_remote}` 先解析成功 || 一次性任务目录(应用按日期新建的目录、临时解包目录) | 什么都不用做,记忆进入用户级空间 |-| 同一仓库下各个 agent 想各存各的 | `peer.source: "{git_remote}-{harness}"`。默认不这么分——跨 agent 共享一份项目记忆通常才是想要的,所以这一档得自己写 |+| 同一仓库下各个 agent 想各存各的 | `peer.source: "{git_remote}-{harness}"`。需要显式设置;默认按项目共享,不区分 Agent || 几个目录共享一份记忆 | 各处写同一个 `peer.id` || 不想按项目区分 | `peer.source: "none"`(等同于 `OPENVIKING_WORKSPACE_PEER=0`) |@@ -278,10 +274,10 @@ peer 是用户空间下的一段路径前缀——`viking://user/<you>/peers/<pe| `recall.peer_scope` | 召回读什么 ||---|---|-| `"all"`(默认) | 用户级记忆与本工作区 peer 全权重参与,再对该用户的其他 peer 做一次扫描,命中结果按类别降分——服务端 `other_peer_penalty` 默认对 events、entities 为 0.1,对 preferences、experiences、resources、skills 为 0.02。因此其他项目的内容只能垫底 |+| `"all"`(默认) | 用户级记忆与本工作区 peer 全权重参与,再对该用户的其他 peer 做一次扫描,命中结果按类别降分——服务端 `other_peer_penalty` 默认对 events、entities 为 0.1,对 preferences、experiences、resources、skills 为 0.02。扣分会降低其他项目内容的排序,但不会保证它们始终排在最后 || `"actor"` | 只看用户级记忆和本工作区的 peer。插件会额外查询一次此处按 `git` 默认之前的规则推导出的 peer,因此旧版本写下的内容不会丢 |-两档之下用户级记忆都是全权重,这也是"不在仓库中就不发 peer"的代价:一次性任务里学到的东西,之后在每个项目里都会参与召回。需要更强隔离时,给这类目录也写一个自己的 `peer.id`,或整体切到 `"actor"`。+两档之下用户级记忆都是全权重,这也是"不在仓库中就不发 peer"的代价:一次性任务里学到的东西,之后在每个项目里都会参与召回。要把这类目录后续产生的记忆分开存放,给它设置独立的 `peer.id`,并用 `"actor"` 限制跨 peer 召回。`"actor"` 仍会读取已有的用户级记忆;它不会把这些记忆重新归属或隐藏。切换到 `git` 默认值不需要迁移,也不会搬动任何数据:写在旧的 cwd 派生 peer 下的记忆原地不动,召回仍然读得到——`"all"` 下靠跨 peer 扫描,`"actor"` 下靠那次额外查询。`peer_scope` 是逐请求参数;服务端版本过旧、不认识它时,插件会记录一次降级并告警,而不是静默地读取全部。@@ -315,7 +311,7 @@ hook 是非交互进程,因此这些文件不经确认即被信任;被拒绝`ov config add` 和 `ov config edit` 的 `--api-key-env <变量名>`、`--root-api-key-env <变量名>` 可以从指定环境变量读取密钥,并写入配置文件。-Agent 插件使用的 `OPENVIKING_AUTO_RECALL`、`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_AUTO_CAPTURE`、`OPENVIKING_DEBUG` 等变量由插件进程读取,不是 `ovcli.conf` 字段。+Agent 插件读取 `OPENVIKING_AUTO_RECALL`、`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_AUTO_CAPTURE`、`OPENVIKING_DEBUG` 等环境变量。不要把环境变量名直接写成 JSON 键;支持的文件配置使用 `plugin` 段中的对应字段。## 多服务配置diff --git a/docs/zh/getting-started/04-setup-for-agent.md b/docs/zh/getting-started/04-setup-for-agent.mdindex 2a5a7101b..63211e9b7 100644--- a/docs/zh/getting-started/04-setup-for-agent.md+++ b/docs/zh/getting-started/04-setup-for-agent.md@@ -9,8 +9,9 @@## 总原则- 默认走普通用户安装路径,不默认走源码构建-- 默认使用预编译包,不默认要求 Go / Rust / C++ / CMake-- 配置不确定时必须先问用户,不要替用户猜 provider、model、api_base、api_key、workspace+- 默认使用预编译包,不默认要求 Rust / C++ / CMake+- 先读取已有配置和用户已给出的信息,缺失或不确定的项要先问用户;不要替用户猜 provider、model、api_base、api_key、workspace+- 不覆盖已有配置;更新前检查实际差异,保留与本次安装无关的字段- 只有在安装失败并明确指向本地编译,或用户主动要求源码安装时,才进入源码构建路径## SOP@@ -40,9 +41,10 @@- 用户不想手填大量模型参数执行路径:-1. 运行 `openviking-server init`-2. 运行 `openviking-server doctor`-3. 启动 `openviking-server`+1. 安装 OpenViking Python 包并确认 Ollama 已运行+2. 运行 `openviking-server init` 选择本地模型+3. 运行 `openviking-server doctor`+4. 启动 `openviking-server`#### C. Docker 安装满足任一情况即可进入:@@ -76,16 +78,15 @@- 用户明确要修改或重编底层原生组件进入后再说明需要:-- Go 1.22+- Rust 1.91.1+- C++ 编译器- CMake### 2. 提问-如果用户没有给出完整模型配置,先问,不要直接写配置文件。+先检查配置文件、环境变量和用户已给出的选择。下面是信息清单,只补问仍缺失且会影响安装的项。API Key 应由用户在本地配置或通过已有凭据机制提供,不要求粘贴进聊天。-#### 必问项+#### 需要的信息1. 你准备使用哪种模型提供商?- `openai`@@ -132,7 +133,7 @@- 是否已经安装 Ollama- 希望使用哪些本地 embedding / VLM 模型-#### Docker 额外必问项+#### Docker 需要的信息如果用户选择 Docker,还要继续确认:- 用户是想用 `docker run` 还是 `docker compose`@@ -140,7 +141,7 @@- 是否要把宿主机 `~/.openviking` 挂载到容器 `/app/.openviking`- 是否要直接通过环境变量 `OPENVIKING_CONF_CONTENT` 注入完整 JSON 配置-#### Windows 额外必问项+#### Windows 需要的信息如果用户在 Windows,还要继续确认:- 用户使用的是 PowerShell 还是 cmd.exe@@ -149,7 +150,7 @@### 3. 生成配置-只有在用户确认完必要信息后,才能写 `~/.openviking/ov.conf`。+只有在用户确认完必要信息后,才能写入或更新 `~/.openviking/ov.conf`,已有配置先保留副本。不要把下面的占位值直接作为可用配置。#### 最小配置结构@@ -195,8 +196,10 @@#### 路径 A:普通最小安装+先使用 Python 3.10+ 的虚拟环境,或按[快速开始](02-quickstart.md)用 `uv tool install` 安装。已激活虚拟环境时:+```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking```用户确认配置后写入 `~/.openviking/ov.conf`,然后执行:@@ -208,6 +211,8 @@ openviking-server#### 路径 B:本地模型安装(Ollama)+先完成路径 A 的包安装,并启动 Ollama,再运行:+```bashopenviking-server initopenviking-server doctor@@ -222,7 +227,8 @@ openviking-server```bashdocker run --rm \- -p 1933:1933 \+ --name openviking \+ -p 127.0.0.1:1933:1933 \-v ~/.openviking:/app/.openviking \ghcr.io/volcengine/openviking:latest```@@ -252,20 +258,23 @@ docker compose up -d如果用户还没有 `ov.conf`,可以二选一:1. 先在宿主机生成并挂载进容器-2. 启动容器后进入容器内执行:+2. 用一次性容器初始化同一个挂载目录,再按方案 1 启动服务:```bash-docker exec -it openviking openviking-server init+docker run --rm -it \+ -v ~/.openviking:/app/.openviking \+ ghcr.io/volcengine/openviking:latest openviking-server init```Dockerfile 还支持在首次启动时通过 `OPENVIKING_CONF_CONTENT` 注入完整 JSON;如果用户明确想这样做,可以采用,但前提仍是配置值已确认。##### Docker 验证-启动后验证:+`/health` 只确认进程可响应;缺配置的容器会返回 `503 pending_initialization`,不能只看 curl 是否收到了响应。启动后检查日志和 `/ready`:```bashcurl http://localhost:1933/health+curl http://localhost:1933/ready```#### 路径 D:Windows 安装@@ -273,7 +282,7 @@ curl http://localhost:1933/health优先按预编译 wheel 路径执行:```bat-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade openviking```配置文件写好后,按用户 shell 设置环境变量。@@ -313,7 +322,7 @@ set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"#### 路径 E:源码构建-只有进入源码构建路径后,才向用户说明并准备 Go / Rust / C++ / CMake。+只有进入源码构建路径后,才准备 Rust、C++ 和 CMake。完整构建步骤见仓库 CONTRIBUTING.md。### 5. 失败分流@@ -373,7 +382,7 @@ openviking-server doctor- 先执行一次标准重装:```bash-pip install openviking --upgrade --force-reinstall+python -m pip install --upgrade --force-reinstall openviking```- 如果仍失败,再判断是否需要进入源码构建路径@@ -387,7 +396,7 @@ pip install openviking --upgrade --force-reinstall- 预编译产物缺失处理原则:-- 只有确认进入源码构建路径后,才补充 Go / Rust / C++ / CMake+- 只有确认进入源码构建路径后,才补充 Rust / C++ / CMake- Windows 本地编译优先补 CMake 和 MinGW- 不要把源码构建依赖当作普通安装默认前置diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.mdindex a95684879..c5e514948 100644--- a/docs/zh/getting-started/05-cli-setup.md+++ b/docs/zh/getting-started/05-cli-setup.md@@ -13,7 +13,7 @@ CLI 会持续演进。请把 `ov --help` 和 `ov <command> --help` 作为当前## 本文配置什么-CLI 使用 `~/.openviking/ovcli.conf` 作为 active 客户端连接配置。+CLI 默认使用 `~/.openviking/ovcli.conf`。若设置了 `OPENVIKING_CLI_CONFIG_FILE`,普通命令读取该变量指定的文件;命名配置管理仍操作默认目录,切换后需确认实际生效的路径。创建命名配置时,`ov` 会把配置保存为 `~/.openviking/ovcli.conf.<name>`。切换配置时,`ov` 会把选中的已保存配置复制到 `~/.openviking/ovcli.conf`。@@ -53,7 +53,7 @@ CLI 使用 `~/.openviking/ovcli.conf` 作为 active 客户端连接配置。- 本地无鉴权服务通常不需要 API Key。- 除非用户选择本地自定义配置,否则 Agent 不应探测本地端口、curl 本地 health endpoint,或运行启动服务端的命令。-> **注意:** 最近的 CLI 版本(v0.3.23+)要求在运行大多数命令前先保存一个显示语言。在交互式终端中,CLI 会在首次使用时提示你选择;在非交互式 shell(Agent 或 CI)中,任何非豁免命令都会以 `2` 退出,直到你运行 `ov language en` 或 `ov language zh-CN`。只有 `ov language`/`ov lang`、`ov config add|edit|delete|list` 和 `ov config switch <name>` 是豁免的,因此请在下面的 `ov config validate`、`ov health` 和 `ov status` 检查之前先运行 `ov language <code>`。+> **注意:** 最近的 CLI 版本(v0.3.23+)要求在运行大多数命令前先保存一个显示语言。在交互式终端中,CLI 会在首次使用时提示你选择;在非交互式 shell(Agent 或 CI)中,任何非豁免命令都会以 `2` 退出,直到你运行 `ov language en` 或 `ov language zh-CN`。当前源码中的 help 请求、`ov language`/`ov lang`、`ov config add|edit|delete|list` 和 `ov config switch <name>` 可跳过语言设置,因此请在下面的 `ov config validate`、`ov health` 和 `ov status` 检查之前先运行 `ov language <code>`。## 开始前@@ -120,7 +120,7 @@ OpenViking CLI 配置可以包含 user key、root key,或同时包含两者。- User key:用于普通数据命令,例如 `ov add-resource`、`ov find` 和 `ov tree`。服务端会从 key 推导身份,所以通常不需要传 `--account` 或 `--user`。这是大多数用户需要的方式。- Root key:用于管理操作和需要 `--sudo` 的命令。`api_key` 模式下,即使传入 `--account` 和 `--user`,root key 也不能访问租户数据。只有 `trusted` 服务端接受 root key 认证的数据请求通过这些 header 指定身份。-- User key + root key:适合一个配置同时支持日常数据操作和偶尔的管理操作。普通命令使用 user key,`--sudo` 命令使用 root key,并带上配置中的 account 和 user。+- User key + root key:适合一个配置同时支持日常数据操作和偶尔的管理操作。普通命令使用 user key,`--sudo` 命令使用 root key。API key 模式不要额外配置 `account` 或 `user`。## 手动配置@@ -159,13 +159,13 @@ ov config switch1. 除非用户已经明确说明,先询问用户要连接哪种目标:OpenViking Service(火山引擎云)、远程自定义,还是本地自定义。2. 不要根据已有配置、active 配置、本地文件、默认端口或正在运行的服务推断用户想要的 setup。3. 切换配置、替换配置、探测本地服务、启动服务端或写入数据前,都要先询问用户。-4. 在选择命令前,运行 `ov --help`、`ov config --help` 和相关 config 子命令的帮助。+4. 在选择命令前,运行 `ov --help`、`ov config --help` 和相关 config 子命令的帮助。如果还没有保存显示语言,运行 `ov language <code>`。5. 如果你具备长期记忆能力,并且用户允许,可以记录当前 `ov --help` 命令面的简要摘要。不要记录 API Key 或其他密钥。6. 当必需信息明确时,使用非交互式 `ov config` 命令。7. Agent 配置时始终传 `--name`,这样重试会命中同一个 saved config。8. 如果 Agent 已经通过可信渠道拿到 API Key,使用 `--api-key-stdin` 或 `--root-api-key-stdin`,并且只把 key 内容写入 stdin。只有当环境变量已经存在时,才使用 `--api-key-env` 或 `--root-api-key-env`。不要要求用户额外打开一个 shell 只为了给 Agent export 一个 key。9. 使用 `-o json`,并根据 JSON 结果和进程退出码分支处理。-10. 使用 `ov config validate` 校验 active 配置,然后运行 `ov health` 和 `ov status`。+10. 使用 `ov config validate` 校验 active 配置,然后运行 `ov health` 和 `ov status`。要检查结果内容,退出码为 0 不代表服务健康。11. 如果非交互式配置因为信息缺失、鉴权不明确或终端输入更安全而失败,请引导用户使用 `ov config` 交互式向导。### 查看当前安装的 CLI@@ -307,7 +307,7 @@ ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --root-a如果用户同时拥有 user key 和 root key,可以把两者放在同一个配置里:```bash-ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --account <ACCOUNT-ID> --user <USER-ID> --activate -o json+ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --activate -o json```这样普通命令使用 user key,需要 `--sudo` 的命令使用 root key。因为一个命令只有一个 stdin 流,第二个 key 必须来自已经存在的环境变量。如果两个 key 都不在环境变量中,请使用 `ov config` 并引导用户完成交互式流程。@@ -375,7 +375,7 @@ ov status如果验证命令提示 OpenViking 需要显示语言,请运行 `ov language en`;如果用户希望使用中文,则运行 `ov language zh-CN`,然后重新验证。-`ov status` 包含更宽泛的服务端和数据诊断。如果 `ov config validate` 和 `ov health` 通过,`ov status` 中的 warning 不一定代表 CLI 配置失败。+`ov status` 包含更宽泛的服务端和数据诊断。先确认 `ov config validate` 成功,并检查 `ov health` 返回的 `healthy` 值。当前 `ov health` 和表格模式的 `ov status` 可能在报告异常时仍以 0 退出,自动化应解析结果内容。`ov status` 中与连接无关的 warning 不一定代表 CLI 配置失败。## 学习其他 CLI 命令@@ -387,7 +387,7 @@ ov config --helpov add-resource --help```-Agent 在运行不熟悉的命令前,应该重新查看帮助。如果 Agent 为用户维护长期记忆,并且用户允许,可以记录当前命令面的简要摘要,方便之后继续工作。不要记录密钥、原始配置文件或私有服务详情,除非用户明确要求。+运行不熟悉的命令前查看对应帮助,尤其是导入目标、异步等待和删除参数。## 凭证安全@@ -469,7 +469,7 @@ ov configCLI 配置完成后,使用 `ov --help` 和 `ov <command> --help` 继续了解其他命令。-添加资源会把数据写入 active OpenViking 服务端。如果你想做一个小演示,请选择你愿意存入服务端的资源。Agent 运行这类演示命令前,必须先征得用户同意。+添加资源会把数据写入 active OpenViking 服务端。如果你想做一个小演示,请选择你愿意存入服务端的资源。Agent 运行这类演示命令前,必须先征得用户同意。单纯验证连接无需写入资源。```bashov add-resource https://github.com/volcengine/OpenVikingdiff --git a/docs/zh/migration/01-user-peer-model.md b/docs/zh/migration/01-user-peer-model.mdindex c27c8d7e0..cfec68965 100644--- a/docs/zh/migration/01-user-peer-model.md+++ b/docs/zh/migration/01-user-peer-model.md@@ -2,6 +2,8 @@> **版本范围:** 本页记录 0.3.x 到 0.4.0 的历史迁移流程,不适用于当前版本的 Agent 目录。当前 `viking://agent/...` 统一表示账号内公共目录,已移除 Agent ID 路径兼容及其迁移、cleanup。当前 `admin migrate` 只处理旧 Session 数据。+当前部署请查阅[管理 API](../api/08-admin.md)中的旧数据迁移说明。历史迁移验证完成前,应保留原安装环境及其备份;本页命令不构成从 0.3.x 直接升级到最新版的流程。+本文面向已经运行 OpenViking 0.3.x 的用户,说明升级到 0.4.0 前后需要做什么、哪些旧用法仍然兼容、数据迁移如何执行,以及业务代码如何逐步迁移到新模型。## 是否需要升级