OpenViking

RAG and semantic search via OpenViking Context Database MCP server. Query documents, search knowledge base, add files/URLs to vector memory. Use for document Q&A, knowledge management, AI agent memory, file search, semantic retrieval. Triggers on "openviking", "search documents", "semantic search", "knowledge base", "vector database", "RAG", "query pdf", "document query", "add resource".

Security Scan

The skill's requirements and instructions are internally consistent with a local RAG/vector DB setup that uses Volcengine/Ark keys; the main risks are installing/starting third‑party code and sending uploaded files to an external API — behaviour that matches its stated purpose.

Purpose & Capability

Name/description (RAG, semantic search, add resources) align with the instructions and files: the skill directs you to clone OpenViking, run its MCP server, and use it for queries, search, and adding resources. Requested resources (API keys for embeddings and LLM) are coherent with a hosted embedding/LLM backend.

Instruction Scope

SKILL.md stays on-scope: it instructs cloning the repo, creating ov.conf, starting a local server, and using MCP to query/add resources. It explicitly asks you to add local files/URLs to the knowledge base — which will cause those contents to be processed (embedded and sent to the configured external APIs). It does not instruct reading unrelated system files or harvesting credentials, but adding files can result in data leaving your machine (to Volcengine) which is expected for the feature.

Install Mechanism

There is no packaged install spec; the init script clones https://github.com/volcengine/OpenViking and runs 'uv sync'. Cloning a known GitHub repo is expected for this skill, but 'uv sync' will install project dependencies and may execute install hooks in the repository — a moderate install risk because arbitrary repo code will be placed on disk and later executed when you run the server.

Credentials

The skill does not declare environment variables in metadata, but SKILL.md/init.sh require you to provide Volcengine/Ark API keys in ov.conf (embedding.dense.api_key and vlm.api_key). Those credentials are directly necessary for embeddings/LLM calls. This is proportionate to the stated purpose, but these keys grant an external provider access to any content you add — treat them like sensitive credentials and do not reuse high-privilege keys.

Persistence & Privilege

The skill is not always-enabled and does not request system-wide privileges. It instructs creating files under the user's home (~/code/openviking) and running a local server bound to 127.0.0.1 by default. It does not modify other skills or global agent config automatically.

Assessment

This skill appears to do what it claims (run a local OpenViking MCP server and use Volcengine for embeddings/LLM). Before installing: 1) Review the GitHub repo and server.py in the cloned code to confirm you trust it; 'uv sync' may run install hooks. 2) Be aware that any local files or URLs you add will be sent to the configured Volcengine APIs — do not upload sensitive or regulated data unless you understand the provider's policy. 3) Protect the Ark API keys you add to ov.conf (use keys with minimal scope) and do not share them. 4) Consider running the server in an isolated environment (VM/container) if you want extra safety. If you need confirmation that the remote repo is unchanged, fetch its release signatures or inspect the code before running.

OpenViking - Context Database for AI Agents

OpenViking is ByteDance's open-source Context Database designed for AI Agents — a next-generation RAG system that replaces flat vector storage with a filesystem paradigm for managing memories, resources, and skills.

Key Features:

• Filesystem paradigm: Organize context like files with URIs (viking://resources/...)
• Tiered context (L0/L1/L2): Abstract → Overview → Full content, loaded on demand
• Directory recursive retrieval: Better accuracy than flat vector search
• MCP server included: Full RAG pipeline via Model Context Protocol

---

Quick Check: Is It Set Up?

test -f ~/code/openviking/examples/mcp-query/ov.conf && echo "Ready" || echo "Needs setup"
curl -s http://localhost:2033/mcp && echo "Running" || echo "Not running"

If Not Set Up → Initialize

Run the init script (one-time):

bash ~/.openclaw/skills/openviking-mcp/scripts/init.sh

This will:

1. Clone OpenViking from https://github.com/volcengine/OpenViking
2. Install dependencies with uv sync
3. Create ov.conf template
4. Pause for you to add API keys (embedding.dense.api_key, vlm.api_key)

Required: Volcengine/Ark API Keys

Config Key	Purpose
embedding.dense.api_key	Semantic search embeddings
vlm.api_key	LLM for answer generation

Get keys from: https://console.volcengine.com/ark

Start the Server

cd ~/code/openviking/examples/mcp-query
uv run server.py

Options:

• --port 2033 - Listen port
• --host 127.0.0.1 - Bind address
• --data ./data - Data directory

Server will be at: http://127.0.0.1:2033/mcp

Connect to Claude

claude mcp add --transport http openviking http://localhost:2033/mcp

Or add to ~/.mcp.json:

{
  "mcpServers": {
    "openviking": {
      "type": "http",
      "url": "http://localhost:2033/mcp"
    }
  }
}

Tools Available

Tool	Description
query	Full RAG pipeline — search + LLM answer
search	Semantic search only, returns docs
add_resource	Add files, directories, or URLs

Example Usage

Once connected via MCP:

"Query: What is OpenViking?"
"Search: machine learning papers"
"Add https://example.com/article to knowledge base"
"Add ~/documents/report.pdf"

Troubleshooting

Issue	Fix
Port in use	uv run server.py --port 2034
Auth errors	Check API keys in ov.conf
Server not found	Ensure it's running: curl localhost:2033/mcp

Files

• ov.conf - Configuration (API keys, models)
• data/ - Vector database storage
• server.py - MCP server implementation