OpenViking

0.3.12 verified Mon Apr 27 auth: no python

An Agent-native context database built by Volcengine. Current version 0.3.12, with active weekly releases. It provides memory, retrieval, RAG, and plugin systems for building AI agents, with support for various LLM/VLM providers and VikingDB integration.

pip install openviking

Common errors

error ImportError: cannot import name 'OpenViking' from 'openviking' (unknown location) ↓

cause Attempting to import OpenViking directly from the package, but it is not exposed at the top level in older versions (<0.3.0).

fix

Use from openviking.client import OpenViking (for v0.2.x) or upgrade to v0.3.x and use from openviking import OpenViking.

error ModuleNotFoundError: No module named 'openviking.memory' ↓

cause The memory module was renamed in v0.3.0; older imports break.

fix

Use from openviking.memory_v2 import VikingMemory (for v0.3.x). Check your version: pip show openviking

error TypeError: VikingMemory.store() got an unexpected keyword argument 'metadata' ↓

cause The `metadata` parameter was added in v0.3.5. Older versions don't support it.

fix

Either upgrade openviking to >=0.3.5, or omit the metadata argument for older versions.

Warnings

breaking Memory V1 is deprecated since v0.3.8. Memory V2 uses YAML-based templates and requires migration of existing memory definitions. ↓

fix Update memory configs to use V2 template format; see migration guide at https://github.com/volcengine/OpenViking/wiki/Memory-V2-Migration

gotcha OpenViking requires Python >=3.10. Trying to install on older versions will fail. ↓

fix Ensure your Python version is 3.10 or higher: python --version

deprecated The `openviking.OpenClaw` plugin system is being replaced by `openviking.plugins` module. OpenClaw remains functional but will be removed in a future version. ↓

fix Use `from openviking.plugins import PluginManager` instead.

Imports

VikingMemory
```
from openviking.memory import VikingMemory
```
The correct import path for the memory class.
OpenViking
wrong
```
import openviking
```
correct
```
from openviking import OpenViking
```
Direct import of openviking doesn't expose OpenViking class; use from openviking import OpenViking.

Context

wrong

from openviking import Context

correct

from openviking.core import Context

Context is in the core submodule, not top-level.

Quickstart

Initializes OpenViking client, stores and retrieves a simple memory.

import os
from openviking import OpenViking

def main():
    # Initialize client (requires a VikingDB instance and API key)
    vk = OpenViking(
        host=os.environ.get('VIKING_HOST', 'http://localhost:8080'),
        api_key=os.environ.get('VIKING_API_KEY', 'your-api-key-here')
    )
    # Store a memory
    memory_id = "my-first-memory"
    vk.memory.store(
        memory_id=memory_id,
        content="Hello, OpenViking! This is a test memory.",
        metadata={"type": "greeting"}
    )
    print(f"Stored memory: {memory_id}")
    
    # Retrieve the memory
    result = vk.memory.retrieve(memory_id=memory_id)
    print(f"Retrieved content: {result.content}")

if __name__ == "__main__":
    main()