OpenViking Setup

OpenViking Setup for OpenClaw

OpenViking brings filesystem-based memory management to AI agents with tiered context loading and self-evolving memory. This skill guides you through installation and configuration.

What OpenViking Provides

Prerequisites

Quick Start

Step 1: Install OpenViking

# Python package
pip install openviking --upgrade --force-reinstall
CLI tool
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

Step 2: Create Configuration

Create ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "your-openai-api-key",
      "provider": "openai",
      "dimension": 1536,
      "model": "text-embedding-3-small"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "your-openai-api-key",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}

Step 3: Configure Provider

OpenViking supports multiple VLM providers:

| Provider | Model Example | Notes | |----------|---------------|-------| | openai | gpt-4o | Official OpenAI API | | volcengine | doubao-seed-2-0-pro | Volcengine Doubao | | litellm | claude-3-5-sonnet | Unified access (Anthropic, DeepSeek, Gemini, etc.) |

For LiteLLM (recommended for flexibility):

{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20241022",
    "api_key": "your-anthropic-key"
  }
}

For Ollama (local models):

{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}

OpenClaw Integration

Plugin Installation

OpenViking has a native OpenClaw plugin for seamless integration:

# Install OpenClaw plugin
pip install openviking-openclaw
Or from source
git clone https://github.com/volcengine/OpenViking
cd OpenViking/plugins/openclaw
pip install -e .

Configuration for OpenClaw

Add to your OpenClaw config:

# ~/.openclaw/config.yaml
memory:
  provider: openviking
  config:
    workspace: ~/.openviking/workspace
    tiers:
      l0:
        max_tokens: 4000
        auto_flush: true
      l1:
        max_tokens: 16000
        compression: true
      l2:
        max_tokens: 100000
        archive: true

Memory Tiers Explained

| Tier | Purpose | Token Budget | Behavior | |------|---------|--------------|----------| | L0 | Active working memory | 4K tokens | Always loaded, fast access | | L1 | Frequently accessed | 16K tokens | Compressed, on-demand | | L2 | Archive/cold storage | 100K+ tokens | Semantic search only |

How Tiers Work

1. New context goes to L0 2. L0 fills → oldest items compressed to L1 3. L1 fills → oldest items archived to L2 4. Retrieval searches all tiers, returns relevant context

Directory Structure

~/.openviking/
├── ov.conf                 # Configuration
└── workspace/
    ├── memories/
    │   ├── sessions/        # L0: Active session memory
    │   ├── compressed/     # L1: Compressed memories
    │   └── archive/        # L2: Long-term storage
    ├── resources/          # Files, documents, assets
    └── skills/             # Skill-specific context

Usage Patterns

Adding Memory

from openviking import MemoryStore
store = MemoryStore()
Add to L0
store.add_memory(
    content="User prefers Portuguese language responses",
    metadata={"tier": "l0", "category": "preference"}
)
Add resource
store.add_resource(
    path="project_spec.md",
    content=open("project_spec.md").read()
)

Retrieving Context

# Semantic search across all tiers
results = store.search(
    query="user preferences",
    tiers=["l0", "l1", "l2"],
    limit=10
)
Directory-based retrieval (more precise)
results = store.retrieve(
    path="memories/sessions/2026-03-16/",
    recursive=True
)

Compaction

# Trigger manual compaction
store.compact()
View compaction status
status = store.status()
print(f"L0: {status.l0_tokens}/{status.l0_max}")
print(f"L1: {status.l1_tokens}/{status.l1_max}")

Best Practices

Memory Hygiene

1. Categorize entries: Use metadata tags for better retrieval 2. Flush L0 regularly: Let compaction run, don't hoard 3. Use directory structure: Organize by project/topic 4. Review L2 periodically: Archive stale memories

Token Efficiency

1. Let OpenViking manage tiers automatically 2. Use semantic search for L2 (don't load entire archive) 3. Compress verbose content before adding to L1 4. Keep L0 under 50% capacity for best performance

OpenClaw Workflow

1. Session starts → OpenViking loads L0 2. Conversation proceeds → context auto-promoted to L1/L2 3. Long gaps → L2 provides relevant historical context 4. Sessions compound → agent gets smarter over time

Troubleshooting

Common Issues

"No module named 'openviking'"

"Embedding model not found"

"L0 overflow"

"Slow retrieval from L2"

Resources

What Gets Better

After setup, your agent gains:

1. Persistent memory across sessions 2. Smarter retrieval with semantic + directory search 3. Token efficiency with tiered loading 4. Self-improvement as context accumulates 5. Observable context with retrieval trajectories

The more your agent works, the more context it retains—without token bloat.

Step 1: Install OpenViking

# Python package
pip install openviking --upgrade --force-reinstall
CLI tool
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

Step 2: Create Configuration

Create ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "your-openai-api-key",
      "provider": "openai",
      "dimension": 1536,
      "model": "text-embedding-3-small"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "your-openai-api-key",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}

Step 3: Configure Provider

OpenViking supports multiple VLM providers:

| Provider | Model Example | Notes | |----------|---------------|-------| | openai | gpt-4o | Official OpenAI API | | volcengine | doubao-seed-2-0-pro | Volcengine Doubao | | litellm | claude-3-5-sonnet | Unified access (Anthropic, DeepSeek, Gemini, etc.) |

For LiteLLM (recommended for flexibility):

{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20241022",
    "api_key": "your-anthropic-key"
  }
}

For Ollama (local models):

{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}

Memory Hygiene

1. Categorize entries: Use metadata tags for better retrieval 2. Flush L0 regularly: Let compaction run, don't hoard 3. Use directory structure: Organize by project/topic 4. Review L2 periodically: Archive stale memories

Token Efficiency

1. Let OpenViking manage tiers automatically 2. Use semantic search for L2 (don't load entire archive) 3. Compress verbose content before adding to L1 4. Keep L0 under 50% capacity for best performance

OpenClaw Workflow

1. Session starts → OpenViking loads L0 2. Conversation proceeds → context auto-promoted to L1/L2 3. Long gaps → L2 provides relevant historical context 4. Sessions compound → agent gets smarter over time