OpenClaw Integration

Use OpenViking as long-term memory for OpenClaw AI agent framework

Integrate OpenViking as the long-term memory backend for OpenClaw. The plugin enables automatic memory capture from conversations and intelligent recall when relevant.

Performance Benchmarks

Tested on LoCoMo10 dataset (1,540 long-range dialogue cases):

Configuration	Task Completion	Input Tokens
OpenClaw (baseline)	35.65%	24.6M
OpenClaw + LanceDB	44.55%	51.6M
OpenClaw + OpenViking	52.08%	4.3M

Result: 49% improvement over baseline with 83% token reduction compared to native memory.

Prerequisites

• Python 3.10+
• Node.js 22+
• cmake and g++ (for compiling C++ extensions)
• OpenClaw installed globally: npm install -g openclaw
• OpenViking installed: pip install openviking --upgrade --force-reinstall

Quick Start

One-Click Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-memory-plugin/install.sh | bash

The script validates your environment, installs dependencies, and configures the plugin automatically.

Manual Setup

1. Install OpenClaw

   npm install -g openclaw
   openclaw onboard  # Configure your LLM
   
2. Install OpenViking

   pip install openviking --upgrade --force-reinstall
   
3. Run Setup Helper

   From the OpenViking repository:

   git clone https://github.com/volcengine/OpenViking.git
   cd OpenViking
   npx ./examples/openclaw-memory-plugin/setup-helper
   

   The helper will:

   • Create ~/.openviking/ov.conf with your API keys
   • Deploy the plugin to ~/.openclaw/extensions/memory-openviking
   • Configure OpenClaw to use the plugin
   • Generate environment file ~/.openclaw/openviking.env
4. Start OpenClaw

   Linux/macOS:

   source ~/.openclaw/openviking.env && openclaw gateway
   

   Windows (cmd):

   call "%USERPROFILE%\.openclaw\openviking.env.bat" && openclaw gateway
   

Configuration

Server Config (~/.openviking/ov.conf)

{
  "server": {
    "host": "127.0.0.1",
    "port": 1933
  },
  "storage": {
    "workspace": "/home/yourname/.openviking/data"
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "<your-api-key>",
      "model": "doubao-embedding-vision-250615",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "dimension": 1024
    }
  },
  "vlm": {
    "provider": "volcengine",
    "api_key": "<your-api-key>",
    "model": "doubao-seed-2-0-pro-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}

The workspace path must be absolute (e.g., /home/yourname/.openviking/data). Tilde (~) is not supported.

Plugin Configuration

The plugin operates in two modes:

Local Mode (Default)

# Plugin auto-starts OpenViking server
openclaw config set plugins.slots.memory memory-openviking
openclaw config set plugins.entries.memory-openviking.config.mode "local"
openclaw config set plugins.entries.memory-openviking.config.configPath "~/.openviking/ov.conf"

Memory Behavior

# Enable auto-capture (default: true)
openclaw config set plugins.entries.memory-openviking.config.autoCapture true --json

# Enable auto-recall (default: true)
openclaw config set plugins.entries.memory-openviking.config.autoRecall true --json

# Set recall limit (default: 6)
openclaw config set plugins.entries.memory-openviking.config.recallLimit 10

# Set score threshold (default: 0.01)
openclaw config set plugins.entries.memory-openviking.config.recallScoreThreshold 0.2

Usage

Once configured, memory works automatically:

Storing Memories

openclaw tui

Then in chat:

You: Please remember: my favorite programming language is Python.
Agent: I'll remember that.

Memories are automatically extracted from conversations when:

• User provides factual information
• Preferences or settings are mentioned
• Important decisions are discussed

Recalling Memories

In a later session:

You: What is my favorite programming language?
Agent: Based on our previous conversation, your favorite programming language is Python.

The plugin automatically injects relevant memories into the context before the agent responds.

Manual Tools

OpenClaw also provides explicit memory tools:

// Search memories
memory_recall({ query: "programming preferences", limit: 5 })

// Store information
memory_store({ text: "User prefers dark mode for all applications" })

// Forget specific memory
memory_forget({ query: "programming language preference" })

Troubleshooting

Plugin not showing in gateway output

Verify the environment file is loaded:

openclaw status  # Check if plugin is enabled

# Re-run setup helper
npx ./examples/openclaw-memory-plugin/setup-helper

Health check timeout

A stale process may be occupying the port:

# Linux/macOS
lsof -ti tcp:1933 tcp:1833 | xargs kill -9
source ~/.openclaw/openviking.env && openclaw gateway

# Windows
for /f "tokens=5" %a in ('netstat -ano ^| findstr ":1933 :1833"') do taskkill /PID %a /F

Extracted 0 memories

Check your model configuration in ov.conf:

• Verify embedding.dense.api_key is a valid API key
• Verify vlm.api_key is set
• Verify vlm.model is a model name (not an API key)

Test manually:

python3 -c "import openviking; print('ok')"

Memory shows 'disabled' or 'memory-core'

The plugin slot is not set correctly:

openclaw config set plugins.slots.memory memory-openviking
openclaw config set plugins.enabled true --json

Restart the gateway after changing slots.

Daily Usage

Create a convenient alias (Linux/macOS):

.bashrc

alias openclaw-start='source ~/.openclaw/openviking.env && openclaw gateway'

Then simply run:

openclaw-start

Advanced Options

Capture Mode

Control what gets captured:

# Semantic mode (default) - captures all eligible text
openclaw config set plugins.entries.memory-openviking.config.captureMode "semantic"

# Keyword mode - only triggers on memory-related keywords
openclaw config set plugins.entries.memory-openviking.config.captureMode "keyword"

Target URI

Specify where memories are stored:

openclaw config set plugins.entries.memory-openviking.config.targetUri "viking://user/memories"

Setup Helper Options

# Non-interactive mode
npx ./examples/openclaw-memory-plugin/setup-helper -y

# Environment variables
export OPENVIKING_PYTHON=/usr/local/bin/python3
export OPENVIKING_ARK_API_KEY=your-api-key
npx ./examples/openclaw-memory-plugin/setup-helper -y

See Also

• OpenClaw GitHub
• Configuration Reference
• Memory Management