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: align MCP references with implementation (#3146)
yufeng0a14967f6b9c
diff --git a/docs/en/about/02-changelog.md b/docs/en/about/02-changelog.mdindex d471bdb16..c205f8561 100644--- a/docs/en/about/02-changelog.md+++ b/docs/en/about/02-changelog.md@@ -3,6 +3,55 @@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).+## v0.4.9 (2026-07-10)++### Highlights++- **Agent workspace isolation**: Codex, Claude Code, OpenCode, and Pi integrations gain workspace-derived peer identity for per-project memory, together with broader shared installer and hybrid MCP support.+- **Retrieval and memory correctness**: image search is supported, agent-only and peer-only memory scopes are respected, and nested rendered memory links are avoided.+- **Storage and security hardening**: local collection loading is serialized, VikingDB content writes are backend-aware, and Git submodule ingestion blocks SSRF targets.+- **VikingBot and platform fixes**: unified gateway routing and OpenViking authentication were added, with fixes for channel sender metadata, VLM-only configurations, Windows vector backends, and benchmark concurrency.++[Full Changelog](https://github.com/volcengine/OpenViking/compare/v0.4.8...v0.4.9)++## v0.4.8 (2026-07-08)++### Highlights++- **NVIDIA cuVS vector backend**: opt-in exact and approximate GPU retrieval, plus memory-aware fallback from the local backend.+- **Recursive web ingestion**: bounded same-site crawling with depth, page, path, and download-link controls, backed by Scrapy and trafilatura.+- **Memory v3 and training**: v3 extraction is the active pipeline, with streaming patch-merge updates and session train/eval support.+- **Agent plugin installation**: Codex and Claude Code support remote marketplaces and a stdio MCP proxy that shares `ovcli.conf` credentials with hooks.+- **Filesystem and RAGFS improvements**: backend-paged glob, stable directory-first ordering, and standard relative-path matching.++[Full Changelog](https://github.com/volcengine/OpenViking/compare/v0.4.7...v0.4.8)++## v0.4.7 (2026-07-02)++### Highlights++- **MCP local-file flow**: compact tool descriptions reduce context usage, while signed `temp_upload` tokens automatically ingest local uploads.+- **Filesystem and versioning**: filesystem attrs and account-level `.ovgitignore` rules expand metadata and snapshot controls.+- **SDK and authentication**: the Go SDK adds skill scoping and grep depth controls; OAuth client scopes are persisted and seeded API keys are supported.+- **Studio and setup UX**: Connection & Identity was redesigned, assumed accounts are pinned correctly, and initialization gains a TUI-style setup wizard.++[Full Changelog](https://github.com/volcengine/OpenViking/compare/v0.4.6...v0.4.7)++## v0.4.6 (2026-06-29)++### Highlights++- **VikingFS snapshot versioning**: Git-backed `commit`, `log`, `show`, and `restore` across HTTP, Python SDK, and CLI surfaces.+- **Whole-site ingestion**: sitemap, sitemap-index, RSS, and Atom imports produce watchable resource trees.+- **Shared Agent Skills**: `viking://agent/skills` is restored as the account-shared skill root, while user-private skills remain the default.+- **VikingDB BM25 grep and Studio metrics**: keyword retrieval and user-visible usage dashboards expand search and observability.++### Upgrade Notes++- Deployments upgrading from 0.3.x with legacy agent/session data should migrate and clean up on v0.4.5 before upgrading to v0.4.6 or later.++[Full Changelog](https://github.com/volcengine/OpenViking/compare/v0.4.5...v0.4.6)+## v0.4.5 (2026-06-24)### Highlightsdiff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.mdindex efbe29d99..4ce682ce9 100644--- a/docs/en/agent-integrations/03-openclaw.md+++ b/docs/en/agent-integrations/03-openclaw.md@@ -9,7 +9,7 @@ Source: [examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree| Component | Required Version || --- | --- || Node.js | >= 22 |-| OpenClaw | >= 2026.4.8 |+| OpenClaw | >= 2026.5.27 |The plugin connects to a running OpenViking server — see the [Deployment Guide](../guides/03-deployment.md) if you need one.diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex a5d9117fc..cdbd40f3c 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 memories will be automatically recalled with every prompt, captured after each turn, and committed before compaction. The plugin also connects Codex to OpenViking's `/mcp` endpoint, enabling the model to search, store, and manage memories directly.+Equip [Codex](https://developers.openai.com/codex) with persistent memory across sessions. Install it once, and memories will be automatically recalled with every prompt, captured after each turn, and committed before compaction. The plugin also connects Codex to OpenViking's `/mcp` endpoint, enabling the model to call tools such as `find`, `search`, `recall`, and `remember` directly.Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: Motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)diff --git a/docs/en/agent-integrations/06-mcp-clients.md b/docs/en/agent-integrations/06-mcp-clients.mdindex 4612f1629..dc625826d 100644--- a/docs/en/agent-integrations/06-mcp-clients.md+++ b/docs/en/agent-integrations/06-mcp-clients.md@@ -37,10 +37,14 @@ 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 / Codex+### Trae / Cursor / ChatGPTStandard `mcpServers` config as shown above — all verified with API key auth.+### Codex++For Codex, use the [Codex Memory Plugin](./04-codex.md). It supplies a stdio MCP proxy through the plugin manifest and keeps MCP credentials aligned with the lifecycle hooks.+### OpenCodeUse OpenCode's native `mcp` config in `~/.config/opencode/opencode.json`:@@ -71,26 +75,7 @@ See the [OAuth 2.1 Guide](../guides/11-oauth.md) and [Public Access Guide](../gu## Available tools-Once connected, OpenViking exposes 14 tools:--| Tool | Description |-|------|-------------|-| `search` | Semantic search across memories, resources, and skills |-| `read` | Read one or more `viking://` URIs |-| `list` | List entries under a `viking://` directory |-| `store` | Store messages into long-term memory |-| `add_resource` | Add a local file or URL as a resource |-| `grep` | Regex content search across `viking://` files |-| `glob` | Find files matching a glob pattern |-| `forget` | Delete a `viking://` URI |-| `code_outline` | Show a file's symbol structure |-| `code_search` | Search symbol names across a directory |-| `code_expand` | Return the full source of a single named symbol |-| `health` | Check OpenViking service health |-| `list_watches` | List auto-refresh subscriptions |-| `cancel_watch` | Cancel a watch task |--For tool parameters, progressive file upload, and advanced configuration, see the [MCP Integration Guide](../guides/06-mcp-integration.md).+Once connected, OpenViking exposes retrieval, memory, resource, watch, filesystem, and code-navigation tools. See the [MCP Integration Guide](../guides/06-mcp-integration.md#available-mcp-tools) for the canonical tool list, parameters, progressive file upload, and advanced configuration.## Troubleshootingdiff --git a/docs/en/api/07-system.md b/docs/en/api/07-system.mdindex ba84b90b5..db81939de 100644--- a/docs/en/api/07-system.md+++ b/docs/en/api/07-system.md@@ -611,7 +611,6 @@ Get queue system status (embedding and semantic processing queues). Shows pendin- `openviking/server/routers/observer.py:observer_queue` - HTTP route- `openviking/service/debug_service.py:ObserverService.queue` - Core implementation- `openviking/storage/observers/queue_observer.py` - Queue observer-- `crates/ov_cli/src/commands/observer.rs` - CLI command#### 2. Interface and Parameters@@ -861,11 +860,7 @@ curl -X GET http://localhost:1933/api/v1/observer/lock \print(client.observer.lock)```-**CLI**--```bash-ov observer transaction-```+The CLI does not currently expose a lock-specific observer subcommand. Use the HTTP API or Python SDK for this component; `ov observer system` includes it in the aggregate status.**Response Example**diff --git a/docs/en/api/11-snapshot.md b/docs/en/api/11-snapshot.mdindex 64a2dc568..1bbd8d08e 100644--- a/docs/en/api/11-snapshot.md+++ b/docs/en/api/11-snapshot.md@@ -24,10 +24,10 @@ In addition, account-level `.ovgitignore` exclusion rules can be managed (`get`/## Implementation-- HTTP routes: [snapshot.py](file:///cloudide/workspace/OpenViking/openviking/server/routers/snapshot.py), prefix `/api/v1/snapshot`.-- SDK namespace: [snapshot_namespace.py](file:///cloudide/workspace/OpenViking/openviking/snapshot_namespace.py), exposed as `client.snapshot.*`.-- Underlying semantics: `commit` / `restore` / `show` / `log` in [viking_fs.py](file:///cloudide/workspace/OpenViking/openviking/storage/viking_fs.py).-- CLI: the `SnapshotCmd` in [main.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/main.rs), subcommands in [snapshot.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/commands/snapshot.rs).+- HTTP routes: [snapshot.py](https://github.com/volcengine/OpenViking/blob/main/openviking/server/routers/snapshot.py), prefix `/api/v1/snapshot`.+- SDK namespace: [snapshot_namespace.py](https://github.com/volcengine/OpenViking/blob/main/openviking/snapshot_namespace.py), exposed as `client.snapshot.*`.+- Underlying semantics: `commit` / `restore` / `show` / `log` in [viking_fs.py](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/viking_fs.py).+- CLI: the `SnapshotCmd` in [main.rs](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/src/main.rs), subcommands in [snapshot.rs](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/src/commands/snapshot.rs).## API Reference@@ -544,7 +544,7 @@ client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], messagclient.close()```-For more end-to-end examples, see the [examples/snapshot/](file:///cloudide/workspace/OpenViking/examples/snapshot) directory in the repository, covering the SDK, HTTP, and CLI surfaces.+For more end-to-end examples, see the [examples/snapshot/](https://github.com/volcengine/OpenViking/tree/main/examples/snapshot) directory in the repository, covering the SDK, HTTP, and CLI surfaces.## Error Handlingdiff --git a/docs/en/guides/05-observability.md b/docs/en/guides/05-observability.mdindex bc20ed32e..83745edfd 100644--- a/docs/en/guides/05-observability.md+++ b/docs/en/guides/05-observability.md@@ -58,9 +58,12 @@ curl http://localhost:1933/api/v1/observer/system \"is_healthy": true,"errors": [],"components": {- "queue": {"name": "queue", "is_healthy": true, "has_errors": false},- "vikingdb": {"name": "vikingdb", "is_healthy": true, "has_errors": false},- "vlm": {"name": "vlm", "is_healthy": true, "has_errors": false}+ "queue": {"name": "queue", "is_healthy": true, "has_errors": false, "status": "..."},+ "vikingdb": {"name": "vikingdb", "is_healthy": true, "has_errors": false, "status": "..."},+ "models": {"name": "models", "is_healthy": true, "has_errors": false, "status": "..."},+ "lock": {"name": "lock", "is_healthy": true, "has_errors": false, "status": "..."},+ "retrieval": {"name": "retrieval", "is_healthy": true, "has_errors": false, "status": "..."},+ "filesystem": {"name": "filesystem", "is_healthy": true, "has_errors": false, "status": "..."}}}}@@ -72,7 +75,10 @@ curl http://localhost:1933/api/v1/observer/system \| --- | --- | --- || `GET /api/v1/observer/queue` | Queue | Processing queue status || `GET /api/v1/observer/vikingdb` | VikingDB | Vector database status |-| `GET /api/v1/observer/vlm` | VLM | Vision Language Model status |+| `GET /api/v1/observer/models` | Models | VLM, embedding, and rerank model status |+| `GET /api/v1/observer/lock` | Lock | Lock and transaction status |+| `GET /api/v1/observer/retrieval` | Retrieval | Retrieval quality metrics |+| `GET /api/v1/observer/filesystem` | Filesystem | Filesystem operation metrics |For example:diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex ff1fc7913..6f9625280 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -129,19 +129,21 @@ If you already have HTTPS configured, just connect to `https://your-server.com/m## Available MCP Tools-Once connected, OpenViking exposes 14 tools:+Once connected, OpenViking exposes 16 tools:| Tool | Description | Key Parameters ||------|-------------|----------------|-| `search` | Semantic search across memories, resources, and skills | `query`, `target_uri` (optional), `limit`, `min_score` |+| `find` | Fast semantic retrieval without session context | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional) |+| `search` | Deep semantic retrieval with optional session context and intent analysis | `query`, `target_uri` (optional), `session_id` (optional), `limit`, `min_score`, `level` (optional) |+| `recall` | Type-quota recall across memory categories | `query`, `quotas` (optional), `max_chars`, `min_score`, `peer_scope`, `other_peer_penalty` (optional) || `read` | Read one or more `viking://` URIs | `uris` (single string or array) || `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |-| `store` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |+| `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) || `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, such as `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}` for Feishu user-token watches) || `list_watches` | List watch tasks (auto-refresh subscriptions) visible to the current agent. Each entry shows target URI, refresh interval (minutes), active/paused status, and next scheduled execution time | none || `cancel_watch` | Cancel (delete) a watch task by its target URI. To change the cadence or pause temporarily, cancel and re-add with a new `watch_interval` | `to_uri` (must match the watch task's `to` value, e.g. `viking://resources/...`) |-| `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string), `case_insensitive` |-| `glob` | Find files matching a glob pattern | `pattern`, `uri` (optional scope) |+| `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string or array), `case_insensitive`, `node_limit` |+| `glob` | Find files matching a glob pattern | `pattern`, `uri` (optional scope), `node_limit` || `forget` | Delete any `viking://` URI (use `search` to find it first; pass `recursive=true` to delete a directory) | `uri`, `recursive` (optional) || `code_outline` | Show a file's symbol structure (classes, functions, methods, line ranges) without reading bodies. Survey a file before deciding what to `read`. | `uri` (must be a `viking://` **file** URI) || `code_search` | Search symbol names (class / function / method) by substring across a `viking://` directory. Returns symbol type, class context, file URI, line range. Scans up to 200 source files. | `query`, `uri` (must be a `viking://` directory; narrow to subdir for deeper coverage) |diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.mdindex f9b661929..1c226b385 100644--- a/docs/en/guides/08-encryption.md+++ b/docs/en/guides/08-encryption.md@@ -58,14 +58,17 @@ Edit `~/.openviking/ov.conf`:```pythonimport openviking as ovimport asyncio+from pathlib import Pathasync def test():client = ov.AsyncOpenViking(path="./data")await client.initialize()- # Add resource (automatically encrypted)- await client.add_resource("Hello, encrypted world!", reason="Test encryption")+ # add_resource expects a file path or URL+ sample = Path("./encrypted-sample.txt")+ sample.write_text("Hello, encrypted world!", encoding="utf-8")+ await client.add_resource(str(sample), reason="Test encryption")# Read resource (automatically decrypted)results = await client.find("encrypted")@@ -394,33 +397,24 @@ except Exception as e:### Migrating from Unencrypted to Encrypted-1. Back up existing data-2. Enable encryption (see above)-3. Re-import all resources:+Enabling encryption does not rewrite existing plaintext files. They remain readable for backward compatibility, while new writes use encryption. To encrypt existing public scopes, migrate them through OVPack into a new, empty encrypted storage environment:-```python-import openviking as ov-import asyncio---async def migrate():- client = ov.AsyncOpenViking(path="./data")- await client.initialize()+1. Stop application writes and create a logical backup while the original unencrypted environment is running:- # List all resources- resources = await client.list_resources()+```bash+ov backup ./backups/before-encryption.ovpack+```- for resource in resources:- # Read old resource (unencrypted)- content = await client.read_resource(resource["uri"])- # Re-write (automatically encrypted)- await client.add_resource(content, reason="Migrate to encrypted storage")+2. Stop OpenViking. Enable encryption and point the storage configuration at a **new, empty** workspace/backend. Keep the original data and encryption key backup until verification is complete.+3. Start the encrypted environment and restore the logical backup. Restore writes the package content through the encrypted storage layer:- await client.close()+```bash+ov restore ./backups/before-encryption.ovpack --on-conflict fail+```+4. Verify resource, user, session, and index data before switching traffic. OVPack excludes runtime/internal state such as queues, uploads, locks, watches, and relation files; recreate or validate those separately.-asyncio.run(migrate())-```+See [OVPack Import and Export](09-ovpack.md#full-backup-and-restore) for supported scopes and restore options.### Switching Key Providersdiff --git a/docs/en/guides/15-snapshot.md b/docs/en/guides/15-snapshot.mdindex 83a80389f..6e59a500c 100644--- a/docs/en/guides/15-snapshot.md+++ b/docs/en/guides/15-snapshot.md@@ -94,7 +94,7 @@ Configuration reference:After editing the config, restart the OpenViking service (or re-initialize the SDK client) for it to take effect.-> The repository ships ready-to-use examples: [ov.conf.git-local.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-local.example) and [ov.conf.git-s3-tos.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-s3-tos.example).+> The repository ships ready-to-use examples: [ov.conf.git-local.example](https://github.com/volcengine/OpenViking/blob/main/examples/snapshot/ov.conf.git-local.example) and [ov.conf.git-s3-tos.example](https://github.com/volcengine/OpenViking/blob/main/examples/snapshot/ov.conf.git-s3-tos.example).## Directory Layout Change: the `.ovgit` Directorydiff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.mdindex 1fe55dae9..ddaa372b5 100644--- a/docs/images/agents/en/codex.md+++ b/docs/images/agents/en/codex.md@@ -1,4 +1,4 @@-Add persistent, cross-session memory to [Codex](https://developers.openai.com/codex). Install it once, and the plugin will automatically recall memories before every user prompt, capture updates after each turn, and commit changes before compaction. It also connects Codex to OpenViking's `/mcp` endpoint, allowing the model to directly invoke tools like search and store.+Add persistent, cross-session memory to [Codex](https://developers.openai.com/codex). Install it once, and the plugin will automatically recall memories before every user prompt, capture updates after each turn, and commit changes before compaction. It also connects Codex to OpenViking's `/mcp` endpoint, allowing the model to directly invoke tools such as find, search, recall, and remember.Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: motivation and demo](https://blog.openviking.ai/post/openviking-coding-agent/)diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.mdindex f317e5912..05621966b 100644--- a/docs/images/agents/zh/codex.md+++ b/docs/images/agents/zh/codex.md@@ -1,4 +1,4 @@-为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆。一次安装,即可实现:在用户每次输入前自动召回记忆,每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将记忆提交给抽取器。该插件还将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 search、store 等工具来管理记忆。+为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆。一次安装,即可实现:在用户每次输入前自动召回记忆,每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将记忆提交给抽取器。该插件还将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 find、search、recall、remember 等工具来管理记忆。源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)diff --git a/docs/zh/about/02-changelog.md b/docs/zh/about/02-changelog.mdindex d825335f5..88e86e538 100644--- a/docs/zh/about/02-changelog.md+++ b/docs/zh/about/02-changelog.md@@ -3,6 +3,55 @@OpenViking 的所有重要变更都将记录在此文件中。此更新日志从 [GitHub Releases](https://github.com/volcengine/OpenViking/releases) 自动生成。+## v0.4.9 (2026-07-10)++### 重点更新++- **Agent 工作区隔离**:Codex、Claude Code、OpenCode 和 Pi 集成支持从工作区派生 peer identity,实现项目级记忆隔离,并扩展共享安装器与混合 MCP 支持。+- **检索与记忆正确性**:新增图片搜索,正确处理 agent-only / peer-only 记忆范围,并避免生成嵌套的记忆链接。+- **存储与安全加固**:串行化本地 collection 懒加载,按后端约束 VikingDB content 写入,并阻止 Git submodule SSRF。+- **VikingBot 与平台修复**:新增统一 gateway 路由和 OpenViking 鉴权,并修复渠道 sender metadata、仅 VLM 配置、Windows 向量后端和 benchmark 并发问题。++[完整变更记录](https://github.com/volcengine/OpenViking/compare/v0.4.8...v0.4.9)++## v0.4.8 (2026-07-08)++### 重点更新++- **NVIDIA cuVS 向量后端**:支持 opt-in 的 GPU 精确/近似检索,以及本地后端的显存感知回退。+- **递归网页导入**:基于 Scrapy 和 trafilatura,支持深度、页数、路径和下载链接限制的同站爬取。+- **记忆 v3 与训练**:启用 v3 抽取链路、流式 patch-merge 更新和 session train/eval。+- **Agent 插件安装**:Codex / Claude Code 支持远程 marketplace,stdio MCP 代理与 hooks 共享 `ovcli.conf` 凭据。+- **文件系统与 RAGFS**:支持后端分页 glob、稳定的目录优先排序和标准相对路径匹配。++[完整变更记录](https://github.com/volcengine/OpenViking/compare/v0.4.7...v0.4.8)++## v0.4.7 (2026-07-02)++### 重点更新++- **MCP 本地文件链路**:compact 工具描述降低上下文开销,签名 `temp_upload` token 支持本地文件自动入库。+- **文件系统与版本管理**:新增 filesystem attrs 和账号级 `.ovgitignore` 规则。+- **SDK 与鉴权**:Go SDK 新增 skill scope 和 grep 深度控制,OAuth client scope 持久化,并支持 seeded API key。+- **Studio 与初始化体验**:重做 Connection & Identity 页面,修正 assumed account,并新增 TUI 风格初始化向导。++[完整变更记录](https://github.com/volcengine/OpenViking/compare/v0.4.6...v0.4.7)++## v0.4.6 (2026-06-29)++### 重点更新++- **VikingFS 快照版本管理**:HTTP、Python SDK 和 CLI 支持 Git-backed `commit`、`log`、`show`、`restore`。+- **整站导入**:支持 sitemap、sitemap index、RSS 和 Atom,并可生成持续刷新的资源树。+- **共享 Agent Skills**:恢复 `viking://agent/skills` 账号级共享根,用户私有 skill 仍为默认目标。+- **VikingDB BM25 grep 与 Studio 指标**:增强关键词检索与用户可见的使用指标。++### 升级说明++- 从 0.3.x 升级且仍有 legacy agent/session 数据时,应先在 v0.4.5 完成迁移和 cleanup,再升级到 v0.4.6 或更高版本。++[完整变更记录](https://github.com/volcengine/OpenViking/compare/v0.4.5...v0.4.6)+## v0.4.5 (2026-06-24)### 重点更新diff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.mdindex 8af4e8f9d..9c2a3a3d0 100644--- a/docs/zh/agent-integrations/03-openclaw.md+++ b/docs/zh/agent-integrations/03-openclaw.md@@ -9,7 +9,7 @@| 组件 | 版本要求 || --- | --- || Node.js | >= 22 |-| OpenClaw | >= 2026.4.8 |+| OpenClaw | >= 2026.5.27 |插件需要连接到一个正在运行的 OpenViking 服务——参见 [部署指南](../guides/03-deployment.md)。diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex c558ecdec..b89be0fbd 100644--- a/docs/zh/agent-integrations/04-codex.md+++ b/docs/zh/agent-integrations/04-codex.md@@ -1,6 +1,6 @@# Codex 记忆插件-本插件旨在为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆功能。只需安装一次,即可实现:在每次用户输入前自动召回相关记忆,在每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将完整记录提交给记忆抽取器。同时,该插件将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 `search`、`store` 等工具来主动管理记忆。+本插件旨在为 [Codex](https://developers.openai.com/codex) 提供持久化的跨会话(session)记忆功能。只需安装一次,即可实现:在每次用户输入前自动召回相关记忆,在每轮对话结束后进行增量捕获,并在上下文压缩(compaction)前将完整记录提交给记忆抽取器。同时,该插件将 Codex 连接至 OpenViking 的 `/mcp` 端点,使模型能够直接调用 `find`、`search`、`recall`、`remember` 等工具来主动管理记忆。源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)diff --git a/docs/zh/agent-integrations/06-mcp-clients.md b/docs/zh/agent-integrations/06-mcp-clients.mdindex 68e4549d5..c5a41b528 100644--- a/docs/zh/agent-integrations/06-mcp-clients.md+++ b/docs/zh/agent-integrations/06-mcp-clients.md@@ -37,10 +37,14 @@ claude mcp add --transport http openviking \> 如果你需要免工具调用的自动召回与自动捕获,请使用 [Claude Code 记忆插件](./02-claude-code.md)。-### Trae / Cursor / ChatGPT / Codex+### Trae / Cursor / ChatGPT使用上面的标准 `mcpServers` 配置即可——均已通过 API Key 鉴权验证。+### Codex++Codex 请使用 [Codex 记忆插件](./04-codex.md)。插件通过 manifest 提供 stdio MCP 代理,并让 MCP 与生命周期 hooks 共用同一套凭据配置。+### OpenCode在 `~/.config/opencode/opencode.json` 中使用 OpenCode 原生 `mcp` 配置:@@ -71,26 +75,7 @@ HTTPS 配置、部署模板和完整授权流程详见 [OAuth 2.1 指南](../gui## 可用工具-连接后 OpenViking 暴露 14 个工具:--| 工具 | 说明 |-|------|------|-| `search` | 跨记忆、资源、技能的语义搜索 |-| `read` | 读取一个或多个 `viking://` URI |-| `list` | 列出 `viking://` 目录下的条目 |-| `store` | 存储消息到长期记忆 |-| `add_resource` | 添加本地文件或 URL 作为资源 |-| `grep` | 正则内容搜索 |-| `glob` | 按 glob 模式查找文件 |-| `forget` | 删除 `viking://` URI |-| `code_outline` | 展示文件的符号结构 |-| `code_search` | 跨目录搜索符号名 |-| `code_expand` | 返回单个符号的完整源码 |-| `health` | 检查 OpenViking 服务状态 |-| `list_watches` | 列出自动刷新订阅 |-| `cancel_watch` | 取消 watch 任务 |--工具参数、渐进式文件上传和高级配置见 [MCP 集成指南](../guides/06-mcp-integration.md)。+连接后,OpenViking 会提供检索、记忆、资源、watch、文件系统和代码导航工具。完整工具清单、参数、渐进式文件上传和高级配置见 [MCP 集成指南](../guides/06-mcp-integration.md#可用-mcp-工具)。## 故障排查diff --git a/docs/zh/api/07-system.md b/docs/zh/api/07-system.mdindex d82b612c4..aef1b2e82 100644--- a/docs/zh/api/07-system.md+++ b/docs/zh/api/07-system.md@@ -605,7 +605,6 @@ Observer API 提供详细的组件级监控。- `openviking/server/routers/observer.py:observer_queue` - HTTP 路由- `openviking/service/debug_service.py:ObserverService.queue` - 核心实现- `openviking/storage/observers/queue_observer.py` - 队列观察者-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令#### 2. 接口和参数说明@@ -855,11 +854,7 @@ curl -X GET http://localhost:1933/api/v1/observer/lock \print(client.observer.lock)```-**CLI**--```bash-ov observer transaction-```+CLI 目前没有单独的 lock observer 子命令。请使用 HTTP API 或 Python SDK 查询该组件;`ov observer system` 会在汇总状态中包含它。**响应示例**diff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.mdindex 6f0db13b8..fea142838 100644--- a/docs/zh/api/11-snapshot.md+++ b/docs/zh/api/11-snapshot.md@@ -24,10 +24,10 @@ OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力## API 实现介绍-- HTTP 路由:[snapshot.py](file:///cloudide/workspace/OpenViking/openviking/server/routers/snapshot.py),前缀 `/api/v1/snapshot`。-- 命名空间(SDK):[snapshot_namespace.py](file:///cloudide/workspace/OpenViking/openviking/snapshot_namespace.py),暴露为 `client.snapshot.*`。-- 底层语义实现:[viking_fs.py](file:///cloudide/workspace/OpenViking/openviking/storage/viking_fs.py) 的 `commit` / `restore` / `show` / `log`。-- CLI 命令:[main.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/main.rs) 的 `SnapshotCmd`,子命令 [snapshot.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/commands/snapshot.rs)。+- HTTP 路由:[snapshot.py](https://github.com/volcengine/OpenViking/blob/main/openviking/server/routers/snapshot.py),前缀 `/api/v1/snapshot`。+- 命名空间(SDK):[snapshot_namespace.py](https://github.com/volcengine/OpenViking/blob/main/openviking/snapshot_namespace.py),暴露为 `client.snapshot.*`。+- 底层语义实现:[viking_fs.py](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/viking_fs.py) 的 `commit` / `restore` / `show` / `log`。+- CLI 命令:[main.rs](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/src/main.rs) 的 `SnapshotCmd`,子命令 [snapshot.rs](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/src/commands/snapshot.rs)。## API 参考@@ -544,7 +544,7 @@ client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], messagclient.close()```-更多端到端示例参见仓库中的 [examples/snapshot/](file:///cloudide/workspace/OpenViking/examples/snapshot) 目录,涵盖 SDK、HTTP、CLI 三种调用方式。+更多端到端示例参见仓库中的 [examples/snapshot/](https://github.com/volcengine/OpenViking/tree/main/examples/snapshot) 目录,涵盖 SDK、HTTP、CLI 三种调用方式。## 错误处理diff --git a/docs/zh/guides/05-observability.md b/docs/zh/guides/05-observability.mdindex cd60140e7..f377b95fc 100644--- a/docs/zh/guides/05-observability.md+++ b/docs/zh/guides/05-observability.md@@ -58,9 +58,12 @@ curl http://localhost:1933/api/v1/observer/system \"is_healthy": true,"errors": [],"components": {- "queue": {"name": "queue", "is_healthy": true, "has_errors": false},- "vikingdb": {"name": "vikingdb", "is_healthy": true, "has_errors": false},- "vlm": {"name": "vlm", "is_healthy": true, "has_errors": false}+ "queue": {"name": "queue", "is_healthy": true, "has_errors": false, "status": "..."},+ "vikingdb": {"name": "vikingdb", "is_healthy": true, "has_errors": false, "status": "..."},+ "models": {"name": "models", "is_healthy": true, "has_errors": false, "status": "..."},+ "lock": {"name": "lock", "is_healthy": true, "has_errors": false, "status": "..."},+ "retrieval": {"name": "retrieval", "is_healthy": true, "has_errors": false, "status": "..."},+ "filesystem": {"name": "filesystem", "is_healthy": true, "has_errors": false, "status": "..."}}}}@@ -72,7 +75,10 @@ curl http://localhost:1933/api/v1/observer/system \| --- | --- | --- || `GET /api/v1/observer/queue` | Queue | 处理队列状态 || `GET /api/v1/observer/vikingdb` | VikingDB | 向量数据库状态 |-| `GET /api/v1/observer/vlm` | VLM | 视觉语言模型状态 |+| `GET /api/v1/observer/models` | Models | VLM、Embedding 和 Rerank 模型状态 |+| `GET /api/v1/observer/lock` | Lock | 锁和事务状态 |+| `GET /api/v1/observer/retrieval` | Retrieval | 检索质量指标 |+| `GET /api/v1/observer/filesystem` | Filesystem | 文件系统操作指标 |例如:diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex ec3ba88ce..da93871e7 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -121,19 +121,21 @@ claude mcp add --transport http openviking \## 可用的 MCP 工具-连接后,OpenViking MCP 端点暴露 14 个工具:+连接后,OpenViking MCP 端点暴露 16 个工具:| 工具 | 说明 | 主要参数 ||------|------|----------|-| `search` | 语义搜索记忆、资源和技能 | `query`, `target_uri`(可选), `limit`, `min_score` |+| `find` | 无 session 上下文的快速语义检索 | `query`, `target_uri`(可选), `limit`, `min_score`, `level`(可选) |+| `search` | 支持可选 session 上下文和意图分析的深度语义检索 | `query`, `target_uri`(可选), `session_id`(可选), `limit`, `min_score`, `level`(可选) |+| `recall` | 按记忆类别配额召回 | `query`, `quotas`(可选), `max_chars`, `min_score`, `peer_scope`, `other_peer_penalty`(可选) || `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) || `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) |-| `store` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |+| `remember` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) || `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,例如飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,飞书用户 token watch 使用 `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}`) || `list_watches` | 列出当前 Agent 可见的 watch 任务(自动刷新订阅),每行显示目标 URI、刷新间隔(分钟)、active/paused 状态以及下一次调度时间 | 无 || `cancel_watch` | 按目标 URI 取消(删除)watch 任务。若需调整刷新周期或临时暂停,请取消后使用新的 `watch_interval` 重新添加 | `to_uri`(必须匹配 watch 任务的 `to` 值,例如 `viking://resources/...`) |-| `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串), `case_insensitive` |-| `glob` | 按 glob 模式匹配文件 | `pattern`, `uri`(可选范围) |+| `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive`, `node_limit` |+| `glob` | 按 glob 模式匹配文件 | `pattern`, `uri`(可选范围), `node_limit` || `forget` | 删除任意 `viking://` URI(先用 `search` 查找;删除目录需 `recursive=true`) | `uri`, `recursive`(可选) || `code_outline` | 显示文件的符号结构(类、函数、方法及其行号范围),不读取实现体。在决定 `read` 之前用于快速浏览文件。 | `uri`(必须是 `viking://` **文件** URI) || `code_search` | 在 `viking://` 目录下按子串搜索符号名(类 / 函数 / 方法),返回符号类型、所属类、文件 URI、行号范围。最多扫描 200 个源文件。 | `query`, `uri`(必须是 `viking://` 目录;缩小到子目录可获得更深覆盖) |diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.mdindex 15dd2d6ca..da12b8d5d 100644--- a/docs/zh/guides/08-encryption.md+++ b/docs/zh/guides/08-encryption.md@@ -58,14 +58,17 @@ ov system crypto init-key --output ~/.openviking/master.key```pythonimport openviking as ovimport asyncio+from pathlib import Pathasync def test():client = ov.AsyncOpenViking(path="./data")await client.initialize()- # 添加资源(自动加密)- await client.add_resource("Hello, encrypted world!", reason="测试加密")+ # add_resource 接收文件路径或 URL+ sample = Path("./encrypted-sample.txt")+ sample.write_text("Hello, encrypted world!", encoding="utf-8")+ await client.add_resource(str(sample), reason="测试加密")# 读取资源(自动解密)results = await client.find("encrypted")@@ -394,33 +397,24 @@ except Exception as e:### 从无加密迁移到有加密-1. 备份现有数据-2. 启用加密(参考上文)-3. 重新导入所有资源:+启用加密不会改写已有明文文件。为了向后兼容,这些文件仍可读取;新写入的数据会使用加密。如需加密已有公开 scope,应通过 OVPack 将其迁移到全新的空加密存储环境:-```python-import openviking as ov-import asyncio---async def migrate():- client = ov.AsyncOpenViking(path="./data")- await client.initialize()+1. 停止业务写入,在原未加密环境运行时创建逻辑备份:- # 列出所有资源- resources = await client.list_resources()+```bash+ov backup ./backups/before-encryption.ovpack+```- for resource in resources:- # 读取旧资源(未加密)- content = await client.read_resource(resource["uri"])- # 重新写入(自动加密)- await client.add_resource(content, reason="迁移到加密存储")+2. 停止 OpenViking,启用加密,并将存储配置指向**全新的空** workspace/backend。验证完成前保留原数据和加密密钥备份。+3. 启动加密环境后恢复逻辑备份。恢复过程会通过加密存储层写入 package 内容:- await client.close()+```bash+ov restore ./backups/before-encryption.ovpack --on-conflict fail+```+4. 切流前验证资源、用户、session 和索引数据。OVPack 不包含 queue、upload、lock、watch 和 relation 文件等运行时/内部状态,这些内容需要单独重建或验证。-asyncio.run(migrate())-```+支持的 scope 和恢复选项详见 [OVPack 导入与导出](09-ovpack.md#全量备份与恢复)。### 切换密钥提供程序diff --git a/docs/zh/guides/15-snapshot.md b/docs/zh/guides/15-snapshot.mdindex 90aa519ab..aaa512c8c 100644--- a/docs/zh/guides/15-snapshot.md+++ b/docs/zh/guides/15-snapshot.md@@ -94,7 +94,7 @@修改配置后,重启 OpenViking 服务(或重新初始化 SDK 客户端)使其生效。-> 仓库中提供了可直接参考的完整示例:[ov.conf.git-local.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-local.example) 与 [ov.conf.git-s3-tos.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-s3-tos.example)。+> 仓库中提供了可直接参考的完整示例:[ov.conf.git-local.example](https://github.com/volcengine/OpenViking/blob/main/examples/snapshot/ov.conf.git-local.example) 与 [ov.conf.git-s3-tos.example](https://github.com/volcengine/OpenViking/blob/main/examples/snapshot/ov.conf.git-s3-tos.example)。## 目录结构变化:`.ovgit` 目录diff --git a/examples/claude-code-memory-plugin/README.md b/examples/claude-code-memory-plugin/README.mdindex b91e2e2a3..7c1c57b68 100644--- a/examples/claude-code-memory-plugin/README.md+++ b/examples/claude-code-memory-plugin/README.md@@ -318,7 +318,7 @@ Claude Code has a built-in `MEMORY.md` file system. This plugin **complements**│ │ │ │ (Python) ││ ┌────────────▼───────────▼───►│ ││ │ MCP tools (stdio proxy → /mcp) │- │ │ search / read / store / … │ │+ │ │ find/search/recall/remember/… │ │└─────────────────►│ │ │OV session └─────────────────────────────► │context inject └──────────────┘@@ -352,21 +352,9 @@ Disable with `claude_code.writePathAsync: false` if you need deterministic order### MCP tools available from the server-The plugin's `.mcp.json` starts a local stdio proxy, which connects to the OpenViking server's native HTTP MCP endpoint at `/mcp`. The server exposes 9 tools that Claude can call on demand:--| Tool | Description |-|----------------|-------------------------------------------------------------|-| `search` | Semantic search across memories, resources, and skills |-| `read` | Read one or more `viking://` URIs |-| `list` | List entries under a `viking://` directory |-| `store` | Store messages into long-term memory (triggers extraction) |-| `add_resource` | Add a local file or URL as a resource |-| `grep` | Regex content search across `viking://` files |-| `glob` | Find files matching a glob pattern |-| `forget` | Delete any `viking://` URI |-| `health` | Check OpenViking server health |--See the [MCP integration guide](../../docs/en/guides/06-mcp-integration.md) for tool parameters.+The plugin's `.mcp.json` starts a local stdio proxy, which connects to the OpenViking server's native HTTP MCP endpoint at `/mcp`. Claude can call the server's retrieval, memory, resource, watch, filesystem, and code-navigation tools on demand.++See the [MCP integration guide](../../docs/en/guides/06-mcp-integration.md) for the canonical tool list and parameters.### Plugin structurediff --git a/examples/claude-code-memory-plugin/README_CN.md b/examples/claude-code-memory-plugin/README_CN.mdindex 64306d5ef..93f0cc7f8 100644--- a/examples/claude-code-memory-plugin/README_CN.md+++ b/examples/claude-code-memory-plugin/README_CN.md@@ -314,7 +314,7 @@ Claude Code 自带 `MEMORY.md` 文件系统,本插件**与之互补**:│ │ │ │ (Python) ││ ┌────────────▼───────────▼───►│ ││ │ MCP tools (stdio proxy→/mcp) │- │ │ search / read / store / … │ │+ │ │ find/search/recall/remember/… │ │└─────────────────►│ │ │OV session └─────────────────────────────► │context inject └──────────────┘@@ -348,21 +348,9 @@ Claude Code 自带 `MEMORY.md` 文件系统,本插件**与之互补**:### 服务器暴露的 MCP 工具-插件的 `.mcp.json` 启动本地 stdio 代理,代理再连到 OpenViking 服务器原生 HTTP MCP endpoint `/mcp`。服务器暴露 9 个 Claude 可按需调用的工具:--| 工具 | 说明 |-|----------------|----------------------------------------------------|-| `search` | 跨 memories / resources / skills 的语义搜索 |-| `read` | 读一个或多个 `viking://` URI 的内容 |-| `list` | 列出 `viking://` 目录下条目 |-| `store` | 把消息存到长期记忆(触发抽取) |-| `add_resource` | 把本地文件 / URL 加为资源 |-| `grep` | 在 `viking://` 文件里做正则内容搜索 |-| `glob` | 按 glob 模式匹配文件 |-| `forget` | 删除任意 `viking://` URI |-| `health` | 检查 OpenViking 服务健康 |--工具参数详见 [MCP 集成指南](../../docs/zh/guides/06-mcp-integration.md)。+插件的 `.mcp.json` 启动本地 stdio 代理,代理再连到 OpenViking 服务器原生 HTTP MCP endpoint `/mcp`。Claude 可按需调用服务器提供的检索、记忆、资源、watch、文件系统和代码导航工具。++完整工具清单和参数详见 [MCP 集成指南](../../docs/zh/guides/06-mcp-integration.md)。### 插件结构diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.jsonindex ed434440f..393f84f13 100644--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json@@ -21,7 +21,7 @@"interface": {"displayName": "OpenViking Memory","shortDescription": "Long-term semantic memory for Codex",- "longDescription": "Hooks Codex's lifecycle to keep an external semantic memory: recall relevant memories on each UserPromptSubmit; on every Stop (turn end) append the new user/assistant turns to a long-lived OpenViking session keyed by codex session_id; on PreCompact commit that session so OV's extractor produces durable memories before context is summarized; on SessionStart(source=clear) commit any orphaned prior session before /clear discards it. Also exposes explicit MCP tools (recall, search, store, read, list, grep, glob, forget, add_resource, health) through a local stdio proxy to OpenViking's native streamable-HTTP /mcp endpoint for manual use.",+ "longDescription": "Hooks Codex's lifecycle to keep an external semantic memory: recall relevant memories on each UserPromptSubmit; on every Stop (turn end) append the new user/assistant turns to a long-lived OpenViking session keyed by codex session_id; on PreCompact commit that session so OV's extractor produces durable memories before context is summarized; on SessionStart(source=startup|clear) commit eligible orphaned sessions using the active-window and idle-TTL rules. Also exposes OpenViking's native MCP tools through a local stdio proxy to the streamable-HTTP /mcp endpoint for manual use.","developerName": "OpenViking","category": "Productivity","capabilities": [@@ -30,7 +30,7 @@"Pre-compaction memory extraction","Session archive search and original-text read-back","Resource ingestion for RAG (add_resource)",- "Explicit MCP tools: recall, search, store, read, list, grep, glob, forget, add_resource, health"+ "Explicit MCP tools for retrieval, memory, resources, watches, filesystem, and code navigation"],"websiteURL": "https://github.com/volcengine/OpenViking"}diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.mdindex aa326f973..1d016d5cc 100644--- a/examples/codex-memory-plugin/README.md+++ b/examples/codex-memory-plugin/README.md@@ -9,7 +9,7 @@ This is the Codex counterpart to [`claude-code-memory-plugin`](../claude-code-me- **Commit on `PreCompact`**: trigger OpenViking's memory extractor on the full pre-compact transcript before Codex summarizes it.- **Commit on `SessionStart` (source=startup|clear)**: active-window heuristic — if exactly one *other* state file was touched within the last 2 min, commit it (the just-ended session). On `≥2`, defer to idle-TTL sweep at the tail. `source=resume` never commits or sweeps; if the live OV session was already committed, it may inject the latest archive summary for continuity. See `DESIGN.md` for the full decision tree.-It also starts a local stdio MCP proxy that forwards to OpenViking's native `/mcp` endpoint with credentials resolved from env / `ovcli.conf`, so the model has direct access to the `search`, `store`, `read`, `list`, `grep`, `glob`, `forget`, `add_resource`, and `health` tools.+It also starts a local stdio MCP proxy that forwards to OpenViking's native `/mcp` endpoint with credentials resolved from env / `ovcli.conf`, so the model has direct access to the server's retrieval, memory, resource, watch, filesystem, and code-navigation tools.## Quick Start@@ -159,9 +159,9 @@ Earlier plugin versions configured tuning fields under a `codex` block in `~/.op│ /api/v1/content/read │└─────────────────┬─────────────────────────┘│- Codex ◄── stdio MCP proxy ──► /mcp (search, store, read, list,- (env/ovcli.conf) grep, glob, forget,- add_resource, health)+ Codex ◄── stdio MCP proxy ──► /mcp (find, search, recall,+ (env/ovcli.conf) remember, resources, watches,+ filesystem, code navigation)```The checked-in `.mcp.json` starts `servers/mcp-proxy.mjs` with `node`. The proxy keeps stdout protocol-clean, reads the same credential sources as the hooks, sends auth and identity headers to `/mcp`, caches the server `mcp-session-id`, and transparently reinitializes once if the server restarts.diff --git a/examples/codex-memory-plugin/scripts/marketplace.test.mjs b/examples/codex-memory-plugin/scripts/marketplace.test.mjsindex e69721846..a8691009a 100644--- a/examples/codex-memory-plugin/scripts/marketplace.test.mjs+++ b/examples/codex-memory-plugin/scripts/marketplace.test.mjs@@ -21,9 +21,14 @@ const pluginDir = resolve(scriptsDir, "..");const repoRoot = resolve(scriptsDir, "..", "..", "..");const catalogPath = join(repoRoot, ".agents", "plugins", "marketplace.json");const manifestPath = join(pluginDir, ".codex-plugin", "plugin.json");+const mcpEndpointPath = join(repoRoot, "openviking", "server", "mcp_endpoint.py");const PLUGIN_NAME = "openviking-memory";-const REAL_MCP_TOOLS = ["recall", "search", "store", "read", "list", "grep", "glob", "forget", "add_resource", "health"];+const REAL_MCP_TOOLS = [+ "find", "search", "recall", "read", "list", "remember", "add_resource",+ "list_watches", "cancel_watch", "grep", "glob", "forget", "code_outline",+ "code_search", "code_expand", "health",+];const LEGACY_TOOL_NAMES = ["openviking_recall", "openviking_store", "openviking_forget", "openviking_health"];function readJson(path) {@@ -114,14 +119,11 @@ test("required plugin files are present", () => {}});-test("plugin.json describes the real MCP tools, not the legacy names", () => {+test("plugin.json does not describe legacy MCP tool names", () => {const manifest = readJson(manifestPath);- const longDesc = manifest.interface?.longDescription || "";+ const interfaceText = JSON.stringify(manifest.interface || {});for (const legacy of LEGACY_TOOL_NAMES) {- assert.ok(!longDesc.includes(legacy), `longDescription must not reference legacy tool name "${legacy}"`);- }- for (const tool of ["recall", "search", "add_resource", "health"]) {- assert.ok(longDesc.includes(tool), `longDescription should mention real tool "${tool}"`);+ assert.ok(!interfaceText.includes(legacy), `plugin interface must not reference legacy tool name "${legacy}"`);}});@@ -155,7 +157,10 @@ test(".mcp.json starts the stdio MCP proxy from the plugin root", () => {execFileSync("node", ["--check", join(pluginDir, "servers", "mcp-proxy.mjs")], { stdio: "pipe" });});-test("plugin.json keeps the canonical tool list available for reference", () => {- // Sanity: the documented tool set is the one we assert against above.- assert.equal(REAL_MCP_TOOLS.length, 10);+test("canonical MCP tool list matches server registrations", () => {+ const source = readFileSync(mcpEndpointPath, "utf-8");+ const registered = [+ ...source.matchAll(/@mcp\.tool\((?:name="([a-z_]+)")?\)\s*\nasync def ([a-z_]+)\(/g),+ ].map((match) => match[1] || match[2]);+ assert.deepEqual(registered, REAL_MCP_TOOLS);});diff --git a/examples/openclaw-plugin/docs/openviking-openclaw-plugin-guide.md b/examples/openclaw-plugin/docs/openviking-openclaw-plugin-guide.mdindex 748ca9867..ad75c3b0f 100644--- a/examples/openclaw-plugin/docs/openviking-openclaw-plugin-guide.md+++ b/examples/openclaw-plugin/docs/openviking-openclaw-plugin-guide.md@@ -252,7 +252,7 @@ transformContext auto recall 流程:| `POST /api/v1/system/wait` | 等待 semantic/vector 队列处理完成 | 暂未单独封装;`/add-resource`、opt-in `add_resource`、`add_skill` 可用 `wait=true` | 导入后马上检索时建议等待 || `GET /api/v1/observer/queue` | 队列指标 | 暂未封装 | 排查资源/skill 处理积压 || `GET /api/v1/observer/vikingdb` | VikingDB collection/vector 状态 | 暂未封装 | 排查向量库连接和索引数量 |-| `GET /api/v1/observer/vlm` | VLM token 用量 | 暂未封装 | 观测摘要、抽取、视觉处理成本 |+| `GET /api/v1/observer/models` | 模型状态 | 暂未封装 | 观测 VLM、Embedding 和 Rerank 模型状态 || `GET /api/v1/observer/system` | 汇总 observer 状态 | 暂未封装 | 生产监控推荐项 || `GET /api/v1/debug/health` | 认证版健康检查 | 暂未封装 | 返回 `{ healthy: true/false }` |diff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.mdindex 2dc03384a..df00156ba 100644--- a/examples/pi-coding-agent-extension/README.md+++ b/examples/pi-coding-agent-extension/README.md@@ -243,7 +243,7 @@ Both plugins share the same core design (informed by each other):|---------------------|----------------------------------------|----------------------------------------|| Architecture | Hook scripts (.mjs) + MCP delegation | Native TypeScript extension || Recall timing | Synchronous (UserPromptSubmit hook) | Synchronous (context event) |-| Tool delivery | OV server's MCP endpoint (9 tools) | pi.registerTool() (7 tools) |+| Tool delivery | OV server's MCP endpoint (16 tools) | pi.registerTool() (7 tools) || Write path | Detached worker (async) | Async promise (pi's event loop) || Installation | `claude plugin install` + setup script | Copy directory → auto-discovered || Memory index | None (flashlight search model) | Built (map model — model sees what OV knows) |diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex a5c93c83a..fcf98f255 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -957,7 +957,9 @@ async def mcp_lifespan():"""Run the MCP session manager. Call this inside the FastAPI lifespan."""async with mcp.session_manager.run():logger.info(- "MCP endpoint ready (13 tools: find, search, read, list, remember, add_resource, grep, glob, code_outline, code_search, code_expand, forget, health)"+ "MCP endpoint ready (16 tools: find, search, recall, read, list, remember, "+ "add_resource, list_watches, cancel_watch, grep, glob, forget, code_outline, "+ "code_search, code_expand, health)")yield