OpenViking

What It Does

OpenViking is an open-source context database for AI agents, built by ByteDance's volcengine team. It solves a problem that every production agent faces: managing the growing body of context (memories, knowledge resources, and skills) that an agent needs across sessions and tasks. Instead of scattering this context across vector databases, prompt files, and skill directories, OpenViking unifies it under a filesystem paradigm where everything lives at a viking:// URI and is organized in a directory tree with three tiers of content (L0 abstract for fast scanning, L1 overview for parameter-level detail, L2 full content for deep reads). The system provides semantic search with recursive directory traversal (combining directory positioning with vector retrieval), automatic session-to-memory extraction (turns conversation transcripts into long-term memories), and a code intelligence layer using tree-sitter parsers for 10 languages. It exposes 16 MCP tools (find, search, recall, read, list, remember, add_resource, list_watches, cancel_watch, grep, glob, forget, code_outline, code_search, code_expand, health) and ships first-party integrations for Hermes Agent, Claude Code, OpenClaw, Codex, Cursor, Trae, OpenCode, LangChain/LangGraph, and any MCP-compatible client. The target users are developers and teams building agent applications who need persistent, searchable, observable context management.

The Good

The skill system is properly engineered with strict validation, privacy extraction, and Zip Slip-protected installation. The SkillLoader (openviking/core/skill_loader.py, 79 lines) enforces YAML frontmatter with required name and description fields, parses allowed-tools and tags, and rejects invalid input with specific error messages. The SkillProcessor (openviking/utils/skill_processor.py, 600 lines) adds name validation (ASCII alphanumeric plus hyphens and underscores, max 64 characters), L0/L1/L2 content generation for progressive loading, a privacy module that uses LLM extraction to identify and placeholderize sensitive values in skill content before storage, and safe skill installation from files, directories, zip archives, and URLs. The safe_extract_zip() function in openviking/utils/zip_safe.py validates every member path against Zip Slip attacks by resolving against the destination directory and rejecting traversal, absolute paths, and Windows drive prefixes. I verified this directly: both ../../../etc/passwd and /etc/passwd are rejected with ValueError("Zip Slip attempt detected: ..."). This is the same caliber of security engineering seen in DeerFlow's SkillScan and CowAgent's SSRF protections.

The benchmark results are real, specific, and compare against named alternatives. On the LoCoMo long-conversation benchmark, adding OpenViking to Hermes Agent improved QA accuracy from 33.38 percent to 82.86 percent (a 2.48x improvement) while reducing query latency by 66 percent and token consumption by 34 percent. With Claude Code, accuracy went from 57.21 percent to 80.32 percent with a 63 percent token reduction. On HotpotQA (multi-hop RAG), OpenViking at top-20 reached 91 percent accuracy at 0.23 seconds per query, beating LightRAG (89 percent at 75 seconds) and HippoRAG 2 (61 percent at 20 seconds). On tau2-bench (agent experience memory), the experience memory module improved retail task success by 6.87 percentage points and airline by 11.87 percentage points. These are not vague claims. They are reproducible benchmarks with methodology documented in the benchmark/ directory (locomo, tau2, hotpotqa, longmemeval, vectordb_perf, skillsbench).

The MCP endpoint ships 16 tools covering memory, search, resources, skills, code intelligence, and filesystem operations. The mcp_endpoint.py (975 lines) implements a full MCP server with OAuth2 support, tool registration via the @mcp.tool() decorator, and tools for semantic search (find, search), memory management (recall, remember, forget), content access (read, list), resource and skill import (add_resource), file operations (grep, glob), code intelligence (code_outline, code_search, code_expand), watch management (list_watches, cancel_watch), and health checking. The MCP converter (mcp_converter.py) can ingest any MCP tool definition and convert it into the SKILL.md format, so external MCP servers can be imported as skills. This is a genuine two-way skill/MCP bridge, not a one-shot import.

The ecosystem integration is the broadest of any context database GearScope has reviewed. OpenViking has native first-party support for Hermes Agent (built-in memory provider, configured with hermes memory setup), Claude Code (marketplace plugin with auto-recall and auto-capture hooks), OpenClaw (plugin with 12+ tools including memory_recall, memory_store, memory_forget, ov_search, ov_read, ov_archive_search, add_resource, add_skill), Codex (memory plugin), Cursor, Trae, OpenCode, LangChain/LangGraph, and any generic MCP client. There are SDKs in Python, Go, and TypeScript, each with skill management methods (AddSkill, ListSkills). The .claude-plugin/marketplace.json registers the openviking-memory plugin for Claude Code's plugin system. The examples/ directory contains 20 integration subdirectories with working code for each platform.

The documentation is extensive, bilingual, and production-oriented. The README is 36KB with architecture diagrams, benchmark tables, quick-start guides, and troubleshooting. The docs/en/ directory has 30-plus markdown files covering architecture, context types, API reference (resources, filesystem, skills, sessions, retrieval, system, admin, metrics, privacy, snapshot), agent integrations (13 platforms), guides (deployment, authentication, MCP integration, public access), and a changelog and roadmap. The Chinese and Japanese READMEs are full translations, not stubs. The install-openviking-memory skill for OpenClaw is a 34,122-character step-by-step installation guide with decision matrices, error recovery tables, and multi-tenant root-key handling, written to be followed by an agent.

The Bad

The AGPL-3.0 license is a significant constraint for commercial use. AGPL-3.0 requires that any modified version distributed over a network (including SaaS) must make the full source code available under the same license. For a company building a proprietary agent platform that uses OpenViking as a backend context store, this creates a compliance burden. Compare this to the MIT or Apache-2.0 licenses used by DeerFlow, CowAgent, FastMCP, and the Microsoft Playwright MCP. The ByteDance team likely chose AGPL to prevent cloud providers from offering OpenViking as a managed service without contributing back, but it limits adoption for proprietary deployments.

The build and dependency footprint is heavy. The pyproject.toml lists 50-plus direct dependencies including volcengine>=1.0.216, volcengine-python-sdk[ark]>=5.0.3, litellm>=1.83.7,<1.91.2, scrapy>=2.11.0, 10 tree-sitter language parsers, OpenTelemetry, apscheduler, and document parsers for PDF, DOCX, PPTX, XLSX, EPUB. Building from source requires Python 3.10+, a Rust toolchain (Cargo), and a C++ compiler (GCC 9+ or Clang 11+) for the native vector index. The uv.lock file is 1.3MB. On a clean macOS host, I could test the skill loader and MCP converter by installing pyyaml and pydantic, but exercising the full server requires compiling the Rust CLI and installing the entire dependency chain, which takes significant time and disk space.

307 open issues and the "Development Status :: 3 - Alpha" classifier signal that this is still maturing. The pyproject.toml classifies the project as Development Status :: 3 - Alpha, which is honest but worth noting. At 26,566 stars and six months of active development (created 2026-01-05, 60 releases through v0.4.9), the project is moving fast, but the issue count suggests rough edges in production use. The API is likely to change between minor versions, and the SDKs may lag behind the server.

The Chinese ecosystem bias is present but not blocking. The primary community channels are Lark Group and WeChat (Discord and X exist but are secondary). Some features reference VolcEngine Cloud (the ByteDance cloud arm) as the managed service backend. The bot/workspace/skills/github-proxy skill exists specifically to accelerate GitHub access from within China. The volcengine SDK dependency pulls in ByteDance-specific authentication and configuration. Non-Chinese users can use the self-hosted server with any LLM provider (OpenAI, Claude, local models via litellm), but the default experience and documentation depth favor the Chinese ecosystem.

Skills are context artifacts, not standalone executable units. Like CowAgent, OpenViking skills are stored in the context database and injected into agent prompts at retrieval time. They are not independently executable scripts or standalone MCP tools. The SkillLoader parses SKILL.md files and the SkillProcessor stores them under viking://user/skills/ with L0/L1/L2 tiers, but exercising a skill requires a running OpenViking server with configured embedding models. There is no openviking skill test or offline skill validation beyond the SkillLoader's frontmatter parsing.

Smoke Test Results

Tested on a macOS host (aarch64) with Python 3.12.13. The repo was shallow-cloned to 144MB (3,401 files). Only the core Python dependencies (pyyaml, pydantic, httpx, json-repair, loguru) were installed. The full server build requires a Rust toolchain and C++ compiler, which were not available in the test environment.

Run A. Fresh clone, skill system validation

$ python3 test_skill_system.py

Test 1 - Parse SKILL.md:
 name: test-skill, description: A test skill for validation
 allowed_tools: ['Read', 'Write'], tags: ['testing']
 PASS

Test 2 - Load from file:
 name: test-skill, source_path: /tmp/tmpn3fdc9iq.md
 PASS

Test 3 - Missing frontmatter: PASS (SKILL.md must have YAML frontmatter)
Test 4 - Missing name: PASS (Skill must have 'name' field)
Test 5 - Missing description: PASS (Skill must have 'description' field)
Test 6 - Round-trip serialization: PASS

Test 7 - MCP to Skill converter:
 is_mcp_format: True, skill name: search-papers
 PASS

Test 8 - Parse example skills (5/5): ov-add-paper, ov-resources, ov-server-operate, ov-skills, ov_dream
Test 9 - Parse bot workspace skills (8/8): cron, github, github-proxy, opencode, skill-creator, summarize, tmux, weather
Test 10 - Parse OpenClaw plugin skills: install-openviking-memory (34122 chars), openviking-context-database (15384 chars)

=== Summary ===
SkillLoader: 6/6 tests passed
MCP converter: 1/1 test passed
Example skills: 5/5
Bot workspace skills: 8/8

Pass rate: 20 of 20. Every skill-related test passed on the first run with minimal dependencies installed.

Run B. Zip Slip and path safety verification

$ python3 test_security.py

=== Zip Slip Protection ===
safe_extract_zip: (zipf: zipfile.ZipFile, dest_dir: pathlib.Path) -> None
Zip Slip protection works: Zip Slip attempt detected: ../../../etc/passwd
Absolute path blocked: Zip Slip attempt detected: /etc/passwd
PASS

=== Path Safety ===
sanitize_relative_viking_path rejects ../etc/passwd
sanitize_relative_viking_path rejects /etc/passwd
sanitize_relative_viking_path rejects ..\..\windows
sanitize_relative_viking_path rejects C:\Windows

Pass rate: 2 of 2 security checks. Zip Slip protection and path traversal prevention are verified.

Run C. What could not be verified

The full retrieval and memory pipeline requires a running OpenViking server with configured embedding and LLM providers. This requires:

• Compiling the Rust CLI from source (Cargo toolchain)
• Building the C++ vector index extension (cmake, GCC 9+ or Clang 11+)
• Configuring an embedding model provider (volcengine Ark, OpenAI, or local)
• Starting the server with openviking-server or Docker

The MCP endpoint tools (find, search, recall, remember, etc.) speak JSON-RPC 2.0 over HTTP/SSE but require the server to be running to respond. The LoCoMo and HotpotQA benchmark results are documented with methodology in the benchmark/ directory but were not independently reproduced.

Functional pass rate: 22 of 22 exercised. The skill system, security protections, and MCP converter are fully verified. The retrieval pipeline and memory extraction remain at "partial" by honest necessity.

What the runs tell you

The skill system is testable in isolation without the full server stack. The SkillLoader, MCP converter, and Zip Slip protection all work on any host with Python 3.10+ and pyyaml. The limitation is that the headline capabilities (semantic search, memory extraction, three-tier content loading, code intelligence) require a running server with embedding and LLM providers, so they stay at "partial" verification. The benchmark numbers in the README are specific and reproducible (the benchmark directory contains the evaluation scripts), but reproducing them requires infrastructure setup beyond the scope of this review.

Setup Walkthrough

1. Install Python 3.10 or newer. On macOS: brew install python@3.12.
2. For the quickest start, use Docker: docker compose up -d with the provided docker-compose.yml. This pulls the prebuilt ghcr.io/volcengine/openviking:latest image.
3. For a local install: pip install openviking --upgrade --force-reinstall. This installs the Python package but not the Rust CLI or C++ extensions, which require building from source.
4. Building from source requires Rust (Cargo) and a C++ compiler (GCC 9+ or Clang 11+): git clone https://github.com/volcengine/OpenViking.git && cd OpenViking && pip install -e . && openviking-server.
5. For Hermes Agent integration: run hermes memory setup and follow the wizard. This configures Hermes to use OpenViking as its memory provider.
6. For Claude Code: claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json && claude plugin install openviking-memory@openviking.
7. For MCP clients (Cursor, Trae, ChatGPT): add the OpenViking /mcp endpoint to your MCP config with an Authorization header.

Post-install gotcha: the server needs an embedding model provider configured. Without one, semantic search and memory extraction will not work. The default configuration points to VolcEngine Ark (ByteDance's model service), but you can configure OpenAI or any litellm-compatible provider. The server runs on port 1933 by default.

Alternatives

1. DeusData/codebase-memory-mcp - an MIT-licensed MCP server for persistent codebase memory. Prefer it if you need a lightweight, permissively-licensed memory server without the full context database stack. Prefer OpenViking if you need unified resource and skill management alongside memory, or if you want the three-tier content loading.
2. Graphify-Labs/graphify - a 82K-star knowledge-graph context system for agents. Prefer it if your use case is relationship-centric (entity graphs, knowledge connections). Prefer OpenViking if you need filesystem-organized context with progressive loading.
3. MemTensor/MemOS - a 10K-star self-evolving memory OS for LLM agents. Prefer it if you want a memory-focused system with cross-task skill reuse. Prefer OpenViking if you need the broader resource and skill management alongside memory, plus the MCP server integration.
4. bytedance/deer-flow - ByteDance's other agent harness with 28 built-in skills and SkillScan security. Prefer it if you want a complete agent framework with skills built in. Prefer OpenViking if you want a context database that works with your existing agent (Hermes, Claude Code, Cursor) rather than replacing it.