⛵ OpenViking - Lightweight installer

<div align="center"> <a href="" target="_blank"> <picture> <img alt="OpenViking" src="docs/images/ov-logo.png" width="200px" height="auto"> </picture> </a> </div>

In the AI era, data is abundant, but high-quality *context* is scarce. When building autonomous AI Agents, developers face serious challenges: memories are scattered across code, resources are stuck in vector databases, and traditional RAG (vector search) acts as a "black box," burning millions of tokens by loading unnecessary text.

OpenViking is an open-source tool that solves this problem by introducing a completely new approach: a "file system paradigm" for managing an AI Agent's memory, resources, and skills.

🌟 Key Concepts: How OpenViking Thinks

Instead of flat lists of vectors, the system organizes information into a clear hierarchy that an Agent can "navigate" just like a developer in a terminal.

1. Virtual File System (Viking URI)

All agent memory is organized as a directory tree. The agent can use commands (like ls or find) to consciously navigate through folders:

viking://
├── resources/              # External resources: documentation, code repos, web pages
│   └── my_project/
│       ├── docs/
│       └── src/
├── user/                   # User: habits, preferences, communication style
│   └── memories/
└── agent/                  # Agent: instructions, logic, task history
    ├── skills/             # Available tools (APIs, scripts)
    └── instructions/

2. Tiered Context Loading (Token Savings)

Trying to load an entire project into a model's prompt at once is expensive and inefficient. OpenViking automatically splits any uploaded document into three layers:

• L0 (Abstract): A short title (~100 tokens). Used for quick relevance checks.
• L1 (Overview): A summary (~2k tokens). Allows the agent to understand the structure and essence to plan its actions.
• L2 (Details): The full document text. Loaded only when absolutely necessary.

3. Directory Recursive Retrieval

Traditional RAG just looks for similar words. OpenViking first finds the most suitable "folder" (L0/L1) and then drills down into it (L2). This makes the search precise and allows the AI to see the full context of the document.

4. Automatic Memory Evolution

After a conversation ends, the system can analyze it, extract useful experiences (e.g., the user's preferred coding style), and save it into long-term memory. The Agent gets smarter with every use.

---

🚀 Effectiveness (Benchmarks)

Testing on a dataset of long-context dialogues (LoCoMo10) showed impressive results:

| Agent Configuration | Task Completion Rate | Input Token Cost (Total) | | :--- | :--- | :--- | | Base Agent (OpenClaw) | 35.65% | ~24.6M | | Agent + LanceDB (Vector DB) | 44.55% | ~51.5M | | Agent + OpenViking | 52.08% | ~4.2M (83-92% Reduction) |

---

🛠️ Quick Start

1. Installation

Download the latest installer for your operating system from the Releases section.

🍎 macOS (DMG)

1. Download the OpenViking_macOS.dmg file.
2. Open it and drag the OpenClaw icon to your Applications folder.
3. Run OpenClaw from your Applications folder to initialize. (Note: If you see a security warning, right-click the app and select "Open").
4. The deer-flow command is now available in your terminal.

🪟 Windows (EXE)

1. Download the OpenViking_x64.exe file.
2. Run the installer.
3. Open the Deer-Flow application.

2. Model Preparation (LLM)

Two models are required: a VLM (for text understanding) and an Embedding model (for vectors). Create a configuration file at ~/.openviking/ov.conf. You can use OpenAI, Volcengine (Doubao), or LiteLLM (for Claude, Gemini, Ollama, etc.).

Configuration Example (OpenAI):

{
  "storage": {
    "workspace": "/path/to/your/workspace"
  },
  "embedding": {
    "dense": {
      "provider": "openai", 
      "model": "text-embedding-3-large",
      "api_key": "YOUR_API_KEY",
      "api_base": "https://api.openai.com/v1"
    }
  },
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "YOUR_API_KEY",
    "api_base": "https://api.openai.com/v1"
  }
}

Don't forget to set the environment variable pointing to the config: export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf (for Linux/macOS).

3. Run Your First Example

Start the server in your terminal:

openviking-server

(Or run in the background: nohup openviking-server > /data/log/openviking.log 2>&1 &)

Now use the ov CLI utility to interact with the database:

# Check status
ov status

# Add a resource (automatically creates L0, L1, L2 layers)
ov add-resource https://github.com/volcengine/OpenViking

# View the virtual folder structure
ov tree viking://resources/volcengine -L 2

# Search for information
ov find "what is openviking"

4. VikingBot (Interactive AI Agent)

VikingBot is an AI agent framework built on top of OpenViking. Here's how to get started:

# 1. Install the VikingBot plugin
pip install "openviking[bot]"

# 2. Start the OpenViking server with the Bot enabled
openviking-server --with-bot

# 3. In a new terminal window, start the interactive chat
ov chat

---