volcengine/OpenViking

OpenViking – a context database for AI agents

What it is – OpenViking is an open‑source context store that lets LLM‑based agents treat their memories, resources, and skills like files in a virtual filesystem (viking://). Instead of sending a raw vector query to a black‑box store, an agent can browse, list, and search the hierarchy with familiar commands (ls, tree, find). Each entry is pre‑processed into three layers – a tiny abstract summary (L0), a medium‑sized overview (L1), and the full original data (L2) – so the agent only loads as much text as it actually needs.

Why it matters

• Deterministic, observable retrieval – the path the system follows is recorded, making debugging of “why did the agent pick this piece of info?” straightforward.
• Token‑efficient – L0/L1 layers let the agent discard irrelevant branches early, cutting token usage and latency dramatically (the README cites 34‑91 % token reduction and ~60 % latency drop in benchmarks).
• Unified URI scheme – everything lives under viking:// URIs, giving a single, file‑system‑like view of memories, user preferences, public resources, private files, and even other agents.
• Session‑to‑memory – after a conversation ends, OpenViking extracts preferences and experience and stores them as long‑term memory for the next session.

Core concepts

Concept	What it does
Viking URI	Uniform address (viking://…) for any context type (resources, memories, skills, peers).
Context layers (L0‑L2)	L0: one‑sentence abstract (100 tokens) for quick relevance checks. L1: overview (2 k tokens) for planning. L2: full content, read only when needed.
Directory‑recursive retrieval	Vector search first picks the highest‑scoring directory, then drills down layer by layer, returning results with surrounding context.
Sessions → Memory	Completed sessions are asynchronously turned into persistent memory entries (preferences, experience).

How to try it

1. Install – pip install openviking --upgrade (requires Python 3.10+).
   
2. Initialize – openviking-server init runs an interactive wizard that creates ~/.openviking/ov.conf and configures providers (Volcengine, OpenAI, Ollama, etc.).
   
3. Validate – openviking-server doctor checks the config, Python version, connectivity and disk space.
   
4. Run – openviking-server starts the HTTP service (or nohup … & for background).
   
5. Use the CLI – the bundled ov client lets you add resources, list directories, search, and inspect tasks, e.g.:

   ov add-resource https://github.com/volcengine/OpenViking
   ov ls viking://resources/
   ov find "what is openviking"
   

6. Play without installing – the OpenViking Studio web playground (https://openviking.ai/studio) offers a live demo of the filesystem, semantic search and a multi‑agent hub.

Agent integrations – OpenViking provides ready‑made adapters for many popular LLM‑agent frameworks, including Claude Code, Codex, OpenClaw, Hermes, Cursor, TRAE, LangChain/LangGraph, and more. The adapters automatically inject retrieved context into the agent’s prompt and commit session memory back to the store.

VikingBot – an optional Python‑based agent framework that ships with the server (pip install "openviking[bot]"). Running the server with --with-bot starts a chat interface (ov chat). A Docker image bundles VikingBot, the server, and the console UI for one‑click deployment.

Deployment options

• Self‑hosted – run the HTTP service on your own cloud, VPC, or offline air‑gapped environment. Production guides cover Docker, Kubernetes, and scaling.
• Managed SaaS – Volcano Engine offers a hosted version (free trial up to 50 files, then paid tiers). The open‑source edition remains fully functional without any license key.

Performance evidence – Benchmarks (LoCoMo memory test and tau2‑bench multi‑turn tasks) show accuracy jumps from the mid‑20 % range to ~80 % when agents use OpenViking, while token consumption and latency drop substantially.

License – The core project is released under AGPL‑v3 (full source, no feature gating). The CLI crate (crates/ov_cli) and example code are Apache 2.0.

Where to learn more

• Docs & tutorials – https://docs.openviking.ai
• Benchmark scripts – ./benchmark directory in the repo.
• Research paper – VikingMem: A Memory Base Management System for Stateful LLM‑based Applications (arXiv 2605.29640, VLDB 2026).
• Community – Discord, Lark, WeChat, X (Twitter) links in the README.

---

TL;DR – OpenViking replaces opaque vector stores with a hierarchical, layer‑aware filesystem that agents can explore and debug. It cuts token usage, improves recall accuracy, and works with a wide range of LLM agents, all under an AGPL‑v3 open‑source license.