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

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

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

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)

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

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

ov add-resource ./docs --wait

Wait with timeout (in seconds)

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

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

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

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

如何编写优质记忆

Be specific — Include concrete details, not vague summaries
Include context — Why this matters, when it applies
Use structured format — Separate the what from the why

具体明确——包含具体细节，避免模糊总结
包含上下文——说明该记忆的重要性、适用场景
使用结构化格式——区分内容本身和背景信息

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

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

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

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

Wait with timeout (in seconds)

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

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:

./skills/code-runner/

├── SKILL.md

├── helper.py

└── templates/

└── script.py

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

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格式。

ov-add-data

Original

Translation

OpenViking (OV) add-resource

OpenViking (OV) add-resource

When to Use

适用场景

CLI Options

CLI选项

Basic Usage

基本用法

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

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

add a file from url

add a file from url

add a file from local filesystem

add a file from local filesystem

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

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

add a directory from local filesystem

add a directory from local filesystem

Context and Instructions (TBD)

上下文与指令（待上线）

Async Processing Control

异步处理控制

Wait until semantic processing finishes

Wait until semantic processing finishes

Wait with timeout (in seconds)

Wait with timeout (in seconds)

Fire and forget (default, without --wait)

Fire and forget (default, without --wait)

Specify the target path

指定目标路径

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

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

CLI Output

CLI输出

CLI Prerequisites

CLI使用前提

OpenViking (OV) add-memory

OpenViking (OV) add-memory

When to Use

适用场景

Input Modes

输入模式

Mode 1: Plain Text for compressed memory

模式1：纯文本压缩记忆

Mode 2: Multi-turn Conversation for Richer Context

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

Output

输出

Agent Best Practices

Agent最佳实践

How to Write Good Memories

如何编写优质记忆

Batch Related Facts

批量处理关联事实

Prerequisites

使用前提

OpenViking (OV) add-skill

OpenViking (OV) add-skill

When to Use

适用场景

Input Formats

输入格式

Mode 1: SKILL.md File

模式1：SKILL.md文件

Add from a single SKILL.md file

Add from a single SKILL.md file

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

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

CLI Options

CLI选项

Async Processing Control

异步处理控制

Wait until semantic processing finishes

Wait until semantic processing finishes

Wait with timeout (in seconds)

OpenViking (OV)
`add-resource`

OpenViking (OV)
`add-resource`

OpenViking (OV)
`add-memory`

OpenViking (OV)
`add-memory`

OpenViking (OV)
`add-skill`

OpenViking (OV)
`add-skill`