ByteDance Open-Sources OpenViking: Context Database Gives AI Agents Cross-Session Memory

Introduction

OpenViking is an open-source context database designed for AI Agents. It unifies memory, resources, and skills under the viking:// virtual file system protocol. Unlike opaque vector stores, agents browse their context using familiar commands like ls, tree, and find. Content is processed into three layers on write: L0 summary, L1 overview, L2 detail — loaded on demand to save tokens. Every retrieval leaves a directory traversal trail, allowing traceback to exact paths when results are unsatisfactory.

Key Features

Directory Recursive Retrieval: Locates the highest-scoring directory first, then drills down layer by layer, returning results with surrounding context.

Session Memory Persistence: After a session ends, user preferences and agent experiences are asynchronously written as long-term memory and automatically recalled in the next conversation — no cross-session amnesia.

Multi-Agent Sharing: The same memory can be plugged into external agents such as Claude Code, Codex, and Cursor via plugins, MCP, and SDKs, enabling cross-project reuse.

Installation and Configuration

The guide demonstrates deployment on a Linux server (192.168.3.101) using Docker.

Configuration File ( ov.conf )

Create ov.conf and copy to /mydata/openviking:

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "abc123456efg",
    "public_base_url": "http://192.168.3.101:1933"
  },
  "storage": {
    "workspace": "./data",
    "agfs": { "backend": "local" },
    "vectordb": { "backend": "local" }
  },
  "embedding": {
    "dense": {
      "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "<your-alibaba-cloud-bailian-api-key>",
      "provider": "openai",
      "dimension": 1024,
      "model": "text-embedding-v4"
    }
  },
  "vlm": {
    "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "<your-alibaba-cloud-bailian-api-key>",
    "provider": "openai",
    "model": "qwen3-vl-plus"
  }
}

Four configuration sections: server: service listen address, port, admin key; public_base_url lets the server return client-reachable URLs for file uploads. storage: specifies where memory and vector data persist inside the container. embedding: vector model (Alibaba Cloud Bailian OpenAI-compatible endpoint) converting text to searchable vectors. vlm: multimodal LLM for summarization, content understanding, and powering VikingBot's reasoning.

Docker Deployment

docker pull ghcr.io/volcengine/openviking:latest

docker run --name openviking \
  -p 1933:1933 \
  -v /mydata/openviking:/app/.openviking \
  -d ghcr.io/volcengine/openviking:latest

Health Check

curl http://192.168.3.101:1933/health

Expected response: status: ok, healthy: true, plus service version and auth_mode.

Web Studio

Access http://192.168.3.101:1933/studio. Dashboard shows context volume, token usage, retrieval counts. Left navigation: Workspace, Activity, Settings, Resources — entries for workbench, retrieval, skills, sessions, user management, agent integration.

Connection Setup

In Connection Settings , enter the root_api_key from ov.conf. Console permissions turn green when correct.

Management key only covers admin ops; data access requires a user-scoped API key.

In User Management , create a user (e.g., macro, role user) to generate a user API key. Save it and paste into the User API Key field in Connection Settings.

Workbench Layout

Three panes: left context tree ( user for personalized memory, resources for referenceable assets), middle viking:// directory browser, right session area with Terminal and Agent modes. Agent tool calls sync with the left tree — clicking a touched viking:// file locates it on the left and opens it in the middle.

Usage Demonstration: Cross-Session Memory

Using the built-in VikingBot:

In the workbench, tell the agent: 记住我的职业：Java开发工程师 (Remember my profession: Java developer). Agent calls openviking_memory_commit, writes the preference, and returns the Memory URI showing where it was stored.

Start a brand-new session and ask: 我的职业是什么 (What is my profession?). The agent has no conversation history but first calls openviking_search against the memory store, then answers: "Your profession is Java developer." The information comes from OpenViking, not the session — cross-session memory works.

Switch to Terminal mode and run /search 职业. Results list matched resources, memories, skills with filenames like .abstract.md, .overview.md, profile.md and their L0/L1/L2 levels plus similarity scores. The left context tree expands to user/macro/peers/macro/memories/profile.md, preview showing plain text: "职业：Java开发工程师". Memory persists as readable files on disk.

AI Agent Integrations

OpenViking is not limited to VikingBot. The official integration page lists Claude Code, Codex, OpenClaw, plus generic MCP (for TRAE, Cursor, etc.) and SDKs (Python, LangChain). Integration steps:

Launch self-hosted OpenViking Server.

Run an install script to connect Claude Code.

Restart Claude Code — it now has long-term memory backed by OpenViking.

Summary

OpenViking treats context as an engineering artifact. Deployment is lightweight: a single docker run brings up the server, console, and VikingBot. Memory, resources, and skills are laid out in the viking:// file system — what was recalled, what was stored, all visible in the console. With plugins, MCP, and SDKs, this memory layer plugs into Claude Code, Codex, Cursor, and other agents.

If you're tired of agents forgetting everything when a session ends, or want to equip your coding agent with an observable, manageable long-term memory, OpenViking is worth a half-hour deployment to try out.

Project Repository

https://github.com/volcengine/OpenViking