Skip to content

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

docs: rewrite About, FAQ and context compilation pages in plain terms (#5511)

Zayn Jarvis15eac24c29d9
diff --git a/docs/en/about/01-about-us.md b/docs/en/about/01-about-us.md
index 463df06f3..7afc9063d 100644
--- a/docs/en/about/01-about-us.md
+++ b/docs/en/about/01-about-us.md
@@ -2,13 +2,13 @@
## Project Overview
-OpenViking is an open-source context database initiated and maintained by ByteDance’s Volcano Engine Viking team, dedicated to building robust context engineering infrastructure for the AI Agent ecosystem. As a new-generation context database, OpenViking provides a unified data abstraction layer, an intelligent semantic parsing engine, and a high-performance hybrid retrieval system to deliver reliable backend support for all kinds of AI applications.
+OpenViking is an open-source context database for AI agents, initiated and maintained by the Viking team at ByteDance's Volcengine. It organizes resources, memories, and skills as files that agents can browse, search, and read on demand.
## Team Introduction
### Viking Team Background
-The Viking team belongs to ByteDance’s Volcano Engine and focuses on unstructured information processing and intelligent retrieval. The team brings together dozens of seasoned experts across distributed systems, machine learning, data engineering, and AI algorithms, with extensive commercial experience in context engineering.
+The Viking team develops vector retrieval, knowledge base, and memory management products. Its dozens of engineers work across distributed systems, machine learning, data engineering, and AI algorithms, and have run context engineering in commercial production. OpenViking applies that engineering experience to a context database developed with the open-source community.
#### Core Technical Capabilities
@@ -27,9 +27,9 @@ The Viking team belongs to ByteDance’s Volcano Engine and focuses on unstructu
- Supports elastic scaling and automatic failure recovery
- Balances data consistency and system performance
-### Development History and Technical Evolution
+This work involves three related problems: extracting searchable information from unstructured content, finding relevant context among many candidates, and retaining interaction experience for later tasks. OpenViking addresses these through [resource parsing and extraction](../concepts/06-extraction.md), [context retrieval](../concepts/07-retrieval.md), and [session and memory management](../concepts/08-session.md). These pages explain the implementation and conditions for use.
-The Viking team’s exploration in context engineering reflects our commitment to continuous innovation and industry impact. As AI Agent applications rapidly evolve, we plan to use OpenViking as a public verification platform for new concepts and approaches, building in the open together with the community to create a responsible AI application stack.
+### Development History and Technical Evolution
| Time Period | Milestone | Technical Breakthroughs and Industry Impact |
|-------------|-----------|---------------------------------------------|
@@ -41,7 +41,7 @@ The Viking team’s exploration in context engineering reflects our commitment t
### Academic Collaboration and Industry–Academia Integration
-Since its inception, OpenViking has established deep academic collaborations with top universities and research institutes worldwide to jointly explore context database design paradigms and best engineering practices for the AI era. This industry–academia collaboration ensures technological advancement while staying closely aligned with real application needs.
+Since its launch, OpenViking has worked with universities and research institutes to explore context database design and engineering practice for AI agents, keeping research work tied to real application needs.
We sincerely thank the following scholars for their contributions and guidance in launching OpenViking:
@@ -50,157 +50,71 @@ We sincerely thank the following scholars for their contributions and guidance i
- Associate Professor Dai Guohao, School of Artificial Intelligence, Shanghai Jiao Tong University; Co‑founder and Chief Scientist of Wuwen Xinqiong
Our collaboration models include:
-- **Joint research projects**: conduct frontier research in context engineering
-- **Technical workshops**: organize regular academic exchanges and technical reviews
-- **Talent cultivation**: provide practice platforms and research topics for graduate students
-- **Technology transfer**: transform academic findings into engineering best practices
-## Open-Source Organization
-
-### Project Development Stages
+- **Joint research projects**: frontier research in context engineering
+- **Technical workshops**: regular academic exchanges and technical reviews
+- **Talent cultivation**: practice platforms and research topics for graduate students
+- **Technology transfer**: turning research results into engineering practice
-OpenViking is currently in its early development stage. We divide development into three key phases:
+### Research Papers
-- Phase 1: Foundation building
-Focus on constructing solid technical foundations after open-sourcing, including core protocols, interfaces, AI Agent facilities, and providing a reliable minimal implementation.
-
-- Phase 2: Ecosystem expansion
-Build a plugin ecosystem, support third-party feature extensions, drive deep integration with mainstream AI frameworks and tools, and extend enterprise-grade capabilities to meet large-scale deployment needs.
-
-- Phase 3: Industry adoption
-Establish industry technical standards and best practices, build certification systems and partner ecosystems, and promote broader real-world adoption of context engineering.
-
-### Governance Structure and Decision-Making
+The following papers come from this collaboration. Parts of their core mechanisms are integrated into OpenViking.
-Based on the project’s long-term roadmap, we are establishing a layered governance structure:
+- **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**<br>
+ Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao. arXiv:2605.29640, 2026. Presented at VLDB 2026.<br>
+ Event-driven extraction, update, and consolidation of long-term memory for stateful agents. [arXiv](https://arxiv.org/abs/2605.29640) · [PDF](https://arxiv.org/pdf/2605.29640)
+- **Directory-Aware Query and Maintenance in Vector Databases**<br>
+ Mengzhao Wang, Zheng Gong, Jingpei Hu, Jiajie Fu, Maojia Sheng, Junwen Chen, and Yifan Zhu. arXiv:2606.16903, 2026. Accepted by ICDE.<br>
+ Formal foundations and index design (TrieHI) for directory-scoped retrieval, which OpenViking uses to resolve directory scopes before vector ranking. [arXiv](https://arxiv.org/abs/2606.16903) · [PDF](https://arxiv.org/pdf/2606.16903)
+- **VikingRAG: Accurate and Token-efficient Retrieval-augmented Generation over Structured Documents**<br>
+ Peiyuan Gao, Gaoyuan Zhang, Haojie Qin, Yahui Sun, Qianyi Zhang, Yunhao Zhang, Zeyu Wang, and Wei Lu. arXiv:2609.11390, 2026. Submitted.<br>
+ Combines semantic search with document structure, expanding relevant directory segments as evidence gaps arise. [arXiv](https://arxiv.org/abs/2609.11390) · [PDF](https://arxiv.org/pdf/2609.11390)
-#### Open-Source Governance Committee
-OpenViking is guided by a professional governance committee responsible for overall strategic planning and technical decisions. The committee consists of core contributors and domain experts, with responsibilities including:
+## Open-Source Organization
-**Strategic Planning**
-- Define the long-term technical roadmap and vision
-- Set release plans and feature priorities
-- Evaluate the long-term impact of technical decisions on the ecosystem
+### Project Development Stages
-**Technical Governance**
-- Establish and maintain code quality standards and engineering norms
-- Review core architecture changes and major feature implementations
-- Ensure sustainability and backward compatibility
+Development covers context storage and retrieval, agent integrations, and deployment. See the [roadmap](03-roadmap.md) for implemented capabilities and future directions, and the [changelog](02-changelog.md) for released changes.
-**Community Development**
-- Define community development strategy and contributor growth paths
-- Organize technical exchange activities and developer conferences
-- Build incentive mechanisms and recognition systems
+### Governance Structure and Decision-Making
-**Ecosystem Collaboration**
-- Establish technical cooperation with related open-source projects
-- Promote integration and certification with commercial products
-- Manage intellectual property and license compliance
+The governance committee oversees technical direction, release and feature priorities, architecture and compatibility reviews, engineering standards, contributor collaboration, and integrations with related projects. Members include Maojia Sheng ([@MaojiaSheng](https://github.com/MaojiaSheng)), Haojie Qin ([@qin-ctx](https://github.com/qin-ctx)), Jiahui Zhou ([@zhoujh01](https://github.com/zhoujh01)), and Zhiheng Liu ([@ZaynJarvis](https://github.com/ZaynJarvis)). Eligible community contributors can join the committee through future nomination and election procedures.
-#### Committee Core Members
-Current core members of the governance committee:
-Haojie Qin, Jiahui Zhou, Linggang Wang, Maojia Sheng, Yaohui Sun
+See the [contribution guide](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md) for module contacts and recently active reviewers.
-To ensure openness and diversity, we welcome eligible community contributors to join the committee through future nomination and election procedures.
+Feature proposals and problems are discussed in [GitHub Issues](https://github.com/volcengine/OpenViking/issues). Code and documentation changes are reviewed through pull requests. Before implementing changes to public interfaces, persistence, permission boundaries, or architecture across modules, describe the current and intended behavior, request or configuration examples, and compatibility impact.
## Community Participation
### Join the Community
-We warmly invite developers worldwide to join the OpenViking community and co-build next-generation context engineering infrastructure. You can participate in the following ways:
-
-#### Instant Messaging
-
-##### Lark Group
+#### Lark Group
-Scan the QR code below to join the Lark group and communicate with the core development team in real time:
+Scan the QR code to discuss usage questions and development plans:
![Join via Lark QR](../../images/lark-group-qrcode.png)
-*Note: Please ensure you have installed the [Lark client](https://www.feishu.cn/) before joining.*
+Install the [Lark client](https://www.feishu.cn/) first.
-##### WeChat Group
+#### WeChat Group
-Scan the QR code below to add the assistant on WeChat, mention "OpenViking" and you will be invited to the WeChat group:
+Scan the QR code to add the assistant and mention "OpenViking" to request an invitation:
![Join via WeChat QR](../../images/wechat-group-qrcode.png)
-**Discord**
-
-[Join our Discord Server](https://discord.com/invite/eHvx8E9XF3)
-
-**X**
-
-[Follow us on X](https://x.com/openvikingai)
+You can also join [Discord](https://discord.com/invite/eHvx8E9XF3) or follow project updates on [X](https://x.com/openvikingai).
### Ways to Participate
-We provide multiple participation channels to meet different collaboration needs:
+- **Report a problem or suggest a feature:** include the use case, version, and reproduction steps in an [issue](https://github.com/volcengine/OpenViking/issues).
+- **Improve code or documentation:** read the [contribution guide](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md), then submit code, tests, documentation, or translations.
+- **Build an integration:** add a plugin for an agent tool or framework using the [plugin development guide](../agent-integrations/18-plugin-development.md).
+- **Share experience:** post usage examples and troubleshooting notes, or help other users in the community.
-#### 1. Code Contributions
-- **Submit Issues**: report bugs, propose features, or discuss technical solutions
-- **Submit Pull Requests**: contribute code improvements, documentation updates, or test cases
-- **Code Review**: participate in reviews to improve code quality
-
-#### 2. Documentation Contributions
-- **Improve documentation**: enhance user guides, API docs, or tutorials
-- **Translation support**: help translate documentation into other languages
-- **Example code**: provide usage examples and best practices
-
-#### 3. Community Support
-- **Technical sharing**: share experiences and technical insights
-- **Q&A**: help other developers solve usage problems
-- **Ecosystem building**: promote integration of OpenViking with other open-source projects
-
-#### 4. Ecosystem Expansion
-- **Plugin development**: develop third-party plugins or feature extensions
-- **Integration adaptation**: drive deep integration with mainstream frameworks
-- **Application cases**: share real-world adoption experiences
+For what to include in issues and pull requests, see the [contribution guide](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md).
## Discussion and Collaboration
-### Official Channels
-
-#### GitHub Platform
-- **Issues**: feature suggestions, bug reports, and technical discussions
-- **Pull Requests**: code contributions and documentation updates
-- **Discussions**: design discussions and community exchange
-
-#### Repository
-- **Main repository**: `https://github.com/volcengine/openviking`
-- **Issue tracking**: `https://github.com/volcengine/openviking/issues`
-
-### Real-Time Communication
-
-#### Lark Group
-- **Technical discussion**: real-time technical exchange and Q&A
-- **Code review**: fast feedback and collaborative development
-- **Event notice**: community activities and technical sharing
-
-### Social Media
-
-We follow major technical communities and social media platforms and respond promptly to user feedback:
-- **Technical blog**: regular technical articles and project updates
-- **Social media**: share project news and usage cases
-- **Technical conferences**: participate in industry events to share engineering practice
-
-### Community Goals
-
-We aim to achieve the following goals through the open-source community:
-
-1. **Technology democratization**: enable more developers to use advanced context engineering technologies
-2. **Innovation acceleration**: accelerate innovation and product iteration through collaboration
-3. **Standards building**: promote technical standards and best practices in context engineering
-4. **Talent development**: cultivate more talent in the context engineering field
-
-### Open Collaboration
-
-OpenViking welcomes collaboration from developers, research institutions, and companies. We look forward to:
-
-- **Technical collaboration**: deep technical cooperation with academia and industry
-- **Ecosystem integration**: establish integrations with related open-source projects and commercial products
-- **Application promotion**: jointly promote the application of context engineering technologies across more scenarios
-
----
+The [GitHub repository](https://github.com/volcengine/OpenViking) holds code, documentation, and review records. Use [GitHub Discussions](https://github.com/volcengine/OpenViking/discussions) for design discussions and community exchange, chat for immediate discussion, and an issue or pull request for work that needs tracking.
-**Join us to build the context infrastructure for the AI Agent era!**
+Research institutions and companies interested in technical collaboration or integrations can start a thread in GitHub Discussions or contact the team through the Lark group.
diff --git a/docs/en/context-compilation/01-overview.md b/docs/en/context-compilation/01-overview.md
index 78638749d..afaf044f0 100644
--- a/docs/en/context-compilation/01-overview.md
+++ b/docs/en/context-compilation/01-overview.md
@@ -1,23 +1,23 @@
# Context Compilation Overview
-`ov compile` turns the raw material scattered across OpenViking — documents, notes, web pages, transcripts, research files, code repositories — into structured, retrievable knowledge that people and agents can reuse over and over.
+`ov compile` reads documents, notes, web pages, or session records from OpenViking and uses a Skill to organize them into a Wiki, knowledge graph, daily report, or other output stored in OpenViking.
## How it works
-You supply three things:
+Compilation with an installed Skill needs:
-- **Where it comes from (`--from`)**: one or more source directories/files;
-- **Where it goes (`--to`)**: the target directory for the output;
-- **Which Skill to use (`--skill`)**: a spec describing what the output should look like.
+- `--from`: one or more source directories or files.
+- `--to`: the output directory.
+- `--skill`: the URI of an installed Skill that defines the output's content and structure.
-Plus an optional **`--instruction`**: extra instructions for this run — scope, audience, language, emphasis, or date range. The Skill defines *what shape* to compile into; `--instruction` tells the agent *what you want this particular time* on top of that.
+Use the optional `--instruction` to specify this run's scope, audience, language, emphasis, or date range.
-OpenViking does the rest. Compile is powered by [VikingBot](../concepts/15-vikingbot.md): once a task is accepted, VikingBot loads the Skill you named, reads the sources under your identity, and works through them autonomously in a dedicated **agent loop** — reading, distilling, organizing, and writing pages, much like hiring someone to turn a pile of material into a clean knowledge base and hand you back the finished result. The whole thing runs asynchronously: you can wait for it, or grab the `task_id` and move on.
-
-In other words: **you provide the material and the goal, the agent does the actual work of organizing the knowledge.**
+The configured [Agent Runtime](../api/23-agent-runtime.md) runs the compilation; local deployments can use the built-in [VikingBot](../concepts/15-vikingbot.md). It reads the sources and Skill under the requesting user's identity, then organizes and writes content in a dedicated agent loop. The task runs asynchronously and returns a `task_id` for checking progress and results.
## Run it in one command
+First import the sources and install the Skill using the [LLM Wiki example](02-llm-wiki.md), then run:
+
```bash
ov compile \
--from viking://resources/research \
@@ -30,7 +30,7 @@ The command returns a `cmp_...` task ID immediately. Use `ov task status <id>` t
## Swap the Skill, get a different output
-Compile itself does not decide *what* to compile into — the Skill does. The same sources, paired with different Skills, produce completely different knowledge artifacts. Here are the example Skills we ship; the first two also come with a visualization script you can run as-is:
+The Skill defines the output. The repository includes these examples; LLM Wiki and Knowledge Graph also include visualization scripts:
| Skill | Output shape | Good for | Example |
|-------|-------------|----------|---------|
@@ -47,12 +47,13 @@ Besides compiling source material into new knowledge artifacts with a Skill, `ov
## Prerequisites
-- A running OpenViking service with Bot enabled (`--with-bot`). The default endpoint is `http://localhost:1933`; remote use needs an API Key — see [Authentication](../guides/04-authentication.md). No service yet? Start with the [Quick Start](../getting-started/02-quickstart.md).
-- The `ov` CLI configured with a connection (`~/.openviking/ovcli.conf` or `OPENVIKING_*` environment variables).
-- Python 3 for the visualization scripts; the LLM Wiki script also uses the `openviking` Python package to read Wiki pages straight from the service.
+- For the Skill-based examples, a running OpenViking service with a Compile Runtime configured. For local use, install the `openviking[bot]` dependencies and enable the built-in VikingBot with `--with-bot`. The `--skill memory` mode runs in-process without a Compile Runtime and takes no `--from`. The default endpoint is `http://localhost:1933`; remote use needs an API Key — see [Authentication](../guides/04-authentication.md). No service yet? Start with the [Quick Start](../getting-started/02-quickstart.md).
+- The `ov` CLI configured with a connection (`~/.openviking/ovcli.conf`, or a file selected by `OPENVIKING_CLI_CONFIG_FILE`).
+- Paths beginning with `examples/...` are relative to the repository. Download the [OpenViking repository](https://github.com/volcengine/OpenViking) and run the commands from its root.
+- Python 3 for the visualization scripts. The [LLM Wiki script](https://github.com/volcengine/OpenViking/blob/main/examples/compile/graph-show/llm-wiki/wiki_graph.py) also requires the `openviking` Python package.
## Related docs
-- [VikingBot concepts](../concepts/15-vikingbot.md) — the runtime behind Compile
+- [VikingBot concepts](../concepts/15-vikingbot.md) — the built-in Compile runtime
- [Agent Runtime API](../api/23-agent-runtime.md) — full reference for creating, inspecting, and cancelling Compile tasks
- [Skills API](../api/04-skills.md) — managing and customizing Skills
diff --git a/docs/en/context-compilation/02-llm-wiki.md b/docs/en/context-compilation/02-llm-wiki.md
index 1034ac9f4..7c0a54081 100644
--- a/docs/en/context-compilation/02-llm-wiki.md
+++ b/docs/en/context-compilation/02-llm-wiki.md
@@ -1,6 +1,6 @@
# Example: LLM Wiki
-Compile a set of heterogeneous sources into a Karpathy-style, evidence-grounded, interlinked **LLM Wiki**: every page has one clear retrieval purpose, opens with a direct summary, uses consistent terminology, makes relationships explicit, keeps evidence close to the claims it supports, and is fronted by an `index.md` navigation page.
+Organize material from different sources into a Karpathy-style LLM Wiki of interlinked Markdown pages. Each page covers an entity, concept, or question, leading with a conclusion and citing its sources. An `index.md` page provides navigation.
The Skill picks the smallest page type that matches each page's retrieval purpose:
@@ -13,17 +13,19 @@ The Skill picks the smallest page type that matches each page's retrieval purpos
| `analysis` | A cross-source conclusion tied to a clear question |
| `summary` | A faithful digest of one source (only when `--instruction` explicitly asks for it) |
-`entity` and `concept` are the defaults; the others are promoted only when they pass their stricter tests. The result is a knowledge base, not a source-by-source pile of summaries.
+The default page types are `entity` and `concept`; other types follow the conditions in the Skill. Related material from multiple sources is grouped under the same topic.
Skill source: [examples/compile/ov-compile-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/llm-wiki) · Visualization script: [examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
+Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
+
## Step 1: Prepare the sources
If the material is not in OpenViking yet, import it. Use `ov add-resource` for directories, `ov write` for a single file:
```bash
# Import a directory as a source
-ov add-resource ./my-research --to viking://resources/research
+ov add-resource ./my-research --to viking://resources/research --wait
# Or write a single file
ov mkdir viking://resources/research
@@ -39,17 +41,17 @@ ov ls -r viking://resources/research
## Step 2: Add the Skill
-Install the LLM Wiki Skill. By default it lands in your user-private skills namespace; use `-p viking://agent/skills` to make it shared across the team:
+This example installs the Skill under `viking://agent/skills`, matching the compile command below. Omit `-p` for a private installation, then use the returned URI in `--skill`:
```bash
-ov add-skill examples/compile/ov-compile-skills/llm-wiki
+ov add-skill examples/compile/ov-compile-skills/llm-wiki -p viking://agent/skills --wait
```
Find the installed Skill URI:
```bash
ov skills list
-# → viking://agent/skills/llm-wiki (or viking://user/<you>/skills/llm-wiki)
+# → viking://agent/skills/llm-wiki
```
## Step 3: Run compile
diff --git a/docs/en/context-compilation/03-knowledge-graph.md b/docs/en/context-compilation/03-knowledge-graph.md
index 5b95afbf7..6c81a82ae 100644
--- a/docs/en/context-compilation/03-knowledge-graph.md
+++ b/docs/en/context-compilation/03-knowledge-graph.md
@@ -1,6 +1,6 @@
# Example: Knowledge Graph
-Compile a set of sources into an **evidence-grounded, visualization-ready** knowledge graph: semantically typed entity nodes, statement-level provenance, and typed directed relationship edges. The output is this artifact tree:
+Extract typed entities and typed, directed relationships into a knowledge graph, keeping source references for each statement and edge. The output contains entity files and an edge list:
```text
entities/
@@ -18,17 +18,19 @@ Each edge is a compact JSON line, readable as the statement `<from> <relation> <
Skill source: [examples/compile/ov-compile-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-graph) · Visualization script: [examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
+Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
+
## Step 1: Prepare the sources
```bash
-ov add-resource ./journal-to-the-west --to viking://resources/journal
+ov add-resource ./journal-to-the-west --to viking://resources/journal --wait
ov ls -r viking://resources/journal
```
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-graph
+ov add-skill examples/compile/ov-compile-skills/knowledge-graph -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-graph
```
@@ -62,7 +64,7 @@ ov read viking://resources/journal-kg/entities/sun-wukong.md
Unlike the LLM Wiki script, `knowledge_graph.py` reads from a **local directory** (it needs both `entities/` and `relations.jsonl` on disk). So download the output first, then generate the HTML.
-Download the whole artifact tree. `ov get` downloads one file at a time; combine it with `ov ls -r -s` to pull every path:
+`ov get` downloads one file at a time. This script downloads only the entity Markdown files and edge list:
```bash
SRC="viking://resources/journal-kg"
@@ -71,7 +73,8 @@ mkdir -p "$DST"
ov ls -r -s "$SRC" | while read -r uri; do
# only download files (entities/*.md and relations.jsonl), skip directories
case "$uri" in
- */entities|"$SRC") continue ;;
+ "$SRC"/entities/*.md|"$SRC"/relations.jsonl) ;;
+ *) continue ;;
esac
rel="${uri#$SRC/}"
mkdir -p "$DST/$(dirname "$rel")"
@@ -79,7 +82,7 @@ ov ls -r -s "$SRC" | while read -r uri; do
done
```
-> `ov get` requires the local target path to not exist yet, so clear the old directory (`rm -rf ./journal-kg`) before re-downloading.
+> `ov get` requires the local target file to not exist. To download again, change `DST` to a new directory and keep the previous result.
Confirm the local layout is correct:
diff --git a/docs/en/context-compilation/04-daily-report.md b/docs/en/context-compilation/04-daily-report.md
index d88fd430f..42de5563a 100644
--- a/docs/en/context-compilation/04-daily-report.md
+++ b/docs/en/context-compilation/04-daily-report.md
@@ -4,21 +4,23 @@ Compile timestamped conversation logs, agent sessions, IM messages, collaborativ
Skill source: [examples/compile/ov-compile-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/daily-report)
+Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
+
## Step 1: Prepare the sources
Daily-report sources are usually sessions, messages, or documents already in OpenViking. To import a batch of records from local:
```bash
-ov add-resource ./work-logs --to viking://resources/work-logs
+ov add-resource ./work-logs --to viking://resources/work-logs --wait
ov ls -r viking://resources/work-logs
```
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/daily-report
+ov add-skill examples/compile/ov-compile-skills/daily-report -p viking://agent/skills --wait
ov skills list
-# → viking://agent/skills/daily-report (or viking://user/<you>/skills/daily-report)
+# → viking://agent/skills/daily-report
```
## Step 3: Run compile
@@ -30,7 +32,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --instruction "Daily report for 2026-08-20, focused on my outcomes and decisions"
+ --instruction "Daily report for 2026-08-20 in Asia/Shanghai, focused on my outcomes and decisions"
```
For several days at once, put the date range in `--instruction` (each day is still its own page):
@@ -40,7 +42,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --instruction "One daily report per day for 2026-08-18 to 2026-08-20"
+ --instruction "One daily report per day for 2026-08-18 to 2026-08-20 in Asia/Shanghai"
```
The command returns a `task_id` immediately:
diff --git a/docs/en/context-compilation/05-knowledge-distillation.md b/docs/en/context-compilation/05-knowledge-distillation.md
index ef9f6e307..0432569a9 100644
--- a/docs/en/context-compilation/05-knowledge-distillation.md
+++ b/docs/en/context-compilation/05-knowledge-distillation.md
@@ -1,10 +1,10 @@
# Example: Knowledge Distillation
-**Distill** one or more knowledge bases or document collections into topic-organized, evidence-grounded high-level knowledge: cross-source findings, trends, changes, drivers, comparisons, implications, and uncertainties.
+Extract conclusions from one or more knowledge bases, organize them by topic, and retain source references and uncertainties.
-Typical uses: distill a knowledge base, compare multiple collections, or derive higher-order insights such as "changes across financial reports."
+For example, compare financial reports to analyze changes in revenue, profitability, and risk over time.
-The output is a shallow, topic-organized artifact tree where each topic directory is a durable semantic area and each page is one independently useful high-level conclusion:
+The output uses one directory per topic and one page per conclusion:
```text
revenue-quality/
@@ -20,19 +20,21 @@ risk/
Skill source: [examples/compile/ov-compile-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-distillation)
+Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
+
## Step 1: Prepare the sources
```bash
-ov add-resource ./finance-reports --to viking://resources/finance-reports
+ov add-resource ./finance-reports --to viking://resources/finance-reports --wait
ov ls -r viking://resources/finance-reports
```
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-distillation
+ov add-skill examples/compile/ov-compile-skills/knowledge-distillation -p viking://agent/skills --wait
ov skills list
-# → viking://agent/skills/knowledge-distillation (or viking://user/<user_name>/skills/knowledge-distillation)
+# → viking://agent/skills/knowledge-distillation
```
## Step 3: Run compile
@@ -66,7 +68,7 @@ ov task cancel cmp_01abc # cooperative cancel
## Step 4: Inspect the output
-Read the topic tree first, then drill into a specific conclusion page:
+List the output first, then read a generated conclusion page. The filename below is illustrative:
```bash
ov tree viking://resources/finance-insights
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 9775c6174..8ddadfa46 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -4,37 +4,42 @@
### What is OpenViking? What problems does it solve?
-OpenViking is an open-source context database designed specifically for AI Agents. It solves core pain points when building AI Agents:
+OpenViking organizes an agent's resources, memories, and skills as files. Applications can browse paths, search semantically, and read content on demand. They can also retain preferences and experience extracted from sessions for later tasks.
-- **Fragmented Context**: Memories, resources, and skills are scattered everywhere, difficult to manage uniformly
-- **Poor Retrieval Effectiveness**: Traditional RAG's flat storage lacks global view, making it hard to understand complete context
-- **Unobservable Context**: Implicit retrieval chains are like black boxes, difficult to debug when errors occur
-- **Limited Memory Iteration**: Lacks Agent-related task memory and self-evolution capabilities
+It targets four common problems when building agents:
-OpenViking unifies all context management through a filesystem paradigm, enabling tiered delivery and self-iteration.
+- **Fragmented context**: memories, resources, and skills live in different places and are hard to manage together
+- **Weak retrieval**: flat chunk storage loses the surrounding structure, so results lack the full context
+- **Opaque retrieval**: implicit retrieval chains are hard to inspect when results go wrong
+- **Limited memory iteration**: agents lack task memory that improves across sessions
+
+For example, an agent revising a deployment plan can search project documentation and read the relevant configuration. Constraints agreed in an earlier session can also be retrieved and reused if they were extracted as memories. The application must connect retrieval and session submission; installing the database alone does not give an agent this context. Start by [importing and searching a resource](../getting-started/02-quickstart.md), then connect an [agent tool](../agent-integrations/01-overview.md) if needed.
### What's the fundamental difference between OpenViking and traditional vector databases?
-| Dimension | Traditional Vector DB | OpenViking |
-|-----------|----------------------|------------|
-| **Storage Model** | Flat vector storage | Hierarchical filesystem (AGFS) |
-| **Retrieval Method** | Single vector similarity search | Directory recursive retrieval + Intent analysis + Rerank |
-| **Output Format** | Raw chunks | Structured context (L0 Abstract/L1 Overview/L2 Details) |
-| **Memory Capability** | Not supported | Multiple extensible memory types with automatic extraction and continuous iteration |
-| **Observability** | Black box | Fully traceable retrieval trajectory |
-| **Context Types** | Documents only | Resource + Memory + Skill three types |
+A vector database primarily stores vectors and supports similarity search. OpenViking adds context directories, layered summaries, resource ingestion, sessions, and memory management. Vector database capabilities vary by product; compare them against your requirements.
+
+| Need | OpenViking capability |
+| --- | --- |
+| Organize context | Manage resources, memories, and skills through `viking://` paths |
+| Retrieve content | Run vector search within a directory scope, with configurable intent analysis and reranking |
+| Control how much to read | Read directory abstracts or overviews before loading details |
+| Reuse session experience | Extract and update memories after a session is committed, following the memory policy |
+| Diagnose retrieval problems | Inspect processing and retrieval through logs and telemetry |
+
+If your application only needs similarity queries over existing vectors, evaluate whether its current database is sufficient. Consider OpenViking when you also need directory browsing, layered reading of summaries and details, or memory across sessions. Compare retrieved content, reading volume, latency, and processing cost using your own data and representative questions; benefits depend on the data, models, and configuration.
### What is the L0/L1/L2 layered model? Why is it needed?
-L0/L1/L2 is OpenViking's progressive content loading mechanism, solving the problem of "stuffing massive context into prompts all at once":
+An agent can use summaries to locate relevant material before reading full content, reducing unrelated content in its context.
-| Layer | Name | Token Limit | Purpose |
-|-------|------|-------------|---------|
-| **L0** | Abstract | ~100 tokens | Vector search recall, quick filtering, list display |
-| **L1** | Overview | ~2000 tokens | Rerank refinement, content navigation, decision reference |
-| **L2** | Details | Unlimited | Complete original content, on-demand deep loading |
+| Layer | Content | Default body target | Purpose |
+| --- | --- | --- | --- |
+| L0 | Directory abstract, `.abstract.md` | 256 characters | Retrieval and quick filtering |
+| L1 | Directory overview, `.overview.md` | 4,000 characters | Navigation and reranking |
+| L2 | Original or parsed content | No shared limit | Reading details on demand |
-This design allows Agents to browse abstracts for quick positioning, then load details on demand, significantly saving token consumption.
+L0/L1 are directory sidecars. Their availability depends on processing state and configuration. Generated resource summaries use character targets configured through `semantic.abstract_max_chars` and `semantic.overview_max_chars`. Truncation preserves complete sentences, so the first sentence can exceed the target; these are not hard limits on stored sidecars. See [Context Layers](../concepts/03-context-layers.md).
### What is Viking URI? What's its purpose?
@@ -71,19 +76,14 @@ viking://
OpenViking runs the RAGFS filesystem in-process through the Rust binding
(`ragfs_python` / `RAGFSBindingClient`). The binding executes filesystem logic
-directly within the Python process, giving extremely high performance and zero
-network latency. A compiled RAGFS shared library must be available locally
-(shipped in the prebuilt Wheel, or built from source).
+directly within the Python process; remote storage backends still make network requests. The RAGFS shared library ships in prebuilt wheels and can also be built from source.
> [!WARNING]
> OpenViking no longer supports the AGFS HTTP client mode. AGFS / RAGFS filesystem access now happens only through the in-process Rust binding (`RAGFSBindingClient`). This does not affect the OpenViking server HTTP API, the `ov` CLI, or `AsyncHTTPClient` / `SyncHTTPClient` when they connect to an OpenViking server.
### What should I do if I encounter "AGFS binding library not found"?
-This usually means the RAGFS shared library is not available in your
-environment. Re-compile and install it by running
-`pip install -e . --force-reinstall` in the project root (requires a Rust
-toolchain).
+This usually means the RAGFS shared library is missing or cannot be loaded. Check whether a prebuilt wheel exists for your Python version and platform, then try reinstalling. [Build from source](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md) only if no wheel is available or you need to change the source; that path requires the native build toolchain.
### How do I install/upgrade OpenViking?
@@ -94,7 +94,7 @@ pip install openviking --upgrade --force-reinstall
### How do I configure OpenViking?
-Create an `~/.openviking/ov.conf` configuration file in your project directory:
+Create `~/.openviking/ov.conf` under your home directory. Replace the example models and credentials with your own:
```json
{
@@ -114,9 +114,11 @@ Create an `~/.openviking/ov.conf` configuration file in your project directory:
"api_base": "https://ark.cn-beijing.volces.com/api/v3"
},
"rerank": {
- "provider": "volcengine",
- "api_key": "your-api-key",
- "model": "doubao-rerank-250615"
+ "provider": "vikingdb",
+ "ak": "your-access-key",
+ "sk": "your-secret-key",
+ "model_name": "doubao-seed-rerank",
+ "model_version": "251028"
},
"storage": {
"workspace": "./data",
@@ -170,8 +172,8 @@ Embedding, VLM, storage, and other service configuration is managed by the OpenV
# Add single file
await client.add_resource(
path="./document.pdf",
- parent="viking://resources/docs", # Store under this directory; the name comes from the source
- options={"reason": "Project technical documentation"}, # Describe resource purpose to improve retrieval quality
+ parent="viking://resources", # Store under this directory; the name comes from the source
+ options={"reason": "Project technical documentation"}, # Used for L0/L1 summaries when no instruction is given, and for resource-linked memory extraction
)
# Add web page
@@ -189,10 +191,10 @@ await client.wait_processed()
| | `to` | `parent` |
|---|---|---|
| What you pass | The exact final URI, **including the leaf name** | An **existing directory**; the leaf name comes from the source |
-| On a name collision | No renaming. An existing target is synced to the new source, so visible entries the source does not contain are deleted | Never overwrites. Falls back to `name_1`, `name_2`, … and returns a warning |
+| On a name collision | No renaming. An existing target directory is synced to the new source, so visible entries the source does not contain are deleted | Never overwrites. Falls back to `name_1`, `name_2`, … and returns a warning |
| When to use it | The final name is known and must be honored verbatim, or you want to update an existing resource in place | The leaf name is derived server-side (URL / repository imports, split documents), or nothing already at the destination may be touched |
-Leaving both empty derives the directory and the leaf name from the source, with the same collision handling as `parent`.
+Leaving both empty derives the directory and the leaf name from the source, with the same collision handling as `parent`. As an exception to exact-target behavior, `to` set to a resource namespace root such as `viking://resources` acts as a parent. Resource roots are created when needed; for other missing parents, pass `options={"create_parent": True}`.
`to` and `parent` cannot be combined; passing both is an error.
@@ -211,9 +213,9 @@ Note: `processing_mode="vectors_only"` skips semantic processing, so the survivi
| Feature | `find()` | `search()` |
|---------|----------|------------|
-| **Session Context** | Not required | Required |
-| **Intent Analysis** | Not used | Uses LLM to analyze and generate 0-5 queries |
-| **Latency** | Low | Higher |
+| **Session Context** | Not used | Optional; used when `session_id` is supplied and intent analysis is enabled |
+| **Intent Analysis** | Not used | Uses an LLM when session content exists and intent analysis is enabled |
+| **Latency** | Depends on embedding, retrieval, and reranking | Intent analysis adds an LLM call when used |
| **Use Case** | Simple semantic search | Complex tasks requiring context understanding |
```python
@@ -261,7 +263,7 @@ await session.commit()
### What memory types does OpenViking support?
-OpenViking includes memory types such as `profile`, `preferences`, `entities`, `events`, `identity`, `soul`, `cases`, `trajectories`, `experiences`, `tools`, and `skills`. After a session is committed, the active memory policy determines which useful information to extract. Applications can also extend or adjust the memory types for their own needs.
+OpenViking includes memory types such as `profile`, `preferences`, `entities`, `events`, `identity`, `soul`, `cases`, `trajectories`, and `experiences`. After a session is committed, the active memory policy determines which useful information to extract. Applications can also extend or adjust the memory types for their own needs.
Memories are stored in the current User or Peer namespace; there is no current writable `viking://agent/memories` directory. See [Context Types](../concepts/02-context-types.md) for the complete type and path mapping.
@@ -285,11 +287,11 @@ overview = await client.overview(uri="viking://resources")
### How do I improve retrieval quality?
-1. **Use Rerank model**: Configuring Rerank significantly improves ranking effectiveness
-2. **Provide meaningful `reason`**: Describe purpose when adding resources to help system understand resource value
-3. **Organize directory structure properly**: Use `target` parameter to group related resources together
-4. **Use session context**: `search()` leverages session history for intent analysis
-5. **Choose appropriate Embedding mode**: Use `multimodal` input for multimodal content
+1. **Check summaries**: Verify that L0/L1 represent the source accurately; adjust the import `instruction` or summary templates when needed
+2. **Organize directories**: Import with `parent` for an existing parent directory or `to` for an exact target URI
+3. **Use session context**: Keep `retrieval.enable_intent` on (default) and pass a session with content to `search()`
+4. **Choose appropriate Embedding mode**: Use `multimodal` input for multimodal content
+5. **Evaluate reranking**: Compare ranking results with and without reranking on representative queries before enabling it. You can try Jev (TypeSafe System One) as the rerank provider: it judges each candidate's relevance to the query independently, so candidate scores do not compete. See the [Configuration Guide](../guides/01-configuration.md#rerank) for setup
### How is the retrieval result score calculated?
@@ -307,9 +309,10 @@ Each query runs one global vector search within its directory scope, permission
1. **Didn't wait for processing to complete**
```python
- await client.add_resource(path="./doc.pdf")
- await client.wait_processed() # Must wait
+ result = await client.add_resource(path="./doc.pdf", wait=True)
+ print(result)
```
+ Use `wait=True` for a new import. To inspect an import already submitted, query its returned `task_id` instead of importing it again. Keep waiting while its status is `pending` or `running`; inspect the task details if it is `failed` or `cancelled`. A request timeout alone does not mean the background task failed. See [Async Tasks](../api/17-tasks.md).
2. **Embedding model configuration error**
- Check if `api_key` in `~/.openviking/ov.conf` is correct
@@ -319,20 +322,20 @@ Each query runs one global vector search within its directory scope, permission
- Check if file extension is in the supported list
- Confirm file content is valid and not corrupted
-4. **View processing logs**
- ```python
- import logging
- logging.basicConfig(level=logging.DEBUG)
- ```
+4. **View server-side processing logs**
+ Inspect the task error in the server terminal or logging system. Python logging settings in a client do not enable logs on a remote server.
### Search not returning expected results
**Troubleshooting steps**:
-1. **Confirm resources have been processed**
+1. **Confirm resources exist, then check the import task**
+ Use the `task_id` returned by the import. `completed` means processing has finished; inspect the cause if the task is `failed` or `cancelled`.
```python
# Check if resources exist
items = await client.ls(uri="viking://resources/")
+ task = await client.get_task("<task_id returned by the import>")
+ print(task["status"] if task is not None else "Task not found or expired")
```
2. **Check `target_uri` filter condition**
@@ -366,19 +369,16 @@ Each query runs one global vector search within its directory scope, permission
- Casual chat may not produce memories
- Needs to contain extractable information (preferences, entities, events, etc.)
-4. **View extracted memories**
+4. **List the memory directory**
```python
- memories = await client.find(
- query="",
- target_uri="viking://~/memories/",
- )
+ memories = await client.ls(uri="viking://~/memories/")
```
### Performance issues
**Optimization suggestions**:
-1. **Batch processing**: Adding multiple resources at once is more efficient than one by one
+1. **Locate the bottleneck**: Inspect queues, model latency, and storage time before changing concurrency
2. **Set appropriate `batch_size`**: Adjust batch processing size in Embedding configuration
3. **Use local storage**: Use `local` backend during development to reduce network latency
4. **Async operations**: Fully utilize `AsyncHTTPClient`'s async capabilities
@@ -387,7 +387,7 @@ Each query runs one global vector search within its directory scope, permission
### Is OpenViking open source?
-Yes, OpenViking main project is open source under the AGPL-3.0 license, and examples/ and crates/ov_cli are licensed under the Apache 2.0 license.
+The main project uses AGPLv3; the CLI and most examples use Apache 2.0. See the repository [license summary](https://github.com/volcengine/OpenViking#license) for component licenses and exceptions.
## Related Documentation
diff --git a/docs/zh/about/01-about-us.md b/docs/zh/about/01-about-us.md
index ba31c13f6..51efe1293 100644
--- a/docs/zh/about/01-about-us.md
+++ b/docs/zh/about/01-about-us.md
@@ -2,13 +2,13 @@
## 项目概述
-OpenViking 是由字节跳动公司火山引擎 Viking 团队发起并维护的开源项目,致力于为 AI Agent 生态系统构建强大的上下文工程基础设施。作为新一代的上下文数据库,OpenViking 通过统一的数据抽象层、智能的语义解析引擎和高性能的混合检索系统,为各类 AI 应用提供坚实可靠的后端支撑。
+OpenViking 是面向 AI Agent 的开源上下文数据库,由字节跳动火山引擎 Viking 团队发起并维护。它用文件系统组织资源、记忆和技能,供 Agent 浏览、检索和按需读取。
## 团队介绍
### Viking 团队背景
-Viking 团队隶属于字节跳动火山引擎,是专注于非结构化信息处理和智能检索领域的核心技术团队。团队汇聚了数十名在分布式系统、机器学习、数据工程和人工智能算法等领域的资深专家,在上下文工程技术方面积累了丰富的商业化实践经验。
+Viking 团队主要开发向量检索、知识库和记忆管理产品。团队有数十名工程师,覆盖分布式系统、机器学习、数据工程和 AI 算法,在上下文工程上有商业化落地经验。OpenViking 将这些领域的工程经验用于开源上下文数据库,与社区共同开发。
#### 核心技术能力
@@ -27,9 +27,9 @@ Viking 团队隶属于字节跳动火山引擎,是专注于非结构化信息
- 支持弹性伸缩与故障自动恢复机制
- 实现数据一致性与系统性能的最佳平衡
-### 发展历程与技术演进
+这些工作涉及三个相互关联的问题:如何从非结构化内容中提取可检索的信息,如何在大量候选内容中找到相关上下文,以及如何保留对后续任务有用的交互经验。OpenViking 对应提供[资源解析与提取](../concepts/06-extraction.md)、[上下文检索](../concepts/07-retrieval.md)和[会话与记忆管理](../concepts/08-session.md)。可沿这些入口了解实现和使用条件。
-Viking 团队在上下文工程领域的探索历程,体现了我们对技术创新与产业应用的持续追求,而随着 AI Agent 应用生态的快速发展,我们计划将 OpenViking 项目作为新理念和新思路的验证平台,实现公开构建,与开源社区一道构建负责任的 AI 应用软件栈。
+### 发展历程与技术演进
| 时间阶段 | 里程碑事件 | 技术突破与产业影响 |
|----------|-----------|-------------------|
@@ -41,7 +41,7 @@ Viking 团队在上下文工程领域的探索历程,体现了我们对技术
### 学术合作与产学研结合
-OpenViking 项目自启动之初就与国内外顶尖高校和研究机构建立了深度的学术合作关系,共同探索适用于 AI 时代的上下文数据库设计范式与技术最佳实践。这种产学研结合的模式,确保了项目在保持技术先进性的同时,也能够紧密结合实际应用需求。
+OpenViking 自启动起就与高校和研究机构合作,共同探索面向 AI Agent 的上下文数据库设计与工程实践,让研究工作贴近实际应用需求。
我们诚挚感谢以下学者的宝贵贡献与技术指导,共同发起了 OpenViking 项目:
@@ -50,157 +50,71 @@ OpenViking 项目自启动之初就与国内外顶尖高校和研究机构建立
- 上海交通大学人工智能学院副教授,无问芯穹联合创始人兼首席科学家戴国浩老师
我们与学术界的合作模式包括:
-- **联合研究项目**:共同开展上下文工程技术的前沿研究
+
+- **联合研究项目**:共同开展上下文工程的前沿研究
- **技术研讨会**:定期组织学术交流与技术方案评审
- **人才培养**:为研究生提供实践平台与研究课题
-- **成果转化**:将学术研究成果转化为工程实现的最佳实践
+- **成果转化**:将学术研究成果转化为工程实践
-## 开源组织建设
+### 研究论文
-### 项目发展阶段
+以下论文来自上述合作,其中部分核心机制已集成到 OpenViking。
-OpenViking 目前处于项目发展的早期阶段,我们将其划分为三个关键发展阶段:
+- **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**<br>
+ Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao. arXiv:2605.29640, 2026。已在 VLDB 2026 演讲。<br>
+ 以事件驱动长期记忆的提取、更新与整合,服务有状态 Agent。[arXiv](https://arxiv.org/abs/2605.29640) · [PDF](https://arxiv.org/pdf/2605.29640)
+- **Directory-Aware Query and Maintenance in Vector Databases**<br>
+ Mengzhao Wang, Zheng Gong, Jingpei Hu, Jiajie Fu, Maojia Sheng, Junwen Chen, and Yifan Zhu. arXiv:2606.16903, 2026。已被 ICDE 接收。<br>
+ 目录范围检索的形式化基础与索引设计(TrieHI),OpenViking 用它在向量排序前确定目录检索范围。[arXiv](https://arxiv.org/abs/2606.16903) · [PDF](https://arxiv.org/pdf/2606.16903)
+- **VikingRAG: Accurate and Token-efficient Retrieval-augmented Generation over Structured Documents**<br>
+ Peiyuan Gao, Gaoyuan Zhang, Haojie Qin, Yahui Sun, Qianyi Zhang, Yunhao Zhang, Zeyu Wang, and Wei Lu. arXiv:2609.11390, 2026。投递中。<br>
+ 将语义检索与文档结构结合,按证据缺口展开相关目录片段。[arXiv](https://arxiv.org/abs/2609.11390) · [PDF](https://arxiv.org/pdf/2609.11390)
-- 第一阶段:基础能力建设
-在开源后的初始阶段,我们将专注于构建坚实的技术基础,包括上下文数据库的核心协议、接口、AI Agent 设施等,并且提供一个可靠完整的最小实现。
+## 开源组织建设
-- 第二阶段:生态扩展
-建立插件生态系统,支持第三方功能扩展、推动与主流 AI 框架和工具的深度集成,并扩展企业级功能,满足规模化部署需求
+### 项目发展阶段
-- 第三阶段:产业应用
-形成行业技术标准与最佳实践、建立认证体系与合作伙伴生态、推动上下文工程技术在更多产业场景的落地应用
+项目围绕上下文存储与检索、Agent 集成和部署能力持续迭代。已实现的能力与后续方向见[路线图](03-roadmap.md),已发布的变更见[更新日志](02-changelog.md)。
### 治理架构与决策机制
-基于项目的长期发展规划,我们尝试建立分层的治理架构:
-
-#### 开源治理委员会
-OpenViking 项目由一个专业的开源治理委员会负责整体战略规划与技术决策,该委员会由项目的核心贡献者与领域专家组成,主要职责包括:
-
-**战略规划职能**
-- 制定项目的长期技术路线图与发展愿景
-- 确定版本发布计划与功能优先级
-- 评估技术决策对项目生态的长期影响
+开源治理委员会负责技术路线、版本与功能优先级、核心架构和兼容性评审、工程规范、贡献者协作,以及相关项目的集成。成员包括 Maojia Sheng([@MaojiaSheng](https://github.com/MaojiaSheng))、Haojie Qin([@qin-ctx](https://github.com/qin-ctx))、Jiahui Zhou([@zhoujh01](https://github.com/zhoujh01))、Zhiheng Liu([@ZaynJarvis](https://github.com/ZaynJarvis))。符合条件的社区贡献者可以通过后续的提名与选举程序加入委员会。
-**技术治理职能**
-- 建立并维护代码质量标准与工程规范
-- 审核核心架构变更与重大功能实现
-- 确保技术实现的可持续性与向后兼容性
+具体模块的协作入口和近期活跃评审者见[贡献指南](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md)。
-**社区发展职能**
-- 制定社区发展策略与贡献者成长路径
-- 组织技术交流活动与开发者大会
-- 建立社区激励机制与荣誉体系
-
-**生态合作职能**
-- 建立与相关开源项目的技术合作关系
-- 推动与商业产品的集成与认证
-- 管理项目的知识产权与许可证合规
-
-#### 委员会核心成员构成
-当前开源治理委员会的核心成员包括以下技术专家:
-Haojie Qin, Jiahui Zhou, Linggang Wang, Maojia Sheng, Yaohui Sun
-
-为确保治理结构的开放性与多样性,我们欢迎符合条件的社区贡献者通过未来的提名与选举程序加入治理委员会。
+功能建议和问题在 [GitHub Issues](https://github.com/volcengine/OpenViking/issues) 讨论,代码与文档变更通过 Pull Request 评审。涉及公开接口、数据存储、权限边界或跨模块架构的改动,请先说明当前行为、目标行为、请求或配置示例,以及兼容性影响,再开始实现。
## 社区参与
### 加入社区
-我们诚挚邀请全球开发者加入 OpenViking 社区,共同构建下一代上下文工程基础设施。您可以通过以下方式参与:
-
-#### 即时交流
+#### 飞书群
-##### 飞书群
-
-扫描下方二维码加入飞书群组,与核心开发团队实时交流:
+扫描二维码加入飞书群,交流使用问题和开发方案:
![飞书扫码加群](../../images/lark-group-qrcode.png)
-*注:加入群组前请确保已安装 [飞书客户端](https://www.feishu.cn/)*
+需要先安装[飞书客户端](https://www.feishu.cn/)。
-##### 微信群
+#### 微信群
-扫描下方二维码添加小助手微信,备注「OpenViking」后即可加入微信交流群:
+扫描二维码添加小助手,备注“OpenViking”,申请加入交流群:
![微信扫码加群](../../images/wechat-group-qrcode.png)
-**Discord**
-
-[加入 Discord 服务器](https://discord.com/invite/eHvx8E9XF3)
-
-**X**
-
-[关注我们的动态](https://x.com/openvikingai)
+也可以加入 [Discord](https://discord.com/invite/eHvx8E9XF3),或在 [X](https://x.com/openvikingai) 查看项目动态。
### 参与方式
-我们提供多种参与渠道,满足不同开发者的协作需求:
+- **报告问题或提建议**:在 [Issues](https://github.com/volcengine/OpenViking/issues) 提供场景、版本和复现步骤。
+- **改代码或文档**:阅读[贡献指南](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md),提交实现、测试、文档或翻译。
+- **开发集成**:为 Agent 工具或框架添加插件,参考[插件开发指南](../agent-integrations/18-plugin-development.md)。
+- **分享经验**:在社区分享使用案例、排障过程,或帮助其他用户解决问题。
-#### 1. 代码贡献
-- **提交 Issue**:报告 Bug、提出功能建议或讨论技术方案
-- **提交 Pull Request**:贡献代码改进、文档更新或测试用例
-- **代码审查**:参与代码审查,帮助提升代码质量
-
-#### 2. 文档贡献
-- **完善文档**:补充用户指南、API 文档或开发教程
-- **翻译支持**:协助将文档翻译为其他语言版本
-- **示例代码**:提供更多使用示例和最佳实践
-
-#### 3. 社区支持
-- **技术分享**:在社区中分享使用经验和技术见解
-- **问题解答**:帮助其他开发者解决使用中的问题
-- **生态建设**:推动 OpenViking 与其他开源项目的集成
-
-#### 4. 生态拓展
-- **插件开发**:开发第三方插件或扩展功能
-- **集成适配**:推动 OpenViking 与主流框架的深度集成
-- **应用案例**:分享在实际项目中的应用经验
+Issue 和 PR 需要提供的信息见[贡献指南](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md)。
## 讨论与协作机制
-### 正式渠道
-
-#### GitHub 平台
-- **Issues**:用于功能建议、Bug 报告和技术讨论
-- **Pull Requests**:用于代码贡献和文档更新
-- **Discussions**:用于技术方案讨论和社区交流
-
-#### 代码仓库
-- **主仓库**:`https://github.com/volcengine/openviking`
-- **Issue 追踪**:`https://github.com/volcengine/openviking/issues`
-
-### 实时交流
-
-#### 飞书群组
-- **技术讨论**:实时技术交流与问题解答
-- **代码审查**:快速反馈和协作开发
-- **活动通知**:社区活动和技术分享通知
-
-### 社交媒体
-
-我们关注各大技术社区和社交媒体平台,及时回应用户反馈:
-- **技术博客**:定期发布技术文章和项目进展
-- **社交媒体**:在相关平台分享项目动态和使用案例
-- **技术会议**:参与行业会议,分享技术实践
-
-### 社区目标
-
-我们期望通过开源社区实现以下目标:
-
-1. **技术民主化**:让更多开发者能够使用先进的上下文工程技术
-2. **创新加速**:通过社区协作加速技术创新和产品迭代
-3. **标准建立**:推动上下文工程领域的技术标准和最佳实践
-4. **人才培养**:培养更多上下文工程领域的技术人才
-
-### 合作开放
-
-OpenViking 项目向所有开发者、研究机构和商业公司开放合作机会。我们期待:
-
-- **技术合作**:与学术界和产业界开展深度技术合作
-- **生态集成**:与相关开源项目和商业产品建立集成关系
-- **应用推广**:共同推动上下文工程技术在更多场景的应用
-
----
+[GitHub 仓库](https://github.com/volcengine/OpenViking) 保存代码、文档和评审记录。[GitHub Discussions](https://github.com/volcengine/OpenViking/discussions) 用于技术方案讨论和社区交流,群聊适合即时交流;需要跟踪的问题和方案请同步到 Issue 或 Pull Request,方便后续查阅和协作。
-**加入我们,共同构建 AI Agent 时代的上下文基础设施!**
+希望开展技术合作或生态集成的研究机构和企业,可以在 GitHub Discussions 发起讨论,或通过飞书群联系团队。
diff --git a/docs/zh/context-compilation/01-overview.md b/docs/zh/context-compilation/01-overview.md
index 7effab2da..331765cc5 100644
--- a/docs/zh/context-compilation/01-overview.md
+++ b/docs/zh/context-compilation/01-overview.md
@@ -1,23 +1,23 @@
# 上下文编译概览
-`ov compile` 把散落在 OpenViking 里的原始材料——文档、笔记、网页、访谈记录、研究资料、代码仓库——**编译**成结构化、可检索、方便人和 Agent 反复使用的知识产物。
+`ov compile` 读取 OpenViking 中的文档、笔记、网页或会话记录,按指定 Skill 整理成 Wiki、知识图谱、日报等内容,并写回 OpenViking。
## 它是怎么工作的
-你只需要提供三样东西:
+使用已安装 Skill 编译时,需要指定:
-- **从哪里来(`--from`)**:一个或多个来源目录/文件;
-- **到哪里去(`--to`)**:产物写入的目标目录;
-- **用哪个 Skill(`--skill`)**:一份描述「要编译成什么样」的说明书。
+- `--from`:一个或多个来源目录或文件。
+- `--to`:输出目录。
+- `--skill`:已安装的 Skill URI,定义输出内容和结构。
-再加上一个可选的 **`--instruction`**:给这次编译的补充指令,比如范围、受众、语言、侧重点。Skill 定义了「编译成什么形态」,`--instruction` 则在此之上告诉 Agent「这一次具体要什么」。
+可选的 `--instruction` 用来补充本次任务的范围、受众、语言、侧重点或日期。
-剩下的交给 OpenViking。Compile 依赖 [VikingBot](../concepts/15-vikingbot.md):任务被接受后,VikingBot 会加载你指定的 Skill,以你的身份读取来源,在一个独立的 **Agent Loop** 里自主地阅读、归纳、组织、写页面——就像你雇了一个人,把一堆资料整理成一份干净的知识库,然后把成品交回给你。整个过程是异步的,你可以等它跑完,也可以拿到 `task_id` 之后去做别的事。
-
-换句话说:**你负责给材料和目标,Agent 负责真正把知识整理出来。**
+编译由服务端配置的 [Agent Runtime](../api/23-agent-runtime.md) 执行,本地部署可使用内置 [VikingBot](../concepts/15-vikingbot.md)。它以请求用户的身份读取来源和 Skill,在独立的 Agent Loop 中整理并写入内容。任务异步运行,返回 `task_id` 后可查询进度和结果。
## 一条命令跑起来
+先按 [LLM Wiki 示例](02-llm-wiki.md) 导入来源、安装 Skill,再执行:
+
```bash
ov compile \
--from viking://resources/research \
@@ -30,7 +30,7 @@ ov compile \
## 换个 Skill,就换一种产物
-Compile 本身不规定「编译成什么」——那由 Skill 决定。同一批来源,配不同的 Skill,就能得到形态完全不同的知识产物。下面是我们提供的示例 Skill,前两个还各自配了一个可视化脚本,可以直接照着跑:
+Skill 决定输出内容和结构。仓库提供以下示例,其中 LLM Wiki 和 Knowledge Graph 还包含可视化脚本:
| Skill | 产物形态 | 适合 | 示例 |
|-------|---------|------|------|
@@ -47,12 +47,13 @@ Compile 本身不规定「编译成什么」——那由 Skill 决定。同一
## 前置条件
-- 一个正在运行、且启用了 Bot(`--with-bot`)的 OpenViking 服务。默认端点是 `http://localhost:1933`;远程使用需要 API Key,参见 [鉴权](../guides/04-authentication.md)。没有服务先看 [快速开始](../getting-started/02-quickstart.md)。
-- `ov` CLI 已配置好连接(`~/.openviking/ovcli.conf` 或 `OPENVIKING_*` 环境变量)。
-- 可视化脚本需要 Python 3;LLM Wiki 的脚本还会用到 `openviking` Python 包来直接读取服务里的 Wiki 页面。
+- 使用 Skill 的示例需要一个已配置 Compile Runtime 的 OpenViking 服务;本地使用需安装 `openviking[bot]` 依赖,并通过 `--with-bot` 启用内置 VikingBot。`--skill memory` 模式在进程内运行,不需要 Compile Runtime,也不传 `--from`。默认端点是 `http://localhost:1933`;远程使用需要 API Key,参见 [鉴权](../guides/04-authentication.md)。没有服务先看 [快速开始](../getting-started/02-quickstart.md)。
+- `ov` CLI 已配置好连接(`~/.openviking/ovcli.conf`,或由 `OPENVIKING_CLI_CONFIG_FILE` 指定的文件)。
+- 示例中的 `examples/...` 是仓库相对路径。先下载 [OpenViking 仓库](https://github.com/volcengine/OpenViking),在仓库根目录运行命令。
+- 可视化脚本需要 Python 3。[LLM Wiki 脚本](https://github.com/volcengine/OpenViking/blob/main/examples/compile/graph-show/llm-wiki/wiki_graph.py)还需要 `openviking` Python 包。
## 相关文档
-- [VikingBot 概念](../concepts/15-vikingbot.md) — Compile 背后的执行体
+- [VikingBot 概念](../concepts/15-vikingbot.md) — 内置 Compile 执行端
- [Agent Runtime API](../api/23-agent-runtime.md) — 创建、查询和取消 Compile 任务的完整参考
- [Skills API](../api/04-skills.md) — 如何管理和自定义 Skill
diff --git a/docs/zh/context-compilation/02-llm-wiki.md b/docs/zh/context-compilation/02-llm-wiki.md
index d8e9f0e76..5523a9fbc 100644
--- a/docs/zh/context-compilation/02-llm-wiki.md
+++ b/docs/zh/context-compilation/02-llm-wiki.md
@@ -1,6 +1,6 @@
# 示例:LLM Wiki
-把一批异构来源编译成一套 Karpathy 风格、有出处、互相链接的 **LLM Wiki**:每一页有明确的检索目的,开头一句话直给结论,术语统一,关系显式,证据紧贴结论,并由一个 `index.md` 做导航入口。
+将不同来源的材料整理成 Karpathy 风格的 LLM Wiki,即互相链接的 Markdown 知识库。每页围绕一个实体、概念或问题,先给结论,再列出处;`index.md` 提供导航。
这套 Skill 会按页面的检索目的挑选最合适的页面类型:
@@ -13,17 +13,19 @@
| `analysis` | 围绕一个问题的跨来源结论 |
| `summary` | 单一来源的忠实数字化摘要(仅当 `--instruction` 明确要求时才生成) |
-默认以 `entity` 和 `concept` 为主,其余类型只在满足各自的严格判定时才提升。产物是一个**知识库**,不是逐文档的摘要拼盘。
+默认生成 `entity` 和 `concept` 页面,其他类型按 Skill 中的条件生成。多个来源中的相关内容会合并到同一主题下。
Skill 源码:[examples/compile/ov-compile-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/llm-wiki) · 可视化脚本:[examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
+先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
+
## 第一步:准备来源
如果材料还没进 OpenViking,先导入。目录型来源用 `ov add-resource`,单文件可以用 `ov write`:
```bash
# 导入一个目录作为来源
-ov add-resource ./my-research --to viking://resources/research
+ov add-resource ./my-research --to viking://resources/research --wait
# 或者写入单个文件
ov mkdir viking://resources/research
@@ -39,17 +41,17 @@ ov ls -r viking://resources/research
## 第二步:添加 Skill
-把 LLM Wiki 的 Skill 装进服务。默认落到你的用户私有 skills 命名空间;想让团队共用就用 `-p viking://agent/skills`:
+本例将 Skill 安装到共享目录 `viking://agent/skills`,与后面的编译命令保持一致。省略 `-p` 会安装到用户私有目录,此时应把 `--skill` 改为安装返回的 URI:
```bash
-ov add-skill examples/compile/ov-compile-skills/llm-wiki
+ov add-skill examples/compile/ov-compile-skills/llm-wiki -p viking://agent/skills --wait
```
查看装好的 Skill URI:
```bash
ov skills list
-# → viking://agent/skills/llm-wiki (或 viking://user/<你>/skills/llm-wiki)
+# → viking://agent/skills/llm-wiki
```
## 第三步:执行编译
@@ -71,7 +73,7 @@ ov task status cmp_01abc # 查看进度与最终结果
ov task cancel cmp_01abc # 协作式取消
```
-## 第四步:看看产物
+## 第四步:查看产物
编译完成后目标目录里就是一套 Markdown 知识库。先看导航页,再按需钻进去:
diff --git a/docs/zh/context-compilation/03-knowledge-graph.md b/docs/zh/context-compilation/03-knowledge-graph.md
index ba34386a5..2d5b13df7 100644
--- a/docs/zh/context-compilation/03-knowledge-graph.md
+++ b/docs/zh/context-compilation/03-knowledge-graph.md
@@ -1,6 +1,6 @@
# 示例:Knowledge Graph
-把一批来源编译成一个**证据可溯、可直接可视化**的知识图谱:语义分类的实体节点、语句级出处、带类型的有向关系边。产物是这样一棵工件树:
+将来源中的实体及其关系整理成知识图谱:实体带语义类型,关系是带类型的有向边,每条陈述和边都保留出处。输出包含实体文件和关系表:
```text
entities/
@@ -18,17 +18,19 @@ relations.jsonl # 每行一条有向边
Skill 源码:[examples/compile/ov-compile-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-graph) · 可视化脚本:[examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
+先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
+
## 第一步:准备来源
```bash
-ov add-resource ./journal-to-the-west --to viking://resources/journal
+ov add-resource ./journal-to-the-west --to viking://resources/journal --wait
ov ls -r viking://resources/journal
```
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-graph
+ov add-skill examples/compile/ov-compile-skills/knowledge-graph -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-graph
```
@@ -50,7 +52,7 @@ ov task status cmp_01abc # 查看进度与最终结果
ov task cancel cmp_01abc # 协作式取消
```
-## 第四步:看看产物
+## 第四步:查看产物
```bash
ov tree viking://resources/journal-kg
@@ -62,7 +64,7 @@ ov read viking://resources/journal-kg/entities/孙悟空.md
与 LLM Wiki 的脚本不同,`knowledge_graph.py` 读取的是**本地目录**(需要 `entities/` 和 `relations.jsonl` 都在本地)。所以先把产物拉到本地,再生成 HTML。
-先把整棵工件树下载下来。`ov get` 一次下载一个文件,配合 `ov ls -r -s` 列出全部路径即可批量拉取:
+`ov get` 一次下载一个文件。下面的脚本只下载实体 Markdown 和关系表:
```bash
SRC="viking://resources/journal-kg"
@@ -71,7 +73,8 @@ mkdir -p "$DST"
ov ls -r -s "$SRC" | while read -r uri; do
# 只下载文件(entities/*.md 和 relations.jsonl),跳过目录
case "$uri" in
- */entities|"$SRC") continue ;;
+ "$SRC"/entities/*.md|"$SRC"/relations.jsonl) ;;
+ *) continue ;;
esac
rel="${uri#$SRC/}"
mkdir -p "$DST/$(dirname "$rel")"
@@ -79,7 +82,7 @@ ov ls -r -s "$SRC" | while read -r uri; do
done
```
-> `ov get` 要求本地目标路径尚不存在,所以重新下载前先清掉旧目录(`rm -rf ./journal-kg`)。
+> `ov get` 要求本地目标文件尚不存在。重复下载时,将 `DST` 换为一个新目录,保留上次结果。
确认本地目录结构正确:
diff --git a/docs/zh/context-compilation/04-daily-report.md b/docs/zh/context-compilation/04-daily-report.md
index c17a626a5..cd59573ae 100644
--- a/docs/zh/context-compilation/04-daily-report.md
+++ b/docs/zh/context-compilation/04-daily-report.md
@@ -4,21 +4,23 @@
Skill 源码:[examples/compile/ov-compile-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/daily-report)
+先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
+
## 第一步:准备来源
日报的来源通常是已经在 OpenViking 里的会话、消息或文档。如果要从本地导入一批记录:
```bash
-ov add-resource ./work-logs --to viking://resources/work-logs
+ov add-resource ./work-logs --to viking://resources/work-logs --wait
ov ls -r viking://resources/work-logs
```
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/daily-report
+ov add-skill examples/compile/ov-compile-skills/daily-report -p viking://agent/skills --wait
ov skills list
-# → viking://agent/skills/daily-report (或 viking://user/<你>/skills/daily-report)
+# → viking://agent/skills/daily-report
```
## 第三步:执行编译
@@ -30,7 +32,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --instruction "生成 2026-08-20 的日报,聚焦我的工作产出与决策"
+ --instruction "按 Asia/Shanghai 时区生成 2026-08-20 的日报,聚焦我的工作产出与决策"
```
一次生成多天,把日期范围写进 `--instruction` 即可(每天仍是独立一页):
@@ -40,7 +42,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --instruction "生成 2026-08-18 至 2026-08-20 每天一份日报"
+ --instruction "按 Asia/Shanghai 时区生成 2026-08-18 至 2026-08-20 每天一份日报"
```
命令会立刻返回 `task_id`:
@@ -50,7 +52,7 @@ ov task status cmp_01abc # 查看进度与最终结果
ov task cancel cmp_01abc # 协作式取消
```
-## 第四步:看看产物
+## 第四步:查看产物
日报是纯 Markdown,直接读即可:
diff --git a/docs/zh/context-compilation/05-knowledge-distillation.md b/docs/zh/context-compilation/05-knowledge-distillation.md
index d57748cbb..bf1852ed1 100644
--- a/docs/zh/context-compilation/05-knowledge-distillation.md
+++ b/docs/zh/context-compilation/05-knowledge-distillation.md
@@ -1,10 +1,10 @@
# 示例:知识蒸馏
-把一个或多个知识库、文档集合**蒸馏**成按主题组织、有出处的高层次知识:跨来源的发现、趋势、变化、驱动因素、对比、影响和不确定性。
+从一个或多个知识库中提炼结论,按主题组织,并保留出处与不确定性。
-典型用途:蒸馏一个知识库、对比多个集合,如从一叠财报里推导出「跨报告期的变化」这类高阶洞察。
+例如,对比多期财报,分析营收、利润和风险随时间的变化。
-产物是一棵按主题组织的浅层工件树,每个主题目录是一个持久的语义领域,每一页是一条独立有用的高层次结论:
+输出按主题分目录,每页说明一条结论:
```text
revenue-quality/
@@ -16,23 +16,25 @@ risk/
customer-concentration-increased.md
```
-> 上面只是形态示例——真实的主题和结论由你给的领域决定。
+> 以上仅展示目录结构。实际主题和结论由来源与指令决定,文件名概括结论。
Skill 源码:[examples/compile/ov-compile-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-distillation)
+先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
+
## 第一步:准备来源
```bash
-ov add-resource ./finance-reports --to viking://resources/finance-reports
+ov add-resource ./finance-reports --to viking://resources/finance-reports --wait
ov ls -r viking://resources/finance-reports
```
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-distillation
+ov add-skill examples/compile/ov-compile-skills/knowledge-distillation -p viking://agent/skills --wait
ov skills list
-# → viking://agent/skills/knowledge-distillation (或 viking://user/<user_name>/skills/knowledge-distillation)
+# → viking://agent/skills/knowledge-distillation
```
## 第三步:执行编译
@@ -64,15 +66,17 @@ ov task status cmp_01abc # 查看进度与最终结果
ov task cancel cmp_01abc # 协作式取消
```
-## 第四步:看看产物
+## 第四步:查看产物
-先看主题树,再钻进具体结论页:
+先查看目录,再读取实际生成的结论页。下面的文件名仅为示例:
```bash
ov tree viking://resources/finance-insights
ov read viking://resources/finance-insights/revenue-quality/growth-shifted-from-volume-to-pricing.md
```
+默认不生成 `index.md`;需要导航页时,在 `--instruction` 中明确要求。再次编译同一主题时,Skill 会要求更新已有分析页,并标注可能随时间变化的结论。
+
## 相关文档
- [上下文编译概览](./01-overview.md)
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index c6af6719d..8f3475e87 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -4,37 +4,42 @@
### OpenViking 是什么?解决什么问题?
-OpenViking 是一个专为 AI Agent 设计的开源上下文数据库。它解决了构建 AI Agent 时的核心痛点:
+OpenViking 用文件系统组织 Agent 的资源、记忆和技能,支持按路径浏览、语义检索和按需读取。应用可以把会话中提取的偏好与经验保存下来,在后续任务中复用。
-- **上下文碎片化**:记忆、资源、技能散落各处,难以统一管理
-- **检索效果不佳**:传统 RAG 平铺式存储缺乏全局视野,难以理解完整语境
-- **上下文不可观测**:隐式检索链路如同黑箱,出错时难以调试
-- **记忆迭代有限**:缺乏 Agent 相关的任务记忆和自我进化能力
+它针对构建 Agent 时的四个常见问题:
-OpenViking 通过文件系统范式统一管理所有上下文,实现分层供给与自我迭代。
+- **上下文碎片化**:记忆、资源、技能分散在不同位置,难以统一管理
+- **检索效果不佳**:平铺式分块存储丢失了周边结构,检索结果缺少完整语境
+- **上下文不可观测**:隐式检索链路出错时难以排查
+- **记忆迭代有限**:缺少可跨会话积累的任务记忆
+
+例如,用户让 Agent 修改部署方案时,Agent 可以检索项目文档,再读取相关配置;上次会话中已确认的部署约束,如果已提取为记忆,也可以在这次任务中检索和复用。应用需要接入检索与会话提交流程,安装数据库本身不会让 Agent 自动获得这些上下文。首次使用可从[导入一份资料并检索](../getting-started/02-quickstart.md)开始,再按需要接入[Agent 工具](../agent-integrations/01-overview.md)。
### OpenViking 和传统向量数据库有什么本质区别?
-| 维度 | 传统向量数据库 | OpenViking |
-|------|---------------|------------|
-| **存储模型** | 扁平化向量存储 | 层级化文件系统(AGFS) |
-| **检索方式** | 单一向量相似度搜索 | 目录递归检索 + 意图分析 + Rerank |
-| **输出形式** | 原始分块 | 结构化上下文(L0 摘要/L1 概览/L2 详情) |
-| **记忆能力** | 不支持 | 内置多种可扩展的记忆类型,支持自动提取和持续迭代 |
-| **可观测性** | 黑箱 | 检索轨迹完整可追溯 |
-| **上下文类型** | 仅文档 | Resource + Memory + Skill 三种类型 |
+向量数据库主要提供向量存储和相似度检索。OpenViking 在向量检索之上,提供上下文目录、分层摘要、资源导入、会话和记忆管理。已有向量数据库的能力因产品而异,选型时应按具体需求比较。
+
+| 需求 | OpenViking 提供的能力 |
+| --- | --- |
+| 组织上下文 | 用 `viking://` 路径管理资源、记忆和技能 |
+| 检索内容 | 在目录范围内做向量检索,可配置意图分析和 Rerank |
+| 控制读取量 | 先读目录摘要或概览,再按需读取详细内容 |
+| 复用会话经验 | 提交会话后,按记忆策略提取和更新记忆 |
+| 排查检索问题 | 使用日志与 telemetry 查看处理和检索过程 |
+
+如果应用只需要对已有向量做相似度查询,应先评估现有数据库是否够用。需要目录浏览、摘要与详情分层读取,或跨会话记忆管理时,再评估 OpenViking。用自己的资料和代表性问题比较召回内容、读取量、延迟和处理成本;收益取决于数据、模型与配置。
### 什么是 L0/L1/L2 分层模型?为什么需要它?
-L0/L1/L2 是 OpenViking 的渐进式内容加载机制,解决了"海量上下文一次性塞入提示词"的问题:
+Agent 可以先读摘要定位内容,再按需读全文,减少不相关内容进入上下文。
-| 层级 | 名称 | Token 限制 | 用途 |
-|------|------|-----------|------|
-| **L0** | 摘要 | ~100 tokens | 向量搜索召回、快速过滤、列表展示 |
-| **L1** | 概览 | ~2000 tokens | Rerank 精排、内容导航、决策参考 |
-| **L2** | 详情 | 无限制 | 完整原始内容、按需深度加载 |
+| 层级 | 内容 | 默认正文目标 | 用途 |
+| --- | --- | --- | --- |
+| L0 | 目录摘要 `.abstract.md` | 256 字符 | 检索与快速筛选 |
+| L1 | 目录概览 `.overview.md` | 4,000 字符 | 导航与精排 |
+| L2 | 原始文件或解析后的内容 | 无统一上限 | 按需读取详情 |
-这种设计让 Agent 可以先浏览摘要快速定位,再按需加载详情,显著节省 Token 消耗。
+L0/L1 是目录级附属文件,是否可用取决于处理状态和配置。资源摘要的生成目标按字符计算,可通过 `semantic.abstract_max_chars` 和 `semantic.overview_max_chars` 调整。截断会保留完整句子,因此首句可能超过目标;这不是已存储附属文件的硬上限,详见[上下文层级](../concepts/03-context-layers.md)。
### Viking URI 是什么?有什么作用?
@@ -70,14 +75,14 @@ viking://
### OpenViking 是如何访问 AGFS 文件系统的?
-OpenViking 通过 Rust 绑定(`ragfs_python` / `RAGFSBindingClient`)在 Python 进程内直接运行 RAGFS 文件系统逻辑。优点是性能极高、无网络延迟;前提是本地需要有编译好的 RAGFS 共享库(预编译 Wheel 包内置,或从源码编译)。
+OpenViking 通过 Rust 绑定(`ragfs_python` / `RAGFSBindingClient`)在 Python 进程内直接运行 RAGFS 文件系统逻辑。文件系统调用在进程内完成;使用远程存储后端时仍会访问网络。RAGFS 共享库随预编译 wheel 提供,也可从源码构建。
> [!WARNING]
> OpenViking 已不再支持 AGFS HTTP client 模式。当前 AGFS / RAGFS 文件系统访问仅通过 Rust binding(`RAGFSBindingClient`)在进程内完成。这不影响 OpenViking server 的 HTTP API、`ov` CLI,或 `AsyncHTTPClient` / `SyncHTTPClient` 访问 OpenViking 服务端的能力。
### 遇到 "AGFS binding library not found" 错误怎么办?
-这通常是因为本地没有可用的 RAGFS 共享库。在项目根目录运行 `pip install -e . --force-reinstall` 重新编译安装即可(需要 Rust 工具链)。
+这通常表示 RAGFS 共享库缺失或无法加载。先检查 Python 版本和平台是否有对应的预编译 wheel,并尝试重新安装。只有平台缺少 wheel 或需要修改源码时才[从源码构建](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md),届时需准备原生编译工具链。
### 如何安装 OpenViking?
@@ -87,7 +92,7 @@ pip install openviking --upgrade --force-reinstall
### 如何配置 OpenViking?
-在项目目录创建 `~/.openviking/ov.conf` 配置文件:
+在用户主目录下创建 `~/.openviking/ov.conf`,将示例中的模型和凭据替换为实际配置:
```json
{
@@ -107,9 +112,11 @@ pip install openviking --upgrade --force-reinstall
"api_base": "https://ark.cn-beijing.volces.com/api/v3"
},
"rerank": {
- "provider": "volcengine",
- "api_key": "your-api-key",
- "model": "doubao-rerank-250615"
+ "provider": "vikingdb",
+ "ak": "your-access-key",
+ "sk": "your-secret-key",
+ "model_name": "doubao-seed-rerank",
+ "model_version": "251028"
},
"storage": {
"workspace": "./data",
@@ -163,8 +170,8 @@ Embedding、VLM、存储等服务配置由 OpenViking Server 通过 `ov.conf`
# 添加单个文件
await client.add_resource(
path="./document.pdf",
- parent="viking://resources/docs", # 存到这个目录下面,文件名由来源决定
- options={"reason": "项目技术文档"}, # 描述资源用途,提升检索质量
+ parent="viking://resources", # 存到这个目录下面,文件名由来源决定
+ options={"reason": "项目技术文档"}, # 未传 instruction 时用于生成 L0/L1 摘要,也用于资源相关的记忆提取
)
# 添加网页
@@ -182,10 +189,10 @@ await client.wait_processed()
| | `to` | `parent` |
|---|---|---|
| 传什么 | 完整最终 URI,**含叶子名** | 一个**已存在的目录**,叶子名由来源决定 |
-| 撞名怎么办 | 不改名。目标已存在时按新来源同步,来源里没有的可见条目会被删除 | 不覆盖。退到 `name_1`、`name_2`……并返回一条 warning |
+| 撞名怎么办 | 不改名。目标目录已存在时按新来源同步,来源里没有的可见条目会被删除 | 不覆盖。退到 `name_1`、`name_2`……并返回一条 warning |
| 什么时候用 | 名字已知且必须逐字生效;或者要原地更新一个已有资源 | 叶子名由服务端派生(URL / 仓库导入、大文件切分),或者目标下已有的内容一点都不能动 |
-两个都留空 = 目录和叶子名都从来源推导,撞名行为同 `parent`。
+两个都留空 = 目录和叶子名都从来源推导,撞名行为同 `parent`。资源命名空间根目录是例外:`to` 为 `viking://resources` 等资源根目录时,会按父目录处理。资源根目录不存在时会自动创建;其他父目录不存在时,可传入 `options={"create_parent": True}`。
`to` 和 `parent` 不能同时传,会直接报错。
@@ -204,9 +211,9 @@ await client.wait_processed()
| 特性 | `find()` | `search()` |
|------|----------|------------|
-| **会话上下文** | 不需要 | 需要 |
-| **意图分析** | 不使用 | 使用 LLM 分析生成 0-5 个查询 |
-| **延迟** | 低 | 较高 |
+| **会话上下文** | 不使用 | 可选,传入 `session_id` 且启用意图分析时使用 |
+| **意图分析** | 不使用 | 有会话内容且启用意图分析时使用 LLM |
+| **延迟** | 取决于 Embedding、检索和 Rerank | 使用意图分析时增加一次 LLM 调用 |
| **适用场景** | 简单语义搜索 | 复杂任务、需要理解上下文 |
```python
@@ -254,7 +261,7 @@ await session.commit()
### OpenViking 支持哪些记忆类型?
-OpenViking 内置 `profile`、`preferences`、`entities`、`events`、`identity`、`soul`、`cases`、`trajectories`、`experiences`、`tools` 和 `skills` 等记忆类型。提交会话后,系统会按当前记忆策略提取适用内容;也可以根据业务需要扩展或调整记忆类型。
+OpenViking 内置 `profile`、`preferences`、`entities`、`events`、`identity`、`soul`、`cases`、`trajectories`、`experiences` 等记忆类型。提交会话后,系统会按当前记忆策略提取适用内容;也可以根据业务需要扩展或调整记忆类型。
记忆存储在当前用户或 Peer 命名空间,不存在当前可写的 `viking://agent/memories` 目录。完整类型与路径见 [上下文类型](../concepts/02-context-types.md)。
@@ -278,11 +285,11 @@ overview = await client.overview(uri="viking://resources")
### 如何提升检索质量?
-1. **使用 Rerank 模型**:配置 Rerank 可显著提升精排效果
-2. **提供有意义的 `reason`**:添加资源时描述用途,帮助系统理解资源价值
-3. **合理组织目录结构**:使用 `target` 参数将相关资源放在一起
-4. **使用会话上下文**:`search()` 会利用会话历史进行意图分析
-5. **选择合适的 Embedding 模式**:多模态内容使用 `multimodal` 输入
+1. **检查摘要**:确认 L0/L1 是否准确反映来源;需要调整时使用导入的 `instruction` 或摘要模板
+2. **组织目录结构**:导入时用 `parent` 指定现有父目录,或用 `to` 指定最终 URI
+3. **使用会话上下文**:保持 `retrieval.enable_intent` 开启(默认),并向 `search()` 传入有内容的会话
+4. **选择合适的 Embedding 模式**:多模态内容使用 `multimodal` 输入
+5. **评估 Rerank 模型**:对代表性查询比较启用前后的排序结果,再决定是否启用。可以尝试用 Jev(TypeSafe System One)做 rerank:它对每个候选单独判断与查询的相关性,各候选分数互不竞争;配置见[配置指南](../guides/01-configuration.md#rerank)
### 检索结果的分数是如何计算的?
@@ -300,9 +307,10 @@ overview = await client.overview(uri="viking://resources")
1. **未等待处理完成**
```python
- await client.add_resource(path="./doc.pdf")
- await client.wait_processed() # 必须等待
+ result = await client.add_resource(path="./doc.pdf", wait=True)
+ print(result)
```
+ 新导入时可用 `wait=True` 等待。排查已经提交的导入时,用返回的 `task_id` 查询任务,不必重复导入。状态仍为 `pending` 或 `running` 时需要继续等待;`failed` 或 `cancelled` 时查看任务详情。请求超时也不能据此判断后台任务已经失败,详见[异步任务](../api/17-tasks.md)。
2. **Embedding 模型配置错误**
- 检查 `~/.openviking/ov.conf` 中的 `api_key` 是否正确
@@ -312,20 +320,20 @@ overview = await client.overview(uri="viking://resources")
- 检查文件扩展名是否在支持列表中
- 确认文件内容有效且未损坏
-4. **查看处理日志**
- ```python
- import logging
- logging.basicConfig(level=logging.DEBUG)
- ```
+4. **查看服务端处理日志**
+ 在运行服务端的终端或日志系统中查看对应任务的错误。客户端的 Python 日志设置不会开启远程服务端日志。
### 搜索没有返回预期结果
**排查步骤**:
-1. **确认资源已处理完成**
+1. **确认资源存在,再查询导入任务状态**
+ 用导入时返回的 `task_id` 查询任务;`completed` 表示处理完成,`failed` 或 `cancelled` 需先检查原因。
```python
# 检查资源是否存在
items = await client.ls(uri="viking://resources/")
+ task = await client.get_task("<导入时返回的 task_id>")
+ print(task["status"] if task is not None else "任务不存在或已过期")
```
2. **检查 `target_uri` 过滤条件**
@@ -359,19 +367,16 @@ overview = await client.overview(uri="viking://resources")
- 闲聊内容可能不会产生记忆
- 需要包含可提取的信息(偏好、实体、事件等)
-4. **查看提取的记忆**
+4. **查看记忆目录**
```python
- memories = await client.find(
- query="",
- target_uri="viking://~/memories/",
- )
+ memories = await client.ls(uri="viking://~/memories/")
```
### 性能问题
**优化建议**:
-1. **批量处理**:一次添加多个资源比逐个添加更高效
+1. **定位瓶颈**:先检查处理队列、模型延迟和存储耗时,再调整并发
2. **合理设置 `batch_size`**:Embedding 配置中调整批处理大小
3. **使用本地存储**:开发阶段使用 `local` 后端减少网络延迟
4. **异步操作**:充分利用 `AsyncHTTPClient` 的异步特性
@@ -380,7 +385,7 @@ overview = await client.overview(uri="viking://resources")
### OpenViking 是开源的吗?
-是的,OpenViking 完全开源,主体采用 AGPLv3 许可证,详见 README.md 说明。
+OpenViking 主体采用 AGPLv3,CLI 和大部分示例采用 Apache 2.0。各组件及例外见仓库的[许可证说明](https://github.com/volcengine/OpenViking#license)。
## 相关文档