Back to Details

ov-add-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenViking (OV) 
add-resource

OpenViking (OV) 
add-resource

The 
ov add-resource
command imports external resources into OpenViking's context database — supporting local files, directories, URLs, and remote repositories. Resources are automatically processed with semantic analysis and organized under the 
viking://resources/
namespace.
ov add-resource
命令可将外部资源导入OpenViking的上下文数据库，支持本地文件、目录、URL和远程仓库。资源会自动经过语义分析处理，并收纳在
viking://resources/
命名空间下。

When to Use

适用场景

  • Importing project documentation, code repositories, or reference materials
  • Adding web pages, articles, or online resources for future retrieval
  • Building a knowledge base from external sources
  • When an agent encounters valuable content that should persist across sessions
  • Recording a project's product documentation, design specs, or other valuable materials
  • Storing sensitive information or private data of the user, like photo and albums
  • 导入项目文档、代码仓库或参考资料
  • 添加网页、文章或在线资源供后续检索
  • 基于外部数据源搭建知识库
  • Agent遇到需要跨会话留存的高价值内容时
  • 记录项目的产品文档、设计规范或其他高价值材料
  • 存储用户的敏感信息或私有数据，比如照片和相册

CLI Options

CLI选项

Basic Usage

基本用法

Import a local file or URL:
bash
undefined
导入本地文件或URL：
bash
undefined

add a code repo from github or gitlab or a git address

add a code repo from github or gitlab or a git address

ov add-resource https://github.com/volcengine/OpenViking ov add-resource https://code.xxxx.org/viking/viking ov add-resource git@code.xxxx.org:viking/viking.git
ov add-resource https://github.com/volcengine/OpenViking ov add-resource https://code.xxxx.org/viking/viking ov add-resource git@code.xxxx.org:viking/viking.git

add a file from url

add a file from url

ov add-resource https://arxiv.org/pdf/2602.09540 ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md
ov add-resource https://arxiv.org/pdf/2602.09540 ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md

add a file from local filesystem

add a file from local filesystem

ov add-resource ./docs/api-spec.md ov add-resource ./team_building.jpg ov add-resource /User/volcengine/Documents/profile.pdf ov add-resource /User/volcengine/Documents/project.docx
ov add-resource ./docs/api-spec.md ov add-resource ./team_building.jpg ov add-resource /User/volcengine/Documents/profile.pdf ov add-resource /User/volcengine/Documents/project.docx

add a zip file from local filesystem (will be unzipped on server)

add a zip file from local filesystem (will be unzipped on server)

ov add-resource ./docs-of-project.zip
ov add-resource ./docs-of-project.zip

add a directory from local filesystem

add a directory from local filesystem

ov add-resource /User/volcengine/Photo/Travels/2026/ --include ".jpg,.jpeg,*.png" ov add-resource /User/volcengine/Documents/OV项目设计文档/
undefined
ov add-resource /User/volcengine/Photo/Travels/2026/ --include ".jpg,.jpeg,*.png" ov add-resource /User/volcengine/Documents/OV项目设计文档/
undefined

Context and Instructions (TBD)

上下文与指令（待上线）

Add metadata to guide processing: --reason and --instruction will be supported in the future.
添加元数据引导处理：后续将支持--reason和--instruction参数。

Async Processing Control

异步处理控制

The time of adding resources could cost long (like minutes), and the semantic processing could be async. Use 
--wait
to wait for the processing to complete.
bash
undefined
添加资源可能耗时较长（可达数分钟），语义处理可异步执行。使用
--wait
参数可等待处理完成。
bash
undefined

Wait until semantic processing finishes

Wait until semantic processing finishes

ov add-resource ./docs --wait
ov add-resource ./docs --wait

Wait with timeout (in seconds)

Wait with timeout (in seconds)

ov add-resource https://example.com/docs --wait --timeout 60
ov add-resource https://example.com/docs --wait --timeout 60

Fire and forget (default, without --wait)

Fire and forget (default, without --wait)

ov add-resource ./docs

If you fire and forget, the command will return after the resource is completely downloaded/uploaded on server, and then the CLI will return the root URI of the imported resource. To check the status of the resource, you can use `ov ls` or `ov tree` to list the resources under root URI or `viking://resources/`.
ov add-resource ./docs

如果使用异步执行模式，命令会在资源完全下载/上传到服务器后返回，CLI会返回导入资源的根URI。你可以使用`ov ls`或`ov tree`命令列出根URI或`viking://resources/`下的资源，查看资源处理状态。

Specify the target path

指定目标路径

By default, resources are imported under 
viking://resources/
. Use 
--to
or 
--parent
to specify a target uri.
bash
undefined
默认情况下，资源会导入到
viking://resources/
下。你可以使用
--to
或
--parent
参数指定目标URI。
bash
undefined

The data will be imported as viking://resources/2026/2026-01-01/, which should not exist before

The data will be imported as viking://resources/2026/2026-01-01/, which should not exist before

ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-01/ --to "viking://resources/2026/2026-01-01/"
ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-01/ --to "viking://resources/2026/2026-01-01/"

The data will be imported under viking://resources/2026, which should exist and be a directory

The data will be imported under viking://resources/2026, which should exist and be a directory

ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-02/ --parent "viking://resources/2026/"
undefined
ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-02/ --parent "viking://resources/2026/"
undefined

CLI Output

CLI输出

Returns the root URI of the imported resource, like:
root_uri  viking://resources/2026/2026-01-01
返回导入资源的根URI，示例如下：
root_uri  viking://resources/2026/2026-01-01

CLI Prerequisites

CLI使用前提

  • CLI configured in: 
    ~/.openviking/ovcli.conf
  • Network access for the importing URL from server
  • Local read access for the importing local files/directories from CLI.
  • CLI配置文件存放在：
    ~/.openviking/ovcli.conf
  • 服务器可访问要导入的URL对应的网络资源
  • CLI对要导入的本地文件/目录有读取权限

OpenViking (OV) 
add-memory

OpenViking (OV) 
add-memory

The 
ov add-memory
command adds long persistant memory — turning text and structured conversations into searchable, retrievable memories in the OpenViking context database. Use 
ov add-memory --help
for latest usage.
ov add-memory
命令用于添加长期持久记忆，可将文本和结构化对话转换为OpenViking上下文数据库中可搜索、可检索的记忆。可使用
ov add-memory --help
查看最新用法。

When to Use

适用场景

  • After learning something worth remembering across sessions
  • To persist conversation insights, decisions, or findings
  • To build up a knowledge base from interactions
  • When an agent wants to store context for future retrieval
  • 学习到需要跨会话留存的重要内容后
  • 持久化对话洞察、决策或发现的结论
  • 基于交互内容搭建知识库
  • Agent需要存储上下文供后续检索时

Input Modes

输入模式

choose wisely between plain text and multi-turn mode. Multi-turn mode can contain more complex insights, let openviking handle the memory extraction.
请根据场景选择纯文本模式和多轮对话模式。多轮模式可承载更复杂的洞察，可交由OpenViking处理记忆提取逻辑。

Mode 1: Plain Text for compressed memory

模式1：纯文本压缩记忆

A simple string is stored as a 
user
message:
bash
ov add-memory "User's name is Bob, he participate in Global Hackathon in 2025-01-08, and won Champion."
简单字符串会被存储为
user
消息：
bash
ov add-memory "User's name is Bob, he participate in Global Hackathon in 2025-01-08, and won Champion."

Mode 2: Multi-turn Conversation for Richer Context

模式2：多轮对话承载丰富上下文

A JSON array of 
{role, content}
objects to store a full exchange:
bash
ov add-memory '[
  {"role": "user", "content": "I love traveling. Give me some options of Transport from Beijing to Shanghai."},
  {"role": "assistant", "content": "You can use train, bus, or plane. Train is the fastest, but you need to book in advance. Bus is cheaper, but you need to wait. Plane is the most expensive, but you can get there any time of day."},
  {"role": "user", "content": "I prefer train. I like sightseeing on the train. Can you give me the train schedule?"},
  < ... more possible conversation about schedule and tickest need to be memorized ... >
]'
传入
{role, content}
对象组成的JSON数组，可存储完整交互过程：
bash
ov add-memory '[
  {"role": "user", "content": "I love traveling. Give me some options of Transport from Beijing to Shanghai."},
  {"role": "assistant", "content": "You can use train, bus, or plane. Train is the fastest, but you need to book in advance. Bus is cheaper, but you need to wait. Plane is the most expensive, but you can get there any time of day."},
  {"role": "user", "content": "I prefer train. I like sightseeing on the train. Can you give me the train schedule?"},
  < ... more possible conversation about schedule and tickest need to be memorized ... >
]'

Output

输出

Returns count of memory extracted:
memories_extracted   1
返回提取的记忆数量，示例如下：
memories_extracted   1

Agent Best Practices

Agent最佳实践

How to Write Good Memories

如何编写优质记忆

  1. Be specific — Include concrete details, not vague summaries
  2. Include context — Why this matters, when it applies
  3. Use structured format — Separate the what from the why
  1. 具体明确——包含具体细节，避免模糊总结
  2. 包含上下文——说明该记忆的重要性、适用场景
  3. 使用结构化格式——区分内容本身和背景信息

Batch Related Facts

批量处理关联事实

Group related memories in one call rather than many small ones:
bash
ov add-memory '[
  {"role": "user", "content": "Key facts about the ov_cli Rust crate"},
  {"role": "assistant", "content": "1. runs faster than python cli\n2. uses HttpClient to connect openviking server\n3. Output formatting supports table and JSON modes\n4. Config lives at ~/.openviking/ovcli.conf"}
]'
将关联的记忆合并为一次调用，避免多次发送小请求：
bash
ov add-memory '[
  {"role": "user", "content": "Key facts about the ov_cli Rust crate"},
  {"role": "assistant", "content": "1. runs faster than python cli\n2. uses HttpClient to connect openviking server\n3. Output formatting supports table and JSON modes\n4. Config lives at ~/.openviking/ovcli.conf"}
]'

Prerequisites

使用前提

  • CLI configured: 
    ~/.openviking/ovcli.conf
  • CLI已配置：
    ~/.openviking/ovcli.conf

OpenViking (OV) 
add-skill

OpenViking (OV) 
add-skill

The 
ov add-skill
command adds agent capabilities to OpenViking — supporting SKILL.md files, MCP tool definitions, and raw skill content. Skills are automatically processed and organized under the 
viking://agent/skills/
namespace, making them discoverable and usable by agents.
ov add-skill
命令用于为OpenViking添加Agent能力，支持SKILL.md文件、MCP工具定义和原生技能内容。技能会自动经过处理并收纳在
viking://agent/skills/
命名空间下，可供Agent发现和使用。

When to Use

适用场景

  • Adding custom agent capabilities and workflows
  • Importing MCP (Model Context Protocol) tools
  • Persisting skill definitions across agent sessions
  • Building a library of reusable agent capabilities
  • When an agent needs to extend its toolset with custom logic
  • 添加自定义Agent能力和工作流
  • 导入MCP（模型上下文协议）工具
  • 跨Agent会话持久化技能定义
  • 搭建可复用的Agent能力库
  • Agent需要通过自定义逻辑扩展工具集时

Input Formats

输入格式

Mode 1: SKILL.md File

模式1：SKILL.md文件

Import from a single SKILL.md file with YAML frontmatter:
bash
undefined
从单个带YAML前置元数据的SKILL.md文件导入：
bash
undefined

Add from a single SKILL.md file

Add from a single SKILL.md file

ov add-skill ./skills/my-skill/SKILL.md
ov add-skill ./skills/my-skill/SKILL.md

Add from a directory containing SKILL.md (includes auxiliary files)

Add from a directory containing SKILL.md (includes auxiliary files)

ov add-skill ./skills/my-skill/
undefined
ov add-skill ./skills/my-skill/
undefined

CLI Options

CLI选项

Async Processing Control

异步处理控制

Semantic processing happens asynchronously. Use 
--wait
to block until complete:
bash
undefined
语义处理为异步执行，可使用
--wait
参数阻塞直到处理完成：
bash
undefined

Wait until semantic processing finishes

Wait until semantic processing finishes

ov add-skill ./skills/my-skill/ --wait
ov add-skill ./skills/my-skill/ --wait

Wait with timeout (in seconds)

Wait with timeout (in seconds)

ov add-skill ./skills/my-skill/ --wait --timeout 60
ov add-skill ./skills/my-skill/ --wait --timeout 60

Fire and forget (default, without --wait)

Fire and forget (default, without --wait)

ov add-skill ./skills/my-skill/
undefined
ov add-skill ./skills/my-skill/
undefined

CLI Output

CLI输出

Returns the URI of the added skill, like:
uri  viking://agent/skills/my-skill/
返回添加的技能的URI，示例如下：
uri  viking://agent/skills/my-skill/

SKILL.md Format

SKILL.md格式

Skills use Markdown with YAML frontmatter:
markdown
---
name: skill-name
description: Brief description of the skill
allowed-tools:
  - Tool1
  - Tool2
tags:
  - tag1
  - tag2
---
技能使用带YAML前置元数据的Markdown格式：
markdown
---
name: skill-name
description: Brief description of the skill
allowed-tools:
  - Tool1
  - Tool2
tags:
  - tag1
  - tag2
---

Including Auxiliary Files

包含辅助文件

When adding from a directory, all files in the directory are included as auxiliary files:
bash
undefined
从目录导入技能时，目录下的所有文件都会作为辅助文件包含在内：
bash
undefined

Directory structure:

Directory structure:

./skills/code-runner/

./skills/code-runner/

├── SKILL.md

├── SKILL.md

├── helper.py

├── helper.py

└── templates/

└── templates/

└── script.py

└── script.py

ov add-skill ./skills/code-runner/
ov add-skill ./skills/code-runner/

Both helper.py and templates/ are included

Both helper.py and templates/ are included

undefined
undefined

CLI Prerequisites

CLI使用前提

  • CLI configured: 
    ~/.openviking/ovcli.conf
  • The skill file (SKILL.md) should be in the correct markdown format.
  • CLI已配置：
    ~/.openviking/ovcli.conf
  • 技能文件（SKILL.md）需符合正确的Markdown格式。