### OpenViking: The Context Database for AI Agents English / [中文](README_CN.md) / [日本語](README_JA.md) Website · Live Demo · GitHub · Issues · Docs 👋 Join our Community 📱 Lark Group · WeChat · Discord · X

*** ## What is OpenViking OpenViking is an open-source context database for AI agents. It stores memories, resources, and skills as one virtual filesystem under the `viking://` protocol, so an agent browses its own context with `ls`, `tree`, and `find` instead of querying a black-box vector store. Content is processed into three tiers — L0 abstract, L1 overview, L2 details — and loaded on demand. Every retrieval leaves a trajectory you can watch and debug. Full introduction: [Getting started](https://docs.openviking.ai/en/getting-started/01-introduction). *The [OpenViking Studio](https://openviking.ai/studio) playground — a live demo you can open in the browser, no installation required.* ## Why OpenViking - **One filesystem for all context.** Memories, resources, and skills each get a `viking://` URI. Agents locate and manipulate context deterministically, like a developer working with files. → [Viking URI](https://docs.openviking.ai/en/concepts/04-viking-uri) · [Context types](https://docs.openviking.ai/en/concepts/02-context-types) - **Tiered loading cuts token spend.** Every entry is processed into L0 (abstract), L1 (overview), and L2 (details) on write, then loaded only as deep as the task requires. → [Context layers](https://docs.openviking.ai/en/concepts/03-context-layers) - **Directory recursive retrieval.** Vector search first locates the highest-scoring directory, then drills down layer by layer, so results arrive with their surrounding context intact. → [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval) - **Observable retrieval.** Each query preserves its directory-browsing trajectory. When a result looks wrong, you can see exactly which path produced it. → [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval) - **Sessions become memory.** After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory. → [Session](https://docs.openviking.ai/en/concepts/08-session) How the pieces fit together: [Architecture](https://docs.openviking.ai/en/concepts/01-architecture). The thinking behind the design: [The Database Paradigm for Context Engineering](https://blog.openviking.ai/post/openviking-context-database/). ``` viking:// ├── resources/ # Resources: project docs, repos, web pages, etc. │ └── my_project/ │ ├── docs/ │ │ ├── api/ │ │ └── tutorials/ │ └── src/ └── user/ └── {user_id}/ ├── memories/ │ └── preferences/ │ ├── writing_style │ └── coding_habits ├── resources/ │ └── private_project/ ├── skills/ │ ├── search_code │ └── analyze_data └── peers/ └── web-visitor-alice/ ``` The three loading tiers: - **L0 (Abstract)**: a one-sentence summary for quick relevance checks. - **L1 (Overview)**: core information and usage scenarios for planning. - **L2 (Details)**: the full original data, read only when needed. Each directory carries its own L0/L1 layers, so relevance can be judged before any full file is read: ``` viking://resources/my_project/ ├── .abstract # L0: ~100 tokens - quick relevance check ├── .overview # L1: ~2k tokens - structure and key points └── docs/ ├── .abstract ├── .overview └── api/ ├── auth.md # L2: full content, loaded on demand └── endpoints.md ``` ## Proof it works OpenViking 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the [benchmark report](https://blog.openviking.ai/post/openviking-benchmark-results/); reproduction scripts live in [./benchmark](./benchmark). The memory evaluation used [Doubao 2.0 Pro](https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-seed-2-0-pro) as the VLM and [Doubao-embedding-vision-251215](https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-embedding-vision) as the embedding model.

Benchmark results. LoCoMo accuracy: OpenClaw 24.20% native vs 82.08% with OpenViking; Hermes 33.38% vs 82.86%; Claude Code 57.21% vs 80.32%. tau2-bench task success: Retail 70.94% vs 77.81%; Airline 54.38% vs 66.25%.

- **User memory (LoCoMo)**: with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%. - **Agent experience (tau2-bench)**: experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory. ## Quick start > 💡 **Want to see it in action first?** Try [OpenViking Studio](https://openviking.ai/studio) — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required. Requires Python 3.10 or higher. ```bash pip install openviking --upgrade openviking-server init # interactive wizard: providers, models, ov.conf openviking-server doctor # validate setup openviking-server # start (background: nohup openviking-server > openviking.log 2>&1 &) ``` `init` walks you through provider setup and writes `~/.openviking/ov.conf`. It supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama — for Ollama it can detect and install the runtime and pull models suited to your hardware. `doctor` checks the config file, Python version, provider connectivity, and disk space without a running server. Manual `ov.conf` templates, per-provider examples, environment variables, and Windows setup: [Configuration guide](https://docs.openviking.ai/en/guides/01-configuration) · [Quick start docs](https://docs.openviking.ai/en/getting-started/02-quickstart). The install already includes the `ov` client CLI. With the server running: ```bash ov status ov add-resource https://github.com/volcengine/OpenViking # --wait ov ls viking://resources/ ov tree viking://resources/volcengine -L 2 # wait some time for semantic processing if not --wait ov find "what is openviking" ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en ``` Next steps: - Client configuration (`ov config`), standalone CLI installs (npm / cargo), and advanced usage such as index rebuilding: [CLI setup](https://docs.openviking.ai/en/getting-started/05-cli-setup) - Docker and production deployment: [Deployment guide](https://docs.openviking.ai/en/guides/03-deployment) ## Use it with your agent Integrations inject OpenViking recall into your agent's context and auto-commit session memory: - [Claude Code](https://docs.openviking.ai/en/agent-integrations/02-claude-code) - [Codex](https://docs.openviking.ai/en/agent-integrations/04-codex) - [OpenClaw](https://docs.openviking.ai/en/agent-integrations/03-openclaw) - [Hermes](https://docs.openviking.ai/en/agent-integrations/05-hermes) - [Cursor](https://docs.openviking.ai/en/agent-integrations/12-cursor) - [TRAE / TRAE CN / TraeCode CLI 2.0](https://docs.openviking.ai/en/agent-integrations/13-trae) - [OpenCode](https://docs.openviking.ai/en/agent-integrations/10-opencode) - [pi](https://docs.openviking.ai/en/agent-integrations/11-pi) - [Agent Plugins 1.0](https://docs.openviking.ai/en/agent-integrations/15-agent-plugins) - [MCP clients](https://docs.openviking.ai/en/agent-integrations/06-mcp-clients) - [LangChain / LangGraph](https://docs.openviking.ai/en/agent-integrations/07-langchain-langgraph) Setup instructions for each agent: [Agent integrations overview](https://docs.openviking.ai/en/agent-integrations/01-overview). ## OpenViking Helper (Beta) OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64: - **Visual local agent setup**: detects OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configures supported plugin, MCP, Hook, and CLI integrations. - **Session trace inspection**: parses Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events. - **Local memory and skill management**: views local memory / rule files and `SKILL.md` skills, then syncs them to OpenViking. Download: - [macOS Apple Silicon (arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg) - [macOS Intel (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg) - [Windows (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe) ## VikingBot VikingBot is an AI agent framework built on top of OpenViking: ```bash pip install "openviking[bot]" openviking-server --with-bot ov chat # in another terminal ``` The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: [VikingBot guide](https://docs.openviking.ai/en/guides/17-vikingbot). ## Deploy in production For production, run OpenViking as a standalone HTTP service — see [Server deployment](https://docs.openviking.ai/en/getting-started/03-quickstart-server) and the [Deployment guide](https://docs.openviking.ai/en/guides/03-deployment). ## Commercial editions **The open-source edition is not crippled.** OpenViking in this repo is fully open source under AGPLv3: no feature gates, no account required, no activation key. Follow [Deploy in production](#deploy-in-production) above and run it in production yourself — and that will stay true. The two editions below answer "who operates it and where it runs", not "can I use it".

☁️ Managed SaaS

Officially hosted on Volcano Engine. Nothing to set up, nothing to operate.

Personal — for individual developers. Free trial for up to 50 files, and scales far beyond local hardware with VikingDB.
Enterprise — multi-user context management, team collaboration and permissions, enterprise SLA and support.

Existing open-source users can move over with the migration tool.

→ Volcano Engine product page · Documentation

_{Global hosting for regions outside China is coming to BytePlus.}

🏢 Self-Managed

Runs inside your own environment. Data never leaves it.

Online — deployed into your own cloud account / VPC, BYOC supported, with outbound access for updates and licensing.
Offline — fully air-gapped environments with no internet access, for regulated industries.

Adds distributed deployment and official support on top of the open-source edition, activated by license key.

→ Talk to us about self-managed deployment

> Just want to run the open-source edition? Go ahead — you don't need to contact anyone. Head to [Quick start](#quick-start). ## Research OpenViking open-sources a subset of the core capabilities described in the VikingMem paper: > **VikingMem: A Memory Base Management System for Stateful LLM-based Applications** > Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao. > arXiv:2605.29640, 2026. Accepted by VLDB 2026. > 📄 [Read the paper on arXiv](https://arxiv.org/abs/2605.29640) ## Partner Projects OpenViking welcomes collaboration with other open-source projects to build the context data ecosystem. Our confirmed partners include: - [deer-flow](https://github.com/bytedance/deer-flow) - Open-source long-horizon SuperAgent harness - [NoKV](https://github.com/NoKV-Lab/NoKV) - AI native distributed file system - [loopx](https://github.com/huangruiteng/loopx) - Lightweight loop engineering state kernel - [Hermes Agent](https://github.com/NousResearch/hermes-agent) - The agent that grows with you Interested in joining our partner list? Please submit an issue to our community to apply. ## Community & contributing OpenViking is still in its early stages, and there is plenty left to build. - **Docs**: [docs.openviking.ai](https://docs.openviking.ai/) · [FAQ](https://docs.openviking.ai/en/faq/faq) - **Blog**: [blog.openviking.ai](https://blog.openviking.ai/) - **Team**: [About us](https://docs.openviking.ai/en/about/01-about-us) - **Chat**: 📱 [Lark Group](https://docs.openviking.ai/en/about/01-about-us#lark-group) · 💬 [WeChat](https://docs.openviking.ai/en/about/01-about-us#wechat-group) · 🎮 [Discord](https://discord.com/invite/eHvx8E9XF3) · 🐦 [X](https://x.com/openvikingai) - **Contribute**: bug fixes and new features are both welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) ## Security and privacy This project takes security seriously. For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md) ## License The OpenViking project uses different licenses for different components: - **Main Project**: AGPLv3 - see the [LICENSE](./LICENSE) file for details - **crates/ov\_cli**: Apache 2.0 - see the [LICENSE](./crates/LICENSE) for details - **examples**: Apache 2.0 - see the [LICENSE](./examples/LICENSE) for details - **third\_party**: Respective original licenses of third-party projects