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 - **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: | 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): ```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 | 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 ```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.