OpenViking README

The project's README from github.com/volcengine/OpenViking. As one markdown file: README.md.

OpenViking

OpenViking: The Context Database for AI Agents

English / 中文 / 日本語

Website · Live Demo · GitHub · Issues · Docs

👋 Join our Community

📱 Lark Group · WeChat · Discord · X

volcengine%2FOpenViking | Trendshift

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.

OpenViking Studio playground

The OpenViking Studio playground — a live demo you can open in the browser, no installation required.

Why OpenViking

How the pieces fit together: Architecture. The thinking behind the design: The Database Paradigm for Context Engineering.

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:

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; reproduction scripts live in ./benchmark.

The memory evaluation used Doubao 2.0 Pro as the VLM and Doubao-embedding-vision-251215 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%.

Quick start

💡 Want to see it in action first? Try OpenViking 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.

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 · Quick start docs.

The install already includes the ov client CLI. With the server running:

ov status
ov add-resource https://github.com/volcengine/OpenViking
# Replace TASK_ID with the returned task_id; continue after status is completed
ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

Next steps:

Use it with your agent

Integrations inject OpenViking recall into your agent's context and auto-commit session memory:

Setup instructions for each agent: Agent integrations overview.

OpenViking Helper (Beta)

OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64:

Download:

VikingBot

VikingBot is an AI agent framework built on top of OpenViking:

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.

Deploy in production

For production, run OpenViking as a standalone HTTP service — see Server deployment and the Deployment guide.

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

☁️ 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

🏢 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.

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

Partner Projects

OpenViking welcomes collaboration with other open-source projects to build the context data ecosystem. Our confirmed partners include:

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.

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md

License

The OpenViking project uses different licenses for different components:

OpenViking (volcengine/OpenViking)

vector-database
Searching Database…

40.2K ·GitHub
OpenViking
What is this?An open-source context database for AI agents: memories, resources, and skills live in one virtual filesystem under the viking:// protocol, so the agent browses its own context with ls, tree, and find instead of querying a black-box vector store.
Is it a library my agent imports, or something I run separately?You run it: a server with the bundled 'ov' client CLI, and in production a standalone HTTP service. Agents connect through integrations, MCP clients, or LangChain/LangGraph.
How do I get it running?Install with Python 3.10+ and run 'ov init' — it walks you through provider setup and writes ~/.openviking/ov.conf; 'ov doctor' prechecks the config without a server. A Docker image is ready too, and OpenViking Studio runs in the browser with no installation.
Which coding agents does it plug into?Claude Code, Codex, OpenClaw, Hermes, Cursor, TRAE, OpenCode, pi, any MCP client, and LangChain/LangGraph. Integrations inject recall into the agent's context and auto-commit session memory.
Is the open-source edition hobbled compared to the paid plans?Nothing is gated: the AGPLv3 edition has no feature gates, no account requirement, and no activation key. Paid editions only change who operates it and where it runs.
Does my context data have to leave my infrastructure?No — self-managed deployments run in your own cloud account or VPC, and there is an offline edition for fully air-gapped environments with no internet access.
What are the L0, L1 and L2 context layers?Every entry is processed on write into L0 (a one-sentence abstract), L1 (core info and use scenarios) and L2 (the full original data), then loaded only as deep as the task requires. Directories carry their own L0/L1, so relevance is judged before any full file is read.
Does it remember things between sessions?Yes. After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory — on tau2-bench this lifted task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.
How much does it improve an agent, measurably?On the LoCoMo long-conversation memory benchmark, three agent integrations reached 80–83% accuracy with OpenViking versus 24–57% on their native memory, while input tokens dropped 34.3–91.0% and query latency 58.45–66.10%.
Can I try it without installing anything?Yes — OpenViking Studio is a hosted live demo with a context playground, semantic search, and a multi-agent hub that opens in the browser.
What are similar projects?MemOS, EverOS, ruflo, m_flow, LongMemory, mem0, cognee, memory-lancedb-pro
Which topics is it in?agentic-rag, token-optimization, self-evolving, memory-management, long-term-memory, context-engineering, agplv3, vector-database, agent-memory, memory, dsh-plugin, local-llm
Creator
volcengine
Size
372.6 MB
Stars
40.2K
Updated
CommitOct 18Releasev0.5.0Oct 09
Age
9mo
Commits · 90 Days