ov-add-data

OpenViking (OV) add-resource

ov add-resource コマンドは、ローカルファイル、ディレクトリ、URL、リモートリポジトリに対応し、外部リソースを OpenViking のコンテキストデータベースにインポートします。リソースは意味解析によって自動的に処理され、viking://resources/ 名前空間の下に整理されます。

使用する場面

• プロジェクトのドキュメント、コードリポジトリ、参考資料をインポートする場合
• 後で取得できるように、ウェブページ、記事、オンラインリソースを追加する場合
• 外部ソースからナレッジベースを構築する場合
• エージェントが、セッションをまたいで保持すべき価値のあるコンテンツを見つけた場合
• プロジェクトの製品ドキュメント、設計仕様、その他の価値ある資料を記録する場合
• 写真やアルバムなど、ユーザーの機密情報や個人データを保存する場合

CLI オプション

基本的な使い方

ローカルファイルまたは URL をインポートします。

# 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 [email protected]: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项目设计文档/

コンテキストと指示（未定）

処理をガイドするメタデータを追加します。--reason と --instruction は今後サポートされる予定です。

非同期処理の制御

リソースの追加には長い時間（数分など）がかかる場合があり、意味処理は非同期で実行されることがあります。処理が完了するまで待つには、--wait を使用します。

# 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

待機せずにコマンドを実行すると、リソースのサーバーへのダウンロード／アップロードが完了した時点でコマンドが終了し、インポートしたリソースのルート URI が CLI から返されます。リソースの状態を確認するには、ov ls または ov tree を使用して、ルート URI または viking://resources/ の下にあるリソースを一覧表示します。

対象パスの指定

デフォルトでは、リソースは viking://resources/ の下にインポートされます。--to または --parent を使用して、対象 URI を指定します。

# 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/"

CLI の出力

インポートしたリソースのルート URI が返されます。例：

root_uri  viking://resources/2026/2026-01-01

CLI の前提条件

• CLI が ~/.openviking/ovcli.conf で設定されていること
• インポートする URL にサーバーからネットワークアクセスできること
• インポートするローカルファイル／ディレクトリを CLI から読み取れること

OpenViking (OV) add-memory

ov add-memory コマンドは、長期記憶を追加し、テキストや構造化された会話を、OpenViking のコンテキストデータベースで検索・取得できる記憶に変換します。最新の使い方については、ov add-memory --help を使用してください。

使用する場面

• セッションをまたいで記憶しておく価値のあることを学んだ後
• 会話から得た洞察、決定事項、調査結果を保存する場合
• やり取りを通じてナレッジベースを構築する場合
• エージェントが、後で取得するためのコンテキストを保存したい場合

入力モード

プレーンテキストと複数ターンモードを適切に使い分けてください。複数ターンモードには、より複雑な洞察を含めることができ、記憶の抽出は OpenViking に任せられます。

モード 1：圧縮された記憶用のプレーンテキスト

単純な文字列は、user メッセージとして保存されます。

ov add-memory "User's name is Bob, he participate in Global Hackathon in 2025-01-08, and won Champion."

モード 2：より豊かなコンテキストを含む複数ターンの会話

会話全体を保存するには、{role, content} オブジェクトの JSON 配列を使用します。

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 ... >
]'

出力

リクエストが受け付けられると OK が返されます。コミットがキューに入った後、サーバー上で記憶の抽出が非同期に実行されるため、CLI は抽出の完了を待ちません。

OK

エージェント向けのベストプラクティス

良い記憶の書き方

1. 具体的にする — 曖昧な要約ではなく、具体的な詳細を含めます
2. コンテキストを含める — なぜ重要なのか、いつ当てはまるのかを記載します
3. 構造化された形式を使う — 何についての情報かと、その理由を分けます

関連する事実をまとめる

小さな項目を何度も追加するのではなく、関連する記憶を1回の呼び出しにまとめます。

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"}
]'

前提条件

• CLI が設定されていること：~/.openviking/ovcli.conf

OpenViking (OV) add-skill

ov add-skill コマンドは、SKILL.md ファイル、MCP ツール定義、未加工のスキルコンテンツに対応し、エージェントの機能を OpenViking に追加します。スキルは自動的に処理され、viking://agent/skills/ 名前空間の下に整理されるため、エージェントが見つけて使用できるようになります。

使用する場面

• カスタムエージェント機能やワークフローを追加する
• MCP（Model Context Protocol）ツールをインポートする
• エージェントのセッションをまたいでスキル定義を保持する
• 再利用可能なエージェント機能のライブラリを構築する
• エージェントがカスタムロジックでツールセットを拡張する必要がある場合

入力形式

モード 1：SKILL.md ファイル

YAML フロントマターを含む単一の SKILL.md ファイルからインポートします。

# 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/

CLI オプション

非同期処理の制御

セマンティック処理は非同期で行われます。完了するまで待機するには、--wait を使用します。

# 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/

CLI の出力

追加されたスキルの URI が返されます。例：

uri  viking://agent/skills/my-skill/

SKILL.md の形式

スキルでは、YAML フロントマターを含む 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
# 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

CLI の前提条件

• CLI が設定済みであること：~/.openviking/ovcli.conf
• スキルファイル（SKILL.md）が正しい Markdown 形式であること