Skip to content

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

docs: OpenViking Skills for search, add, operate (#510)

MaojiaShengd35152e4abf8
diff --git a/examples/skills/adding-memory/SKILL.md b/examples/skills/adding-memory/SKILL.md
deleted file mode 100644
index 5151733ac..000000000
--- a/examples/skills/adding-memory/SKILL.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-name: adding-memory
-description: Add memories, learnings and context to OpenViking, aka. ov. Use when saving insights in chat. Trigger this tool when 1. sees keyword "ovm"; 2. is explicitly requested memorizing e.g. "remember ..." 3. identifies valuable memory worth adding
-compatibility: configuration file at `~/.openviking/ovcli.conf`
----
-
-# 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.
-
-## 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
-
-## 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.
-
-### Mode 1: Plain Text for compressed memory
-
-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."
-```
-
-### Mode 2: Multi-turn Conversation for Richer Context
-
-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 ... >
-]'
-```
-
-## Output
-
-Returns count of memory extracted:
-
-```
-memories_extracted 1
-```
-
-## Agent Best Practices
-
-### 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
-
-### 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"}
-]'
-```
-
-## Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
diff --git a/examples/skills/adding-resource/SKILL.md b/examples/skills/adding-resource/SKILL.md
deleted file mode 100644
index 46c7656b3..000000000
--- a/examples/skills/adding-resource/SKILL.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-name: adding-resource
-description: Add resources to OpenViking, aka. ov. Use when an agent needs to add files, URLs, or external knowledge during interactions. Trigger this tool when 1. sees keyword "ovr"; 2. is explicitly requested adding files or knowledge; 3. identifies valuable resources worth importing
-compatibility: CLI configured at `~/.openviking/ovcli.conf`
----
-
-# 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.
-
-## 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
-
-## Input Options
-
-### Basic Usage
-
-Import a local file or URL:
-
-```bash
-# Import from URL
-ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md
-
-# Import local file
-ov add-resource ./docs/api-spec.md
-
-# Import local directory
-ov add-resource ./project-source
-```
-
-### Context and Instructions
-
-Add metadata to guide processing:
-
-```bash
-# Provide reason for import
-ov add-resource ./api-docs.md --reason "REST API documentation for v2 endpoints"
-
-# Add processing instructions
-ov add-resource ./large-repo --instruction "Focus on authentication and authorization patterns"
-
-# Combine reason and instruction
-ov add-resource https://example.com/guide --reason "User guide" --instruction "Extract best practices and examples"
-```
-
-### Async Processing Control
-
-Wait for semantic processing to complete:
-
-```bash
-# Wait until 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)
-ov add-resource ./docs
-```
-
-## Output
-
-Returns the root URI of the imported resource:
-
-```
-root_uri viking://resources/...
-```
-
-## Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
-- Network access for URL imports
-- Read permissions for local files/directories
diff --git a/examples/skills/ov-add-data/SKILL.md b/examples/skills/ov-add-data/SKILL.md
new file mode 100644
index 000000000..da385c2af
--- /dev/null
+++ b/examples/skills/ov-add-data/SKILL.md
@@ -0,0 +1,249 @@
+---
+name: ov-add-data
+description: This skill adds data(like resources) to OpenViking Context Database (aka. ov). Use when an agent needs to add files, data from URLs, or external knowledge during interactions. Trigger this tool when 1. is explicitly requested adding files or knowledge; 2. identifies valuable resources worth importing; 3. the user mentioned adding to OV/OpenViking/Context Database. This skill helps how to use CLI like `ov add-resource`, `ov add-skill` and `ov add-memory` to add resource data, skill files, memory files to OpenViking.
+compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf`
+---
+
+# 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.
+
+## 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
+
+## CLI Options
+
+### Basic Usage
+
+Import a local file or URL:
+
+```bash
+# 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项目设计文档/
+```
+
+### Context and Instructions (TBD)
+
+Add metadata to guide processing: --reason and --instruction will be supported in the future.
+
+### 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
+# 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/`.
+
+### Specify the target path
+
+By default, resources are imported under `viking://resources/`. Use `--to` or `--parent` to specify a target uri.
+
+```bash
+# 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 Output
+
+Returns the root URI of the imported resource, like:
+
+```
+root_uri viking://resources/2026/2026-01-01
+```
+
+## CLI Prerequisites
+
+- 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.
+
+# 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.
+
+## 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
+
+## 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.
+
+### Mode 1: Plain Text for compressed memory
+
+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."
+```
+
+### Mode 2: Multi-turn Conversation for Richer Context
+
+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 ... >
+]'
+```
+
+## Output
+
+Returns count of memory extracted:
+
+```
+memories_extracted 1
+```
+
+## Agent Best Practices
+
+### 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
+
+### 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"}
+]'
+```
+
+## Prerequisites
+
+- CLI configured: `~/.openviking/ovcli.conf`
+
+# 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.
+
+## 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
+
+## Input Formats
+
+### Mode 1: SKILL.md File
+
+Import from a single SKILL.md file with YAML frontmatter:
+
+```bash
+# 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 Options
+
+### Async Processing Control
+
+Semantic processing happens asynchronously. Use `--wait` to block until complete:
+
+```bash
+# 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 Output
+
+Returns the URI of the added skill, like:
+
+```
+uri viking://agent/skills/my-skill/
+```
+
+## SKILL.md Format
+
+Skills use Markdown with YAML frontmatter:
+
+```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 Prerequisites
+
+- CLI configured: `~/.openviking/ovcli.conf`
+- The skill file (SKILL.md) should be in the correct markdown format.
diff --git a/examples/skills/ov-search-context/SKILL.md b/examples/skills/ov-search-context/SKILL.md
new file mode 100644
index 000000000..de9a1e070
--- /dev/null
+++ b/examples/skills/ov-search-context/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: ov-search-context
+description: Search context data(memories, skills and resource) from OpenViking Context Database (aka. ov). Trigger this tool when 1. need information that might be stored as memories, skills or resources on OpenViking; 2. is explicitly requested searching files or knowledge; 3. sees `search context`, `search openviking`, `search ov` request.
+compatibility: CLI configured at `~/.openviking/ovcli.conf`
+---
+# OpenViking (OV) context searching
+The `ov search` command performs context-aware retrieval across all memories and resources in OpenViking — combining semantic understanding with directory recursive retrieval to find the most relevant context for any query.
+
+## Table of Content
+- When to Use
+- Sub-commands for search
+ - List directories (`ov ls`)
+ - Tree view (`ov tree`)
+ - Semantic Search (`ov find`)
+ - Content Pattern Search (`ov grep`)
+ - File Glob Search (`ov glob`)
+ - Full content read (`ov read`)
+ - Get overview (`ov overview`)
+ - Get Abstract (`ov abstract`)
+- Prerequisite
+
+## When to Use
+
+- Finding specific information within imported resources or saved memories
+- Retrieving context about topics, APIs, or patterns previously added
+- Searching across project documentation, code, and learnings
+- When an agent needs to reference previously stored knowledge
+
+> note: cli command can be outdated, when sees error, use `--help` to get latest usage
+
+## Sub-commands for search
+
+### List Contents (`ov ls`)
+
+Browse directory structure:
+
+```bash
+# List root directory
+ov ls
+
+# List specific directory
+ov ls viking://resources/my-project/docs/
+
+# Simple path output (only uris, no metadata)
+ov ls viking://resources --simple
+
+# Show hidden files
+ov ls viking://resources --all
+
+# Control output limits (default 256)
+ov ls viking://resources --node-limit 50
+
+# Control abstract info length limit for each node (default 256)
+ov ls viking://resources --abs-limit 128
+```
+
+### Tree View (`ov tree`)
+
+Visualize directory hierarchy:
+
+```bash
+# Show tree structure
+ov tree viking://resources
+
+# Control depth limits (default 3)
+ov tree viking://resources --level-limit 2
+
+# Control node limits
+ov tree viking://resources --node-limit 100 --abs-limit 128
+
+# Show all files including hidden
+ov tree viking://resources --all
+```
+
+### Semantic find (`ov find`)
+
+Find method with semantic relevance ranking:
+
+```bash
+# Basic find across all context
+ov find "how to handle API rate limits"
+
+# Find within specific URI scope
+ov find "authentication flow" --uri "viking://resources/my-project"
+
+# Limit results and set relevance score threshold
+ov find "error handling" --node-limit 5 --threshold 0.3
+```
+
+### Content Pattern Search (`ov grep`)
+
+Literal pattern matching:
+
+```bash
+# Find exact text pattern (Note: this is expensive, and suggest within specific small URI scope)
+ov grep "viking://resources" "TODO:" --uri "viking://resources/my-project"
+
+# Case-insensitive search
+ov grep "viking://resources" "API_KEY" --ignore-case --uri "viking://resources/my-project"
+
+# Limit results and set node limit
+ov grep "viking://resources" "API_KEY" --node-limit 5 --uri "viking://resources/my-project"
+```
+
+### File Glob Search (`ov glob`)
+
+File path pattern matching:
+
+```bash
+# Find all markdown files (Note: this is expensive, and suggest within specific small URI scope)
+ov glob "**/*.md" --uri "viking://resources/my-project"
+
+# Limit results and set node limit
+ov glob "**/*.md" --uri "viking://resources/my-project" --node-limit 5
+```
+
+### Read File Content (`ov read`)
+
+Retrieve full content (L0-L2 layer):
+
+```bash
+# Read full content
+ov read viking://resources/docs/api/api-1.md
+
+# Read first 10 lines of api-2.md
+ov read viking://resources/docs/api/api-2.md | head -n 10
+
+# Read abstract (L0 - quick summary)
+ov abstract viking://resources/docs/api/
+ov read viking://resources/docs/api/.abstract.md
+
+# Read overview (L1 - key points)
+ov overview viking://resources/docs/api/
+ov read viking://resources/docs/api/.overview.md
+```
+
+### Combining Search
+
+Use search results to guide further actions:
+
+```bash
+ov ls viking://resources/
+
+# Search for relevant files
+ov search "authentication" --uri "viking://resources/project-A"
+
+# Get overview for context
+ov overview viking://resources/project-A/backend
+
+# Decide to read specific content
+ov read viking://resources/project-A/backend/auth.md
+```
+
+## Prerequisites
+
+- CLI configured: `~/.openviking/ovcli.conf`
+- Resources or memories previously added to OpenViking
diff --git a/examples/skills/ov-server-operate/SKILL.md b/examples/skills/ov-server-operate/SKILL.md
new file mode 100644
index 000000000..03a7d4811
--- /dev/null
+++ b/examples/skills/ov-server-operate/SKILL.md
@@ -0,0 +1,440 @@
+---
+name: ov-server-operate
+description: Operate and maintain OpenViking server - configure, install, start, stop, and cleanup the server. Use when need to setup or manage OpenViking service deployment.
+compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf`
+---
+
+# OpenViking Server Operations
+
+This guide provides standard operating procedures for deploying, managing, and maintaining OpenViking servers in production environments.
+
+## Table of Content
+- Service Configuration
+- Environment Setup with uv
+- Server Startup with nohup
+- Server Shutdown
+- Data Cleanup Procedure
+- Verification and Troubleshooting
+
+## Service Configuration
+
+### Default Paths and Structure
+
+OpenViking uses the following standard directory structure under `~/.openviking/`:
+
+```
+~/.openviking/
+├── ov.conf # Server configuration (required)
+├── ovcli.conf # CLI client configuration
+├── ov-venv/ # Virtual environment (created by uv)
+├── log/ # Server log directory
+│ ├── openviking-server.log # server stdout log
+│ └── openviking.log # server log
+└── data/ # Workspace data (configured in ov.conf)
+ ├── ...
+ └── ...
+```
+
+### Configuration Files
+
+#### 1. Server Config (`~/.openviking/ov.conf`)
+
+Create the configuration file with at minimum the following configuration.
+Note 1: Replace the api-key with your own api-key. If you don't have one, ask the user to get one (follow the Volcengine Ark platform guide).
+Note 2: Replace the root_api_key with your own root-api-key. Ask the user to set one — it will be used for authentication when the CLI connects to the server.
+
+```json
+{
+ "server": {
+ "host": "0.0.0.0",
+ "port": 1933,
+ "root_api_key": "your-root-api-key"
+ },
+ "storage": {
+ "workspace": "~/.openviking/data/"
+ },
+ "parsers": {
+ "code": {
+ "gitlab_domains": ["code.byted.org"]
+ }
+ },
+ "embedding": {
+ "dense": {
+ "model": "doubao-embedding-vision-250615",
+ "api_key": "your-volcengine-api-key",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "dimension": 1024,
+ "input": "multimodal",
+ "provider": "volcengine"
+ }
+ },
+ "vlm": {
+ "model": "doubao-seed-1-8-251228",
+ "api_key": "your-volcengine-api-key",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "temperature": 0.0,
+ "max_retries": 2,
+ "provider": "volcengine",
+ "thinking": false
+ },
+ "log": {
+ "level": "INFO",
+ "output": "file",
+ "rotation": true,
+ "rotation_days": 3,
+ "rotation_interval": "midnight"
+ }
+}
+```
+
+#### 2. CLI Config (`~/.openviking/ovcli.conf`)
+
+For client connections from localhost:
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "your-root-api-key"
+}
+```
+
+For remote connections, set the url to the remote server address (for example, the server EIP).
+
+## Environment Setup with uv
+
+### Step 1: Install uv (if not already installed)
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Verify installation
+uv --version
+```
+
+### Step 2: Create Virtual Environment
+
+Create a dedicated virtual environment at `~/.openviking/ov-venv`:
+
+```bash
+# Create venv with Python 3.10+
+cd ~/.openviking
+uv venv --python 3.12 ov-venv
+```
+
+### Step 3: Activate and Install OpenViking
+
+```bash
+# Activate the virtual environment
+source ~/.openviking/ov-venv/bin/activate
+
+# Install or upgrade to latest openviking
+uv pip install --upgrade openviking --force-reinstall
+
+# Verify installation
+which openviking-server
+openviking-server --version
+openviking-server --help
+```
+
+### Step 4: Create Log Directory
+
+```bash
+mkdir -p ~/.openviking/log
+```
+
+## Server Startup with nohup
+
+### Standard Startup Procedure
+
+```bash
+# 1. Activate the virtual environment
+source ~/.openviking/ov-venv/bin/activate
+
+# 2. Ensure log directory exists
+mkdir -p ~/.openviking/log
+
+# 3. Start server with nohup
+nohup openviking-server \
+ > ~/.openviking/log/openviking-server.log 2>&1 &
+
+# 4. Save PID for later reference
+echo $! > ~/.openviking/server.pid
+
+# 5. Verify startup after 10 secs
+sleep 10
+curl -s http://localhost:1933/health
+```
+
+### Verify Server is Running
+
+```bash
+# Method 1: Check health endpoint
+curl http://localhost:1933/health
+# Expected: {"status": "ok"}
+
+# Method 2: Check readiness (includes storage checks)
+curl http://localhost:1933/ready
+
+# Method 3: Check process
+ps aux | grep openviking-server | grep -v grep
+
+# Method 4: Check log output
+tail -10 ~/.openviking/log/openviking-server.log
+tail -50 ~/.openviking/log/openviking.log
+```
+
+## Server Shutdown
+
+### Graceful Shutdown Procedure
+
+```bash
+# 1. Find the server process
+ps aux | grep openviking-server | grep -v grep
+
+# 2. Send SIGTERM for graceful shutdown
+# Option A: Using saved PID
+if [ -f ~/.openviking/server.pid ]; then
+ kill $(cat ~/.openviking/server.pid)
+ rm ~/.openviking/server.pid
+fi
+
+# Option B: Using pgrep
+pkill -f openviking-server
+
+# 3. Wait for process to stop
+sleep 3
+
+# 4. Verify it stopped
+ps aux | grep openviking-server | grep -v grep || echo "Server stopped successfully"
+
+# 5. If still running, force kill
+if pgrep -f openviking-server > /dev/null; then
+ echo "Force killing server..."
+ pkill -9 -f openviking-server
+fi
+```
+
+## Data Cleanup Procedure
+
+### When to Use This Procedure
+
+Perform full data cleanup in these scenarios:
+1. Version upgrade with incompatible data format
+2. Corrupted or inconsistent data
+3. Need to reset to fresh state
+4. Storage space reclamation
+
+### Standard Cleanup Workflow
+
+**CRITICAL: ALWAYS BACKUP BEFORE DELETING DATA**
+
+```bash
+# ==========================================
+# STEP 1: STOP THE SERVER FIRST
+# ==========================================
+echo "Step 1: Stopping OpenViking Server..."
+if pgrep -f openviking-server > /dev/null; then
+ pkill -f openviking-server
+ sleep 3
+ if pgrep -f openviking-server > /dev/null; then
+ pkill -9 -f openviking-server
+ sleep 1
+ fi
+fi
+
+# Verify server is stopped
+if pgrep -f openviking-server > /dev/null; then
+ echo "ERROR: Server still running! Cannot proceed."
+ exit 1
+fi
+echo "✓ Server stopped"
+
+# ==========================================
+# STEP 2: CREATE BACKUP (REQUIRED)
+# ==========================================
+echo ""
+echo "Step 2: Creating backup..."
+BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR=~/.openviking/backup_${BACKUP_DATE}
+
+mkdir -p ${BACKUP_DIR}
+
+# Backup config files
+cp ~/.openviking/ov.conf ${BACKUP_DIR}/ 2>/dev/null || true
+cp ~/.openviking/ovcli.conf ${BACKUP_DIR}/ 2>/dev/null || true
+
+# Backup workspace (if exists)
+WORKSPACE=$(python3 -c '
+import json
+import os
+config_path = os.path.expanduser("~/.openviking/ov.conf")
+if os.path.exists(config_path):
+ with open(config_path) as f:
+ cfg = json.load(f)
+ ws = cfg.get("storage", {}).get("workspace", "./data")
+ print(os.path.expanduser(ws))
+' 2>/dev/null || echo "~/.openviking/data")
+
+if [ -d "${WORKSPACE}" ]; then
+ echo "Backing up workspace: ${WORKSPACE}"
+ tar -czf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE}) $(basename ${WORKSPACE})
+fi
+
+# Backup log
+if [ -d ~/.openviking/log ]; then
+ cp -r ~/.openviking/log ${BACKUP_DIR}/ 2>/dev/null || true
+fi
+
+echo "✓ Backup created at: ${BACKUP_DIR}"
+ls -lh ${BACKUP_DIR}/
+
+# ==========================================
+# STEP 3: CONFIRM DELETION
+# ==========================================
+echo ""
+echo "=========================================="
+echo "WARNING: ABOUT TO DELETE ALL DATA!"
+echo "=========================================="
+echo "Workspace to delete: ${WORKSPACE}"
+echo "Backup location: ${BACKUP_DIR}"
+echo ""
+read -p "Type 'DELETE' to confirm data removal: " CONFIRM
+
+if [ "${CONFIRM}" != "DELETE" ]; then
+ echo "Cleanup cancelled. Backup preserved at ${BACKUP_DIR}"
+ exit 0
+fi
+
+# ==========================================
+# STEP 4: DELETE DATA
+# ==========================================
+echo ""
+echo "Step 4: Deleting data..."
+
+# Delete workspace
+if [ -d "${WORKSPACE}" ]; then
+ echo "Deleting workspace: ${WORKSPACE}"
+ rm -rf "${WORKSPACE}"
+fi
+
+# Optional: Delete old log (uncomment if needed)
+# echo "Deleting old log..."
+# rm -rf ~/.openviking/log/*
+
+# Cleanup any temporary files
+rm -f ~/.openviking/server.pid
+
+echo "✓ Data deleted successfully"
+
+# ==========================================
+# STEP 5: COMPLETION
+# ==========================================
+echo ""
+echo "=========================================="
+echo "Cleanup Complete!"
+echo "=========================================="
+echo "Backup preserved at: ${BACKUP_DIR}"
+echo ""
+echo "Next steps:"
+echo "1. Reconfigure ov.conf if needed"
+echo "2. Start the server: openviking-server"
+echo "3. Verify with: curl http://localhost:1933/health"
+echo ""
+echo "To restore from backup:"
+echo " tar -xzf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE})"
+```
+
+### Quick Cleanup (for Development Only)
+
+```bash
+# WARNING: Only use in development!
+# No backup created - data loss guaranteed!
+
+# 1. Stop server
+pkill -f openviking-server
+sleep 2
+pkill -9 -f openviking-server 2>/dev/null || true
+
+# 2. Delete workspace (adjust path as needed)
+rm -rf ~/.openviking/data
+
+# 3. Cleanup PID and temp files
+rm -f ~/.openviking/server.pid
+
+echo "Quick cleanup complete"
+```
+
+## Verification and Troubleshooting
+
+### Health Check Verification
+
+```bash
+# Basic health check (always available)
+curl http://localhost:1933/health
+# Expected: {"status": "ok"}
+
+# Readiness check (verifies all components)
+curl http://localhost:1933/ready
+# Expected: {"status": "ready", "checks": {"agfs": "ok", "vectordb": "ok", "api_key_manager": "ok"}}
+
+# System status via CLI (~/.openviking/ovcli.conf should be configured)
+ov status
+```
+
+### Common Issues and Solutions
+
+#### Issue: Server won't start
+
+**Check:**
+```bash
+# 1. Check if port is in use
+lsof -i :1933
+netstat -tulpn | grep 1933
+
+# 2. Check log for errors
+tail -10 ~/.openviking/log/openviking-server.log
+tail -100 ~/.openviking/log/openviking.log
+
+
+# 3. Verify config file is valid JSON
+python3 -c 'import json, os; json.load(open(os.path.expanduser("~/.openviking/ov.conf"))); print("Config is valid")'
+
+# 4. Verify virtual environment
+source ~/.openviking/ov-venv/bin/activate
+which openviking-server
+pip list | grep openviking
+```
+
+**Solution:**
+```bash
+# If port conflict: kill the process or use different port
+lsof -ti :1933 | xargs kill -9 2>/dev/null || true
+
+# Or start on different port
+nohup openviking-server --port 1934 > ~/.openviking/log/openviking-server.log 2>&1 &
+```
+
+#### Issue: API Key Errors
+
+**Check:**
+```bash
+# Verify API keys in config
+python3 -c '
+import json, os
+cfg = json.load(open(os.path.expanduser("~/.openviking/ov.conf")))
+print("Embedding provider:", cfg.get("embedding", {}).get("dense", {}).get("provider"))
+print("VLM provider:", cfg.get("vlm", {}).get("provider"))
+print("API keys set:", bool(cfg.get("embedding", {}).get("dense", {}).get("api_key")), bool(cfg.get("vlm", {}).get("api_key")))
+'
+```
+
+**Solution:** Verify API keys are correct and have the required permissions. Check network connectivity to the model provider endpoints. Ensure API keys are not expired.
+
+## Prerequisites
+
+- Python 3.10+ installed
+- uv package manager available
+- Sufficient disk space for workspace and log
+- API keys for embedding and VLM models configured
+- Network access to model providers (if using cloud models)
diff --git a/examples/skills/searching-context/SKILL.md b/examples/skills/searching-context/SKILL.md
deleted file mode 100644
index 0b5e6c5e1..000000000
--- a/examples/skills/searching-context/SKILL.md
+++ /dev/null
@@ -1,225 +0,0 @@
----
-name: searching-context
-description: Search memories and resource context from OpenViking, aka. ov. Trigger this tool when 1. sees keyword "ovs"; 2. is explicitly requested searching files or knowledge; 3. sees `search context` request
-compatibility: CLI configured at `~/.openviking/ovcli.conf`
----
-# OpenViking (OV) context searching
-The `ov search` command performs context-aware retrieval across all memories and resources in OpenViking — combining semantic understanding with directory recursive retrieval to find the most relevant context for any query.
-
-## Table of Content
-- When to Use
-- Search Modes
- - Context-Aware Search (`ov search`)
- - Content Pattern Search (`ov grep`)
- - File Glob Search (`ov glob`)
-- Search Options
- - Result Control
- - Scope Control
- - Session-Aware Search
-- Output
-- Other Utilities
- - List Contents (`ov ls`)
- - Tree View (`ov tree`)
- - Read File Content (`ov read`)
-- Agent Best Practices
- - Choosing Search Methods
- - Query Formulation
- - Combining with Other Commands
-- Prerequisite
-
-## When to Use
-
-- Finding specific information within imported resources or saved memories
-- Retrieving context about topics, APIs, or patterns previously added
-- Searching across project documentation, code, and learnings
-- When an agent needs to reference previously stored knowledge
-
-> note: cli command can be outdated, when sees error, use `--help` to get latest usage
-
-## Search Modes
-
-### Context-Aware Search (`ov search`)
-
-Primary search method with session context awareness:
-
-```bash
-# Basic search across all context
-ov search "how to handle API rate limits"
-
-# Search within specific URI scope
-ov search "authentication flow" --uri "viking://resources/my-project"
-
-# Limit results and set threshold
-ov search "error handling" --limit 5 --threshold 0.7
-```
-
-### Content Pattern Search (`ov grep`)
-
-Literal pattern matching:
-
-```bash
-# Search for exact text pattern
-ov grep "viking://resources" "TODO:"
-
-# Case-insensitive search
-ov grep "viking://resources" "API_KEY" --ignore-case
-```
-
-### File Glob Search (`ov glob`)
-
-File path pattern matching:
-
-```bash
-# Find all markdown files
-ov glob "**/*.md"
-
-# Find Python files in specific directory
-ov glob --uri="viking://user/" "**/*.md"
-```
-
-## Search Options
-
-### Result Control
-
-```bash
-# Limit number of results
-ov search "authentication" --limit 5
-
-# Set minimum relevance threshold (0.0-1.0)
-ov search "deployment" --threshold 0.8
-
-# Combine limit and threshold
-ov search "monitoring" --limit 10 --threshold 0.7
-```
-
-### Scope Control
-
-```bash
-# Search specific directory
-ov search "API design" --uri "viking://resources/xxx"
-
-# Search within memories
-ov search "user habits" --uri "viking://user/memories"
-```
-
-### Session-Aware Search
-
-```bash
-# Search with session context (uses conversation history for better retrieval)
-ov search "previous decision" --session-id "session-abc123"
-```
-
-## Output
-
-Returns a ranked list of matching resources with relevance scores:
-
-```
-URI: viking://resources/docs/api.md
-Score: 0.8523
-Abstract: API endpoints for user authentication...
-
-URI: viking://user/memories/preferences
-Score: 0.7891
-Abstract: User prefers dark mode and compact layout...
-```
-
-## Other Utilities
-
-### List Contents (`ov ls`)
-
-Browse directory structure:
-
-```bash
-# List root directory
-ov ls
-
-# List specific directory
-ov ls viking://resources/my-project
-
-# Simple path output (for scripts)
-ov ls viking://resources --simple
-
-# Recursive listing
-ov ls viking://resources --recursive
-
-# Show hidden files
-ov ls viking://resources --all
-
-# Control output limits
-ov ls viking://resources --node-limit 50 --abs-limit 128
-```
-
-### Tree View (`ov tree`)
-
-Visualize directory hierarchy:
-
-```bash
-# Show tree structure
-ov tree viking://resources
-
-# Control depth and limits
-ov tree viking://resources --node-limit 100 --abs-limit 128
-
-# Show all files including hidden
-ov tree viking://resources --all
-```
-
-### Read File Content (`ov read`)
-
-Retrieve full content (L2 layer):
-
-```bash
-# Read full content
-ov read viking://resources/docs/api.md
-
-# Read abstract (L0 - quick summary)
-ov abstract viking://resources/docs/api.md
-
-# Read overview (L1 - key points)
-ov overview viking://resources/docs/api.md
-```
-
-## Agent Best Practices
-
-### Choosing Search Methods
-
-- **`ov search`** — Default choice. Context-aware, combines semantic + directory recursive retrieval
-- **`ov grep`** — Exact text pattern matching (like `grep` command)
-- **`ov glob`** — File path pattern matching (like shell glob)
-
-### Query Formulation
-
-Write specific, contextual queries:
-
-```bash
-# Too vague
-ov search "API"
-
-# Better
-ov search "REST API authentication with JWT tokens"
-
-# Even better with scope
-ov search "JWT token refresh flow" --uri "viking://resources/backend"
-```
-
-### Combining with Other Commands
-
-Use search results to guide further actions:
-
-```bash
-ov ls viking://resources/
-
-# Search for relevant files
-ov search "authentication" --uri "viking://resources/xxx"
-
-# Then read specific content
-ov read viking://resources/backend/auth.md
-
-# Or get overview for context
-ov overview viking://resources/backend
-```
-
-## Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
-- Resources or memories previously added to OpenViking
diff --git a/examples/skills/tests.md b/examples/skills/tests.md
deleted file mode 100644
index e0086dd1f..000000000
--- a/examples/skills/tests.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# Memory Skill Test Cases
-
-## T1: Profile — Basic Identity
-**Conversation:**
-1. `我叫张明,在字节跳动做后端开发,base北京`
-2. `ovm`
-
-**Eval search:** "张明是谁"
-**Expected memory:**
-- `profile`: name=张明, role=后端开发, company=字节跳动, location=北京
-
----
-
-## T2: Profile — Incremental Update (Merge)
-**Conversation:**
-1. `我叫张明,做后端开发`
-2. `ovm`
-3. `最近转岗了,现在做 infra`
-4. `ovm`
-
-**Eval search:** "张明做什么工作"
-**Expected memory:**
-- `profile`: role updated to infra (merged, not duplicated)
-
----
-
-## T3: Preferences
-**Conversation:**
-1. `写代码的时候我习惯用 vim + tmux,不喜欢 IDE`
-2. `回复我的时候用中文就好,技术术语保持英文`
-3. `ovm`
-
-**Eval search:** "用户开发工具偏好"
-**Expected memories:**
-- `preferences`: editor=vim+tmux, anti-preference=IDE
-- `preferences`: language=中文为主, technical terms in English
-
----
-
-## T4: Entities — People & Projects
-**Conversation:**
-1. `我们组的 tech lead 是 Kevin,他主推用 Go 重写网关`
-2. `目前在做 Project Atlas,是一个内部 API 网关平台`
-3. `ovm`
-
-**Eval search:** "Kevin" / "Project Atlas"
-**Expected memories:**
-- `entities`: person Kevin, role=tech lead, advocates Go rewrite
-- `entities`: project Atlas, type=内部API网关平台
-
----
-
-## T5: Events — Decision Point
-**Conversation:**
-1. `今天和老板聊了,决定放弃 Python 方案,全面转 Go`
-2. `主要原因是性能瓶颈和团队技术栈统一`
-3. `ovm`
-
-**Eval search:** "为什么选 Go"
-**Expected memory:**
-- `events`: decision=弃Python转Go, reason=性能+技术栈统一, date=today
-
----
-
-## T6: Cases — Problem → Solution
-**Conversation:**
-1. `我们的 gRPC 服务偶尔出现 deadline exceeded,大概每天几十次`
-2. `查了 trace 发现是下游 Redis 偶尔 latency spike`
-3. `试了连接池调大没用,最后发现是 Redis cluster 有个慢节点`
-4. `把那个节点摘掉换了新实例就好了`
-5. `ovm`
-
-**Eval search:** "gRPC deadline exceeded 怎么解决"
-**Expected memory:**
-- `cases`: problem=gRPC deadline exceeded, root_cause=Redis慢节点, solution=替换节点, investigation_path=[trace→Redis latency→连接池排除→慢节点定位]
-
----
-
-## T7: Patterns — Reusable Practice
-**Conversation:**
-1. `我发现做 code review 有个好办法`
-2. `先看测试理解意图,再看 diff,最后跑一遍确认`
-3. `这样比直接看 diff 效率高很多,漏的也少`
-4. `ovm`
-
-**Eval search:** "code review 方法"
-**Expected memory:**
-- `patterns`: code review流程=测试→diff→运行验证, benefit=高效+低遗漏
-
----
-
-## T8: Patterns — Merge Existing
-**Conversation (session A):**
-1. `部署前一定要先跑 smoke test`
-2. `ovm`
-
-**Conversation (session B):**
-1. `部署前除了 smoke test,还要检查 config diff`
-2. `ovm`
-
-**Eval search:** "部署前检查"
-**Expected memory:**
-- `patterns`: pre-deploy checklist=[smoke test, config diff] (merged)
-
----
-
-## T9: Complex Multi-Round — Mixed Categories
-**Conversation:**
-1. `我在做一个 RAG 系统的 chunk 策略优化`
-2. `现在用的是固定 512 token 切分,效果不好`
-3. `我试了 semantic chunking,用 embedding similarity 找分割点`
-4. `同事 Lisa 建议试 late chunking,她在另一个项目上效果不错`
-5. `最后我们决定用 semantic chunking + overlap 50 token 的方案`
-6. `关键 insight 是:chunk boundary 要对齐语义边界,不能硬切`
-7. `以后做 RAG 都应该先评估 chunk 质量再调 retrieval`
-8. `ovm`
-
-**Eval search:** "RAG chunking 怎么做" / "Lisa" / "chunk 优化经验"
-**Expected memories:**
-- `events`: decision=semantic chunking + 50 token overlap, rejected=固定512切分
-- `entities`: person Lisa, context=推荐late chunking
-- `cases`: problem=固定chunk效果差, solution=semantic chunking+overlap
-- `patterns`: RAG best practice=先评估chunk质量再调retrieval, chunk应对齐语义边界
-
----
-
-## T10: Noise Resistance — Should NOT Store
-**Conversation:**
-1. `今天天气不错`
-2. `帮我写个 hello world`
-3. `谢谢,挺好的`
-4. `ovm`
-
-**Eval search:** "天气" / "hello world"
-**Expected memory:** **None** (no meaningful memory to extract)
-
----
-
-## Coverage Matrix
-
-| Test | profile | preferences | entities | events | cases | patterns | merge |
-|------|---------|-------------|----------|--------|-------|----------|-------|
-| T1 | x | | | | | | |
-| T2 | x | | | | | | x |
-| T3 | | x | | | | | |
-| T4 | | | x | | | | |
-| T5 | | | | x | | | |
-| T6 | | | | | x | | |
-| T7 | | | | | | x | |
-| T8 | | | | | | x | x |
-| T9 | | | x | x | x | x | |
-| T10 | | | | | | | noise |
-
-**Key properties tested:**
-- Single-category extraction (T1-T7)
-- Merge behavior on mergeable categories (T2, T8)
-- Multi-category extraction from one conversation (T9)
-- Noise resistance — no spurious memories (T10)
-- Non-mergeable uniqueness — events/cases create new entries, not merge (T5, T6)
-
diff --git a/openviking/models/embedder/volcengine_embedders.py b/openviking/models/embedder/volcengine_embedders.py
index a7c1b677a..aa22169b5 100644
--- a/openviking/models/embedder/volcengine_embedders.py
+++ b/openviking/models/embedder/volcengine_embedders.py
@@ -13,6 +13,7 @@ from openviking.models.embedder.base import (
SparseEmbedderBase,
truncate_and_normalize,
)
+from openviking_cli.utils.logger import default_logger as logger
def process_sparse_embedding(sparse_data: Any) -> Dict[str, float]:
@@ -164,6 +165,9 @@ class VolcengineDenseEmbedder(DenseEmbedderBase):
for item in data
]
except Exception as e:
+ logger.error(
+ f"Volcengine batch embedding failed, texts length: {len(texts)}, input_type: {self.input_type}, model_name: {self.model_name}"
+ )
raise RuntimeError(f"Volcengine batch embedding failed: {str(e)}") from e
def get_dimension(self) -> int: