Skip to content

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

docs: revamp README — sell first, link detail to docs.openviking.ai (#3395)

Zayn Jarvis94827db8f560
diff --git a/README.md b/README.md
index 4ab383006..5e86b0d32 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
English / [中文](README_CN.md) / [日本語](README_JA.md)
-<a href="https://www.openviking.ai">Website</a> · <a href="https://openviking.ai/studio">Live Demo</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="./docs">Docs</a>
+<a href="https://www.openviking.ai">Website</a> · <a href="https://openviking.ai/studio">Live Demo</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://docs.openviking.ai/">Docs</a>
[![](https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff\&labelColor=black\&logo=github\&style=flat-square)](https://github.com/volcengine/OpenViking/releases)
[![](https://img.shields.io/github/stars/volcengine/OpenViking?labelColor\&style=flat-square\&color=ffcb47)](https://github.com/volcengine/OpenViking)
@@ -21,7 +21,7 @@ English / [中文](README_CN.md) / [日本語](README_JA.md)
👋 Join our Community
-📱 <a href="./docs/en/about/01-about-us.md#lark-group">Lark Group</a> · <a href="./docs/en/about/01-about-us.md#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
+📱 <a href="https://docs.openviking.ai/en/about/01-about-us#lark-group">Lark Group</a> · <a href="https://docs.openviking.ai/en/about/01-about-us#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
<a href="https://trendshift.io/repositories/19668" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19668" alt="volcengine%2FOpenViking | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
@@ -29,564 +29,95 @@ English / [中文](README_CN.md) / [日本語](README_JA.md)
***
-✨ **May 2026 Update**: Updated OpenViking benchmark results across User Memory, Agent Memory, and Knowledge Base QA scenarios. → See [Evaluation Highlights](#evaluation-highlights).
+## What is OpenViking
-## Overview
+OpenViking is an open-source context database for AI agents. It stores memories, resources, and skills as one virtual filesystem under the `viking://` protocol, so an agent browses its own context with `ls`, `tree`, and `find` instead of querying a black-box vector store. Content is processed into three tiers — L0 abstract, L1 overview, L2 details — and loaded on demand. Every retrieval leaves a trajectory you can watch and debug. Full introduction: [Getting started](https://docs.openviking.ai/en/getting-started/01-introduction).
-### Challenges in Agent Development
+[![OpenViking Studio playground](docs/images/studio-playground.png)](https://openviking.ai/studio)
-In the AI era, data is abundant, but high-quality context is hard to come by. When building AI Agents, developers often face these challenges:
+*The [OpenViking Studio](https://openviking.ai/studio) playground — a live demo you can open in the browser, no installation required.*
-- **Fragmented Context**: Memories are in code, resources are in vector databases, and skills are scattered, making them difficult to manage uniformly.
-- **Surging Context Demand**: An Agent's long-running tasks produce context at every execution. Simple truncation or compression leads to information loss.
-- **Poor Retrieval Effectiveness**: Traditional RAG uses flat storage, lacking a global view and making it difficult to understand the full context of information.
-- **Unobservable Context**: The implicit retrieval chain of traditional RAG is like a black box, making it hard to debug when errors occur.
-- **Limited Memory Iteration**: Current memory is just a record of user interactions, lacking Agent-related task memory.
+## Why OpenViking
-### The OpenViking Solution
+- **One filesystem for all context.** Memories, resources, and skills each get a `viking://` URI. Agents locate and manipulate context deterministically, like a developer working with files. → [Viking URI](https://docs.openviking.ai/en/concepts/04-viking-uri) · [Context types](https://docs.openviking.ai/en/concepts/02-context-types)
+- **Tiered loading cuts token spend.** Every entry is processed into L0 (abstract), L1 (overview), and L2 (details) on write, then loaded only as deep as the task requires. → [Context layers](https://docs.openviking.ai/en/concepts/03-context-layers)
+- **Directory recursive retrieval.** Vector search first locates the highest-scoring directory, then drills down layer by layer, so results arrive with their surrounding context intact. → [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval)
+- **Observable retrieval.** Each query preserves its directory-browsing trajectory. When a result looks wrong, you can see exactly which path produced it. → [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval)
+- **Sessions become memory.** After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory. → [Session](https://docs.openviking.ai/en/concepts/08-session)
-**OpenViking** is an open-source **Context Database** designed specifically for AI Agents.
+How the pieces fit together: [Architecture](https://docs.openviking.ai/en/concepts/01-architecture). The thinking behind the design: [The Database Paradigm for Context Engineering](https://blog.openviking.ai/post/openviking-context-database/).
-We aim to define a minimalist context interaction paradigm for Agents, allowing developers to completely say goodbye to the hassle of context management. OpenViking abandons the fragmented vector storage model of traditional RAG and innovatively adopts a **"file system paradigm"** to unify the structured organization of memories, resources, and skills needed by Agents.
-
-With OpenViking, developers can build an Agent's brain just like managing local files:
-
-- **Filesystem Management Paradigm** → **Solves Fragmentation**: Unified context management of memories, resources, and skills based on a filesystem paradigm.
-- **Tiered Context Loading** → **Reduces Token Consumption**: L0/L1/L2 three-tier structure, loaded on demand, significantly saving costs.
-- **Directory Recursive Retrieval** → **Improves Retrieval Effect**: Supports native filesystem retrieval methods, combining directory positioning with semantic search to achieve recursive and precise context acquisition.
-- **Visualized Retrieval Trajectory** → **Observable Context**: Supports visualization of directory retrieval trajectories, allowing users to clearly observe the root cause of issues and guide retrieval logic optimization.
-- **Automatic Session Management** → **Context Self-Iteration**: Automatically compresses content, resource references, tool calls, etc., in conversations, extracting long-term memory, making the Agent smarter with use.
-
-## Quick Start
-
-> 💡 **Want to see it in action first?** Try [OpenViking Studio](https://openviking.ai/studio) — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required.
-
-### OpenViking Helper for macOS and Windows (Beta)
-
-**OpenViking Helper** is a desktop app for OpenViking users. It brings local agent setup, session traces, memories, and skills into a visual console, making it easier to verify setup and sync local context into OpenViking.
-
-Highlights:
-
-- **Visual local Agent setup**: Detect OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configure supported plugin, MCP, Hook, and CLI integrations.
-- **Session trace inspection**: Parse Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events.
-- **Local memory and skill management**: View local memory / rule files and `SKILL.md` skills, then sync them to OpenViking.
-
-> OpenViking Helper is currently in beta and supports macOS and Windows x64.
-
-Download:
-
-- [macOS Apple Silicon (arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
-- [macOS Intel (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
-- [Windows (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-
-### Local Deployment
-
-#### Prerequisites
-
-Before starting with OpenViking, please ensure your environment meets the following requirements:
-
-- **Python Version**: 3.10 or higher
-- **Rust Toolchain**: Cargo (Required for building RAGFS and CLI components from source)
-- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions)
-- **Operating System**: Linux, macOS, Windows
-- **Network Connection**: A stable network connection is required (for downloading dependencies and accessing model services)
-
-#### 1. Installation
-
-##### Python Package
-
-```bash
-pip install openviking --upgrade --force-reinstall
-```
-
-##### Rust CLI (Optional)
-
-```bash
-npm i -g @openviking/cli
```
+viking://
+├── resources/ # Resources: project docs, repos, web pages, etc.
+│ └── my_project/
+│ ├── docs/
+│ │ ├── api/
+│ │ └── tutorials/
+│ └── src/
+└── user/
+ └── {user_id}/
+ ├── memories/
+ │ └── preferences/
+ │ ├── writing_style
+ │ └── coding_habits
+ ├── resources/
+ │ └── private_project/
+ ├── skills/
+ │ ├── search_code
+ │ └── analyze_data
+ └── peers/
+ └── web-visitor-alice/
+```
+
+The three loading tiers:
+
+- **L0 (Abstract)**: a one-sentence summary for quick relevance checks.
+- **L1 (Overview)**: core information and usage scenarios for planning.
+- **L2 (Details)**: the full original data, read only when needed.
+
+Each directory carries its own L0/L1 layers, so relevance can be judged before any full file is read:
-Or build from source:
-
-```bash
-cargo install --git https://github.com/volcengine/OpenViking ov_cli
-```
-
-#### 2. Model Preparation
-
-OpenViking requires the following model capabilities:
-
-- **VLM Model**: For image and content understanding
-- **Embedding Model**: For vectorization and semantic retrieval
-
-##### Supported VLM Providers
-
-OpenViking supports multiple VLM providers:
-
-| Provider | Description | Setup |
-| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `volcengine` | Volcengine Doubao Models | [Volcengine Console](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new\&utm_content=OpenViking\&utm_medium=devrel\&utm_source=OWO\&utm_term=OpenViking) |
-| `openai` | OpenAI Official API | [OpenAI Platform](https://platform.openai.com) |
-| `openai-codex` | Codex VLM | Use `openviking-server init` |
-| `kimi` | Kimi Code Membership | Use `openviking-server init` |
-| `glm` | GLM Coding Plan | Use `openviking-server init` |
-
-##### Provider-Specific Notes
-
-<details>
-<summary><b>Volcengine (Doubao)</b></summary>
-
-Volcengine supports both model names and endpoint IDs. Using model names is recommended for simplicity:
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "doubao-seed-2-0-lite-260428",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-You can also use endpoint IDs (found in [Volcengine ARK Console](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new\&utm_content=OpenViking\&utm_medium=devrel\&utm_source=OWO\&utm_term=OpenViking):
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "ep-20241220174930-xxxxx",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>OpenAI</b></summary>
-
-Use OpenAI's official API:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://api.openai.com/v1"
- }
-}
-```
-
-You can also use a custom OpenAI-compatible endpoint:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://your-custom-endpoint.com/v1"
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>OpenAI Codex (OAuth)</b></summary>
-
-Use this provider when you want OpenViking to call Codex VLM through your ChatGPT/Codex OAuth session instead of a standard OpenAI API key:
-
-```bash
-openviking-server init
-# choose OpenAI Codex when prompted
-openviking-server doctor
-```
-
-```json
-{
- "vlm": {
- "provider": "openai-codex",
- "model": "gpt-5.3-codex",
- "api_base": "https://chatgpt.com/backend-api/codex",
- "temperature": 0.0,
- "max_retries": 2
- }
-}
-```
-
-> 💡 **Tip**:
->
-> - `openai-codex` does not require `vlm.api_key` when Codex OAuth is available
-> - OpenViking stores its own Codex auth state at `~/.openviking/codex_auth.json`
-> - `openviking-server doctor` validates that the current Codex auth is usable
-
-</details>
-
-<details>
-<summary><b>Kimi Coding (Subscription)</b></summary>
-
-Use this provider when you want OpenViking to call the dedicated Kimi Coding subscription endpoint directly:
-
-```bash
-openviking-server init
-# choose Kimi Coding when prompted
-openviking-server doctor
-```
-
-```json
-{
- "vlm": {
- "provider": "kimi",
- "model": "kimi-code",
- "api_key": "your-kimi-subscription-api-key",
- "api_base": "https://api.kimi.com/coding",
- "temperature": 0.0,
- "max_retries": 2
- }
-}
-```
-
-> 💡 **Tip**:
->
-> - `kimi` applies the recommended Kimi Coding defaults automatically, including the default Kimi Coding user agent
-> - `kimi-code` and `kimi-coding` are accepted aliases for the provider name
-> - `kimi-code` is normalized to Kimi's upstream coding model automatically
-
-</details>
-
-<details>
-<summary><b>GLM Coding Plan (Subscription)</b></summary>
-
-Use this provider when you want OpenViking to call Z.AI's OpenAI-compatible Coding Plan endpoint directly:
-
-```bash
-openviking-server init
-# choose GLM Coding Plan when prompted
-openviking-server doctor
-```
-
-```json
-{
- "vlm": {
- "provider": "glm",
- "model": "glm-4.6v",
- "api_key": "your-zai-api-key",
- "api_base": "https://api.z.ai/api/coding/paas/v4",
- "temperature": 0.0,
- "max_retries": 2
- }
-}
-```
-
-> 💡 **Tip**:
->
-> - `glm`, `zhipu`, `zai`, `z-ai`, and `z.ai` all resolve to the same first-class GLM provider
-> - The default endpoint is the Coding Plan endpoint, not the general Z.AI endpoint
-> - Use a vision-capable model such as `glm-4.6v` or `glm-5v-turbo` for multimodal parsing
-
-</details>
-
-#### 3. Environment Configuration
-
-##### Quick Setup for Local Models (Ollama)
-
-If you want to run OpenViking with local models via [Ollama](https://ollama.ai), the interactive setup wizard handles everything automatically:
-
-```bash
-openviking-server init
-```
-
-The wizard will:
-
-- Detect and install Ollama if needed
-- Recommend and pull suitable embedding and VLM models for your hardware
-- Generate a ready-to-use `ov.conf` configuration file
-
-To validate your setup at any time:
-
-```bash
-openviking-server doctor
-```
-
-`doctor` checks local prerequisites (config file, Python version, embedding/VLM provider connectivity, disk space) without requiring a running server.
-
-> For cloud API providers (Volcengine, OpenAI, Gemini, etc.), continue with the manual configuration below.
-
-##### Server Configuration Template
-
-The recommended first-time flow is:
-
-```bash
-openviking-server init
-openviking-server doctor
-```
-
-If you choose `OpenAI Codex` inside `openviking-server init`, the wizard can import existing Codex auth or start the Codex sign-in flow for you.
-
-If you prefer manual configuration, create `~/.openviking/ov.conf`, remove the comments before copy:
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // Log output: "stdout" or "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "<api-endpoint>", // API endpoint address
- "api_key" : "<your-api-key>", // Model service API Key
- "provider" : "<provider-type>", // Provider type: "volcengine" or "openai" (currently supported)
- "dimension": 1024, // Vector dimension
- "model" : "<model-name>" // Embedding model name (e.g., doubao-embedding-vision-251215 or text-embedding-3-large)
- },
- "max_concurrent": 10, // Max concurrent embedding requests (default: 10)
- "text_source": "content_only", // Text file vectorization source: content_only|summary_first|summary_only
- "max_input_tokens": 4096 // Max estimated raw text tokens sent to embedding
- },
- "vlm": {
- "api_base" : "<api-endpoint>", // API endpoint address
- "api_key" : "<your-api-key>", // Model service API Key (optional for openai-codex)
- "provider" : "<provider-type>", // Provider type (volcengine, openai, openai-codex, kimi, glm, etc.)
- "model" : "<model-name>", // VLM model name (e.g., doubao-seed-2-0-lite-260428 or gpt-4-vision-preview)
- "max_concurrent": 64 // Max concurrent LLM calls for semantic processing (default: 64)
- }
-}
-```
-
-> **Note**: For embedding models, supported providers are `volcengine` (Doubao), `openai`, `azure`, `jina`, `ollama`, `voyage`, `dashscope`, `minimax`, `cohere`, `vikingdb`, `gemini` (requires `pip install "google-genai>=1.0.0"`), `litellm`, and `local`. For VLM models, common providers include `volcengine`, `openai`, `openai-codex`, `kimi`, and `glm`.
-
-> **Memory config**: OpenViking always uses the v3 memory extraction pipeline. The legacy `memory.version` setting is deprecated and ignored; existing configs that set it still load without changing behavior.
-
-> **Memory schema scope**: Memory schema YAML defaults to `stage: "user"` and `peer_enabled: true`. Use `stage: "agent"` for execution-derived schemas such as trajectories/experiences, and set `peer_enabled: false` when a schema must stay in the current user's memory directory instead of peer directories.
-
-##### Server Configuration Examples
-
-👇 Expand to see the configuration example for your model service:
-
-<details>
-<summary><b>Example 1: Using Volcengine (Doubao Models)</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // Log output: "stdout" or "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "dimension": 1024,
- "model" : "doubao-embedding-vision-251215"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "model" : "doubao-seed-2-0-lite-260428",
- "max_concurrent": 64
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Example 2: Using OpenAI Models</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // Log output: "stdout" or "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "dimension": 3072,
- "model" : "text-embedding-3-large"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "model" : "gpt-4-vision-preview",
- "max_concurrent": 64
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Example 3: Using Google Gemini Embedding</b></summary>
-
-Install the required package first:
-
-```bash
-pip install "google-genai>=1.0.0"
-```
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "embedding": {
- "dense": {
- "provider": "gemini",
- "api_key": "your-google-api-key",
- "model": "gemini-embedding-2-preview",
- "dimension": 3072
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "model" : "gpt-4o",
- "max_concurrent": 64
- }
-}
-```
-
-Get your Google API key at <https://aistudio.google.com/apikey>
-
-</details>
-
-<details>
-<summary><b>Example 4: Using Volcengine Embedding + Codex VLM</b></summary>
-
-Use `openviking-server init` and choose `OpenAI Codex`, then run `openviking-server doctor`.
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "dimension": 1024,
- "model" : "doubao-embedding-vision-251215"
- }
- },
- "vlm": {
- "api_base" : "https://chatgpt.com/backend-api/codex",
- "provider" : "openai-codex",
- "model" : "gpt-5.3-codex",
- "max_concurrent": 64
- }
-}
-```
-
-</details>
-
-##### Set Server Configuration Environment Variable
-
-After creating the configuration file, set the environment variable to point to it (Linux/macOS):
-
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # by default
-```
-
-On Windows, use one of the following:
-
-PowerShell:
-
-```powershell
-$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"
-```
-
-Command Prompt (cmd.exe):
-
-```bat
-set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"
-```
-
-> 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable.
-
-##### CLI/Client Configuration Examples
-
-You can initialize the configuration of the CLI/client interactively through the `ov config` command. If you have multiple openviking servers, you can also switch to other configurations using the `ov config switch` command.
-
-👇 Expand to see the configuration example for your CLI/Client:
-<details>
-<summary><b>Example: ovcli.conf for visiting localhost server</b></summary>
-
-
-```json
-{
- "url": "http://localhost:1933",
- "timeout": 60.0
-}
```
-
-After creating the configuration file, set the environment variable to point to it (Linux/macOS):
-
-```bash
-export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # by default
+viking://resources/my_project/
+├── .abstract # L0: ~100 tokens - quick relevance check
+├── .overview # L1: ~2k tokens - structure and key points
+└── docs/
+ ├── .abstract
+ ├── .overview
+ └── api/
+ ├── auth.md # L2: full content, loaded on demand
+ └── endpoints.md
```
-On Windows, use one of the following:
+## Proof it works
-PowerShell:
+OpenViking 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the [benchmark report](https://blog.openviking.ai/post/openviking-benchmark-results/); reproduction scripts live in [./benchmark](./benchmark).
-```powershell
-$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"
-```
-
-Command Prompt (cmd.exe):
-
-```bat
-set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"
-```
-</details>
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/benchmark-dark.svg">
+ <img alt="Benchmark results. LoCoMo accuracy: OpenClaw 24.20% native vs 82.08% with OpenViking; Hermes 33.38% vs 82.86%; Claude Code 57.21% vs 80.32%. tau2-bench task success: Retail 70.94% vs 77.81%; Airline 54.38% vs 66.25%." src="docs/images/benchmark-light.svg">
+</picture>
-#### 4. Run Your First Example
+- **User memory (LoCoMo)**: with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%.
+- **Agent experience (tau2-bench)**: experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.
-> 📝 **Prerequisite**: Ensure you have completed the configuration (ov.conf and ovcli.conf) in the previous step.
+## Quick start
-Now let's run a complete example to experience the core features of OpenViking.
+> 💡 **Want to see it in action first?** Try [OpenViking Studio](https://openviking.ai/studio) — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required.
-##### Launch Server
+Requires Python 3.10 or higher.
```bash
-openviking-server doctor
-openviking-server
+pip install openviking --upgrade
+openviking-server init # interactive wizard: providers, models, ov.conf
+openviking-server doctor # validate setup
+openviking-server # start (background: nohup openviking-server > openviking.log 2>&1 &)
```
-If you configured `provider=openai-codex`, `openviking-server doctor` already validates Codex auth.
+`init` walks you through provider setup and writes `~/.openviking/ov.conf`. It supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama — for Ollama it can detect and install the runtime and pull models suited to your hardware. `doctor` checks the config file, Python version, provider connectivity, and disk space without a running server. Manual `ov.conf` templates, per-provider examples, environment variables, and Windows setup: [Configuration guide](https://docs.openviking.ai/en/guides/01-configuration) · [Quick start docs](https://docs.openviking.ai/en/getting-started/02-quickstart).
-or you can run in background
-
-```bash
-nohup openviking-server > /data/log/openviking.log 2>&1 &
-```
-
-##### Run the CLI
+The install already includes the `ov` client CLI. With the server running:
```bash
ov status
@@ -595,243 +126,81 @@ ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# wait some time for semantic processing if not --wait
ov find "what is openviking"
-ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh
+ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
```
-To rebuild existing indexes, `ov reindex <uri> --mode vectors_only` refreshes vectors only. Use `--mode semantic_and_vectors` when semantic artifacts (`.abstract.md` and `.overview.md`) must be regenerated before vectors. Use `--mode prune_orphans` to remove vector records whose source files no longer exist; add `--dry-run` to preview the cleanup. There is no `semantic` or `full` mode alias.
-
-Congratulations! You have successfully run OpenViking 🎉
-
-### Commercial Access
-
-OpenViking Personal is now officially available. Compared with the open-source edition, the Service version is officially hosted and ready to use, scales far beyond local hardware with VikingDB, and comes with richer integrations plus professional support. It includes a free trial for up to 50 files, and existing open-source users can move over smoothly with our migration tool.
-
-### VikingBot Quick Start
-
-VikingBot is an AI agent framework built on top of OpenViking. Here's how to get started:
-
-```bash
-# Option 1: Install VikingBot from PyPI (recommended for most users)
-pip install "openviking[bot]"
-
-# Option 2: Install VikingBot from source (for development)
-uv pip install -e ".[bot]"
-
-# Start OpenViking server with Bot enabled
-openviking-server --with-bot
-
-# In another terminal, start interactive chat
-ov chat
-```
-
-If you use the official Docker image, `vikingbot` is already bundled in the image and starts by default together with the OpenViking server and console UI. You can disable it at runtime with either `--without-bot` or `-e OPENVIKING_WITH_BOT=0`.
-
-***
-
-## Server Deployment Details
-
-For production environments, we recommend running OpenViking as a standalone HTTP service to provide persistent, high-performance context support for your AI Agents.
-
-🚀 **Deploy OpenViking on Cloud**:
-To ensure optimal storage performance and data security, we recommend deploying on **Volcengine Elastic Compute Service (ECS)** using the **veLinux** operating system. We have prepared a detailed step-by-step guide to get you started quickly.
+Next steps:
-👉 **[View: Server Deployment & ECS Setup Guide](./docs/en/getting-started/03-quickstart-server.md)**
+- Client configuration (`ov config`), standalone CLI installs (npm / cargo), and advanced usage such as index rebuilding: [CLI setup](https://docs.openviking.ai/en/getting-started/05-cli-setup)
+- Docker and production deployment: [Deployment guide](https://docs.openviking.ai/en/guides/03-deployment)
----
+## Use it with your agent
-## Evaluation Highlights
+Integrations inject OpenViking recall into your agent's context and auto-commit session memory:
-OpenViking 0.3.22 has been evaluated across three scenarios: long-conversation user memory, agent experience memory, and knowledge-base QA.
+- [Claude Code](https://docs.openviking.ai/en/agent-integrations/02-claude-code)
+- [Codex](https://docs.openviking.ai/en/agent-integrations/04-codex)
+- [OpenClaw](https://docs.openviking.ai/en/agent-integrations/03-openclaw)
+- [Hermes](https://docs.openviking.ai/en/agent-integrations/05-hermes)
+- [Cursor](https://docs.openviking.ai/en/agent-integrations/12-cursor)
+- [Trae](https://docs.openviking.ai/en/agent-integrations/13-trae)
+- [OpenCode](https://docs.openviking.ai/en/agent-integrations/10-opencode)
+- [pi](https://docs.openviking.ai/en/agent-integrations/11-pi)
+- [MCP clients](https://docs.openviking.ai/en/agent-integrations/06-mcp-clients)
+- [LangChain / LangGraph](https://docs.openviking.ai/en/agent-integrations/07-langchain-langgraph)
-### 1. User Memory on LoCoMo
+Setup instructions for each agent: [Agent integrations overview](https://docs.openviking.ai/en/agent-integrations/01-overview).
-On the LoCoMo benchmark, OpenViking improves long-context QA accuracy while reducing both latency and token usage across multiple agent integrations:
+## OpenViking Helper (Beta)
-| Integration | Accuracy | Avg. Query Time | Total Input Tokens |
-|:-----------:|---------:|----------------:|-------------------:|
-| OpenClaw + native memory | 24.20% | 95.14s | 392,559,404 |
-| OpenClaw + OpenViking | **82.08%** | 38.8s | 37,423,456 |
-| Hermes native memory | 33.38% | 82.4s | 79,228,398 |
-| Hermes + OpenViking | **82.86%** | **27.9s** | 52,026,755 |
-| Claude Code auto-memory | 57.21% | 49.1s | 353,306,422 |
-| Claude Code + OpenViking | **80.32%** | **20.4s** | 129,968,899 |
+OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64:
-#### 1.1 Key Efficiency Improvements
+- **Visual local agent setup**: detects OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configures supported plugin, MCP, Hook, and CLI integrations.
+- **Session trace inspection**: parses Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events.
+- **Local memory and skill management**: views local memory / rule files and `SKILL.md` skills, then syncs them to OpenViking.
-| Agent | Accuracy Improvement | Latency Reduction | Token Reduction |
-|:-----:|---------------------:|------------------:|----------------:|
-| OpenClaw | 24.20% → 82.08% (+3.39×) | -59.22% | **-91.0%** |
-| Hermes | 33.38% → 82.86% (+2.48×) | -66.10% | -34.3% |
-| Claude Code | 57.21% → 80.32% (+1.40×) | -58.45% | -63.2% |
-
-### 2. Agent Experience Memory on tau2-bench
-
-For multi-turn agent tasks on tau2-bench, OpenViking's experience memory improves task success in both retail and airline domains:
+Download:
-| Setting | Retail Accuracy | Airline Accuracy |
-|:-------:|----------------:|-----------------:|
-| LLM without memory | 70.94% | 54.38% |
-| LLM + OpenViking experience memory | **77.81%** (+6.87pp) | **66.25%** (+11.87pp) |
+- [macOS Apple Silicon (arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
+- [macOS Intel (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
+- [Windows (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-### 3. Knowledge Base QA on HotpotQA
+## VikingBot
-On multi-hop RAG tasks from HotpotQA, increasing OpenViking retrieval from top-5 to top-20 delivers the highest accuracy in this comparison while keeping retrieval latency low:
+VikingBot is an AI agent framework built on top of OpenViking:
-| Method | Retrieval Pattern | Accuracy | Tokens / QA | Latency / QA |
-|:------:|:-----------------:|---------:|------------:|-------------:|
-| Naive RAG | Vector retrieval | 62.50% | 1,290 | **0.11s** |
-| HippoRAG 2 | Vector + knowledge graph | 61.00% | 726 | 20s |
-| LightRAG | Vector + knowledge graph | 89.00% | 28,443 | 75s |
-| LangChain SQL (Agent) | SQL agent | 78.00% | 4,776 | 132s |
-| OpenViking (top-5) | Vector retrieval | 72.75% | 3,154 | 0.22s |
-| OpenViking (top-20) | Vector retrieval | **91.00%** | 12,533 | 0.23s |
-| Nanobot + OpenViking (Agent) | Vector retrieval + Agent | 87.00% | 71,300 | 61.6s |
+```bash
+pip install "openviking[bot]"
+openviking-server --with-bot
+ov chat # in another terminal
+```
-#### 3.1 Single-turn RAG Across 5 Open-source Datasets
+The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: [VikingBot guide](https://docs.openviking.ai/en/guides/17-vikingbot).
-| Method | Retrieval Pattern | Average Accuracy | Indexing Tokens | Tokens / QA | Retrieval Latency |
-|:------:|:-----------------:|-----------------:|----------------:|------------:|------------------:|
-| Naive RAG | Vector retrieval | 53.93% | 2,755,356 | 1,435 | **0.13s** |
-| PageIndex | Vector + tree structure | 36.75% | 5,609,206 | 710,480 | 84.60s |
-| HippoRAG 2 | Vector + knowledge graph | 44.50% | 124,963,618 | **637** | 18.83s |
-| LightRAG | Vector + knowledge graph | **76.00%** | 62,705,469 | 27,035 | 9.19s |
-| **OpenViking** | **Vector retrieval** | **66.87%** | **8,671,538** | **3,060** | **0.19s** |
+## Deploy in production
-> Datasets: FinanceBench, NaturalQuestions, ClapNQ, Qasper, and SyllabusQA. OpenViking reaches 66.87% average accuracy with very low retrieval latency (0.19s), while indexing cost is only 13.8% of LightRAG.
+For production, run OpenViking as a standalone HTTP service — see [Server deployment](https://docs.openviking.ai/en/getting-started/03-quickstart-server) and the [Deployment guide](https://docs.openviking.ai/en/guides/03-deployment).
----
+Prefer not to operate it yourself? OpenViking Personal is officially hosted and ready to use, scales far beyond local hardware with VikingDB, and includes a free trial for up to 50 files; existing open-source users can move over with the migration tool. → [openviking.ai](https://www.openviking.ai)
-## Academic Backing
+## Research
-OpenViking open-sources a subset of the core capabilities described in the `VikingMem` paper, making the context database and memory management ideas accessible to AI agent developers.
+OpenViking open-sources a subset of the core capabilities described in the VikingMem paper:
> **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**
> Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.
> arXiv:2605.29640, 2026. Accepted by VLDB 2026.
->
> 📄 [Read the paper on arXiv](https://arxiv.org/abs/2605.29640)
-## Core Concepts
-
-After running the first example, let's dive into the design philosophy of OpenViking. These five core concepts correspond one-to-one with the solutions mentioned earlier, together building a complete context management system:
-
-### 1. Filesystem Management Paradigm → Solves Fragmentation
-
-We no longer view context as flat text slices but unify them into an abstract virtual filesystem. Whether it's memories, resources, or capabilities, they are mapped to virtual directories under the `viking://` protocol, each with a unique URI.
-
-This paradigm gives Agents unprecedented context manipulation capabilities, enabling them to locate, browse, and manipulate information precisely and deterministically through standard commands like `ls` and `find`, just like a developer. This transforms context management from vague semantic matching into intuitive, traceable "file operations". Learn more: [Viking URI](./docs/en/concepts/04-viking-uri.md) | [Context Types](./docs/en/concepts/02-context-types.md)
-
-```
-viking://
-├── resources/ # Resources: project docs, repos, web pages, etc.
-│ ├── my_project/
-│ │ ├── docs/
-│ │ │ ├── api/
-│ │ │ └── tutorials/
-│ │ └── src/
-│ └── ...
-├── user/ # User: personal preferences, habits, etc.
-│ └── {user_id}/
-│ ├── memories/
-│ │ ├── preferences/
-│ │ │ ├── writing_style
-│ │ │ └── coding_habits
-│ │ └── ...
-│ ├── resources/
-│ │ └── private_project/
-│ ├── skills/
-│ │ ├── search_code
-│ │ └── analyze_data
-│ └── peers/
-│ └── web-visitor-alice/
-│ ├── memories/
-│ └── resources/
-```
-
-### 2. Tiered Context Loading → Reduces Token Consumption
-
-Stuffing massive amounts of context into a prompt all at once is not only expensive but also prone to exceeding model windows and introducing noise. OpenViking automatically processes context into three levels upon writing:
-
-- **L0 (Abstract)**: A one-sentence summary for quick retrieval and identification.
-- **L1 (Overview)**: Contains core information and usage scenarios for Agent decision-making during the planning phase.
-- **L2 (Details)**: The full original data, for deep reading by the Agent when absolutely necessary.
-
-Learn more: [Context Layers](./docs/en/concepts/03-context-layers.md)
+## Community & contributing
-```
-viking://resources/my_project/
-├── .abstract # L0 Layer: Abstract (~100 tokens) - Quick relevance check
-├── .overview # L1 Layer: Overview (~2k tokens) - Understand structure and key points
-├── docs/
-│ ├── .abstract # Each directory has corresponding L0/L1 layers
-│ ├── .overview
-│ ├── api/
-│ │ ├── .abstract
-│ │ ├── .overview
-│ │ ├── auth.md # L2 Layer: Full content - Load on demand
-│ │ └── endpoints.md
-│ └── ...
-└── src/
- └── ...
-```
-
-### 3. Directory Recursive Retrieval → Improves Retrieval Effect
-
-Single vector retrieval struggles with complex query intents. OpenViking has designed an innovative **Directory Recursive Retrieval Strategy** that deeply integrates multiple retrieval methods:
-
-1. **Intent Analysis**: Generate multiple retrieval conditions through intent analysis.
-2. **Initial Positioning**: Use vector retrieval to quickly locate the high-score directory where the initial slice is located.
-3. **Refined Exploration**: Perform a secondary retrieval within that directory and update high-score results to the candidate set.
-4. **Recursive Drill-down**: If subdirectories exist, recursively repeat the secondary retrieval steps layer by layer.
-5. **Result Aggregation**: Finally, obtain the most relevant context to return.
-
-This "lock high-score directory first, then refine content exploration" strategy not only finds the semantically best-matching fragments but also understands the full context where the information resides, thereby improving the globality and accuracy of retrieval. Learn more: [Retrieval Mechanism](./docs/en/concepts/07-retrieval.md)
+OpenViking is still in its early stages, and there is plenty left to build.
-### 4. Visualized Retrieval Trajectory → Observable Context
-
-OpenViking's organization uses a hierarchical virtual filesystem structure. All context is integrated in a unified format, and each entry corresponds to a unique URI (like a `viking://` path), breaking the traditional flat black-box management mode with a clear hierarchy that is easy to understand.
-
-The retrieval process adopts a directory recursive strategy. The trajectory of directory browsing and file positioning for each retrieval is fully preserved, allowing users to clearly observe the root cause of problems and guide the optimization of retrieval logic. Learn more: [Retrieval Mechanism](./docs/en/concepts/07-retrieval.md)
-
-### 5. Automatic Session Management → Context Self-Iteration
-
-OpenViking has a built-in memory self-iteration loop. After a session is committed, the system asynchronously analyzes task outcomes and user feedback, then updates memory in the current User or Peer namespace according to the active memory policy.
-
-- **User Memory Update**: Update memories related to user preferences, making Agent responses better fit user needs.
-- **Agent Experience Accumulation**: Extract core content such as operational tips and tool usage experience from task execution experience, aiding efficient decision-making in subsequent tasks.
-
-This allows the Agent to get "smarter with use" through interactions with the world, achieving self-evolution. Learn more: [Session Management](./docs/en/concepts/08-session.md)
-
-***
-
-## Advanced Reading
-
-### Documentation
-
-For more details, please visit our [Full Documentation](./docs/en/).
-
-### Community & Team
-
-For more details, please see: **[About Us](./docs/en/about/01-about-us.md)**
-
-### Join the Community
-
-OpenViking is still in its early stages, and there are many areas for improvement and exploration. We sincerely invite every developer passionate about AI Agent technology:
-
-- Light up a precious **Star** for us to give us the motivation to move forward.
-- Visit our **[Website](https://www.openviking.ai)** to understand the philosophy we convey, and use it in your projects via the **[Documentation](https://www.openviking.ai/docs)**. Feel the change it brings and give us feedback on your truest experience.
-- Join our community to share your insights, help answer others' questions, and jointly create an open and mutually helpful technical atmosphere:
- - 📱 **Lark Group**: Scan the QR code to join → [View QR Code](./docs/en/about/01-about-us.md#lark-group)
- - 💬 **WeChat Group**: Scan the QR code to add assistant → [View QR Code](./docs/en/about/01-about-us.md#wechat-group)
- - 🎮 **Discord**: [Join Discord Server](https://discord.com/invite/eHvx8E9XF3)
- - 🐦 **X (Twitter)**:[Follow us](https://x.com/openvikingai)
-- Become a **Contributor**, whether submitting a bug fix or contributing a new feature, every line of your code will be an important cornerstone of OpenViking's growth.
-
-Let's work together to define and build the future of AI Agent context management. The journey has begun, looking forward to your participation!
-
-### Star Trend
-
-[![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking\&type=timeline\&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking\&type=timeline\&legend=top-left)
+- **Docs**: [docs.openviking.ai](https://docs.openviking.ai/) · [FAQ](https://docs.openviking.ai/en/faq/faq)
+- **Blog**: [blog.openviking.ai](https://blog.openviking.ai/)
+- **Team**: [About us](https://docs.openviking.ai/en/about/01-about-us)
+- **Chat**: 📱 [Lark Group](https://docs.openviking.ai/en/about/01-about-us#lark-group) · 💬 [WeChat](https://docs.openviking.ai/en/about/01-about-us#wechat-group) · 🎮 [Discord](https://discord.com/invite/eHvx8E9XF3) · 🐦 [X](https://x.com/openvikingai)
+- **Contribute**: bug fixes and new features are both welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
## Security and privacy
@@ -846,5 +215,3 @@ The OpenViking project uses different licenses for different components:
- **crates/ov\_cli**: Apache 2.0 - see the [LICENSE](./crates/LICENSE) for details
- **examples**: Apache 2.0 - see the [LICENSE](./examples/LICENSE) for details
- **third\_party**: Respective original licenses of third-party projects
-
-<!-- Link Definitions -->
diff --git a/README_CN.md b/README_CN.md
index 7a849c4e2..3cc1027eb 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -1,4 +1,5 @@
<div align="center">
+
<a href="https://openviking.ai/" target="_blank">
<picture>
<img alt="OpenViking" src="docs/images/ov-logo.png" width="200px" height="auto">
@@ -9,897 +10,217 @@
[English](README.md) / 中文 / [日本語](README_JA.md)
-<a href="https://www.openviking.ai">官网</a> · <a href="https://openviking.net/studio">在线体验</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">问题反馈</a> · <a href="https://www.openviking.ai/docs">文档</a>
-
-[![][release-shield]][release-link]
-[![][github-stars-shield]][github-stars-link]
-[![][github-issues-shield]][github-issues-shield-link]
-[![][github-contributors-shield]][github-contributors-link]
-[![][license-shield]][license-shield-link]
-[![][last-commit-shield]][last-commit-shield-link]
+<a href="https://www.openviking.ai">官网</a> · <a href="https://openviking.ai/studio">在线体验</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">问题反馈</a> · <a href="https://docs.openviking.ai/">文档</a>
+[![](https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff\&labelColor=black\&logo=github\&style=flat-square)](https://github.com/volcengine/OpenViking/releases)
+[![](https://img.shields.io/github/stars/volcengine/OpenViking?labelColor\&style=flat-square\&color=ffcb47)](https://github.com/volcengine/OpenViking)
+[![](https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black\&style=flat-square\&color=ff80eb)](https://github.com/volcengine/OpenViking/issues)
+[![](https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042\&labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/graphs/contributors)
+[![](https://img.shields.io/badge/license-AGPLv3-white?labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/blob/main/LICENSE)
+[![](https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042\&labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/commits/main)
👋 加入我们的社区
-📱 <a href="./docs/zh/about/01-about-us.md#lark-group">飞书群</a> · <a href="./docs/zh/about/01-about-us.md#wechat-group">微信群</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
-
-</div>
-
----
-
-✨ **2026年5月更新**:更新 OpenViking 在 User Memory、Agent Memory 和知识库问答三场景上的评测结果。→ 见 [评测结果](#-评测结果)。
-
-## 概述
-
-### 智能体开发面临的挑战
-
-在 AI 时代,数据丰富,但高质量的上下文却难以获得。在构建 AI 智能体时,开发者经常面临以下挑战:
-
-- **上下文碎片化**:记忆存储在代码中,资源在向量数据库中,技能分散在各处,难以统一管理。
-- **上下文需求激增**:智能体的长运行任务在每次执行时都会产生上下文。简单的截断或压缩会导致信息丢失。
-- **检索效果不佳**:传统 RAG 使用扁平化存储,缺乏全局视图,难以理解信息的完整上下文。
-- **上下文不可观察**:传统 RAG 的隐式检索链像黑盒,出错时难以调试。
-- **记忆迭代有限**:当前记忆只是用户交互的记录,缺乏智能体相关的任务记忆。
-
-### OpenViking 解决方案
-
-**OpenViking** 是专为 AI 智能体设计的开源**上下文数据库**。
-
-我们的目标是为智能体定义一个极简的上下文交互范式,让开发者完全告别上下文管理的烦恼。OpenViking 抛弃了传统 RAG 的碎片化向量存储模型,创新性地采用 **"文件系统范式"** 来统一组织智能体所需的记忆、资源和技能。
-
-使用 OpenViking,开发者可以像管理本地文件一样构建智能体的大脑:
-
-- **文件系统管理范式** → **解决碎片化**:基于文件系统范式统一管理记忆、资源和技能。
-- **分层上下文加载** → **降低 Token 消耗**:L0/L1/L2 三层结构,按需加载,显著节省成本。
-- **目录递归检索** → **提升检索效果**:支持原生文件系统检索方式,结合目录定位和语义搜索,实现递归精准的上下文获取。
-- **可视化检索轨迹** → **可观察上下文**:支持目录检索轨迹可视化,让用户清晰观察问题根源,指导检索逻辑优化。
-- **自动会话管理** → **上下文自迭代**:自动压缩对话中的内容、资源引用、工具调用等,提取长期记忆,让智能体越用越聪明。
-
----
-
-## 快速开始
-
-> 💡 **想先看看实际效果?** 试试 [OpenViking Studio](https://openviking.net/studio)——在线托管实例,提供上下文实验场、语义检索和多智能体 Hub,无需安装。
-
-### OpenViking Helper 桌面端(Beta)
-
-**OpenViking Helper** 是面向 OpenViking 用户的桌面应用,把本机 Agent 接入、会话轨迹、记忆和技能放到可视化界面里,方便用户确认接入状态,并把本地上下文同步到 OpenViking。
-
-核心特性:
-
-- **可视化接入本地 Agent**:检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae、OpenCode,并配置支持的插件、MCP、Hook 和 CLI 接入。
-- **回看会话生效过程**:解析 Claude Code、Codex、Trae 会话,展示 OpenViking 的召回、Prompt 注入、MCP 调用、捕获和提交事件。
-- **管理本地记忆与技能**:查看本地 memory / rule 文件和 `SKILL.md` 技能,并同步到 OpenViking。
-
-> OpenViking Helper 目前仍处于 Beta 阶段,支持 macOS 和 Windows x64。
-
-下载:
-
-- [macOS Apple Silicon 版(arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
-- [macOS Intel 版(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
-- [Windows 版(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-
-### 本地部署
-
-#### 前置条件
-
-在开始使用 OpenViking 之前,请确保您的环境满足以下要求:
-
-- **Python 版本**:3.10 或更高版本
-- **Rust 工具链**:Cargo(从源码构建 RAGFS 和 CLI 组件需要)
-- **C++ 编译器**:GCC 9+ 或 Clang 11+(构建核心扩展需要,必须支持 C++17)
-- **操作系统**:Linux、macOS、Windows
-- **网络连接**:需要稳定的网络连接(用于下载依赖和访问模型服务)
-
-#### 1. 安装
-
-##### Python 包
-
-```bash
-pip install openviking --upgrade --force-reinstall
-```
-
-##### Rust CLI(可选)
-
-```bash
-npm i -g @openviking/cli
-```
-
-或从源码构建:
-
-```bash
-cargo install --git https://github.com/volcengine/OpenViking ov_cli
-```
-
-#### 2. 模型准备
-
-OpenViking 需要以下模型能力:
-- **VLM 模型**:用于图像和内容理解
-- **Embedding 模型**:用于向量化和语义检索
-
-##### 支持的 VLM 提供商
-
-OpenViking 支持多种 VLM 提供商:
-
-| 提供商 | 描述 | 设置方式 |
-|----------|-------------|-------------|
-| `volcengine` | 火山引擎豆包模型 | [Volcengine 控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_content=OpenViking&utm_medium=devrel&utm_source=OWO&utm_term=OpenViking) |
-| `openai` | OpenAI 官方 API | [OpenAI 平台](https://platform.openai.com) |
-| `azure` | Azure OpenAI 服务 | [Azure OpenAI 服务](https://portal.azure.com) |
-| `openai-codex` | 通过 ChatGPT/Codex OAuth 使用 Codex VLM | 使用 `openviking-server init` |
-
-##### 提供商特定说明
-
-<details>
-<summary><b>Volcengine (豆包)</b></summary>
-
-Volcengine 支持模型名称和端点 ID。为简单起见,建议使用模型名称:
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "doubao-seed-2-0-lite-260428",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-您也可以使用端点 ID(可在 [Volcengine ARK 控制台](https://console.volcengine.com/ark) 中找到):
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "ep-20241220174930-xxxxx",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>OpenAI</b></summary>
-
-使用 OpenAI 的官方 API:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://api.openai.com/v1"
- }
-}
-```
-
-您也可以使用自定义的 OpenAI 兼容端点:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://your-custom-endpoint.com/v1"
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Azure OpenAI</b></summary>
+📱 <a href="https://docs.openviking.ai/zh/about/01-about-us#飞书群">飞书群</a> · <a href="https://docs.openviking.ai/zh/about/01-about-us#微信群">微信群</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
-使用 Azure OpenAI 服务。`model` 字段需要填写 Azure 上的**部署名称(deployment name)**,而非模型官方名字:
+<a href="https://trendshift.io/repositories/19668" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19668" alt="volcengine%2FOpenViking | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-```json
-{
- "vlm": {
- "provider": "azure",
- "model": "your-deployment-name",
- "api_key": "your-azure-api-key",
- "api_base": "https://your-resource-name.openai.azure.com",
- "api_version": "2025-01-01-preview"
- }
-}
-```
-
-> 💡 **提示**:
-> - `api_base` 填写你的 Azure OpenAI 资源端点,支持 `*.openai.azure.com` 和 `*.cognitiveservices.azure.com` 两种格式
-> - `api_version` 可选,默认值为 `2025-01-01-preview`
-> - `model` 必须与 Azure Portal 中创建的部署名称一致
-
-</details>
-
-<details>
-<summary><b>OpenAI Codex(OAuth)</b></summary>
-
-如果你希望通过 ChatGPT/Codex OAuth 会话来使用 Codex VLM,而不是标准 OpenAI API Key,可以这样配置:
-
-```bash
-openviking-server init
-# 在向导中选择 OpenAI Codex
-openviking-server doctor
-```
-
-```json
-{
- "vlm": {
- "provider": "openai-codex",
- "model": "gpt-5.3-codex",
- "api_base": "https://chatgpt.com/backend-api/codex",
- "temperature": 0.0,
- "max_retries": 2
- }
-}
-```
-
-> 💡 **提示**:
-> - 当 Codex OAuth 可用时,`openai-codex` 不需要 `vlm.api_key`
-> - OpenViking 会把自己的 Codex 鉴权状态保存在 `~/.openviking/codex_auth.json`
-> - 可以通过 `openviking-server doctor` 校验当前 Codex 鉴权是否可用
-
-</details>
-
-#### 3. 环境配置
-
-##### 本地模型快速配置 (Ollama)
-
-如果你想通过 [Ollama](https://ollama.ai) 使用本地模型运行 OpenViking,交互式向导会自动完成所有配置:
-
-```bash
-openviking-server init
-```
-
-向导会:
-- 检测并安装 Ollama(如需要)
-- 根据你的硬件推荐并拉取合适的 embedding 和 VLM 模型
-- 生成可直接使用的 `ov.conf` 配置文件
-
-随时验证配置是否正确:
-
-```bash
-openviking-server doctor
-```
+</div>
-`doctor` 会检查本地环境(配置文件、Python 版本、embedding/VLM 服务连通性、磁盘空间),无需启动服务器。
+***
-> 如果使用云端 API(火山引擎、OpenAI、Gemini 等),请继续下方的手动配置。
+## OpenViking 是什么
-##### 服务器配置模板
+OpenViking 是面向 AI 智能体的开源上下文数据库。记忆、资源、技能统一存放在 `viking://` 协议下的虚拟文件系统里,智能体用 `ls`、`tree`、`find` 浏览自己的上下文,不必去查一个黑盒向量库。内容写入时会处理成三层——L0 摘要、L1 概览、L2 详情——按需加载。每次检索都留下轨迹,可以查看,也可以调试。完整介绍见[入门文档](https://docs.openviking.ai/zh/getting-started/01-introduction)。
-推荐的首次配置流程是:
+[![OpenViking Studio playground](docs/images/studio-playground.png)](https://openviking.ai/studio)
-```bash
-openviking-server init
-openviking-server doctor
-```
+*[OpenViking Studio](https://openviking.ai/studio) 实验场——在线 Demo,打开浏览器就能试,无需安装。*
-如果你在 `openviking-server init` 中选择了 `OpenAI Codex`,初始化向导会帮你导入已有 Codex 鉴权,或直接引导你完成登录。
-
-如果你更想手动配置,再创建 `~/.openviking/ov.conf`,复制前请删除注释:
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // 日志输出:"stdout" 或 "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "<api-endpoint>", // API 端点地址
- "api_key" : "<your-api-key>", // 模型服务 API Key
- "provider" : "<provider-type>", // 提供商类型:"volcengine"、"openai"、"azure" 等
- "api_version": "2025-01-01-preview", // (仅 azure)API 版本,可选,默认 "2025-01-01-preview"
- "dimension": 1024, // 向量维度
- "model" : "<model-name>" // Embedding 模型名称或 Azure 部署名
- },
- "max_concurrent": 10 // 最大并发 embedding 请求(默认:10)
- },
- "vlm": {
- "api_base" : "<api-endpoint>", // API 端点地址
- "api_key" : "<your-api-key>", // 模型服务 API Key(openai-codex 可选)
- "provider" : "<provider-type>", // 提供商类型 (volcengine, openai, azure, openai-codex 等)
- "api_version": "2025-01-01-preview", // (仅 azure)API 版本,可选,默认 "2025-01-01-preview"
- "model" : "<model-name>", // VLM 模型名称或 Azure 部署名
- "max_concurrent": 64 // 语义处理的最大并发 LLM 调用(默认:64)
- }
-}
-```
+## 为什么用 OpenViking
-> **注意**:对于 embedding 模型,支持 `volcengine`(豆包)、`openai`、`azure`、`jina`、`ollama`、`voyage`、`dashscope`、`minimax`、`cohere`、`vikingdb`、`gemini`(需 `pip install "google-genai>=1.0.0"`)、`litellm` 和 `local`。对于 VLM 模型,常见提供商包括 `volcengine`、`openai`、`openai-codex`、`kimi`、`glm`。
-
-> **Memory 配置**:OpenViking 始终使用 v3 记忆抽取链路。旧的 `memory.version` 配置项已废弃且会被忽略;已有配置中保留该字段仍可正常加载,但不会改变行为。
-
-> **Memory schema 作用域**:Memory schema YAML 默认 `stage: "user"` 且 `peer_enabled: true`。trajectories/experiences 这类执行派生 schema 使用 `stage: "agent"`;如果某类记忆必须保留在当前用户目录而不是 peer 目录,设置 `peer_enabled: false`。
-
-##### 服务器配置示例
-
-👇 展开查看您的模型服务的配置示例:
-
-<details>
-<summary><b>示例 1:使用 Volcengine(豆包模型)</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "dimension": 1024,
- "model" : "doubao-embedding-vision-251215"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "model" : "doubao-seed-2-0-lite-260428",
- "max_concurrent": 64
- }
-}
-```
+- **一个文件系统装下所有上下文。** 记忆、资源、技能各有一个 `viking://` URI。智能体像开发者操作文件一样,确定地定位和操作上下文。→ [Viking URI](https://docs.openviking.ai/zh/concepts/04-viking-uri) · [上下文类型](https://docs.openviking.ai/zh/concepts/02-context-types)
+- **分层加载省 token。** 每条内容写入时生成 L0(摘要)、L1(概览)、L2(详情)三层,任务需要多深就加载多深。→ [上下文分层](https://docs.openviking.ai/zh/concepts/03-context-layers)
+- **目录递归检索。** 向量检索先定位得分最高的目录,再逐层向下探索,结果连同周边上下文一起返回。→ [检索机制](https://docs.openviking.ai/zh/concepts/07-retrieval)
+- **检索过程可观察。** 每次查询都保留目录浏览轨迹。结果不对时,能看到它出自哪条路径。→ [检索机制](https://docs.openviking.ai/zh/concepts/07-retrieval)
+- **会话沉淀为记忆。** 会话提交后,OpenViking 异步提取用户偏好和智能体经验,写入长期记忆。→ [会话管理](https://docs.openviking.ai/zh/concepts/08-session)
-</details>
-
-<details>
-<summary><b>示例 2:使用 OpenAI 模型</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "dimension": 3072,
- "model" : "text-embedding-3-large"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "model" : "gpt-4-vision-preview",
- "max_concurrent": 64
- }
-}
-```
+各部分如何配合:见[架构](https://docs.openviking.ai/zh/concepts/01-architecture)。设计思路:[The Database Paradigm for Context Engineering](https://blog.openviking.ai/post/openviking-context-database/)(页内可切换中文)。
-</details>
-
-<details>
-<summary><b>示例 3:使用 Azure OpenAI 模型</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://your-resource-name.openai.azure.com",
- "api_key" : "your-azure-api-key",
- "provider" : "azure",
- "api_version": "2025-01-01-preview",
- "dimension": 1024,
- "model" : "text-embedding-3-large"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://your-resource-name.openai.azure.com",
- "api_key" : "your-azure-api-key",
- "provider" : "azure",
- "api_version": "2025-01-01-preview",
- "model" : "gpt-4o",
- "max_concurrent": 64
- }
-}
```
+viking://
+├── resources/ # 资源:项目文档、代码库、网页等
+│ └── my_project/
+│ ├── docs/
+│ │ ├── api/
+│ │ └── tutorials/
+│ └── src/
+└── user/
+ └── {user_id}/
+ ├── memories/
+ │ └── preferences/
+ │ ├── writing_style
+ │ └── coding_habits
+ ├── resources/
+ │ └── private_project/
+ ├── skills/
+ │ ├── search_code
+ │ └── analyze_data
+ └── peers/
+ └── web-visitor-alice/
+```
+
+三个加载层级:
+
+- **L0(摘要)**:一句话总结,用来快速判断相关性。
+- **L1(概览)**:核心信息和使用场景,供规划阶段决策。
+- **L2(详情)**:完整原始数据,只在需要时读取。
+
+每个目录都带自己的 L0/L1 层,读完整文件之前就能判断相关性:
-> 💡 **提示**:
-> - `model` 必须填写 Azure Portal 中创建的**部署名称**,而非模型官方名字
-> - `api_base` 支持 `*.openai.azure.com` 和 `*.cognitiveservices.azure.com` 两种端点格式
-> - Embedding 和 VLM 可以使用不同的 Azure 资源和 API Key
-
-</details>
-
-##### 设置服务器配置环境变量
-
-创建配置文件后,设置环境变量指向它(Linux/macOS):
-
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # 默认值
-```
-
-在 Windows 上,使用以下任一方式:
-
-PowerShell:
-
-```powershell
-$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"
```
-
-命令提示符 (cmd.exe):
-
-```bat
-set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"
+viking://resources/my_project/
+├── .abstract # L0:约 100 tokens——快速判断相关性
+├── .overview # L1:约 2k tokens——结构和要点
+└── docs/
+ ├── .abstract
+ ├── .overview
+ └── api/
+ ├── auth.md # L2:完整内容,按需加载
+ └── endpoints.md
```
-> 💡 **提示**:您也可以将配置文件放在其他位置,只需在环境变量中指定正确路径。
+## 评测结果
-##### CLI/客户端配置示例
+OpenViking 0.3.22 的评测覆盖长对话用户记忆(LoCoMo)和多轮智能体任务(tau2-bench)。完整结果和实验设置(含知识库问答)见[评测报告](https://blog.openviking.ai/post/openviking-benchmark-results/),复现脚本在 [./benchmark](./benchmark)。
-你可以通过 `ov config` 命令来以交互式方式初始化 CLI/客户端的配置。如果你有多个 openviking 服务器,你还可以通过 `ov config switch` 命令来切换到其他配置。
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/benchmark-dark.svg">
+ <img alt="Benchmark results. LoCoMo accuracy: OpenClaw 24.20% native vs 82.08% with OpenViking; Hermes 33.38% vs 82.86%; Claude Code 57.21% vs 80.32%. tau2-bench task success: Retail 70.94% vs 77.81%; Airline 54.38% vs 66.25%." src="docs/images/benchmark-light.svg">
+</picture>
-👇 展开查看您的 CLI/客户端的配置示例:
+- **用户记忆(LoCoMo)**:接入 OpenViking 后,三种 Agent 集成的准确率都到 80–83%,原生记忆只有 24–57%;同时输入 token 减少 34.3%–91.0%,查询时延降低 58.45%–66.10%。
+- **智能体经验(tau2-bench)**:经验记忆让任务成功率在 Retail 提升 6.87pp、Airline 提升 11.87pp(对比同一 LLM 无记忆)。
-<details>
-<summary><b>示例:用于访问本地服务器的 ovcli.conf</b></summary>
+## 快速开始
-```json
-{
- "url": "http://localhost:1933",
- "timeout": 60.0,
- "output": "table"
-}
-```
+> 💡 **想先看看实际效果?** 试试 [OpenViking Studio](https://openviking.ai/studio)——官方托管的在线实例,带上下文实验场、语义检索和多智能体 Hub,无需安装。
-创建配置文件后,设置环境变量指向它(Linux/macOS):
+需要 Python 3.10 或更高版本。
```bash
-export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # 默认值
-```
-
-在 Windows 上,使用以下任一方式:
-
-PowerShell:
-
-```powershell
-$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"
-```
-
-命令提示符 (cmd.exe):
-
-```bat
-set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"
+pip install openviking --upgrade
+openviking-server init # 交互式向导:提供商、模型、ov.conf
+openviking-server doctor # 校验配置
+openviking-server # 启动
```
-</details>
-
-#### 4. 运行您的第一个示例
-
-> 📝 **前置条件**:确保您已完成上一步的配置(ov.conf 和 ovcli.conf)。
-
-现在让我们运行一个完整的示例,体验 OpenViking 的核心功能。
-
-##### 启动服务器
+或者在后台运行:
```bash
-openviking-server doctor
-openviking-server
+nohup openviking-server > /data/log/openviking.log 2>&1 &
```
-如果你的 `vlm.provider` 是 `openai-codex`,`openviking-server doctor` 已经会校验 Codex 鉴权。
+`init` 引导你完成提供商配置,并写入 `~/.openviking/ov.conf`。它支持火山引擎、OpenAI、Codex OAuth、Kimi、GLM 和本地 Ollama——选 Ollama 时还能检测并安装运行时,按你的硬件拉取合适的模型。`doctor` 检查配置文件、Python 版本、提供商连通性和磁盘空间,不需要先启动服务器。
-或者您可以在后台运行
+手写 `ov.conf` 的模板、各提供商示例、环境变量、Windows 配置和 CLI/客户端配置,见[配置指南](https://docs.openviking.ai/zh/guides/01-configuration)和[快速入门文档](https://docs.openviking.ai/zh/getting-started/02-quickstart)。
-```bash
-nohup openviking-server > /data/log/openviking.log 2>&1 &
-```
-
-##### 运行 CLI
+服务器跑起来之后:
```bash
ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
-# 如果没有使用 --wait,等待一段时间以进行语义处理
+# 没加 --wait 的话,语义处理需要等一段时间
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh
```
-恭喜!您已成功运行 OpenViking 🎉
+重建已有索引:`ov reindex <uri> --mode vectors_only` 只刷新向量;`--mode semantic_and_vectors` 先重新生成语义产物(`.abstract.md`、`.overview.md`)再刷新向量;`--mode prune_orphans` 清理源文件已不存在的向量记录(加 `--dry-run` 可预览)。没有 `semantic` 或 `full` 这样的模式别名。
-### 商业化接入
+客户端配置可以用 `ov config` 交互式初始化;有多台服务器时,用 `ov config switch` 切换。
-OpenViking Personal 现已正式上线。相比开源版本,Service 版本由官方托管、开箱即用,借助 VikingDB 实现远超本地硬件的扩展能力,并提供更丰富的集成和专业的技术支持。新用户可免费试用至多 50 个文件,现有开源版用户也可通过我们的迁移工具平滑迁移。
+Rust CLI 通过 `npm i -g @openviking/cli` 安装,也可以从源码构建:`cargo install --git https://github.com/volcengine/OpenViking ov_cli`,见 [CLI 安装](https://docs.openviking.ai/zh/getting-started/05-cli-setup)。官方 Docker 镜像也已提供,见[部署指南](https://docs.openviking.ai/zh/guides/03-deployment)。
-### VikingBot 快速开始
+## 接入你的 Agent
-VikingBot 是构建在 OpenViking 之上的 AI 智能体框架。以下是快速开始指南:
-
-```bash
-# 选项 1:从 PyPI 安装 VikingBot(推荐大多数用户使用)
-pip install "openviking[bot]"
-
-# 选项 2:从源码安装 VikingBot(用于开发)
-uv pip install -e ".[bot]"
-
-# 启动 OpenViking 服务器(同时启动 Bot)
-openviking-server --with-bot
-
-# 在另一个终端启动交互式聊天
-ov chat
-```
+集成会把 OpenViking 的召回注入 Agent 上下文,并自动提交会话记忆:
----
-
-## 服务器部署详情
-
-对于生产环境,我们建议将 OpenViking 作为独立的 HTTP 服务运行,为您的 AI 智能体提供持久、高性能的上下文支持。
-
-🚀 **在云端部署 OpenViking**:
-为确保最佳的存储性能和数据安全,我们建议在 **火山引擎弹性计算服务 (ECS)** 上使用 **veLinux** 操作系统进行部署。我们准备了详细的分步指南,帮助您快速上手。
-
-👉 **[查看:服务器部署与 ECS 设置指南](./docs/zh/getting-started/03-quickstart-server.md)**
-
----
-
-## 📊 评测结果
-
-OpenViking 0.3.22 的核心价值主张:**在更高问答准确率的同时,消耗更低的 Token,完成任务时延更低**。以下结果覆盖三个评测维度。
-
-### 1. 用户记忆评测(User Memory)
-
-**测试目标**:验证 OpenViking 作为不同 Agent 的外接记忆组件,在长对话记忆问答(LOCOMO 数据集)上的准确率、Token 效率和时延表现。
-
-#### 1.1 各 Agent 基座上的 LOCOMO 测试结果
-
-<table style="width: 100%; table-layout: fixed;">
- <thead>
- <tr>
- <th style="text-align: center; width: 12%;">实验编号</th>
- <th style="text-align: center; width: 30%;">方案</th>
- <th style="text-align: center; width: 20%;">Query 平均耗时</th>
- <th style="text-align: center; width: 14%;">问答准确率</th>
- <th style="text-align: center; width: 24%;">Agent 总输入 Token</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td colspan="5" style="text-align: center; font-weight: bold;">OpenClaw 基座</td>
- </tr>
- <tr>
- <td style="text-align: center;">1</td>
- <td style="text-align: center;">OpenClaw + 原生 memory-core</td>
- <td style="text-align: right; white-space: nowrap;">95.14s</td>
- <td style="text-align: right;">24.20%</td>
- <td style="text-align: right;">392,559,404</td>
- </tr>
- <tr>
- <td style="text-align: center;">2</td>
- <td style="text-align: center;">OpenClaw + Mem0</td>
- <td style="text-align: right; white-space: nowrap; font-weight: bold;">37.6s</td>
- <td style="text-align: right;">56.62%</td>
- <td style="text-align: right;">42,118,285</td>
- </tr>
- <tr>
- <td style="text-align: center;">3</td>
- <td style="text-align: center;">OpenClaw + SuperMemory</td>
- <td style="text-align: right; white-space: nowrap;">109.3s</td>
- <td style="text-align: right;">42.99%</td>
- <td style="text-align: right;">88,304,113</td>
- </tr>
- <tr>
- <td style="text-align: center;">4</td>
- <td style="text-align: center;">OpenClaw + 百炼记忆库</td>
- <td style="text-align: right; white-space: nowrap;">41.6s</td>
- <td style="text-align: right;">39.55%</td>
- <td style="text-align: right;">35,206,037</td>
- </tr>
- <tr>
- <td style="text-align: center; font-weight: bold;">5</td>
- <td style="text-align: center; font-weight: bold;">OpenClaw + OpenViking</td>
- <td style="text-align: right; white-space: nowrap; font-weight: bold;">38.8s</td>
- <td style="text-align: right; font-weight: bold;">82.08%</td>
- <td style="text-align: right; font-weight: bold;">37,423,456</td>
- </tr>
- <tr>
- <td colspan="5" style="text-align: center; font-weight: bold;">Hermes 基座</td>
- </tr>
- <tr>
- <td style="text-align: center;">6</td>
- <td style="text-align: center;">Hermes Native Memory</td>
- <td style="text-align: right; white-space: nowrap;">82.4s (3.57轮/query)</td>
- <td style="text-align: right;">33.38%</td>
- <td style="text-align: right;">79,228,398</td>
- </tr>
- <tr>
- <td style="text-align: center; font-weight: bold;">7</td>
- <td style="text-align: center; font-weight: bold;">Hermes + OpenViking</td>
- <td style="text-align: right; white-space: nowrap; font-weight: bold;">27.9s (1.55轮/query)</td>
- <td style="text-align: right; font-weight: bold;">82.86%</td>
- <td style="text-align: right; font-weight: bold;">52,026,755</td>
- </tr>
- <tr>
- <td colspan="5" style="text-align: center; font-weight: bold;">Claude Code 基座</td>
- </tr>
- <tr>
- <td style="text-align: center;">8</td>
- <td style="text-align: center;">Claude Code Auto-Memory</td>
- <td style="text-align: right; white-space: nowrap;">49.1s (7.2轮/query)</td>
- <td style="text-align: right;">57.21%</td>
- <td style="text-align: right;">353,306,422</td>
- </tr>
- <tr>
- <td style="text-align: center; font-weight: bold;">9</td>
- <td style="text-align: center; font-weight: bold;">Claude Code + OpenViking</td>
- <td style="text-align: right; white-space: nowrap; font-weight: bold;">20.4s (2.6轮/query)</td>
- <td style="text-align: right; font-weight: bold;">80.32%</td>
- <td style="text-align: right; font-weight: bold;">129,968,899</td>
- </tr>
- </tbody>
-</table>
-
-#### 1.2 关键效率提升汇总
-
-| Agent | 准确率提升 | 时延降低 | Token 消耗降低 |
-|:-----:|----------:|---------:|--------------:|
-| OpenClaw | 24.20% → 82.08% (+3.39×) | -59.22% | **-91.0%** |
-| Hermes | 33.38% → 82.86% (+2.48×) | -66.10% | -34.3% |
-| Claude Code | 57.21% → 80.32% (+1.40×) | -58.45% | -63.2% |
-
----
-
-### 2. Agent 经验记忆评测(Agent Memory)
-
-**测试目标**:验证 OpenViking 抽取并召回经验记忆前后,任务执行表现和 Token 节省的效果。
-
-OpenViking 的 Agent Memory 分为两层:
-
-| 层级 | 概念 | 说明 |
-|:----:|:----:|:----:|
-| Layer 1 | **轨迹(Trajectory)** | 每次会话结束后自动提炼,记录"做了什么、怎么做的、结果如何" |
-| Layer 2 | **经验(Experience)** | 由多条相关轨迹归纳而来,跨会话可复用的策略性知识,"Situation / Approach / Reflect"三段式 |
-
-#### 2.1 经济仿真测试(ClawWork)
-
-港大数据科学实验室(HKUDS)构建的"实时经济生存 benchmark",Agent 从 $10 起步,每次 LLM 调用自动扣费,收入来自完成专业任务(覆盖 44 个职业、220 个任务)。
-
-| 方案 | 完成 50 个任务后净收入 | 平均每小时 Token 消耗 |
-|:----:|-------------------:|------------------:|
-| LLM only | $2,269.77 | 1,030.3K/h |
-| **LLM + OpenViking** | **$3,843.74 (+69.34%)** | **872.4K/h (-22.8%)** |
-
-#### 2.2 Tau-2 对话 Agent 测试
-
-Sierra AI 发布的对话式 Agent 评测基准,覆盖 Retail 和 Airline 两个领域。
-
-| 方案 | Retail 正确率 | Airline 正确率 |
-|:----:|------------:|-------------:|
-| LLM 无记忆 | 70.94% | 54.38% |
-| **LLM + OpenViking 经验记忆** | **77.81% (+6.87pp)** | **66.25% (+11.87pp)** |
-
----
-
-### 3. 知识库问答评测(Knowledge Base QA)
-
-**测试目标**:对比 OpenViking 与其他 RAG 方案在开源 benchmark 上的准确率、Token 效率和时延表现。
-
-#### 3.1 多跳、多路 RAG 测试(HotpotQA 数据集)
-
-| 方案 | 检索范式 | Accuracy | 每 QA Token | 每 QA 耗时 |
-|:----:|:------:|---------:|-----------:|---------:|
-| Naive RAG | 向量检索 | 62.50% | 1,290 | **0.11s** |
-| HippoRAG 2 | 向量 + 知识图谱 | 61.00% | 726 | 20s |
-| LightRAG | 向量 + 知识图谱 | 89.00% | 28,443 | 75s |
-| LangChain SQL (Agent) | SQL + Agent | 78.00% | 4,776 | 132s |
-| OpenViking (top5) | 向量检索 | 72.75% | 3,154 | 0.22s |
-| **OpenViking (top20)** | **向量检索** | **91.00%** | **12,533** | **0.23s** |
-
-> 💡 **在本组对比中,OpenViking 在 HotpotQA top20 配置下取得最高准确率(91%);同时检索延迟仅 0.23s,Token 消耗不到 LightRAG 的一半。**
-
-#### 3.2 单轮 RAG 测试(5 个开源数据集均值)
-
-| 方案 | 检索范式 | 平均 Accuracy | 建库 Token | 每 QA Token | 检索耗时 |
-|:----:|:------:|-------------:|---------:|-----------:|-------:|
-| Naive RAG | 向量检索 | 53.93% | 2,755,356 | 1,435 | **0.13s** |
-| PageIndex | 向量 + 树结构 | 36.75% | 5,609,206 | 710,480 | 84.60s |
-| HippoRAG 2 | 向量 + 知识图谱 | 44.50% | 124,963,618 | **637** | 18.83s |
-| LightRAG | 向量 + 知识图谱 | **76.00%** | 62,705,469 | 27,035 | 9.19s |
-| **OpenViking** | **向量检索** | **66.87%** | **8,671,538** | **3,060** | **0.19s** |
-
-> 测试数据集:FinanceBench、NaturalQuestions、ClapNQ、Qasper、SyllabusQA。OpenViking 以极低耗时(0.19s)取得 66.87% 的平均准确率,建库成本仅为 LightRAG 的 13.8%。
+- [Claude Code](https://docs.openviking.ai/zh/agent-integrations/02-claude-code)
+- [Codex](https://docs.openviking.ai/zh/agent-integrations/04-codex)
+- [OpenClaw](https://docs.openviking.ai/zh/agent-integrations/03-openclaw)
+- [Hermes](https://docs.openviking.ai/zh/agent-integrations/05-hermes)
+- [Cursor](https://docs.openviking.ai/zh/agent-integrations/12-cursor)
+- [Trae](https://docs.openviking.ai/zh/agent-integrations/13-trae)
+- [OpenCode](https://docs.openviking.ai/zh/agent-integrations/10-opencode)
+- [pi](https://docs.openviking.ai/zh/agent-integrations/11-pi)
+- [MCP 客户端](https://docs.openviking.ai/zh/agent-integrations/06-mcp-clients)
+- [LangChain / LangGraph](https://docs.openviking.ai/zh/agent-integrations/07-langchain-langgraph)
----
+各 Agent 的接入步骤:[Agent 集成总览](https://docs.openviking.ai/zh/agent-integrations/01-overview)。
-## 学术背书
+## OpenViking Helper(Beta)
-OpenViking 开源了论文 `VikingMem` 中描述的部分核心能力,使 AI 智能体开发者可以直接使用其中的上下文数据库与记忆管理理念。
+OpenViking Helper 是一个桌面控制台,目前处于 Beta 阶段,支持 macOS 和 Windows x64:
-> **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**
-> Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.
-> arXiv:2605.29640, 2026。已被 VLDB 2026 接收。
->
-> 📄 [阅读 arXiv 论文](https://arxiv.org/abs/2605.29640)
-
-## VikingBot 部署详情
-
-OpenViking 有一个类似 nanobot 的机器人用于交互工作,现已可用。
-
-👉 **[查看:使用 VikingBot 部署服务器](bot/README_CN.md)**
-
----
-
-## 核心概念
-
-运行第一个示例后,让我们深入了解 OpenViking 的设计理念。这五个核心概念与前面提到的解决方案一一对应,共同构建了一个完整的上下文管理系统:
-
-### 1. 文件系统管理范式 → 解决碎片化
-
-我们不再将上下文视为扁平的文本切片,而是将它们统一到一个抽象的虚拟文件系统中。无论是记忆、资源还是能力,都映射到 `viking://` 协议下的虚拟目录中,每个都有唯一的 URI。
-
-这种范式赋予智能体前所未有的上下文操作能力,使它们能够像开发者一样,通过 `ls` 和 `find` 等标准命令精确、确定地定位、浏览和操作信息。这将上下文管理从模糊的语义匹配转变为直观、可追踪的"文件操作"。了解更多:[Viking URI](./docs/zh/concepts/04-viking-uri.md) | [上下文类型](./docs/zh/concepts/02-context-types.md)
+- **可视化接入本地 Agent**:检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae 和 OpenCode,并配置支持的插件、MCP、Hook 和 CLI 接入。
+- **查看会话轨迹**:解析 Claude Code、Codex 和 Trae 的会话,展示 OpenViking 的召回、Prompt 注入、MCP 调用、捕获和提交事件。
+- **管理本地记忆与技能**:查看本地 memory / rule 文件和 `SKILL.md` 技能,并同步到 OpenViking。
-```
-viking://
-├── resources/ # 资源:项目文档、代码库、网页等
-│ ├── my_project/
-│ │ ├── docs/
-│ │ │ ├── api/
-│ │ │ └── tutorials/
-│ │ └── src/
-│ └── ...
-├── user/ # 用户:个人偏好、习惯等
-│ └── {user_id}/
-│ ├── memories/
-│ │ ├── preferences/
-│ │ │ ├── writing_style
-│ │ │ └── coding_habits
-│ │ └── ...
-│ ├── resources/
-│ │ └── private_project/
-│ ├── skills/
-│ │ ├── search_code
-│ │ └── analyze_data
-│ └── peers/
-│ └── web-visitor-alice/
-│ ├── memories/
-│ └── resources/
-```
+下载:
-### 2. 分层上下文加载 → 降低 Token 消耗
+- [macOS Apple Silicon 版(arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
+- [macOS Intel 版(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
+- [Windows 版(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-一次性将大量上下文塞入提示不仅昂贵,而且容易超出模型窗口并引入噪声。OpenViking 在写入时自动将上下文处理为三个级别:
-- **L0 (摘要)**:一句话摘要,用于快速检索和识别。
-- **L1 (概览)**:包含核心信息和使用场景,用于智能体在规划阶段的决策。
-- **L2 (详情)**:完整的原始数据,供智能体在绝对必要时深度阅读。
+## VikingBot
-了解更多:[上下文分层](./docs/zh/concepts/03-context-layers.md)
+VikingBot 是构建在 OpenViking 之上的 AI 智能体框架:
+```bash
+pip install "openviking[bot]"
+openviking-server --with-bot
+ov chat # 在另一个终端运行
```
-viking://resources/my_project/
-├── .abstract # L0 层:摘要(~100 tokens)- 快速相关性检查
-├── .overview # L1 层:概览(~2k tokens)- 理解结构和关键点
-├── docs/
-│ ├── .abstract # 每个目录都有对应的 L0/L1 层
-│ ├── .overview
-│ ├── api/
-│ │ ├── .abstract
-│ │ ├── .overview
-│ │ ├── auth.md # L2 层:完整内容 - 按需加载
-│ │ └── endpoints.md
-│ └── ...
-└── src/
- └── ...
-```
-
-### 3. 目录递归检索 → 提升检索效果
-
-单一向量检索难以应对复杂的查询意图。OpenViking 设计了创新的**目录递归检索策略**,深度集成多种检索方法:
-
-1. **意图分析**:通过意图分析生成多个检索条件。
-2. **初始定位**:使用向量检索快速定位初始切片所在的高分目录。
-3. **精细探索**:在该目录内进行二次检索,并将高分结果更新到候选集。
-4. **递归深入**:如果存在子目录,则逐层递归重复二次检索步骤。
-5. **结果聚合**:最终获取最相关的上下文返回。
-
-这种"先锁定高分目录,再精细化内容探索"的策略不仅找到语义最佳匹配的片段,还能理解信息所在的完整上下文,从而提高检索的全局性和准确性。了解更多:[检索机制](./docs/zh/concepts/07-retrieval.md)
-
-### 4. 可视化检索轨迹 → 可观察上下文
-
-OpenViking 的组织采用分层虚拟文件系统结构。所有上下文以统一格式集成,每个条目对应一个唯一的 URI(如 `viking://` 路径),打破了传统的扁平黑盒管理模式,具有清晰易懂的层次结构。
-
-检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹被完整保留,让用户能够清晰观察问题的根源,指导检索逻辑的优化。了解更多:[检索机制](./docs/zh/concepts/07-retrieval.md)
-
-### 5. 自动会话管理 → 上下文自迭代
-OpenViking 内置了记忆自迭代循环。提交会话后,系统会异步分析任务执行结果和用户反馈,并根据记忆策略更新当前用户或 Peer 命名空间中的记忆。
+官方 Docker 镜像内置 VikingBot,默认随服务器和控制台 UI 一起启动。详情见 [VikingBot 指南](https://docs.openviking.ai/zh/guides/17-vikingbot)。
-- **用户记忆更新**:更新与用户偏好相关的记忆,使智能体响应更好地适应用户需求。
-- **智能体经验积累**:从任务执行经验中提取操作技巧和工具使用经验等核心内容,辅助后续任务的高效决策。
+## 生产部署
-这使得智能体能够通过与世界的交互"越用越聪明",实现自我进化。了解更多:[会话管理](./docs/zh/concepts/08-session.md)
+生产环境建议把 OpenViking 作为独立 HTTP 服务运行——见[服务器部署](https://docs.openviking.ai/zh/getting-started/03-quickstart-server)和[部署指南](https://docs.openviking.ai/zh/guides/03-deployment)。
----
+不想自己运维?OpenViking Personal 由官方托管、开箱即用,借助 VikingDB 获得远超本地硬件的扩展能力,并提供至多 50 个文件的免费试用;开源版用户可以用迁移工具平滑迁移。→ [openviking.ai](https://www.openviking.ai)
-## 深入阅读
+## 研究
-### 文档
+OpenViking 开源了 VikingMem 论文中描述的部分核心能力:
-更多详情,请访问我们的[完整文档](./docs/zh/)。
-
-### 社区与团队
-
-更多详情,请参见:**[关于我们](./docs/zh/about/01-about-us.md)**
-
-### 加入社区
-
-OpenViking 仍处于早期阶段,有许多改进和探索的空间。我们真诚邀请每一位对 AI 智能体技术充满热情的开发者:
-
-- 为我们点亮一颗珍贵的 **Star**,给我们前进的动力。
-- 访问我们的[**官网**](https://www.openviking.ai)了解我们传达的理念,并通过[**文档**](https://www.openviking.ai/docs)在您的项目中使用它。感受它带来的变化,并给我们最真实的体验反馈。
-- 加入我们的社区,分享您的见解,帮助回答他人的问题,共同创造开放互助的技术氛围:
- - 📱 **飞书群**:扫码加入 → [查看二维码](./docs/zh/about/01-about-us.md#lark-group)
- - 💬 **微信群**:扫码添加助手 → [查看二维码](./docs/zh/about/01-about-us.md#wechat-group)
- - 🎮 **Discord**:[加入 Discord 服务器](https://discord.com/invite/eHvx8E9XF3)
- - 🐦 **X (Twitter)**:[关注我们](https://x.com/openvikingai)
-- 成为**贡献者**,无论是提交错误修复还是贡献新功能,您的每一行代码都将是 OpenViking 成长的重要基石。
+> **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**
+> Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.
+> arXiv:2605.29640, 2026。已被 VLDB 2026 接收。
+> 📄 [在 arXiv 阅读论文](https://arxiv.org/abs/2605.29640)
-让我们共同努力,定义和构建 AI 智能体上下文管理的未来。旅程已经开始,期待您的参与!
+## 社区与贡献
-### Star 趋势
+OpenViking 还在早期阶段,要做的事还很多。
-[![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking&type=timeline&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left)
+- **文档**:[docs.openviking.ai](https://docs.openviking.ai/) · [FAQ](https://docs.openviking.ai/zh/faq/faq)
+- **博客**:[blog.openviking.ai](https://blog.openviking.ai/)
+- **团队**:[关于我们](https://docs.openviking.ai/zh/about/01-about-us)
+- **交流**:📱 [飞书群](https://docs.openviking.ai/zh/about/01-about-us#飞书群) · 💬 [微信群](https://docs.openviking.ai/zh/about/01-about-us#微信群) · 🎮 [Discord](https://discord.com/invite/eHvx8E9XF3) · 🐦 [X](https://x.com/openvikingai)
+- **贡献**:修 bug、加新功能都欢迎——见 [CONTRIBUTING_CN.md](CONTRIBUTING_CN.md)
## 安全与隐私
-本项目高度重视安全问题。
-有关漏洞报告方式和受支持版本,请参见 [SECURITY.md](SECURITY.md)
+本项目重视安全问题。
+漏洞报告方式和受支持的版本,见 [SECURITY.md](SECURITY.md)
## 许可证
-OpenViking 项目不同组件采用不同的开源协议:
-
-- **主项目**: AGPLv3 - 详情请参见 [LICENSE](./LICENSE) 文件
-- **crates/ov_cli**: Apache 2.0 - 详情请参见 [LICENSE](./crates/LICENSE) 文件
-- **examples**: Apache 2.0 - 详情请参见 [LICENSE](./examples/LICENSE) 文件
-- **third_party**: 保留各三方项目的原有协议
-
-
-<!-- Link Definitions -->
+OpenViking 各组件采用不同的许可证:
-[release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square
-[release-link]: https://github.com/volcengine/OpenViking/releases
-[license-shield]: https://img.shields.io/badge/license-AGPLv3-white?labelColor=black&style=flat-square
-[license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE
-[last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square
-[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main
-[github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47
-[github-stars-link]: https://github.com/volcengine/OpenViking
-[github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb
-[github-issues-shield-link]: https://github.com/volcengine/OpenViking/issues
-[github-contributors-shield]: https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square
-[github-contributors-link]: https://github.com/volcengine/OpenViking/graphs/contributors
+- **主项目**:AGPLv3——详见 [LICENSE](./LICENSE)
+- **crates/ov\_cli**:Apache 2.0——详见 [LICENSE](./crates/LICENSE)
+- **examples**:Apache 2.0——详见 [LICENSE](./examples/LICENSE)
+- **third\_party**:各三方项目保留其原有协议
diff --git a/README_JA.md b/README_JA.md
index ed336c2f6..ea34a013b 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -10,595 +10,217 @@
[English](README.md) / [中文](README_CN.md) / 日本語
-<a href="https://www.openviking.ai">Webサイト</a> · <a href="https://openviking.ai/studio">ライブデモ</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://www.openviking.ai/docs">ドキュメント</a>
+<a href="https://www.openviking.ai">Webサイト</a> · <a href="https://openviking.ai/studio">ライブデモ</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://docs.openviking.ai/">ドキュメント</a>
-[![][release-shield]][release-link]
-[![][github-stars-shield]][github-stars-link]
-[![][github-issues-shield]][github-issues-shield-link]
-[![][github-contributors-shield]][github-contributors-link]
-[![][license-shield]][license-shield-link]
-[![][last-commit-shield]][last-commit-shield-link]
+[![](https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff\&labelColor=black\&logo=github\&style=flat-square)](https://github.com/volcengine/OpenViking/releases)
+[![](https://img.shields.io/github/stars/volcengine/OpenViking?labelColor\&style=flat-square\&color=ffcb47)](https://github.com/volcengine/OpenViking)
+[![](https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black\&style=flat-square\&color=ff80eb)](https://github.com/volcengine/OpenViking/issues)
+[![](https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042\&labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/graphs/contributors)
+[![](https://img.shields.io/badge/license-AGPLv3-white?labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/blob/main/LICENSE)
+[![](https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042\&labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/commits/main)
👋 コミュニティに参加しよう
-📱 <a href="./docs/en/about/01-about-us.md#lark-group">Larkグループ</a> · <a href="./docs/en/about/01-about-us.md#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
+📱 <a href="https://docs.openviking.ai/en/about/01-about-us#lark-group">Larkグループ</a> · <a href="https://docs.openviking.ai/en/about/01-about-us#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
<a href="https://trendshift.io/repositories/19668" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19668" alt="volcengine%2FOpenViking | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</div>
----
+***
-## 概要
+## OpenVikingとは
-### エージェント開発における課題
+OpenVikingは、AIエージェントのためのオープンソースのコンテキストデータベースです。メモリ、リソース、スキルを `viking://` プロトコル配下の1つの仮想ファイルシステムとして保存するため、エージェントはブラックボックスのベクトルストアに問い合わせる代わりに、`ls`、`tree`、`find` で自分のコンテキストを閲覧できます。コンテンツは L0(abstract)、L1(overview)、L2(details)の3階層に処理され、必要に応じてロードされます。すべての検索は、観察してデバッグできる軌跡を残します。詳しい紹介はこちら: [Getting started](https://docs.openviking.ai/en/getting-started/01-introduction)。
-AI時代において、データは豊富ですが、高品質なコンテキストは得がたいものです。AIエージェントを構築する際、開発者はしばしば以下の課題に直面します:
+[![OpenViking Studio playground](docs/images/studio-playground.png)](https://openviking.ai/studio)
-- **断片化されたコンテキスト**: メモリはコードに、リソースはベクトルデータベースに、スキルは散在しており、統一的な管理が困難です。
-- **急増するコンテキスト需要**: エージェントの長時間タスクは実行のたびにコンテキストを生成します。単純な切り詰めや圧縮は情報の損失につながります。
-- **検索効果の低さ**: 従来のRAGはフラットなストレージを使用し、グローバルな視点が欠けているため、情報の全体的なコンテキストを理解することが困難です。
-- **観察不能なコンテキスト**: 従来のRAGの暗黙的な検索チェーンはブラックボックスのようで、エラー発生時のデバッグが困難です。
-- **限定的なメモリの反復**: 現在のメモリはユーザーとのやり取りの記録に過ぎず、エージェント関連のタスクメモリが不足しています。
+*[OpenViking Studio](https://openviking.ai/studio) のプレイグラウンド — インストール不要でブラウザから試せるライブデモです。*
-### OpenVikingのソリューション
+## OpenVikingを選ぶ理由
-**OpenViking**は、AIエージェント専用に設計されたオープンソースの**コンテキストデータベース**です。
+- **すべてのコンテキストを1つのファイルシステムに。** メモリ、リソース、スキルにはそれぞれ `viking://` URI が与えられます。エージェントは、ファイルを扱う開発者のように、コンテキストを決定論的に特定・操作できます。→ [Viking URI](https://docs.openviking.ai/en/concepts/04-viking-uri) · [Context types](https://docs.openviking.ai/en/concepts/02-context-types)
+- **階層型ローディングで token 消費を削減。** すべてのエントリは書き込み時に L0(abstract)、L1(overview)、L2(details)へ処理され、タスクが必要とする深さまでだけロードされます。→ [Context layers](https://docs.openviking.ai/en/concepts/03-context-layers)
+- **ディレクトリ再帰検索。** ベクトル検索でまず最高スコアのディレクトリを特定し、そこから層ごとに掘り下げるため、結果は周辺のコンテキストを保ったまま返ってきます。→ [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval)
+- **観察可能な検索。** 各クエリはディレクトリ閲覧の軌跡を保存します。結果がおかしいときは、どのパスがその結果を生んだのかを正確に確認できます。→ [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval)
+- **セッションはメモリになる。** セッションのコミット後、OpenVikingはユーザーの好みとエージェントの経験を非同期に抽出し、長期メモリとして保存します。→ [Session](https://docs.openviking.ai/en/concepts/08-session)
-私たちは、エージェントのためのミニマリストなコンテキストインタラクションパラダイムを定義し、開発者がコンテキスト管理の煩雑さから完全に解放されることを目指しています。OpenVikingは従来のRAGの断片化されたベクトルストレージモデルを捨て、革新的に**「ファイルシステムパラダイム」**を採用して、エージェントに必要なメモリ、リソース、スキルの構造化された組織を統一します。
+各要素がどう組み合わさるか: [Architecture](https://docs.openviking.ai/en/concepts/01-architecture)。設計思想: [The Database Paradigm for Context Engineering](https://blog.openviking.ai/post/openviking-context-database/)。
-OpenVikingを使えば、開発者はローカルファイルを管理するようにエージェントの頭脳を構築できます:
-
-- **ファイルシステム管理パラダイム** → **断片化を解決**: ファイルシステムパラダイムに基づく、メモリ、リソース、スキルの統一的なコンテキスト管理。
-- **階層型コンテキストローディング** → **トークン消費を削減**: L0/L1/L2の3層構造、オンデマンドでロードし、コストを大幅に削減。
-- **ディレクトリ再帰検索** → **検索効果を向上**: ネイティブのファイルシステム検索手法をサポートし、ディレクトリ位置決めとセマンティック検索を組み合わせて、再帰的で精密なコンテキスト取得を実現。
-- **可視化された検索軌跡** → **観察可能なコンテキスト**: ディレクトリ検索軌跡の可視化をサポートし、ユーザーが問題の根本原因を明確に観察し、検索ロジックの最適化を導くことを可能に。
-- **自動セッション管理** → **コンテキストの自己反復**: 会話中のコンテンツ、リソース参照、ツール呼び出しなどを自動的に圧縮し、長期メモリを抽出して、使うほどエージェントを賢く。
-
----
-
-## クイックスタート
-
-> 💡 **まず実際の動作を見てみたい方へ**:[OpenViking Studio](https://openviking.ai/studio) をお試しください。コンテキストプレイグラウンド、セマンティック検索、マルチエージェント Hub を備えたライブホスト環境で、インストール不要です。
-
-### OpenViking Helper for macOS / Windows(Beta)
-
-**OpenViking Helper** は OpenViking ユーザー向けのデスクトップアプリです。ローカル Agent の接続、セッショントレース、メモリ、スキルを可視化し、接続状態の確認とローカルコンテキストの OpenViking への同期を容易にします。
-
-主な機能:
-
-- **ローカル Agent 接続の可視化**:OpenViking CLI、Claude Code、Codex、Cursor、Trae、OpenCode を検出し、対応している plugin、MCP、Hook、CLI 接続を設定します。
-- **セッショントレースの確認**:Claude Code、Codex、Trae のセッションを解析し、OpenViking の recall、Prompt 注入、MCP 呼び出し、capture、commit イベントを表示します。
-- **ローカルメモリとスキル管理**:ローカルの memory / rule ファイルと `SKILL.md` スキルを確認し、OpenViking に同期します。
-
-> OpenViking Helper は現在 Beta 版で、macOS と Windows x64 をサポートしています。
-
-ダウンロード:
-
-- [macOS Apple Silicon(arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
-- [macOS Intel(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
-- [Windows(x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-
-### ローカルデプロイ
-
-#### 前提条件
-
-OpenVikingを始める前に、環境が以下の要件を満たしていることを確認してください:
-
-- **Pythonバージョン**: 3.10以上
-- **Rustツールチェーン**: Cargo(RAGFSおよびCLIコンポーネントのソースビルドに必要)
-- **C++コンパイラ**: GCC 9以上 または Clang 11以上(コア拡張のビルドに必要)
-- **オペレーティングシステム**: Linux、macOS、Windows
-- **ネットワーク接続**: 安定したネットワーク接続が必要(依存関係のダウンロードとモデルサービスへのアクセスのため)
-
-#### 1. インストール
-
-##### Pythonパッケージ
-
-```bash
-pip install openviking --upgrade --force-reinstall
-```
-
-##### Rust CLI(オプション)
-
-```bash
-npm i -g @openviking/cli
-```
-
-またはソースからビルド:
-
-```bash
-cargo install --git https://github.com/volcengine/OpenViking ov_cli
-```
-
-#### 2. モデルの準備
-
-OpenVikingには以下のモデル機能が必要です:
-- **VLMモデル**: 画像とコンテンツの理解用
-- **Embeddingモデル**: ベクトル化とセマンティック検索用
-
-##### サポートされているVLMプロバイダー
-
-OpenVikingは3つのVLMプロバイダーをサポートしています:
-
-| プロバイダー | 説明 | APIキーの取得 |
-|----------|-------------|-------------|
-| `volcengine` | Volcengine Doubaoモデル | [Volcengineコンソール](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_content=OpenViking&utm_medium=devrel&utm_source=OWO&utm_term=OpenViking) |
-| `openai` | OpenAI公式API | [OpenAIプラットフォーム](https://platform.openai.com) |
-
-##### プロバイダー固有の注意事項
-
-<details>
-<summary><b>Volcengine(Doubao)</b></summary>
-
-Volcengineはモデル名とエンドポイントIDの両方をサポートしています。簡便さのためモデル名の使用を推奨します:
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "doubao-seed-2-0-lite-260428",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-エンドポイントIDも使用できます([Volcengine ARKコンソール](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_content=OpenViking&utm_medium=devrel&utm_source=OWO&utm_term=OpenViking)で確認):
-
-```json
-{
- "vlm": {
- "provider": "volcengine",
- "model": "ep-20241220174930-xxxxx",
- "api_key": "your-api-key",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>OpenAI</b></summary>
-
-OpenAIの公式APIを使用:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://api.openai.com/v1"
- }
-}
-```
-
-カスタムのOpenAI互換エンドポイントも使用できます:
-
-```json
-{
- "vlm": {
- "provider": "openai",
- "model": "gpt-4o",
- "api_key": "your-api-key",
- "api_base": "https://your-custom-endpoint.com/v1"
- }
-}
-```
-
-</details>
-
-#### 3. 環境設定
-
-##### サーバー設定テンプレート
-
-設定ファイル `~/.openviking/ov.conf` を作成します。コピー前にコメントを削除してください:
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // ログ出力: "stdout" または "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "<api-endpoint>", // APIエンドポイントアドレス
- "api_key" : "<your-api-key>", // モデルサービスAPIキー
- "provider" : "<provider-type>", // プロバイダータイプ: "volcengine" または "openai"(現在サポート済み)
- "dimension": 1024, // ベクトル次元
- "model" : "<model-name>" // Embeddingモデル名(例:doubao-embedding-vision-251215 または text-embedding-3-large)
- },
- "max_concurrent": 10 // 最大同時Embeddingリクエスト数(デフォルト: 10)
- },
- "vlm": {
- "api_base" : "<api-endpoint>", // APIエンドポイントアドレス
- "api_key" : "<your-api-key>", // モデルサービスAPIキー
- "provider" : "<provider-type>", // プロバイダータイプ(volcengine、openai、deepseek、anthropicなど)
- "model" : "<model-name>", // VLMモデル名(例:doubao-seed-2-0-lite-260428 または gpt-4-vision-preview)
- "max_concurrent": 100 // セマンティック処理の最大同時LLM呼び出し数(デフォルト: 100)
- }
-}
-```
-
-> **注意**: Embeddingモデルについては、`volcengine`(Doubao)、`openai`、`azure`、`jina`、`ollama`、`voyage`、`dashscope`、`minimax`、`cohere`、`vikingdb`、`gemini`(`pip install "google-genai>=1.0.0"` が必要)、`litellm`、`local` プロバイダーがサポートされています。VLMモデルについては、`volcengine`、`openai`、`openai-codex`、`kimi`、`glm` をサポートしています。
-
-##### サーバー設定例
-
-👇 お使いのモデルサービスの設定例を展開して確認:
-
-<details>
-<summary><b>例1: Volcengine(Doubaoモデル)を使用</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // ログ出力: "stdout" または "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "dimension": 1024,
- "model" : "doubao-embedding-vision-251215"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
- "api_key" : "your-volcengine-api-key",
- "provider" : "volcengine",
- "model" : "doubao-seed-2-0-lite-260428",
- "max_concurrent": 100
- }
-}
-```
-
-</details>
-
-<details>
-<summary><b>例2: OpenAIモデルを使用</b></summary>
-
-```json
-{
- "storage": {
- "workspace": "/home/your-name/openviking_workspace"
- },
- "log": {
- "level": "INFO",
- "output": "stdout" // ログ出力: "stdout" または "file"
- },
- "embedding": {
- "dense": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "dimension": 3072,
- "model" : "text-embedding-3-large"
- },
- "max_concurrent": 10
- },
- "vlm": {
- "api_base" : "https://api.openai.com/v1",
- "api_key" : "your-openai-api-key",
- "provider" : "openai",
- "model" : "gpt-4-vision-preview",
- "max_concurrent": 100
- }
-}
```
+viking://
+├── resources/ # リソース: プロジェクトドキュメント、リポジトリ、Webページなど
+│ └── my_project/
+│ ├── docs/
+│ │ ├── api/
+│ │ └── tutorials/
+│ └── src/
+└── user/
+ └── {user_id}/
+ ├── memories/
+ │ └── preferences/
+ │ ├── writing_style
+ │ └── coding_habits
+ ├── resources/
+ │ └── private_project/
+ ├── skills/
+ │ ├── search_code
+ │ └── analyze_data
+ └── peers/
+ └── web-visitor-alice/
+```
+
+3つのローディング階層:
+
+- **L0(Abstract)**: 迅速な関連性チェックのための一文の要約。
+- **L1(Overview)**: 計画立案のためのコア情報と使用シナリオ。
+- **L2(Details)**: 完全なオリジナルデータ。必要な場合にのみ読み込まれます。
+
+各ディレクトリが自身の L0/L1 レイヤーを持つため、ファイル全体を読む前に関連性を判断できます:
-</details>
-
-##### サーバー設定の環境変数の設定
-
-設定ファイルを作成後、環境変数を設定してファイルを指定します(Linux/macOS):
-
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # デフォルト
```
-
-Windowsの場合、以下のいずれかを使用:
-
-PowerShell:
-
-```powershell
-$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"
+viking://resources/my_project/
+├── .abstract # L0: 〜100 tokens - 迅速な関連性チェック
+├── .overview # L1: 〜2k tokens - 構造とキーポイント
+└── docs/
+ ├── .abstract
+ ├── .overview
+ └── api/
+ ├── auth.md # L2: 完全なコンテンツ、オンデマンドでロード
+ └── endpoints.md
```
-コマンドプロンプト(cmd.exe):
-
-```bat
-set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"
-```
+## 実証データ
-> 💡 **ヒント**: 設定ファイルは他の場所に配置することもできます。環境変数で正しいパスを指定するだけです。
+OpenViking 0.3.22 は、長い会話でのユーザーメモリ(LoCoMo)と複数ターンのエージェントタスク(tau2-bench)で評価されています。ナレッジベースQAを含む完全な結果と実験設定は[ベンチマークレポート](https://blog.openviking.ai/post/openviking-benchmark-results/)を、再現用スクリプトは [./benchmark](./benchmark) を参照してください。
-##### CLI/クライアント設定例
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/benchmark-dark.svg">
+ <img alt="Benchmark results. LoCoMo accuracy: OpenClaw 24.20% native vs 82.08% with OpenViking; Hermes 33.38% vs 82.86%; Claude Code 57.21% vs 80.32%. tau2-bench task success: Retail 70.94% vs 77.81%; Airline 54.38% vs 66.25%." src="docs/images/benchmark-light.svg">
+</picture>
-👇 CLI/クライアントの設定例を展開して確認:
+- **ユーザーメモリ(LoCoMo)**: OpenViking を接続すると、3つのエージェント統合すべてで精度が 80–83% に達します(ネイティブメモリでは 24–57%)。同時に入力 token は 34.3–91.0%、クエリレイテンシは 58.45–66.10% 削減されます。
+- **エージェント経験(tau2-bench)**: 経験メモリにより、タスク成功率は同一 LLM(メモリなし)比で Retail +6.87pp、Airline +11.87pp 向上します。
-例:localhostサーバー接続用のovcli.conf
+## クイックスタート
-```json
-{
- "url": "http://localhost:1933",
- "timeout": 60.0
-}
-```
+> 💡 **まず動くところを見たい方へ**: [OpenViking Studio](https://openviking.ai/studio) をお試しください。コンテキストプレイグラウンド、セマンティック検索、マルチエージェント Hub を備えたライブホスト版インスタンスで、インストールは不要です。
-設定ファイルを作成後、環境変数を設定してファイルを指定します(Linux/macOS):
+Python 3.10 以上が必要です。
```bash
-export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # デフォルト
-```
-
-Windowsの場合、以下のいずれかを使用:
-
-PowerShell:
-
-```powershell
-$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"
-```
-
-コマンドプロンプト(cmd.exe):
-
-```bat
-set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"
+pip install openviking --upgrade
+openviking-server init # 対話式ウィザード: プロバイダー、モデル、ov.conf
+openviking-server doctor # セットアップを検証
+openviking-server # 起動
```
-#### 4. 最初の例を実行
-
-> 📝 **前提条件**: 前のステップで設定(ov.confとovcli.conf)が完了していることを確認してください。
-
-それでは、完全な例を実行してOpenVikingのコア機能を体験しましょう。
-
-##### サーバーの起動
+または、サーバーをバックグラウンドで実行します:
```bash
-openviking-server
+nohup openviking-server > /data/log/openviking.log 2>&1 &
```
-またはバックグラウンドで実行:
+`init` はプロバイダー設定を対話的に進め、`~/.openviking/ov.conf` を書き出します。Volcengine、OpenAI、Codex OAuth、Kimi、GLM、ローカルの Ollama をサポートし、Ollama についてはランタイムの検出とインストール、ハードウェアに適したモデルの取得も行えます。`doctor` は、サーバーを起動せずに設定ファイル、Python バージョン、プロバイダーへの接続性、ディスク容量をチェックします。
-```bash
-nohup openviking-server > /data/log/openviking.log 2>&1 &
-```
+手動で書く `ov.conf` テンプレート、プロバイダーごとの設定例、環境変数、Windows でのセットアップ、CLI/クライアント設定は、[Configuration guide](https://docs.openviking.ai/en/guides/01-configuration) と [Quick start docs](https://docs.openviking.ai/en/getting-started/02-quickstart) にあります。
-##### CLIの実行
+サーバーが起動したら:
```bash
ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
-# --waitを指定しない場合、セマンティック処理の完了を待つ
+# --wait を付けない場合は、セマンティック処理の完了までしばらく待ちます
ov find "what is openviking"
-ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh
-```
-
-おめでとうございます!OpenVikingの実行に成功しました 🎉
-
-### 商用版へのアクセス
-
-OpenViking Personal が正式に提供開始されました。オープンソース版と比較して、Service 版は公式にホスティングされてすぐに利用でき、VikingDB によりローカルハードウェアをはるかに超える規模までスケールし、より豊富な統合機能とプロフェッショナルサポートが付属します。最大 50 ファイルまでの無料トライアルが含まれており、既存のオープンソース版ユーザーは移行ツールを使ってスムーズに乗り換えることができます。
-
-### VikingBotクイックスタート
-
-VikingBotは、OpenViking上に構築されたAIエージェントフレームワークです。始め方は以下の通りです:
-
-```bash
-# オプション1: PyPIからVikingBotをインストール(ほとんどのユーザーに推奨)
-pip install "openviking[bot]"
-
-# オプション2: ソースからVikingBotをインストール(開発用)
-uv pip install -e ".[bot]"
-
-# Bot有効でOpenVikingサーバーを起動
-openviking-server --with-bot
-
-# 別のターミナルでインタラクティブチャットを開始
-ov chat
+ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
```
----
-
-## サーバーデプロイの詳細
-
-本番環境では、AIエージェントに永続的で高性能なコンテキストサポートを提供するため、OpenVikingをスタンドアロンHTTPサービスとして実行することを推奨します。
+既存インデックスの再構築: `ov reindex <uri> --mode vectors_only` はベクトルのみ更新します。`--mode semantic_and_vectors` はセマンティック生成物(`.abstract.md`、`.overview.md`)を再生成してからベクトルを更新し、`--mode prune_orphans` はソースファイルが存在しないベクトルレコードを削除します(`--dry-run` でプレビュー可能)。`semantic` や `full` というモードエイリアスはありません。
-🚀 **クラウドにOpenVikingをデプロイ**:
-最適なストレージパフォーマンスとデータセキュリティを確保するため、**veLinux**オペレーティングシステムを使用した**Volcengine Elastic Compute Service(ECS)**へのデプロイを推奨します。迅速に開始するための詳細なステップバイステップガイドを用意しています。
+クライアント設定は `ov config` で対話的に初期化できます。複数のサーバーを運用する場合は `ov config switch` で切り替えます。
-👉 **[参照: サーバーデプロイ&ECSセットアップガイド](./docs/en/getting-started/03-quickstart-server.md)**
+Rust CLI は `npm i -g @openviking/cli` でインストールできます。ソースからのビルドは `cargo install --git https://github.com/volcengine/OpenViking ov_cli` を使います — [CLI setup](https://docs.openviking.ai/en/getting-started/05-cli-setup) を参照してください。公式 Docker イメージもあります。[Deployment guide](https://docs.openviking.ai/en/guides/03-deployment) を参照してください。
+## エージェントと組み合わせて使う
-## OpenClawコンテキストプラグインの詳細
+統合機能は、OpenViking の recall をエージェントのコンテキストに注入し、セッションメモリを自動的にコミットします:
-* テストデータセット: LoCoMo10(https://github.com/snap-research/locomo)の長距離対話に基づく効果テスト(ground truthのないcategory5を除いた合計1,540ケース)
-* 実験グループ: ユーザーがOpenVikingを使用する際にOpenClawのネイティブメモリを無効にしない可能性があるため、ネイティブメモリの有効/無効の実験グループを追加
-* OpenVikingバージョン: 0.1.18
-* モデル: seed-2.0-code
-* 評価スクリプト: https://github.com/ZaynJarvis/openclaw-eval/tree/main
+- [Claude Code](https://docs.openviking.ai/en/agent-integrations/02-claude-code)
+- [Codex](https://docs.openviking.ai/en/agent-integrations/04-codex)
+- [OpenClaw](https://docs.openviking.ai/en/agent-integrations/03-openclaw)
+- [Hermes](https://docs.openviking.ai/en/agent-integrations/05-hermes)
+- [Cursor](https://docs.openviking.ai/en/agent-integrations/12-cursor)
+- [Trae](https://docs.openviking.ai/en/agent-integrations/13-trae)
+- [OpenCode](https://docs.openviking.ai/en/agent-integrations/10-opencode)
+- [pi](https://docs.openviking.ai/en/agent-integrations/11-pi)
+- [MCP クライアント](https://docs.openviking.ai/en/agent-integrations/06-mcp-clients)
+- [LangChain / LangGraph](https://docs.openviking.ai/en/agent-integrations/07-langchain-langgraph)
-| 実験グループ | タスク完了率 | コスト: 入力トークン数(合計) |
-|----------|------------------|------------------|
-| OpenClaw(memory-core) | 35.65% | 24,611,530 |
-| OpenClaw + LanceDB (-memory-core) | 44.55% | 51,574,530 |
-| OpenClaw + OpenViking Plugin (-memory-core) | 52.08% | 4,264,396 |
-| OpenClaw + OpenViking Plugin (+memory-core) | 51.23% | 2,099,622 |
+各エージェントのセットアップ手順: [Agent integrations overview](https://docs.openviking.ai/en/agent-integrations/01-overview)。
-* 実験結果:
-OpenViking統合後:
-- ネイティブメモリ有効時: オリジナルOpenClawと比較して43%改善、入力トークンコスト91%削減。LanceDBと比較して15%改善、入力トークンコスト96%削減。
-- ネイティブメモリ無効時: オリジナルOpenClawと比較して49%改善、入力トークンコスト83%削減。LanceDBと比較して17%改善、入力トークンコスト92%削減。
+## OpenViking Helper(Beta)
-👉 **[参照: OpenClawコンテキストプラグイン](examples/openclaw-plugin/README.md)**
+OpenViking Helper はデスクトップコンソールで、現在 macOS と Windows x64 向けの Beta 版として提供しています:
-👉 **[参照: OpenCode統合プラグイン](examples/opencode-plugin/README.md)**
+- **ローカルエージェント設定の可視化**: OpenViking CLI、Claude Code、Codex、Cursor、Trae、OpenCode を検出し、対応する plugin、MCP、Hook、CLI 統合を設定します。
+- **セッショントレースの確認**: Claude Code、Codex、Trae のセッションを解析し、OpenViking の recall、プロンプト注入、MCP 呼び出し、capture、commit の各イベントを表示します。
+- **ローカルメモリとスキルの管理**: ローカルの memory / rule ファイルと `SKILL.md` スキルを確認し、OpenViking に同期します。
-👉 **[参照: Claude Codeメモリプラグインの例](examples/claude-code-memory-plugin/README.md)**
+ダウンロード:
---
+- [macOS Apple Silicon (arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
+- [macOS Intel (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
+- [Windows (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
-## コアコンセプト
+## VikingBot
-最初の例を実行した後、OpenVikingの設計思想を掘り下げましょう。これら5つのコアコンセプトは、先に述べたソリューションと1対1で対応し、完全なコンテキスト管理システムを構築します:
+VikingBot は、OpenViking 上に構築された AI エージェントフレームワークです:
-### 1. ファイルシステム管理パラダイム → 断片化の解決
-
-コンテキストをフラットなテキストスライスとして見るのではなく、抽象的な仮想ファイルシステムに統一します。メモリ、リソース、機能のいずれも、`viking://`プロトコル下の仮想ディレクトリにマッピングされ、それぞれにユニークなURIが付与されます。
-
-このパラダイムにより、エージェントはこれまでにないコンテキスト操作能力を獲得し、開発者のように`ls`や`find`などの標準コマンドを通じて、情報を正確かつ決定論的に位置特定、閲覧、操作できます。これにより、コンテキスト管理は曖昧なセマンティックマッチングから、直感的でトレース可能な「ファイル操作」に変わります。詳細: [Viking URI](./docs/en/concepts/04-viking-uri.md) | [コンテキストタイプ](./docs/en/concepts/02-context-types.md)
-
-```
-viking://
-├── resources/ # リソース: プロジェクトドキュメント、リポジトリ、Webページなど
-│ ├── my_project/
-│ │ ├── docs/
-│ │ │ ├── api/
-│ │ │ └── tutorials/
-│ │ └── src/
-│ └── ...
-├── user/ # ユーザー: 個人の好み、習慣など
-│ └── {user_id}/
-│ ├── memories/
-│ │ ├── preferences/
-│ │ │ ├── writing_style
-│ │ │ └── coding_habits
-│ │ └── ...
-│ ├── resources/
-│ │ └── private_project/
-│ ├── skills/
-│ │ ├── search_code
-│ │ └── analyze_data
-│ └── peers/
-│ └── web-visitor-alice/
-│ ├── memories/
-│ └── resources/
-└── agent/
- └── skills/ # 任意のアカウント全体の共有スキル
-```
-
-### 2. 階層型コンテキストローディング → トークン消費の削減
-
-大量のコンテキストをプロンプトに一度に詰め込むことは、コストが高いだけでなく、モデルウィンドウの超過やノイズの混入を招きやすいです。OpenVikingは書き込み時にコンテキストを自動的に3つのレベルに処理します:
-- **L0(Abstract)**: 迅速な検索と識別のための一文の要約。
-- **L1(Overview)**: 計画フェーズでのエージェントの意思決定のための、コア情報と使用シナリオを含む。
-- **L2(Details)**: エージェントが絶対に必要な場合の深い読み込みのための、完全なオリジナルデータ。
-
-詳細: [コンテキストレイヤー](./docs/en/concepts/03-context-layers.md)
-
-```
-viking://resources/my_project/
-├── .abstract # L0レイヤー: 要約(〜100トークン)- 迅速な関連性チェック
-├── .overview # L1レイヤー: 概要(〜2kトークン)- 構造とキーポイントの理解
-├── docs/
-│ ├── .abstract # 各ディレクトリに対応するL0/L1レイヤーあり
-│ ├── .overview
-│ ├── api/
-│ │ ├── .abstract
-│ │ ├── .overview
-│ │ ├── auth.md # L2レイヤー: 完全なコンテンツ - オンデマンドでロード
-│ │ └── endpoints.md
-│ └── ...
-└── src/
- └── ...
+```bash
+pip install "openviking[bot]"
+openviking-server --with-bot
+ov chat # 別のターミナルで実行
```
-### 3. ディレクトリ再帰検索 → 検索効果の向上
+公式 Docker イメージには VikingBot が同梱されており、サーバーとコンソール UI とともにデフォルトで起動します。詳細: [VikingBot guide](https://docs.openviking.ai/en/guides/17-vikingbot)。
-単一のベクトル検索では、複雑なクエリインテントへの対応が困難です。OpenVikingは、複数の検索手法を深く統合する革新的な**ディレクトリ再帰検索戦略**を設計しました:
+## 本番環境へのデプロイ
-1. **インテント分析**: インテント分析により複数の検索条件を生成。
-2. **初期位置特定**: ベクトル検索を使用して、初期スライスが位置する高スコアディレクトリを素早く特定。
-3. **詳細な探索**: そのディレクトリ内で二次検索を実行し、高スコア結果を候補セットに更新。
-4. **再帰的掘り下げ**: サブディレクトリが存在する場合、二次検索ステップを層ごとに再帰的に繰り返し。
-5. **結果集約**: 最終的に、最も関連性の高いコンテキストを取得して返却。
+本番環境では、OpenViking をスタンドアロンの HTTP サービスとして実行してください — [Server deployment](https://docs.openviking.ai/en/getting-started/03-quickstart-server) と [Deployment guide](https://docs.openviking.ai/en/guides/03-deployment) を参照してください。
-この「まず高スコアディレクトリを特定し、次にコンテンツ探索を精緻化する」戦略は、セマンティック的に最もマッチするフラグメントを見つけるだけでなく、情報が存在するコンテキスト全体を理解し、検索のグローバル性と精度を向上させます。詳細: [検索メカニズム](./docs/en/concepts/07-retrieval.md)
+自分で運用したくない場合は、公式ホスティング版の OpenViking Personal をすぐに利用できます。VikingDB によりローカルハードウェアをはるかに超える規模までスケールし、最大 50 ファイルまでの無料トライアルが付属します。既存のオープンソース版ユーザーは移行ツールで移行できます。→ [openviking.ai](https://www.openviking.ai)
-### 4. 可視化された検索軌跡 → 観察可能なコンテキスト
+## 研究
-OpenVikingの組織は階層的な仮想ファイルシステム構造を使用しています。すべてのコンテキストは統一されたフォーマットで統合され、各エントリはユニークなURI(`viking://`パスのようなもの)に対応し、従来のフラットなブラックボックス管理モードを、理解しやすい明確な階層で打ち破ります。
+OpenViking は、VikingMem 論文に記載されたコア機能の一部をオープンソースとして公開しています:
-検索プロセスはディレクトリ再帰戦略を採用しています。各検索のディレクトリブラウジングとファイル位置特定の軌跡が完全に保存され、ユーザーが問題の根本原因を明確に観察し、検索ロジックの最適化を導くことを可能にします。詳細: [検索メカニズム](./docs/en/concepts/07-retrieval.md)
+> **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**
+> Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.
+> arXiv:2605.29640, 2026. Accepted by VLDB 2026.
+> 📄 [arXiv で論文を読む](https://arxiv.org/abs/2605.29640)
-### 5. 自動セッション管理 → コンテキストの自己反復
+## コミュニティとコントリビューション
-OpenVikingにはメモリの自己反復ループが組み込まれています。セッションをコミットすると、システムはタスクの実行結果とユーザーフィードバックを非同期に分析し、メモリポリシーに従って現在のユーザーまたは Peer 名前空間のメモリを更新します。
+OpenViking はまだ初期段階にあり、作るべきものが数多く残っています。
-- **ユーザーメモリの更新**: ユーザーの好みに関するメモリを更新し、エージェントの応答がユーザーのニーズにより適合するように。
-- **エージェントの経験蓄積**: タスク実行経験から操作のヒントやツールの使用経験などのコアコンテンツを抽出し、後続タスクでの効率的な意思決定を支援。
-
-これにより、エージェントは世界とのインタラクションを通じて「使うほど賢く」なり、自己進化を実現します。詳細: [セッション管理](./docs/en/concepts/08-session.md)
-
----
-
-## 上級者向け資料
-
-### ドキュメント
-
-詳細については、[完全なドキュメント](./docs/en/)をご覧ください。
-
-### コミュニティとチーム
-
-詳細については、**[私たちについて](./docs/en/about/01-about-us.md)**をご覧ください。
-
-### コミュニティに参加
-
-OpenVikingはまだ初期段階にあり、改善と探索の余地が多くあります。AIエージェント技術に情熱を持つすべての開発者を心から招待します:
-
-- 前進の原動力となる貴重な**Star**をお願いします。
-- 私たちの[**Webサイト**](https://www.openviking.ai)を訪れて、伝えたい思想を理解し、[**ドキュメント**](https://www.openviking.ai/docs)を通じてプロジェクトで使用してください。変化を感じ、最も率直な体験をフィードバックしてください。
-- コミュニティに参加して、洞察を共有し、他の人の質問に答え、オープンで互助的な技術の雰囲気を共に作りましょう:
- - 📱 **Larkグループ**: QRコードをスキャンして参加 → [QRコードを表示](./docs/en/about/01-about-us.md#lark-group)
- - 💬 **WeChatグループ**: QRコードをスキャンしてアシスタントを追加 → [QRコードを表示](./docs/en/about/01-about-us.md#wechat-group)
- - 🎮 **Discord**: [Discordサーバーに参加](https://discord.com/invite/eHvx8E9XF3)
- - 🐦 **X(Twitter)**: [フォローする](https://x.com/openvikingai)
-- **コントリビューター**になってください。バグ修正の提出でも新機能のコントリビューションでも、あなたのコードの一行一行がOpenVikingの成長の重要な礎石となります。
-
-AIエージェントのコンテキスト管理の未来を共に定義し、構築しましょう。旅は始まりました。あなたの参加をお待ちしています!
-
-### Starの推移
-
-[![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking&type=timeline&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left)
+- **ドキュメント**: [docs.openviking.ai](https://docs.openviking.ai/) · [FAQ](https://docs.openviking.ai/en/faq/faq)
+- **ブログ**: [blog.openviking.ai](https://blog.openviking.ai/)
+- **チーム**: [About us](https://docs.openviking.ai/en/about/01-about-us)
+- **チャット**: 📱 [Larkグループ](https://docs.openviking.ai/en/about/01-about-us#lark-group) · 💬 [WeChat](https://docs.openviking.ai/en/about/01-about-us#wechat-group) · 🎮 [Discord](https://discord.com/invite/eHvx8E9XF3) · 🐦 [X](https://x.com/openvikingai)
+- **コントリビュート**: バグ修正も新機能も歓迎します — [CONTRIBUTING_JA.md](CONTRIBUTING_JA.md) を参照してください
## セキュリティとプライバシー
このプロジェクトはセキュリティを重視しています。
-脆弱性の報告方法とサポート対象バージョンについては、[SECURITY.md](SECURITY.md) を参照してください。
+脆弱性の報告方法とサポート対象バージョンについては、[SECURITY.md](SECURITY.md) を参照してください
## ライセンス
-OpenVikingプロジェクトは、コンポーネントごとに異なるライセンスを使用しています:
-
-- **メインプロジェクト**: AGPLv3 - 詳細は[LICENSE](./LICENSE)ファイルを参照してください
-- **crates/ov_cli**: Apache 2.0 - 詳細は[LICENSE](./crates/ov_cli/LICENSE)ファイルを参照してください
-- **examples**: Apache 2.0 - 詳細は[LICENSE](./examples/LICENSE)ファイルを参照してください
-- **third_party**: 各サードパーティプロジェクトの元のライセンス
-
-
-<!-- リンク定義 -->
+OpenViking プロジェクトは、コンポーネントごとに異なるライセンスを使用しています:
-[release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square
-[release-link]: https://github.com/volcengine/OpenViking/releases
-[license-shield]: https://img.shields.io/badge/license-AGPLv3-white?labelColor=black&style=flat-square
-[license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE
-[last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square
-[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main
-[github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47
-[github-stars-link]: https://github.com/volcengine/OpenViking
-[github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb
-[github-issues-shield-link]: https://github.com/volcengine/OpenViking/issues
-[github-contributors-shield]: https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square
-[github-contributors-link]: https://github.com/volcengine/OpenViking/graphs/contributors
+- **メインプロジェクト**: AGPLv3 - 詳細は [LICENSE](./LICENSE) ファイルを参照してください
+- **crates/ov\_cli**: Apache 2.0 - 詳細は [LICENSE](./crates/LICENSE) を参照してください
+- **examples**: Apache 2.0 - 詳細は [LICENSE](./examples/LICENSE) を参照してください
+- **third\_party**: 各サードパーティプロジェクトの元のライセンス
diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.md
index b5cf8b8da..9b7ea3732 100644
--- a/docs/en/getting-started/05-cli-setup.md
+++ b/docs/en/getting-started/05-cli-setup.md
@@ -92,6 +92,12 @@ Install or upgrade the npm package:
npm i -g @openviking/cli
```
+Or build the Rust CLI from source:
+
+```bash
+cargo install --git https://github.com/volcengine/OpenViking ov_cli
+```
+
The npm package is the simplest standalone CLI install. If you also want the Python SDK or server package, the Python package exposes `ov` too:
```bash
@@ -484,3 +490,13 @@ ov --help
ov config --help
ov add-resource --help
```
+
+## Rebuilding Indexes
+
+`ov reindex <uri>` rebuilds the indexes of already-imported content. Three modes are available:
+
+- `--mode vectors_only` — refresh vectors only.
+- `--mode semantic_and_vectors` — regenerate semantic artifacts (`.abstract.md`, `.overview.md`) before refreshing vectors.
+- `--mode prune_orphans` — remove vector records whose source files no longer exist. Add `--dry-run` to preview the cleanup without applying it.
+
+There is no `semantic` or `full` mode alias.
diff --git a/docs/images/benchmark-dark.svg b/docs/images/benchmark-dark.svg
new file mode 100644
index 000000000..e6b98c50d
--- /dev/null
+++ b/docs/images/benchmark-dark.svg
@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 407" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" role="img" aria-label="OpenViking benchmark results on LoCoMo and tau2-bench">
+<rect x="150" y="4" width="14" height="14" rx="3" fill="#898781"/><text x="170" y="15" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7">Without OpenViking</text><rect x="330" y="4" width="14" height="14" rx="3" fill="#3987e5"/><text x="350" y="15" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7">With OpenViking</text>
+<text x="150" y="48" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="13" font-weight="600" fill="#ffffff">User memory — LoCoMo · long-conversation QA accuracy</text>
+<line x1="150.0" y1="62" x2="150.0" y2="215" stroke="#383835" stroke-width="1"/>
+<text x="150.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">0%</text>
+<line x1="312.5" y1="62" x2="312.5" y2="215" stroke="#2c2c2a" stroke-width="1"/>
+<text x="312.5" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">25%</text>
+<line x1="475.0" y1="62" x2="475.0" y2="215" stroke="#2c2c2a" stroke-width="1"/>
+<text x="475.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">50%</text>
+<line x1="637.5" y1="62" x2="637.5" y2="215" stroke="#2c2c2a" stroke-width="1"/>
+<text x="637.5" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">75%</text>
+<line x1="800.0" y1="62" x2="800.0" y2="215" stroke="#2c2c2a" stroke-width="1"/>
+<text x="800.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">100%</text>
+<text x="138" y="87" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7" text-anchor="end">OpenClaw</text>
+<path d="M150,80 L150,62 L303.3,62 Q307.3,62 307.3,66 L307.3,76 Q307.3,80 303.3,80 Z" fill="#898781"/>
+<text x="314.3" y="75" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">24.20%</text>
+<path d="M150,101 L150,83 L679.52,83 Q683.52,83 683.52,87 L683.52,97 Q683.52,101 679.52,101 Z" fill="#3987e5"/>
+<text x="690.52" y="96" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">82.08%</text>
+<text x="138" y="144" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7" text-anchor="end">Hermes</text>
+<path d="M150,137 L150,119 L362.97,119 Q366.97,119 366.97,123 L366.97,133 Q366.97,137 362.97,137 Z" fill="#898781"/>
+<text x="373.97" y="132" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">33.38%</text>
+<path d="M150,158 L150,140 L684.59,140 Q688.59,140 688.59,144 L688.59,154 Q688.59,158 684.59,158 Z" fill="#3987e5"/>
+<text x="695.59" y="153" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">82.86%</text>
+<text x="138" y="201" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7" text-anchor="end">Claude Code</text>
+<path d="M150,194 L150,176 L517.865,176 Q521.865,176 521.865,180 L521.865,190 Q521.865,194 517.865,194 Z" fill="#898781"/>
+<text x="528.865" y="189" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">57.21%</text>
+<path d="M150,215 L150,197 L668.0799999999999,197 Q672.0799999999999,197 672.0799999999999,201 L672.0799999999999,211 Q672.0799999999999,215 668.0799999999999,215 Z" fill="#3987e5"/>
+<text x="679.0799999999999" y="210" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">80.32%</text>
+<text x="150" y="267" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="13" font-weight="600" fill="#ffffff">Agent experience — tau2-bench · multi-turn task success</text>
+<line x1="150.0" y1="281" x2="150.0" y2="377" stroke="#383835" stroke-width="1"/>
+<text x="150.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">0%</text>
+<line x1="312.5" y1="281" x2="312.5" y2="377" stroke="#2c2c2a" stroke-width="1"/>
+<text x="312.5" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">25%</text>
+<line x1="475.0" y1="281" x2="475.0" y2="377" stroke="#2c2c2a" stroke-width="1"/>
+<text x="475.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">50%</text>
+<line x1="637.5" y1="281" x2="637.5" y2="377" stroke="#2c2c2a" stroke-width="1"/>
+<text x="637.5" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">75%</text>
+<line x1="800.0" y1="281" x2="800.0" y2="377" stroke="#2c2c2a" stroke-width="1"/>
+<text x="800.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">100%</text>
+<text x="138" y="306" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7" text-anchor="end">Retail</text>
+<path d="M150,299 L150,281 L607.11,281 Q611.11,281 611.11,285 L611.11,295 Q611.11,299 607.11,299 Z" fill="#898781"/>
+<text x="618.11" y="294" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">70.94%</text>
+<path d="M150,320 L150,302 L651.765,302 Q655.765,302 655.765,306 L655.765,316 Q655.765,320 651.765,320 Z" fill="#3987e5"/>
+<text x="662.765" y="315" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">77.81%</text>
+<text x="138" y="363" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#c3c2b7" text-anchor="end">Airline</text>
+<path d="M150,356 L150,338 L499.47,338 Q503.47,338 503.47,342 L503.47,352 Q503.47,356 499.47,356 Z" fill="#898781"/>
+<text x="510.47" y="351" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">54.38%</text>
+<path d="M150,377 L150,359 L576.625,359 Q580.625,359 580.625,363 L580.625,373 Q580.625,377 576.625,377 Z" fill="#3987e5"/>
+<text x="587.625" y="372" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#c3c2b7">66.25%</text>
+</svg>
diff --git a/docs/images/benchmark-light.svg b/docs/images/benchmark-light.svg
new file mode 100644
index 000000000..916669199
--- /dev/null
+++ b/docs/images/benchmark-light.svg
@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 407" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" role="img" aria-label="OpenViking benchmark results on LoCoMo and tau2-bench">
+<rect x="150" y="4" width="14" height="14" rx="3" fill="#898781"/><text x="170" y="15" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e">Without OpenViking</text><rect x="330" y="4" width="14" height="14" rx="3" fill="#2a78d6"/><text x="350" y="15" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e">With OpenViking</text>
+<text x="150" y="48" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="13" font-weight="600" fill="#0b0b0b">User memory — LoCoMo · long-conversation QA accuracy</text>
+<line x1="150.0" y1="62" x2="150.0" y2="215" stroke="#c3c2b7" stroke-width="1"/>
+<text x="150.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">0%</text>
+<line x1="312.5" y1="62" x2="312.5" y2="215" stroke="#e1e0d9" stroke-width="1"/>
+<text x="312.5" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">25%</text>
+<line x1="475.0" y1="62" x2="475.0" y2="215" stroke="#e1e0d9" stroke-width="1"/>
+<text x="475.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">50%</text>
+<line x1="637.5" y1="62" x2="637.5" y2="215" stroke="#e1e0d9" stroke-width="1"/>
+<text x="637.5" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">75%</text>
+<line x1="800.0" y1="62" x2="800.0" y2="215" stroke="#e1e0d9" stroke-width="1"/>
+<text x="800.0" y="231" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">100%</text>
+<text x="138" y="87" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e" text-anchor="end">OpenClaw</text>
+<path d="M150,80 L150,62 L303.3,62 Q307.3,62 307.3,66 L307.3,76 Q307.3,80 303.3,80 Z" fill="#898781"/>
+<text x="314.3" y="75" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">24.20%</text>
+<path d="M150,101 L150,83 L679.52,83 Q683.52,83 683.52,87 L683.52,97 Q683.52,101 679.52,101 Z" fill="#2a78d6"/>
+<text x="690.52" y="96" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">82.08%</text>
+<text x="138" y="144" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e" text-anchor="end">Hermes</text>
+<path d="M150,137 L150,119 L362.97,119 Q366.97,119 366.97,123 L366.97,133 Q366.97,137 362.97,137 Z" fill="#898781"/>
+<text x="373.97" y="132" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">33.38%</text>
+<path d="M150,158 L150,140 L684.59,140 Q688.59,140 688.59,144 L688.59,154 Q688.59,158 684.59,158 Z" fill="#2a78d6"/>
+<text x="695.59" y="153" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">82.86%</text>
+<text x="138" y="201" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e" text-anchor="end">Claude Code</text>
+<path d="M150,194 L150,176 L517.865,176 Q521.865,176 521.865,180 L521.865,190 Q521.865,194 517.865,194 Z" fill="#898781"/>
+<text x="528.865" y="189" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">57.21%</text>
+<path d="M150,215 L150,197 L668.0799999999999,197 Q672.0799999999999,197 672.0799999999999,201 L672.0799999999999,211 Q672.0799999999999,215 668.0799999999999,215 Z" fill="#2a78d6"/>
+<text x="679.0799999999999" y="210" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">80.32%</text>
+<text x="150" y="267" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="13" font-weight="600" fill="#0b0b0b">Agent experience — tau2-bench · multi-turn task success</text>
+<line x1="150.0" y1="281" x2="150.0" y2="377" stroke="#c3c2b7" stroke-width="1"/>
+<text x="150.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">0%</text>
+<line x1="312.5" y1="281" x2="312.5" y2="377" stroke="#e1e0d9" stroke-width="1"/>
+<text x="312.5" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">25%</text>
+<line x1="475.0" y1="281" x2="475.0" y2="377" stroke="#e1e0d9" stroke-width="1"/>
+<text x="475.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">50%</text>
+<line x1="637.5" y1="281" x2="637.5" y2="377" stroke="#e1e0d9" stroke-width="1"/>
+<text x="637.5" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">75%</text>
+<line x1="800.0" y1="281" x2="800.0" y2="377" stroke="#e1e0d9" stroke-width="1"/>
+<text x="800.0" y="393" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#898781" text-anchor="middle">100%</text>
+<text x="138" y="306" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e" text-anchor="end">Retail</text>
+<path d="M150,299 L150,281 L607.11,281 Q611.11,281 611.11,285 L611.11,295 Q611.11,299 607.11,299 Z" fill="#898781"/>
+<text x="618.11" y="294" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">70.94%</text>
+<path d="M150,320 L150,302 L651.765,302 Q655.765,302 655.765,306 L655.765,316 Q655.765,320 651.765,320 Z" fill="#2a78d6"/>
+<text x="662.765" y="315" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">77.81%</text>
+<text x="138" y="363" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#52514e" text-anchor="end">Airline</text>
+<path d="M150,356 L150,338 L499.47,338 Q503.47,338 503.47,342 L503.47,352 Q503.47,356 499.47,356 Z" fill="#898781"/>
+<text x="510.47" y="351" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">54.38%</text>
+<path d="M150,377 L150,359 L576.625,359 Q580.625,359 580.625,363 L580.625,373 Q580.625,377 576.625,377 Z" fill="#2a78d6"/>
+<text x="587.625" y="372" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#52514e">66.25%</text>
+</svg>
diff --git a/docs/images/ov-logo.png b/docs/images/ov-logo.png
index 471620331..d3cc9402d 100644
Binary files a/docs/images/ov-logo.png and b/docs/images/ov-logo.png differ
diff --git a/docs/images/studio-playground.png b/docs/images/studio-playground.png
new file mode 100644
index 000000000..236e614eb
Binary files /dev/null and b/docs/images/studio-playground.png differ
diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.md
index 114aec9fe..1d43edc66 100644
--- a/docs/zh/getting-started/05-cli-setup.md
+++ b/docs/zh/getting-started/05-cli-setup.md
@@ -92,6 +92,12 @@ ov language zh-CN
npm i -g @openviking/cli
```
+也可以从源码构建 Rust CLI:
+
+```bash
+cargo install --git https://github.com/volcengine/OpenViking ov_cli
+```
+
npm 包是最轻量的独立 CLI 安装方式。如果你同时需要 Python SDK 或服务端包,Python 包也会提供 `ov`:
```bash
@@ -484,3 +490,13 @@ ov --help
ov config --help
ov add-resource --help
```
+
+## 重建索引
+
+`ov reindex <uri>` 用于重建已导入内容的索引,支持三种模式:
+
+- `--mode vectors_only` —— 只刷新向量。
+- `--mode semantic_and_vectors` —— 先重新生成语义产物(`.abstract.md`、`.overview.md`),再刷新向量。
+- `--mode prune_orphans` —— 清理源文件已不存在的向量记录,加 `--dry-run` 可预览而不实际执行。
+
+没有 `semantic` 或 `full` 这样的模式别名。