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#

• Filesystem paradigm: Unified context management (memories, resources, skills)
• Tiered loading (L0/L1/L2): Load only what's needed, save tokens
• Self-evolving memory: Gets smarter with use
• OpenClaw plugin: Native integration available

Prerequisites#

• Python 3.10+
• Go 1.22+ (for AGFS components)
• GCC 9+ or Clang 11+ (for core extensions)
• VLM model access (for image/content understanding)
• Embedding model access (for vectorization)

Quick Start#

Step 1: Install OpenViking#

bash

# 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:

json

{
  "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:

ProviderModel ExampleNotesopenaigpt-4oOfficial OpenAI APIvolcenginedoubao-seed-2-0-proVolcengine Doubaolitellmclaude-3-5-sonnetUnified access (Anthropic, DeepSeek, Gemini, etc.)

For LiteLLM (recommended for flexibility):

json

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

For Ollama (local models):

json

{
  "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:

bash

# 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:

yaml

# ~/.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#

TierPurposeToken BudgetBehaviorL0Active working memory4K tokensAlways loaded, fast accessL1Frequently accessed16K tokensCompressed, on-demandL2Archive/cold storage100K+ tokensSemantic 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#

text

~/.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#

python

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#

python

# 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#

python

# 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'"

• Ensure Python 3.10+ is active
• Try pip install --user openviking

"Embedding model not found"

• Check ov.conf has correct provider and model
• Verify API key is valid

"L0 overflow"

• Reduce l0.max_tokens in config
• Manually call store.compact()

"Slow retrieval from L2"

• Consider pre-loading frequently accessed resources to L1
• Use directory-based retrieval for better precision

Resources#

• GitHub: https://github.com/volcengine/OpenViking
• Documentation: https://github.com/volcengine/OpenViking/tree/main/docs
• OpenClaw Plugin: https://github.com/volcengine/OpenViking/tree/main/plugins/openclaw
• Examples: https://github.com/volcengine/OpenViking/tree/main/examples

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.