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)

Searching Database…

40.1K ·GitHub
OpenViking
这是什么?一个面向 AI 智能体的开源上下文数据库:记忆、资源和技能都以 viking:// 协议存放在同一个虚拟文件系统里,智能体可以用 ls、tree、find 来浏览自己的上下文,而不是查询一个黑盒向量库。
它是我的智能体要导入的库,还是一个单独运行的服务?你需要单独运行它:一个自带 'ov' 客户端命令行工具的服务器,生产环境中则是一个独立的 HTTP 服务。智能体可以通过集成、MCP 客户端或 LangChain/LangGraph 接入。
我怎么把它跑起来?用 Python 3.10+ 安装后运行 'ov init'——它会引导你完成服务商配置,并写入 ~/.openviking/ov.conf;'ov doctor' 可以在不启动服务器的情况下预检配置。也提供现成的 Docker 镜像,OpenViking Studio 则直接在浏览器里运行,无需安装。
它能接入哪些编程智能体?Claude Code、Codex、OpenClaw、Hermes、Cursor、TRAE、OpenCode、pi、任何 MCP 客户端,以及 LangChain/LangGraph。这些集成会把检索结果注入智能体的上下文,并在会话结束后自动提交记忆。
开源版比起付费版是不是功能受限?没有任何功能限制:AGPLv3 版本没有功能门槛,不需要注册账号,也不需要激活密钥。付费版本只是改变了由谁运维、部署在哪里。
我的上下文数据必须离开我自己的基础设施吗?不必——自行管理的部署可以运行在你自己的云账号或 VPC 里,还有面向完全断网环境的离线版本。
L0、L1 和 L2 这几层上下文是什么?每条内容在写入时都会被处理成 L0(一句话摘要)、L1(核心信息和适用场景)和 L2(完整的原始数据),之后只按任务需要加载到相应的深度。目录本身也带有自己的 L0/L1,所以在读取任何完整文件之前就能先判断相关性。
它能在不同会话之间记住东西吗?可以。会话提交后,OpenViking 会异步地把用户偏好和智能体经验提取到长期记忆中——在 tau2-bench 上,这让任务成功率比不带记忆的同一个 LLM 提高了 6.87 个百分点(零售)和 11.87 个百分点(航空)。
它对智能体的提升能实际测量出来吗?在 LoCoMo 长对话记忆基准测试上,三个智能体集成接入 OpenViking 后达到 80–83% 的准确率,而用自带记忆时只有 24–57%;同时输入 token 减少了 34.3–91.0%,查询延迟降低了 58.45–66.10%。
我不安装任何东西就能试用吗?可以——OpenViking Studio 是一个托管的在线演示,包含上下文试验场、语义搜索和多智能体中心,直接在浏览器里打开即可。
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, dsh-plugin, memory, local-llm
Creator
volcengine
Size
372.1 MB
Stars
40.1K
Updated
CommitOct 16Releasev0.5.0Oct 09
Age
9mo
Commits · 90 Days