openviking

OpenViking: The Context Database for AI Agents

English / 中文 / 日本語

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 gives agents a place to store knowledge, remember users, and reuse experience across sessions.

OpenViking organizes context as a virtual filesystem under viking://. Agents can operate on it like files: use ls, tree, read, and write to browse directories, read, create, and edit content, or search within a directory. Directory summaries support on-demand loading.

Try OpenViking Studio in your browser, no installation required. Self-host Web Studio.

Why OpenViking

• One filesystem for all context. Resources hold documents and code; memories retain user preferences and experience; skills define how to perform tasks. Each has a viking:// URI for browsing and retrieval. → Viking URI · Context types
• Load only the context you need. Directory abstracts (L0) and overviews (L1) help agents decide when to read full content (L2). → Context layers
• Search within the directory structure. Vector search finds candidate directories, then explores their contents. find runs a query directly; search can use session context to plan retrieval. → Retrieval
• Turn sessions into memory. Committing a session archives the conversation and starts background extraction. Memory policies control what is retained; candidates are compared with existing memories for creation, merging, or skipping. With VikingBot enabled, ov compile uses a skill to organize source material into a wiki, knowledge graph, or report. → Sessions · Context compilation

Architecture · Design rationale

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.

Semantically processed directories carry L0/L1 summaries, so agents can judge relevance before reading full files:

viking://resources/my_project/
├── .abstract.md           # L0: quick relevance check
├── .overview.md           # L1: structure and key points
└── docs/
    ├── .abstract.md
    ├── .overview.md
    └── 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.

• 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

Requires Python 3.10+ and access to an embedding model and a VLM (cloud or local).

pip install openviking --upgrade
openviking-server init      # configure providers and models
openviking-server doctor    # check configuration and connectivity
openviking-server           # start the server

init writes ~/.openviking/ov.conf. Supported options include Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama. See the configuration guide for provider setup and the quick start docs for platform instructions.

The package includes the ov CLI. In another terminal, import a repository and search it:

ov status
ov add-resource https://github.com/volcengine/OpenViking
# Replace TASK_ID with the returned task_id; repeat until 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

ov find returns matching context with URIs you can inspect. For client configuration (ov config), standalone CLI installs, and index maintenance, see CLI setup.

Build your own integration with the Python, Go, or TypeScript SDK, or the HTTP API.

Use it with your agent

Connect your agent to OpenViking for cross-session memory. Choose a native integration for automatic recall and session capture, or use MCP to give your agent memory and context tools.