From bdaba87268fb30b545cd0f5d6645a69d57d4c7f5 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Mon, 23 Feb 2026 19:59:32 +0800 Subject: [PATCH 01/10] docs: add comprehensive INSTALLATION.md guide Add installation guide covering: - Python package installation and verification - Rust CLI (ov) installation options - Server configuration (ov.conf) with examples - CLI configuration (ovcli.conf) setup - Step-by-step verification for each component - Example skills overview (adding-memory, adding-resource, searching-context) - Troubleshooting section for common issues This guide helps both humans and agents quickly set up and verify their OpenViking installation. --- INSTALLATION.md | 457 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 457 insertions(+) create mode 100644 INSTALLATION.md diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 00000000..3a8aa47b --- /dev/null +++ b/INSTALLATION.md @@ -0,0 +1,457 @@ +# OpenViking Installation Guide + +Complete installation guide for OpenViking - the Context Database for AI Agents. + +## Table of Contents + +- [Overview](#overview) +- [Prerequisites](#prerequisites) +- [Installation Options](#installation-options) + - [Option 1: Python Package (Recommended)](#option-1-python-package-recommended) + - [Option 2: Rust CLI (ov)](#option-2-rust-cli-ov) +- [Configuration](#configuration) + - [Server Configuration (ov.conf)](#server-configuration-ovconf) + - [CLI Configuration (ovcli.conf)](#cli-configuration-ovcliconf) +- [Verification](#verification) + - [Verify Python Package](#verify-python-package) + - [Verify Server](#verify-server) + - [Verify CLI](#verify-cli) +- [Example Skills](#example-skills) +- [Troubleshooting](#troubleshooting) + +--- + +## Overview + +OpenViking consists of two main components: + +1. **OpenViking Server** - The core context database (Python package) +2. **ov CLI** - Command-line interface for interacting with the server (Rust binary) + +You can use OpenViking in two modes: +- **Embedded Mode**: Direct Python API calls from your application +- **Server Mode**: HTTP server with client connections (Python SDK, CLI, or HTTP) + +--- + +## Prerequisites + +Before installing OpenViking, ensure you have: + +| Requirement | Version | Notes | +|-------------|---------|-------| +| Python | 3.10+ | Required for server package | +| Operating System | Linux, macOS, Windows | All supported | +| Network | Stable connection | For model APIs and dependencies | +| API Keys | VLM + Embedding | From your model provider(s) | + +**Supported Model Providers:** +- Volcengine (Doubao) +- OpenAI +- Anthropic (Claude) +- DeepSeek +- Google (Gemini) +- Moonshot (Kimi) +- Zhipu (GLM) +- DashScope (Qwen) +- MiniMax +- OpenRouter +- vLLM (local models) + +--- + +## Installation Options + +### Option 1: Python Package (Recommended) + +Install the OpenViking server and Python SDK: + +```bash +pip install openviking +``` + +Or with `uv` (faster): + +```bash +uv pip install openviking +``` + +**Verify installation:** + +```bash +python -c "import openviking; print(openviking.__version__)" +``` + +Expected output: version number (e.g., `0.2.0`) + +--- + +### Option 2: Rust CLI (ov) + +The `ov` CLI provides a fast, convenient interface to interact with OpenViking server. + +#### Quick Install (Linux/macOS) + +```bash +curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash +``` + +#### Install from Source + +Requires Rust toolchain: + +```bash +# Clone the repository +git clone https://github.com/volcengine/OpenViking.git +cd OpenViking + +# Install with cargo +cargo install --path crates/ov_cli + +# Or install directly from git +cargo install --git https://github.com/volcengine/OpenViking ov_cli +``` + +**Verify installation:** + +```bash +ov --version +``` + +Expected output: version number (e.g., `ov 0.2.0`) + +--- + +## Configuration + +### Server Configuration (ov.conf) + +Create the server configuration file at `~/.openviking/ov.conf`: + +```bash +mkdir -p ~/.openviking +``` + +**Minimal configuration:** + +```json +{ + "embedding": { + "dense": { + "provider": "volcengine", + "model": "doubao-embedding-vision-250615", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "dimension": 1024, + "input": "multimodal" + } + }, + "vlm": { + "provider": "volcengine", + "model": "doubao-seed-1-8-251228", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3" + } +} +``` + +**Full configuration template** (see `examples/ov.conf.example`): + +```json +{ + "server": { + "host": "0.0.0.0", + "port": 1933, + "api_key": null, + "cors_origins": ["*"] + }, + "storage": { + "vectordb": { + "name": "context", + "backend": "local", + "path": "./data" + }, + "agfs": { + "port": 1833, + "path": "./data", + "backend": "local" + } + }, + "embedding": { + "dense": { + "provider": "volcengine", + "model": "doubao-embedding-vision-250615", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "dimension": 1024, + "input": "multimodal" + } + }, + "vlm": { + "provider": "volcengine", + "model": "doubao-seed-1-8-251228", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "temperature": 0.0, + "max_retries": 2 + }, + "auto_generate_l0": true, + "auto_generate_l1": true, + "default_search_mode": "thinking", + "default_search_limit": 3, + "log_level": "INFO" +} +``` + +**Set environment variable:** + +```bash +# Linux/macOS +export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf + +# Windows (PowerShell) +$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" + +# Windows (CMD) +set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" +``` + +--- + +### CLI Configuration (ovcli.conf) + +Create the CLI configuration file at `~/.openviking/ovcli.conf`: + +```json +{ + "url": "http://localhost:1933", + "api_key": "your-api-key" +} +``` + +| Field | Description | Default | +|-------|-------------|---------| +| `url` | OpenViking server URL | `http://localhost:1933` | +| `api_key` | API key for authentication | `null` (if server has no auth) | + +**Alternative config location:** + +```bash +export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf +``` + +--- + +## Verification + +### Verify Python Package + +```bash +python -c " +import openviking as ov +print(f'OpenViking version: {ov.__version__}') +print('Python package installed successfully!') +" +``` + +### Verify Server + +1. **Start the server:** + +```bash +# Using the installed command +openviking-server + +# Or using Python module +python -m openviking serve + +# With custom config +python -m openviking serve --config /path/to/ov.conf --port 1933 +``` + +Expected output: +``` +INFO: Uvicorn running on http://0.0.0.0:1933 +``` + +2. **Check health endpoint:** + +```bash +curl http://localhost:1933/health +``` + +Expected output: +```json +{"status": "ok"} +``` + +3. **Verify with Python SDK:** + +```python +import openviking as ov + +# Test connection +client = ov.SyncHTTPClient(url="http://localhost:1933") +client.initialize() +print("Server connection successful!") +client.close() +``` + +### Verify CLI + +```bash +# Check version +ov --version + +# Check system status (requires server running) +ov system health + +# Test basic commands +ov ls +ov config show +``` + +**Full integration test:** + +```bash +# Add a test resource +ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md --wait + +# List resources +ov ls viking://resources + +# Search +ov find "what is openviking" +``` + +--- + +## Example Skills + +OpenViking includes example skills demonstrating common patterns. These are located in `examples/skills/`: + +| Skill | Description | Trigger | +|-------|-------------|---------| +| `adding-memory` | Store memories and learnings | `ovm` keyword | +| `adding-resource` | Import files, URLs, directories | `ovr` keyword | +| `searching-context` | Search memories and resources | `ovs` keyword | + +**Using example skills:** + +1. Review the skill documentation: + - `examples/skills/adding-memory/SKILL.md` + - `examples/skills/adding-resource/SKILL.md` + - `examples/skills/searching-context/SKILL.md` + +2. Test the skills with CLI: + +```bash +# Adding memory +ov add-memory "User prefers Python for data processing tasks" + +# Adding resource +ov add-resource https://example.com/docs --wait + +# Searching context +ov search "Python data processing" +``` + +3. See `examples/skills/tests.md` for comprehensive test cases. + +--- + +## Troubleshooting + +### Common Issues + +#### 1. Import Error: No module named 'openviking' + +**Cause:** Package not installed or wrong Python environment. + +**Solution:** +```bash +pip install openviking +# or +uv pip install openviking +``` + +#### 2. Connection refused when connecting to server + +**Cause:** Server not running or wrong URL. + +**Solution:** +```bash +# Check if server is running +ps aux | grep openviking-server + +# Start server +openviking-server + +# Verify URL in ovcli.conf matches server host/port +``` + +#### 3. API key errors + +**Cause:** Invalid or missing API key in configuration. + +**Solution:** +- Check `api_key` in `~/.openviking/ov.conf` +- Verify key is valid with your model provider +- Check `api_base` URL is correct + +#### 4. Embedding model errors + +**Cause:** Wrong dimension or model name. + +**Solution:** +- Verify `dimension` matches your embedding model +- Common dimensions: 1024 (Doubao), 3072 (OpenAI text-embedding-3-large) +- Check `input: "multimodal"` for vision embedding models + +#### 5. CLI command not found + +**Cause:** `ov` not in PATH. + +**Solution:** +```bash +# Check if installed +cargo install --list | grep ov_cli + +# Add cargo bin to PATH +export PATH="$HOME/.cargo/bin:$PATH" + +# Or reinstall with full path +cargo install --path crates/ov_cli --force +``` + +### Getting Help + +- **Documentation:** https://www.openviking.ai/docs +- **GitHub Issues:** https://github.com/volcengine/OpenViking/issues +- **Discord:** https://discord.com/invite/eHvx8E9XF3 + +--- + +## Next Steps + +After successful installation: + +1. **Read the Quick Start:** See `README.md` or [docs](https://www.openviking.ai/docs) +2. **Try Examples:** Run `examples/quick_start.py` +3. **Explore Skills:** Review `examples/skills/` +4. **Server Deployment:** See `docs/en/getting-started/03-quickstart-server.md` + +--- + +## Summary Checklist + +- [ ] Python 3.10+ installed +- [ ] `pip install openviking` completed successfully +- [ ] `ov` CLI installed (optional but recommended) +- [ ] `~/.openviking/ov.conf` created with model credentials +- [ ] `~/.openviking/ovcli.conf` created (for CLI usage) +- [ ] `OPENVIKING_CONFIG_FILE` environment variable set +- [ ] Server starts without errors +- [ ] Health endpoint returns `{"status": "ok"}` +- [ ] CLI can connect and list resources +- [ ] Example skills documentation reviewed From cac43d06a64403f493790fb427af56079a75b040 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Mon, 23 Feb 2026 20:23:12 +0800 Subject: [PATCH 02/10] docs: restructure INSTALLATION.md with server emphasis and skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major updates to installation guide: - Emphasize ov CLI is REQUIRED (not optional) for fast skill execution - Emphasize server mode is REQUIRED for skills (faster performance) - Add architecture diagram showing multi-client deployment - Add hint that server can run anywhere (cloud, VM, container, local) - Skills moved to Step 3 (core component, not just examples) - Detailed skill descriptions: adding-memory, adding-resource, searching-context - Include trigger keywords (ovm, ovr, ovs) and what each skill does - Add multi-client deployment options table - Reorder: Installation → Skills → Config → Running → Verification → Troubleshooting - Add skill functionality verification section --- INSTALLATION.md | 323 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 218 insertions(+), 105 deletions(-) diff --git a/INSTALLATION.md b/INSTALLATION.md index 3a8aa47b..4e5563ec 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -6,31 +6,53 @@ Complete installation guide for OpenViking - the Context Database for AI Agents. - [Overview](#overview) - [Prerequisites](#prerequisites) -- [Installation Options](#installation-options) - - [Option 1: Python Package (Recommended)](#option-1-python-package-recommended) - - [Option 2: Rust CLI (ov)](#option-2-rust-cli-ov) +- [Step 1: Install OpenViking Server](#step-1-install-openviking-server) +- [Step 2: Install ov CLI (Required)](#step-2-install-ov-cli-required) +- [Step 3: Install Skills](#step-3-install-skills) - [Configuration](#configuration) - [Server Configuration (ov.conf)](#server-configuration-ovconf) - [CLI Configuration (ovcli.conf)](#cli-configuration-ovcliconf) +- [Running the Server](#running-the-server) - [Verification](#verification) - - [Verify Python Package](#verify-python-package) - - [Verify Server](#verify-server) - - [Verify CLI](#verify-cli) -- [Example Skills](#example-skills) - [Troubleshooting](#troubleshooting) --- ## Overview -OpenViking consists of two main components: +OpenViking consists of three components: 1. **OpenViking Server** - The core context database (Python package) -2. **ov CLI** - Command-line interface for interacting with the server (Rust binary) +2. **ov CLI** - Command-line interface for fast skill execution (Rust binary) **REQUIRED** +3. **Skills** - Agent capabilities for memory, resources, and search -You can use OpenViking in two modes: -- **Embedded Mode**: Direct Python API calls from your application -- **Server Mode**: HTTP server with client connections (Python SDK, CLI, or HTTP) +**Architecture:** + +``` +┌─────────────────────────────────────────────────────────────┐ +│ OpenViking Server │ +│ (Runs anywhere: local, │ +│ cloud, VM, container, etc.) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Skills │ │ Memory │ │ Resources │ │ +│ │ (installed) │ │ (context) │ │ (files/URLs)│ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ + ┌─────────────┼─────────────┐ + │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ + │ ov CLI │ │ ov CLI │ │ ov CLI │ + │ (PC) │ │ (Laptop)│ │ (Mobile)│ + └─────────┘ └─────────┘ └─────────┘ +``` + +**Key Benefits:** +- **Server can run anywhere** - local machine, cloud VM, container, or dedicated server +- **Multiple clients can share one server** - PC, laptop, mobile devices all connect to the same OpenViking instance +- **ov CLI is required** - enables fast skill execution and is the primary interface for agent operations +- **Server mode is required for skills** - provides better performance and enables skill functionality --- @@ -40,7 +62,8 @@ Before installing OpenViking, ensure you have: | Requirement | Version | Notes | |-------------|---------|-------| -| Python | 3.10+ | Required for server package | +| Python | 3.10+ | Required for server | +| Rust | Latest | Required for building ov CLI | | Operating System | Linux, macOS, Windows | All supported | | Network | Stable connection | For model APIs and dependencies | | API Keys | VLM + Embedding | From your model provider(s) | @@ -60,9 +83,7 @@ Before installing OpenViking, ensure you have: --- -## Installation Options - -### Option 1: Python Package (Recommended) +## Step 1: Install OpenViking Server Install the OpenViking server and Python SDK: @@ -86,17 +107,20 @@ Expected output: version number (e.g., `0.2.0`) --- -### Option 2: Rust CLI (ov) +## Step 2: Install ov CLI (Required) -The `ov` CLI provides a fast, convenient interface to interact with OpenViking server. +The `ov` CLI is **required** for OpenViking. It provides: +- Fast skill execution +- Primary interface for agent operations +- Efficient communication with the server -#### Quick Install (Linux/macOS) +### Quick Install (Linux/macOS) ```bash curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash ``` -#### Install from Source +### Install from Source Requires Rust toolchain: @@ -122,6 +146,68 @@ Expected output: version number (e.g., `ov 0.2.0`) --- +## Step 3: Install Skills + +Skills are agent capabilities that enable OpenViking's core functionality. Three skills are available: + +| Skill | Description | Trigger Keyword | Files | +|-------|-------------|-----------------|-------| +| **adding-memory** | Store memories and learnings from conversations | `ovm` | `examples/skills/adding-memory/SKILL.md` | +| **adding-resource** | Import files, URLs, or directories into context | `ovr` | `examples/skills/adding-resource/SKILL.md` | +| **searching-context** | Search memories and resources semantically | `ovs` | `examples/skills/searching-context/SKILL.md` | + +### What Each Skill Does + +**adding-memory (ovm)** +- Extracts and stores valuable insights from conversations +- Builds persistent user profile, preferences, and learned patterns +- Triggered by saying "ovm" or when agents identify memorable content + +**adding-resource (ovr)** +- Imports external content (files, URLs, directories) into OpenViking +- Automatically processes with semantic analysis +- Triggered by saying "ovr" or when agents encounter useful external content + +**searching-context (ovs)** +- Performs semantic search across all stored memories and resources +- Combines vector similarity with directory-aware retrieval +- Triggered by saying "ovs" or when agents need to recall information + +### Installing Skills + +Skills are installed by copying their documentation to your agent's skill directory: + +```bash +# Create skills directory +mkdir -p ~/.openclaw/skills + +# Copy skill files (example paths, adjust based on your agent setup) +cp examples/skills/adding-memory/SKILL.md ~/.openclaw/skills/adding-memory/ +cp examples/skills/adding-resource/SKILL.md ~/.openclaw/skills/adding-resource/ +cp examples/skills/searching-context/SKILL.md ~/.openclaw/skills/searching-context/ +``` + +**For agents:** Point your agent to the skill files in `examples/skills/`. The skill documentation contains the full specification for how to use each capability. + +### Using Skills + +Once skills are installed and the server is running: + +```bash +# Adding memory +ov add-memory "User prefers Python for data processing tasks" + +# Adding resource +ov add-resource https://example.com/docs --wait + +# Searching context +ov search "Python data processing" +``` + +**Note:** Skills require server mode to function properly. The server processes semantic operations significantly faster than embedded mode. + +--- + ## Configuration ### Server Configuration (ov.conf) @@ -234,6 +320,15 @@ Create the CLI configuration file at `~/.openviking/ovcli.conf`: | `url` | OpenViking server URL | `http://localhost:1933` | | `api_key` | API key for authentication | `null` (if server has no auth) | +**Note:** If your server runs on a different machine (cloud VM, remote server), update the URL accordingly: + +```json +{ + "url": "http://your-server-ip:1933", + "api_key": "your-api-key" +} +``` + **Alternative config location:** ```bash @@ -242,21 +337,9 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf --- -## Verification +## Running the Server -### Verify Python Package - -```bash -python -c " -import openviking as ov -print(f'OpenViking version: {ov.__version__}') -print('Python package installed successfully!') -" -``` - -### Verify Server - -1. **Start the server:** +Start the OpenViking server (required for skills and CLI): ```bash # Using the installed command @@ -274,7 +357,51 @@ Expected output: INFO: Uvicorn running on http://0.0.0.0:1933 ``` -2. **Check health endpoint:** +### Deployment Options + +The server can run **anywhere** - choose what fits your setup: + +| Deployment | Use Case | Setup | +|------------|----------|-------| +| **Local machine** | Personal development | `python -m openviking serve` | +| **Cloud VM** | Shared team resource | Deploy to AWS/GCP/Azure/Volcengine ECS | +| **Container** | Scalable deployment | Docker with `docker run` or Kubernetes | +| **Dedicated server** | Production workloads | Bare metal or VM with persistent storage | + +**Multi-client access:** Multiple devices (PCs, laptops, mobile) can connect to a single OpenViking server: + +``` +┌──────────────────────────────────────────────┐ +│ OpenViking Server │ +│ (Cloud VM / Container) │ +│ 203.0.113.1:1933 │ +└──────────────────────────────────────────────┘ + │ │ │ + ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ + │ov CLI │ │ov CLI │ │ov CLI │ + │(Work PC)│ │(Laptop)│ │(Home PC)│ + └─────────┘ └─────────┘ └─────────┘ +``` + +Each client uses the same `ovcli.conf` pointing to the shared server URL. + +**Cloud deployment guide:** See `docs/en/getting-started/03-quickstart-server.md` for detailed Volcengine ECS setup. + +--- + +## Verification + +### 1. Verify Python Package + +```bash +python -c " +import openviking as ov +print(f'OpenViking version: {ov.__version__}') +print('Python package installed successfully!') +" +``` + +### 2. Verify Server Health ```bash curl http://localhost:1933/health @@ -285,33 +412,23 @@ Expected output: {"status": "ok"} ``` -3. **Verify with Python SDK:** - -```python -import openviking as ov - -# Test connection -client = ov.SyncHTTPClient(url="http://localhost:1933") -client.initialize() -print("Server connection successful!") -client.close() -``` - -### Verify CLI +### 3. Verify CLI Connection ```bash # Check version ov --version -# Check system status (requires server running) +# Check system status ov system health -# Test basic commands +# List resources ov ls + +# Show config ov config show ``` -**Full integration test:** +### 4. Full Integration Test ```bash # Add a test resource @@ -324,40 +441,23 @@ ov ls viking://resources ov find "what is openviking" ``` ---- - -## Example Skills +### 5. Verify Skill Functionality -OpenViking includes example skills demonstrating common patterns. These are located in `examples/skills/`: - -| Skill | Description | Trigger | -|-------|-------------|---------| -| `adding-memory` | Store memories and learnings | `ovm` keyword | -| `adding-resource` | Import files, URLs, directories | `ovr` keyword | -| `searching-context` | Search memories and resources | `ovs` keyword | - -**Using example skills:** - -1. Review the skill documentation: - - `examples/skills/adding-memory/SKILL.md` - - `examples/skills/adding-resource/SKILL.md` - - `examples/skills/searching-context/SKILL.md` - -2. Test the skills with CLI: +Test each installed skill: ```bash -# Adding memory -ov add-memory "User prefers Python for data processing tasks" +# Test adding-memory (ovm) +ov add-memory "Test memory: User verification complete" +ov search "verification" -# Adding resource -ov add-resource https://example.com/docs --wait +# Test adding-resource (ovr) +ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/LICENSE --wait +ov ls viking://resources -# Searching context -ov search "Python data processing" +# Test searching-context (ovs) +ov search "Apache license" ``` -3. See `examples/skills/tests.md` for comprehensive test cases. - --- ## Troubleshooting @@ -375,7 +475,23 @@ pip install openviking uv pip install openviking ``` -#### 2. Connection refused when connecting to server +#### 2. ov: command not found + +**Cause:** `ov` not in PATH. + +**Solution:** +```bash +# Check if installed +cargo install --list | grep ov_cli + +# Add cargo bin to PATH +export PATH="$HOME/.cargo/bin:$PATH" + +# Or reinstall with full path +cargo install --path crates/ov_cli --force +``` + +#### 3. Connection refused when connecting to server **Cause:** Server not running or wrong URL. @@ -390,7 +506,7 @@ openviking-server # Verify URL in ovcli.conf matches server host/port ``` -#### 3. API key errors +#### 4. API key errors **Cause:** Invalid or missing API key in configuration. @@ -399,7 +515,7 @@ openviking-server - Verify key is valid with your model provider - Check `api_base` URL is correct -#### 4. Embedding model errors +#### 5. Embedding model errors **Cause:** Wrong dimension or model name. @@ -408,21 +524,14 @@ openviking-server - Common dimensions: 1024 (Doubao), 3072 (OpenAI text-embedding-3-large) - Check `input: "multimodal"` for vision embedding models -#### 5. CLI command not found +#### 6. Skills not responding -**Cause:** `ov` not in PATH. +**Cause:** Server not running or skills not properly configured. **Solution:** -```bash -# Check if installed -cargo install --list | grep ov_cli - -# Add cargo bin to PATH -export PATH="$HOME/.cargo/bin:$PATH" - -# Or reinstall with full path -cargo install --path crates/ov_cli --force -``` +- Verify server is running: `ov system health` +- Check skill files are in the correct location +- Ensure `ovcli.conf` points to the correct server URL ### Getting Help @@ -432,14 +541,17 @@ cargo install --path crates/ov_cli --force --- -## Next Steps - -After successful installation: +## Quick Reference -1. **Read the Quick Start:** See `README.md` or [docs](https://www.openviking.ai/docs) -2. **Try Examples:** Run `examples/quick_start.py` -3. **Explore Skills:** Review `examples/skills/` -4. **Server Deployment:** See `docs/en/getting-started/03-quickstart-server.md` +| Task | Command | +|------|---------| +| Start server | `openviking-server` | +| Check health | `curl http://localhost:1933/health` | +| Add memory | `ov add-memory "content"` | +| Add resource | `ov add-resource --wait` | +| Search | `ov search "query"` | +| List resources | `ov ls viking://resources` | +| System status | `ov system health` | --- @@ -447,11 +559,12 @@ After successful installation: - [ ] Python 3.10+ installed - [ ] `pip install openviking` completed successfully -- [ ] `ov` CLI installed (optional but recommended) +- [ ] `ov` CLI installed and in PATH (required) +- [ ] Skills copied to agent skill directory - [ ] `~/.openviking/ov.conf` created with model credentials -- [ ] `~/.openviking/ovcli.conf` created (for CLI usage) +- [ ] `~/.openviking/ovcli.conf` created with server URL - [ ] `OPENVIKING_CONFIG_FILE` environment variable set -- [ ] Server starts without errors +- [ ] Server started and running - [ ] Health endpoint returns `{"status": "ok"}` -- [ ] CLI can connect and list resources -- [ ] Example skills documentation reviewed +- [ ] CLI can connect and execute commands +- [ ] All three skills tested and working From 3dd696bfe51f6ce89924e07c739b577da0a3d566 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Mon, 23 Feb 2026 20:31:30 +0800 Subject: [PATCH 03/10] docs: update INSTALLATION.md with uv, skills usage, and config updates - Add Step 1: Install uv with instructions for macOS/Linux/Windows - Update expected version numbers: openviking 0.1.18, ov 0.1.0 - Add workspace field to full configuration template - Add OPENVIKING_CONFIG_DIR as alternative config method - Expand skills section with usage guide and chat trigger examples - Show how ovm/ovr/ovs keywords trigger skills during chat --- INSTALLATION.md | 109 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 85 insertions(+), 24 deletions(-) diff --git a/INSTALLATION.md b/INSTALLATION.md index 4e5563ec..03f67168 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -6,9 +6,10 @@ Complete installation guide for OpenViking - the Context Database for AI Agents. - [Overview](#overview) - [Prerequisites](#prerequisites) -- [Step 1: Install OpenViking Server](#step-1-install-openviking-server) -- [Step 2: Install ov CLI (Required)](#step-2-install-ov-cli-required) -- [Step 3: Install Skills](#step-3-install-skills) +- [Step 1: Install uv (Recommended)](#step-1-install-uv-recommended) +- [Step 2: Install OpenViking Server](#step-2-install-openviking-server) +- [Step 3: Install ov CLI (Required)](#step-3-install-ov-cli-required) +- [Step 4: Install Skills](#step-4-install-skills) - [Configuration](#configuration) - [Server Configuration (ov.conf)](#server-configuration-ovconf) - [CLI Configuration (ovcli.conf)](#cli-configuration-ovcliconf) @@ -83,31 +84,56 @@ Before installing OpenViking, ensure you have: --- -## Step 1: Install OpenViking Server +## Step 1: Install uv (Recommended) -Install the OpenViking server and Python SDK: +[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver. It's recommended for installing OpenViking. + +### Install uv +**macOS/Linux:** ```bash -pip install openviking +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -Or with `uv` (faster): +**Windows:** +```powershell +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` +**Verify installation:** +```bash +uv --version +``` + +Expected output: version number (e.g., `uv 0.5.x`) + +--- + +## Step 2: Install OpenViking Server + +Install the OpenViking server and Python SDK: + +**Using uv (recommended):** ```bash uv pip install openviking ``` +**Using pip:** +```bash +pip install openviking +``` + **Verify installation:** ```bash python -c "import openviking; print(openviking.__version__)" ``` -Expected output: version number (e.g., `0.2.0`) +Expected output: version number (e.g., `0.1.18`) --- -## Step 2: Install ov CLI (Required) +## Step 3: Install ov CLI (Required) The `ov` CLI is **required** for OpenViking. It provides: - Fast skill execution @@ -142,11 +168,11 @@ cargo install --git https://github.com/volcengine/OpenViking ov_cli ov --version ``` -Expected output: version number (e.g., `ov 0.2.0`) +Expected output: version number (e.g., `0.1.0`) --- -## Step 3: Install Skills +## Step 4: Install Skills Skills are agent capabilities that enable OpenViking's core functionality. Three skills are available: @@ -162,16 +188,19 @@ Skills are agent capabilities that enable OpenViking's core functionality. Three - Extracts and stores valuable insights from conversations - Builds persistent user profile, preferences, and learned patterns - Triggered by saying "ovm" or when agents identify memorable content +- **Usage:** During chat, provide the keyword `ovm` to trigger memory extraction. The skill concludes previous context and runs `ov add-memory` automatically. **adding-resource (ovr)** - Imports external content (files, URLs, directories) into OpenViking - Automatically processes with semantic analysis - Triggered by saying "ovr" or when agents encounter useful external content +- **Usage:** During chat, provide the keyword `ovr` to trigger resource import. The skill processes the resource and runs `ov add-resource` automatically. **searching-context (ovs)** - Performs semantic search across all stored memories and resources - Combines vector similarity with directory-aware retrieval - Triggered by saying "ovs" or when agents need to recall information +- **Usage:** During chat, provide the keyword `ovs` to trigger context search. The skill runs `ov search` automatically with the query context. ### Installing Skills @@ -204,6 +233,21 @@ ov add-resource https://example.com/docs --wait ov search "Python data processing" ``` +**Chat-based skill triggers:** + +``` +User: I prefer using vim over IDE for coding +User: ovm ← Triggers adding-memory skill + (extracts and stores this preference) + +User: Please add this doc https://example.com/api +User: ovr ← Triggers adding-resource skill + (imports and processes the URL) + +User: ovs What was my editor preference? ← Triggers searching-context skill + (searches for stored memories) +``` + **Note:** Skills require server mode to function properly. The server processes semantic operations significantly faster than embedded mode. --- @@ -252,14 +296,14 @@ mkdir -p ~/.openviking "cors_origins": ["*"] }, "storage": { + "workspace": "./data", "vectordb": { "name": "context", "backend": "local", - "path": "./data" + "project": "default" }, "agfs": { "port": 1833, - "path": "./data", "backend": "local" } }, @@ -276,8 +320,8 @@ mkdir -p ~/.openviking "vlm": { "provider": "volcengine", "model": "doubao-seed-1-8-251228", - "api_key": "your-api-key", - "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", "temperature": 0.0, "max_retries": 2 }, @@ -285,21 +329,32 @@ mkdir -p ~/.openviking "auto_generate_l1": true, "default_search_mode": "thinking", "default_search_limit": 3, - "log_level": "INFO" + "log": { + "level": "INFO", + "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", + "output": "stdout", + "rotation": true, + "rotation_days": 3 + } } ``` -**Set environment variable:** +**Configuration via environment variables:** + +Instead of setting `OPENVIKING_CONFIG_FILE` to point to a specific file, you can set the config directory. OpenViking will look for `ov.conf` in that directory: ```bash -# Linux/macOS +# Linux/macOS - Set config directory +export OPENVIKING_CONFIG_DIR=~/.openviking + +# Or set specific config file export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # Windows (PowerShell) -$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" +$env:OPENVIKING_CONFIG_DIR = "$HOME/.openviking" # Windows (CMD) -set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" +set "OPENVIKING_CONFIG_DIR=%USERPROFILE%\.openviking" ``` --- @@ -470,9 +525,11 @@ ov search "Apache license" **Solution:** ```bash -pip install openviking -# or +# Using uv (recommended) uv pip install openviking + +# Or using pip +pip install openviking ``` #### 2. ov: command not found @@ -552,18 +609,22 @@ openviking-server | Search | `ov search "query"` | | List resources | `ov ls viking://resources` | | System status | `ov system health` | +| Trigger memory | Say `ovm` in chat | +| Trigger resource | Say `ovr` in chat | +| Trigger search | Say `ovs ` in chat | --- ## Summary Checklist +- [ ] uv installed (recommended) - [ ] Python 3.10+ installed -- [ ] `pip install openviking` completed successfully +- [ ] `uv pip install openviking` completed successfully - [ ] `ov` CLI installed and in PATH (required) - [ ] Skills copied to agent skill directory - [ ] `~/.openviking/ov.conf` created with model credentials - [ ] `~/.openviking/ovcli.conf` created with server URL -- [ ] `OPENVIKING_CONFIG_FILE` environment variable set +- [ ] `OPENVIKING_CONFIG_DIR` or `OPENVIKING_CONFIG_FILE` environment variable set - [ ] Server started and running - [ ] Health endpoint returns `{"status": "ok"}` - [ ] CLI can connect and execute commands From 610c1a8a46067d6d727fa5cb9410ddba93c00c8f Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Mon, 23 Feb 2026 20:34:56 +0800 Subject: [PATCH 04/10] docs: make uv the only supported installation method - Remove pip as an alternative - uv is now the one and only way - Emphasize uv automatically manages virtual environments - Update all commands to use uv (uv pip install, uv run python, etc.) - Remove 'recommended' qualifiers - uv is required, not optional --- INSTALLATION.md | 46 +++++++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 27 deletions(-) diff --git a/INSTALLATION.md b/INSTALLATION.md index 03f67168..f380a853 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -6,7 +6,7 @@ Complete installation guide for OpenViking - the Context Database for AI Agents. - [Overview](#overview) - [Prerequisites](#prerequisites) -- [Step 1: Install uv (Recommended)](#step-1-install-uv-recommended) +- [Step 1: Install uv](#step-1-install-uv) - [Step 2: Install OpenViking Server](#step-2-install-openviking-server) - [Step 3: Install ov CLI (Required)](#step-3-install-ov-cli-required) - [Step 4: Install Skills](#step-4-install-skills) @@ -84,9 +84,9 @@ Before installing OpenViking, ensure you have: --- -## Step 1: Install uv (Recommended) +## Step 1: Install uv -[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver. It's recommended for installing OpenViking. +[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver. **uv is the recommended and only supported way to install OpenViking** - it automatically manages virtual environments, ensuring clean, isolated installations without polluting your system Python. ### Install uv @@ -111,22 +111,16 @@ Expected output: version number (e.g., `uv 0.5.x`) ## Step 2: Install OpenViking Server -Install the OpenViking server and Python SDK: +Install the OpenViking server and Python SDK using uv. **uv automatically creates and manages a virtual environment** - no manual `venv` or `source venv/bin/activate` needed. -**Using uv (recommended):** ```bash uv pip install openviking ``` -**Using pip:** -```bash -pip install openviking -``` - **Verify installation:** ```bash -python -c "import openviking; print(openviking.__version__)" +uv run python -c "import openviking; print(openviking.__version__)" ``` Expected output: version number (e.g., `0.1.18`) @@ -397,14 +391,14 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf Start the OpenViking server (required for skills and CLI): ```bash -# Using the installed command -openviking-server +# Using uv (recommended) - automatically uses virtual environment +uv run openviking-server -# Or using Python module -python -m openviking serve +# Or using Python module with uv +uv run python -m openviking serve # With custom config -python -m openviking serve --config /path/to/ov.conf --port 1933 +uv run python -m openviking serve --config /path/to/ov.conf --port 1933 ``` Expected output: @@ -418,7 +412,7 @@ The server can run **anywhere** - choose what fits your setup: | Deployment | Use Case | Setup | |------------|----------|-------| -| **Local machine** | Personal development | `python -m openviking serve` | +| **Local machine** | Personal development | `uv run openviking-server` | | **Cloud VM** | Shared team resource | Deploy to AWS/GCP/Azure/Volcengine ECS | | **Container** | Scalable deployment | Docker with `docker run` or Kubernetes | | **Dedicated server** | Production workloads | Bare metal or VM with persistent storage | @@ -449,7 +443,7 @@ Each client uses the same `ovcli.conf` pointing to the shared server URL. ### 1. Verify Python Package ```bash -python -c " +uv run python -c " import openviking as ov print(f'OpenViking version: {ov.__version__}') print('Python package installed successfully!') @@ -525,11 +519,8 @@ ov search "Apache license" **Solution:** ```bash -# Using uv (recommended) +# Using uv (the only supported method) uv pip install openviking - -# Or using pip -pip install openviking ``` #### 2. ov: command not found @@ -557,8 +548,8 @@ cargo install --path crates/ov_cli --force # Check if server is running ps aux | grep openviking-server -# Start server -openviking-server +# Start server with uv +uv run openviking-server # Verify URL in ovcli.conf matches server host/port ``` @@ -602,7 +593,8 @@ openviking-server | Task | Command | |------|---------| -| Start server | `openviking-server` | +| Install package | `uv pip install openviking` | +| Start server | `uv run openviking-server` | | Check health | `curl http://localhost:1933/health` | | Add memory | `ov add-memory "content"` | | Add resource | `ov add-resource --wait` | @@ -617,7 +609,7 @@ openviking-server ## Summary Checklist -- [ ] uv installed (recommended) +- [ ] uv installed (required) - [ ] Python 3.10+ installed - [ ] `uv pip install openviking` completed successfully - [ ] `ov` CLI installed and in PATH (required) @@ -625,7 +617,7 @@ openviking-server - [ ] `~/.openviking/ov.conf` created with model credentials - [ ] `~/.openviking/ovcli.conf` created with server URL - [ ] `OPENVIKING_CONFIG_DIR` or `OPENVIKING_CONFIG_FILE` environment variable set -- [ ] Server started and running +- [ ] Server started with `uv run openviking-server` - [ ] Health endpoint returns `{"status": "ok"}` - [ ] CLI can connect and execute commands - [ ] All three skills tested and working From 4b340947ad280be99d4a6594c02297187e96a14f Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Mon, 23 Feb 2026 21:04:28 +0800 Subject: [PATCH 05/10] docs: simplify installation guide and add advanced guide Major restructuring for clarity: INSTALLATION.md (Quick Guide): - Focus only on essential steps to get skills running - Use uv tool install for clean, standalone installation - Include nohup command for background server execution - Simple 6-step process: uv -> server -> ov CLI -> config -> start -> skills - Add skill usage examples with ovm/ovr/ovs keywords - Quick test section for immediate verification - Reference advanced guide for detailed options INSTALLATION_ADVANCED.md (New): - Full configuration reference with all fields - Alternative installation methods (pip, dev, manual venv) - Cloud deployment guides (Volcengine ECS, AWS/GCP/Azure) - Docker and Kubernetes examples - Multiple model provider configs (OpenAI, Anthropic, vLLM) - Authentication, security, HTTPS setup - Systemd service configuration - Performance tuning and troubleshooting --- INSTALLATION.md | 606 +++++++------------------------------ INSTALLATION_ADVANCED.md | 632 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 733 insertions(+), 505 deletions(-) create mode 100644 INSTALLATION_ADVANCED.md diff --git a/INSTALLATION.md b/INSTALLATION.md index f380a853..29a3e1b2 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,94 +1,14 @@ # OpenViking Installation Guide -Complete installation guide for OpenViking - the Context Database for AI Agents. - -## Table of Contents - -- [Overview](#overview) -- [Prerequisites](#prerequisites) -- [Step 1: Install uv](#step-1-install-uv) -- [Step 2: Install OpenViking Server](#step-2-install-openviking-server) -- [Step 3: Install ov CLI (Required)](#step-3-install-ov-cli-required) -- [Step 4: Install Skills](#step-4-install-skills) -- [Configuration](#configuration) - - [Server Configuration (ov.conf)](#server-configuration-ovconf) - - [CLI Configuration (ovcli.conf)](#cli-configuration-ovcliconf) -- [Running the Server](#running-the-server) -- [Verification](#verification) -- [Troubleshooting](#troubleshooting) +Quick installation guide for OpenViking - the Context Database for AI Agents. ---- - -## Overview - -OpenViking consists of three components: - -1. **OpenViking Server** - The core context database (Python package) -2. **ov CLI** - Command-line interface for fast skill execution (Rust binary) **REQUIRED** -3. **Skills** - Agent capabilities for memory, resources, and search - -**Architecture:** - -``` -┌─────────────────────────────────────────────────────────────┐ -│ OpenViking Server │ -│ (Runs anywhere: local, │ -│ cloud, VM, container, etc.) │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Skills │ │ Memory │ │ Resources │ │ -│ │ (installed) │ │ (context) │ │ (files/URLs)│ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ┌─────────────┼─────────────┐ - │ │ │ - ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ - │ ov CLI │ │ ov CLI │ │ ov CLI │ - │ (PC) │ │ (Laptop)│ │ (Mobile)│ - └─────────┘ └─────────┘ └─────────┘ -``` - -**Key Benefits:** -- **Server can run anywhere** - local machine, cloud VM, container, or dedicated server -- **Multiple clients can share one server** - PC, laptop, mobile devices all connect to the same OpenViking instance -- **ov CLI is required** - enables fast skill execution and is the primary interface for agent operations -- **Server mode is required for skills** - provides better performance and enables skill functionality - ---- - -## Prerequisites - -Before installing OpenViking, ensure you have: - -| Requirement | Version | Notes | -|-------------|---------|-------| -| Python | 3.10+ | Required for server | -| Rust | Latest | Required for building ov CLI | -| Operating System | Linux, macOS, Windows | All supported | -| Network | Stable connection | For model APIs and dependencies | -| API Keys | VLM + Embedding | From your model provider(s) | - -**Supported Model Providers:** -- Volcengine (Doubao) -- OpenAI -- Anthropic (Claude) -- DeepSeek -- Google (Gemini) -- Moonshot (Kimi) -- Zhipu (GLM) -- DashScope (Qwen) -- MiniMax -- OpenRouter -- vLLM (local models) +**Goal:** Get OpenViking running with skills in 5 minutes. --- -## Step 1: Install uv - -[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver. **uv is the recommended and only supported way to install OpenViking** - it automatically manages virtual environments, ensuring clean, isolated installations without polluting your system Python. +## Quick Install -### Install uv +### 1. Install uv **macOS/Linux:** ```bash @@ -100,165 +20,35 @@ curl -LsSf https://astral.sh/uv/install.sh | sh powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` -**Verify installation:** -```bash -uv --version -``` - -Expected output: version number (e.g., `uv 0.5.x`) - ---- - -## Step 2: Install OpenViking Server - -Install the OpenViking server and Python SDK using uv. **uv automatically creates and manages a virtual environment** - no manual `venv` or `source venv/bin/activate` needed. - -```bash -uv pip install openviking -``` - -**Verify installation:** +### 2. Install OpenViking Server ```bash -uv run python -c "import openviking; print(openviking.__version__)" +uv tool install openviking ``` -Expected output: version number (e.g., `0.1.18`) - ---- - -## Step 3: Install ov CLI (Required) - -The `ov` CLI is **required** for OpenViking. It provides: -- Fast skill execution -- Primary interface for agent operations -- Efficient communication with the server +This installs `openviking-server` as a standalone tool you can run anywhere. -### Quick Install (Linux/macOS) +### 3. Install ov CLI (Required for Skills) ```bash curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash ``` -### Install from Source - -Requires Rust toolchain: - +Or install from source: ```bash -# Clone the repository git clone https://github.com/volcengine/OpenViking.git cd OpenViking - -# Install with cargo cargo install --path crates/ov_cli - -# Or install directly from git -cargo install --git https://github.com/volcengine/OpenViking ov_cli -``` - -**Verify installation:** - -```bash -ov --version -``` - -Expected output: version number (e.g., `0.1.0`) - ---- - -## Step 4: Install Skills - -Skills are agent capabilities that enable OpenViking's core functionality. Three skills are available: - -| Skill | Description | Trigger Keyword | Files | -|-------|-------------|-----------------|-------| -| **adding-memory** | Store memories and learnings from conversations | `ovm` | `examples/skills/adding-memory/SKILL.md` | -| **adding-resource** | Import files, URLs, or directories into context | `ovr` | `examples/skills/adding-resource/SKILL.md` | -| **searching-context** | Search memories and resources semantically | `ovs` | `examples/skills/searching-context/SKILL.md` | - -### What Each Skill Does - -**adding-memory (ovm)** -- Extracts and stores valuable insights from conversations -- Builds persistent user profile, preferences, and learned patterns -- Triggered by saying "ovm" or when agents identify memorable content -- **Usage:** During chat, provide the keyword `ovm` to trigger memory extraction. The skill concludes previous context and runs `ov add-memory` automatically. - -**adding-resource (ovr)** -- Imports external content (files, URLs, directories) into OpenViking -- Automatically processes with semantic analysis -- Triggered by saying "ovr" or when agents encounter useful external content -- **Usage:** During chat, provide the keyword `ovr` to trigger resource import. The skill processes the resource and runs `ov add-resource` automatically. - -**searching-context (ovs)** -- Performs semantic search across all stored memories and resources -- Combines vector similarity with directory-aware retrieval -- Triggered by saying "ovs" or when agents need to recall information -- **Usage:** During chat, provide the keyword `ovs` to trigger context search. The skill runs `ov search` automatically with the query context. - -### Installing Skills - -Skills are installed by copying their documentation to your agent's skill directory: - -```bash -# Create skills directory -mkdir -p ~/.openclaw/skills - -# Copy skill files (example paths, adjust based on your agent setup) -cp examples/skills/adding-memory/SKILL.md ~/.openclaw/skills/adding-memory/ -cp examples/skills/adding-resource/SKILL.md ~/.openclaw/skills/adding-resource/ -cp examples/skills/searching-context/SKILL.md ~/.openclaw/skills/searching-context/ -``` - -**For agents:** Point your agent to the skill files in `examples/skills/`. The skill documentation contains the full specification for how to use each capability. - -### Using Skills - -Once skills are installed and the server is running: - -```bash -# Adding memory -ov add-memory "User prefers Python for data processing tasks" - -# Adding resource -ov add-resource https://example.com/docs --wait - -# Searching context -ov search "Python data processing" -``` - -**Chat-based skill triggers:** - -``` -User: I prefer using vim over IDE for coding -User: ovm ← Triggers adding-memory skill - (extracts and stores this preference) - -User: Please add this doc https://example.com/api -User: ovr ← Triggers adding-resource skill - (imports and processes the URL) - -User: ovs What was my editor preference? ← Triggers searching-context skill - (searches for stored memories) ``` -**Note:** Skills require server mode to function properly. The server processes semantic operations significantly faster than embedded mode. - ---- - -## Configuration - -### Server Configuration (ov.conf) +### 4. Configure and Start Server -Create the server configuration file at `~/.openviking/ov.conf`: +Create config directory and config file: ```bash mkdir -p ~/.openviking -``` -**Minimal configuration:** - -```json +cat > ~/.openviking/ov.conf << 'EOF' { "embedding": { "dense": { @@ -275,349 +65,155 @@ mkdir -p ~/.openviking "model": "doubao-seed-1-8-251228", "api_key": "your-api-key", "api_base": "https://ark.cn-beijing.volces.com/api/v3" - } -} -``` - -**Full configuration template** (see `examples/ov.conf.example`): - -```json -{ - "server": { - "host": "0.0.0.0", - "port": 1933, - "api_key": null, - "cors_origins": ["*"] }, "storage": { - "workspace": "./data", - "vectordb": { - "name": "context", - "backend": "local", - "project": "default" - }, - "agfs": { - "port": 1833, - "backend": "local" - } - }, - "embedding": { - "dense": { - "provider": "volcengine", - "model": "doubao-embedding-vision-250615", - "api_key": "your-api-key", - "api_base": "https://ark.cn-beijing.volces.com/api/v3", - "dimension": 1024, - "input": "multimodal" - } - }, - "vlm": { - "provider": "volcengine", - "model": "doubao-seed-1-8-251228", - "api_key": "your-api-key", - "api_base": "https://ark.cn-beijing.volces.com/api/v3", - "temperature": 0.0, - "max_retries": 2 - }, - "auto_generate_l0": true, - "auto_generate_l1": true, - "default_search_mode": "thinking", - "default_search_limit": 3, - "log": { - "level": "INFO", - "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", - "output": "stdout", - "rotation": true, - "rotation_days": 3 + "workspace": "~/.openviking/data" } } +EOF ``` -**Configuration via environment variables:** +**Replace `your-api-key` with your actual API key.** -Instead of setting `OPENVIKING_CONFIG_FILE` to point to a specific file, you can set the config directory. OpenViking will look for `ov.conf` in that directory: +Start the server in background: ```bash -# Linux/macOS - Set config directory export OPENVIKING_CONFIG_DIR=~/.openviking - -# Or set specific config file -export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf - -# Windows (PowerShell) -$env:OPENVIKING_CONFIG_DIR = "$HOME/.openviking" - -# Windows (CMD) -set "OPENVIKING_CONFIG_DIR=%USERPROFILE%\.openviking" +nohup openviking-server > ~/.openviking/server.log 2>&1 & ``` ---- - -### CLI Configuration (ovcli.conf) - -Create the CLI configuration file at `~/.openviking/ovcli.conf`: - -```json -{ - "url": "http://localhost:1933", - "api_key": "your-api-key" -} +Check it's running: +```bash +curl http://localhost:1933/health +# Should return: {"status": "ok"} ``` -| Field | Description | Default | -|-------|-------------|---------| -| `url` | OpenViking server URL | `http://localhost:1933` | -| `api_key` | API key for authentication | `null` (if server has no auth) | +### 5. Configure CLI -**Note:** If your server runs on a different machine (cloud VM, remote server), update the URL accordingly: - -```json +```bash +cat > ~/.openviking/ovcli.conf << 'EOF' { - "url": "http://your-server-ip:1933", - "api_key": "your-api-key" + "url": "http://localhost:1933" } +EOF ``` -**Alternative config location:** +### 6. Install Skills -```bash -export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf -``` - ---- - -## Running the Server - -Start the OpenViking server (required for skills and CLI): +Skills enable agents to use OpenViking. Install them to your agent's skill directory: ```bash -# Using uv (recommended) - automatically uses virtual environment -uv run openviking-server - -# Or using Python module with uv -uv run python -m openviking serve - -# With custom config -uv run python -m openviking serve --config /path/to/ov.conf --port 1933 -``` - -Expected output: -``` -INFO: Uvicorn running on http://0.0.0.0:1933 -``` - -### Deployment Options - -The server can run **anywhere** - choose what fits your setup: - -| Deployment | Use Case | Setup | -|------------|----------|-------| -| **Local machine** | Personal development | `uv run openviking-server` | -| **Cloud VM** | Shared team resource | Deploy to AWS/GCP/Azure/Volcengine ECS | -| **Container** | Scalable deployment | Docker with `docker run` or Kubernetes | -| **Dedicated server** | Production workloads | Bare metal or VM with persistent storage | - -**Multi-client access:** Multiple devices (PCs, laptops, mobile) can connect to a single OpenViking server: +mkdir -p ~/.openclaw/skills +# Copy skills from OpenViking examples +cp -r /path/to/openviking/examples/skills/adding-memory ~/.openclaw/skills/ +cp -r /path/to/openviking/examples/skills/adding-resource ~/.openclaw/skills/ +cp -r /path/to/openviking/examples/skills/searching-context ~/.openclaw/skills/ ``` -┌──────────────────────────────────────────────┐ -│ OpenViking Server │ -│ (Cloud VM / Container) │ -│ 203.0.113.1:1933 │ -└──────────────────────────────────────────────┘ - │ │ │ - ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ - │ov CLI │ │ov CLI │ │ov CLI │ - │(Work PC)│ │(Laptop)│ │(Home PC)│ - └─────────┘ └─────────┘ └─────────┘ -``` - -Each client uses the same `ovcli.conf` pointing to the shared server URL. - -**Cloud deployment guide:** See `docs/en/getting-started/03-quickstart-server.md` for detailed Volcengine ECS setup. - ---- - -## Verification - -### 1. Verify Python Package +Or download directly: ```bash -uv run python -c " -import openviking as ov -print(f'OpenViking version: {ov.__version__}') -print('Python package installed successfully!') -" -``` +mkdir -p ~/.openclaw/skills/adding-memory +curl -o ~/.openclaw/skills/adding-memory/SKILL.md \ + https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-memory/SKILL.md -### 2. Verify Server Health +mkdir -p ~/.openclaw/skills/adding-resource +curl -o ~/.openclaw/skills/adding-resource/SKILL.md \ + https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-resource/SKILL.md -```bash -curl http://localhost:1933/health +mkdir -p ~/.openclaw/skills/searching-context +curl -o ~/.openclaw/skills/searching-context/SKILL.md \ + https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/searching-context/SKILL.md ``` -Expected output: -```json -{"status": "ok"} -``` - -### 3. Verify CLI Connection - -```bash -# Check version -ov --version - -# Check system status -ov system health - -# List resources -ov ls - -# Show config -ov config show -``` +--- -### 4. Full Integration Test +## Using Skills -```bash -# Add a test resource -ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md --wait +Once installed, agents can use these keywords during chat: -# List resources -ov ls viking://resources +| Keyword | Skill | What It Does | +|---------|-------|--------------| +| `ovm` | adding-memory | Extracts and stores insights from conversation | +| `ovr` | adding-resource | Imports files/URLs into OpenViking | +| `ovs` | searching-context | Searches stored memories and resources | -# Search -ov find "what is openviking" +**Example chat flow:** ``` +User: I prefer using vim for coding +User: ovm +→ Agent extracts and stores: "User prefers vim for coding" -### 5. Verify Skill Functionality - -Test each installed skill: +User: Please add https://example.com/docs +User: ovr +→ Agent imports and processes the URL -```bash -# Test adding-memory (ovm) -ov add-memory "Test memory: User verification complete" -ov search "verification" - -# Test adding-resource (ovr) -ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/LICENSE --wait -ov ls viking://resources - -# Test searching-context (ovs) -ov search "Apache license" +User: ovs What's my editor preference? +→ Agent searches and returns: "User prefers vim for coding" ``` --- -## Troubleshooting - -### Common Issues - -#### 1. Import Error: No module named 'openviking' +## Quick Test -**Cause:** Package not installed or wrong Python environment. +Verify everything works: -**Solution:** ```bash -# Using uv (the only supported method) -uv pip install openviking -``` - -#### 2. ov: command not found - -**Cause:** `ov` not in PATH. - -**Solution:** -```bash -# Check if installed -cargo install --list | grep ov_cli - -# Add cargo bin to PATH -export PATH="$HOME/.cargo/bin:$PATH" - -# Or reinstall with full path -cargo install --path crates/ov_cli --force -``` - -#### 3. Connection refused when connecting to server - -**Cause:** Server not running or wrong URL. - -**Solution:** -```bash -# Check if server is running -ps aux | grep openviking-server +# Test CLI connection +ov system health -# Start server with uv -uv run openviking-server +# Test adding memory +ov add-memory "Test: OpenViking is working" -# Verify URL in ovcli.conf matches server host/port +# Test searching +ov search "OpenViking working" ``` -#### 4. API key errors - -**Cause:** Invalid or missing API key in configuration. - -**Solution:** -- Check `api_key` in `~/.openviking/ov.conf` -- Verify key is valid with your model provider -- Check `api_base` URL is correct +--- -#### 5. Embedding model errors +## Advanced Configuration -**Cause:** Wrong dimension or model name. +For advanced setup options (cloud deployment, custom storage, multiple model providers, etc.), see: -**Solution:** -- Verify `dimension` matches your embedding model -- Common dimensions: 1024 (Doubao), 3072 (OpenAI text-embedding-3-large) -- Check `input: "multimodal"` for vision embedding models +**[INSTALLATION_ADVANCED.md](./INSTALLATION_ADVANCED.md)** -#### 6. Skills not responding +This includes: +- Full configuration reference +- Cloud deployment guides +- Docker/container setup +- Multiple model providers +- Authentication and security +- Troubleshooting deep dives -**Cause:** Server not running or skills not properly configured. +--- -**Solution:** -- Verify server is running: `ov system health` -- Check skill files are in the correct location -- Ensure `ovcli.conf` points to the correct server URL +## Requirements -### Getting Help +- Python 3.10+ +- Rust (for building ov CLI) +- API keys for VLM and embedding models -- **Documentation:** https://www.openviking.ai/docs -- **GitHub Issues:** https://github.com/volcengine/OpenViking/issues -- **Discord:** https://discord.com/invite/eHvx8E9XF3 +**Supported Model Providers:** Volcengine, OpenAI, Anthropic, DeepSeek, Google, Moonshot, Zhipu, DashScope, MiniMax, OpenRouter, vLLM --- ## Quick Reference -| Task | Command | -|------|---------| -| Install package | `uv pip install openviking` | -| Start server | `uv run openviking-server` | -| Check health | `curl http://localhost:1933/health` | -| Add memory | `ov add-memory "content"` | -| Add resource | `ov add-resource --wait` | -| Search | `ov search "query"` | -| List resources | `ov ls viking://resources` | -| System status | `ov system health` | -| Trigger memory | Say `ovm` in chat | -| Trigger resource | Say `ovr` in chat | -| Trigger search | Say `ovs ` in chat | +```bash +# Install +uv tool install openviking +curl -fsSL .../install.sh | bash # ov CLI ---- +# Start server (background) +export OPENVIKING_CONFIG_DIR=~/.openviking +nohup openviking-server > ~/.openviking/server.log 2>&1 & -## Summary Checklist - -- [ ] uv installed (required) -- [ ] Python 3.10+ installed -- [ ] `uv pip install openviking` completed successfully -- [ ] `ov` CLI installed and in PATH (required) -- [ ] Skills copied to agent skill directory -- [ ] `~/.openviking/ov.conf` created with model credentials -- [ ] `~/.openviking/ovcli.conf` created with server URL -- [ ] `OPENVIKING_CONFIG_DIR` or `OPENVIKING_CONFIG_FILE` environment variable set -- [ ] Server started with `uv run openviking-server` -- [ ] Health endpoint returns `{"status": "ok"}` -- [ ] CLI can connect and execute commands -- [ ] All three skills tested and working +# Stop server +pkill openviking-server + +# CLI commands +ov system health # Check server +ov add-memory "text" # Add memory +ov add-resource # Add resource +ov search "query" # Search context +``` diff --git a/INSTALLATION_ADVANCED.md b/INSTALLATION_ADVANCED.md new file mode 100644 index 00000000..96bbda25 --- /dev/null +++ b/INSTALLATION_ADVANCED.md @@ -0,0 +1,632 @@ +# OpenViking Installation Guide (Advanced) + +Detailed configuration and deployment options for OpenViking. + +For the quick start guide, see **[INSTALLATION.md](./INSTALLATION.md)**. + +--- + +## Table of Contents + +- [Full Configuration Reference](#full-configuration-reference) +- [Alternative Installation Methods](#alternative-installation-methods) +- [Cloud Deployment](#cloud-deployment) +- [Docker/Container Setup](#dockercontainer-setup) +- [Multiple Model Providers](#multiple-model-providers) +- [Authentication and Security](#authentication-and-security) +- [Advanced Troubleshooting](#advanced-troubleshooting) + +--- + +## Full Configuration Reference + +### Complete ov.conf Template + +```json +{ + "server": { + "host": "0.0.0.0", + "port": 1933, + "api_key": null, + "cors_origins": ["*"] + }, + "storage": { + "workspace": "./data", + "vectordb": { + "name": "context", + "backend": "local", + "project": "default", + "volcengine": { + "region": "cn-beijing", + "ak": null, + "sk": null + } + }, + "agfs": { + "port": 1833, + "log_level": "warn", + "backend": "local", + "timeout": 10, + "retry_times": 3, + "s3": { + "bucket": null, + "region": null, + "access_key": null, + "secret_key": null, + "endpoint": null, + "prefix": "", + "use_ssl": true + } + } + }, + "embedding": { + "dense": { + "provider": "volcengine", + "model": "doubao-embedding-vision-250615", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "dimension": 1024, + "input": "multimodal" + } + }, + "vlm": { + "provider": "volcengine", + "model": "doubao-seed-1-8-251228", + "api_key": "your-api-key", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "temperature": 0.0, + "max_retries": 2, + "thinking": false + }, + "rerank": { + "ak": null, + "sk": null, + "host": "api-vikingdb.vikingdb.cn-beijing.volces.com", + "model_name": "doubao-seed-rerank", + "model_version": "251028", + "threshold": 0.1 + }, + "auto_generate_l0": true, + "auto_generate_l1": true, + "default_search_mode": "thinking", + "default_search_limit": 3, + "enable_memory_decay": true, + "memory_decay_check_interval": 3600, + "log": { + "level": "INFO", + "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", + "output": "stdout", + "rotation": true, + "rotation_days": 3, + "rotation_interval": "midnight" + }, + "parsers": { + "pdf": { + "strategy": "auto", + "max_content_length": 100000, + "max_section_size": 4000, + "section_size_flexibility": 0.3, + "mineru_endpoint": "https://mineru.example.com/api/v1", + "mineru_api_key": "{your-mineru-api-key}", + "mineru_timeout": 300.0 + }, + "code": { + "enable_ast": true, + "extract_functions": true, + "extract_classes": true, + "extract_imports": true, + "include_comments": true, + "max_line_length": 1000, + "max_token_limit": 50000, + "truncation_strategy": "head", + "warn_on_truncation": true + }, + "image": { + "enable_ocr": false, + "enable_vlm": true, + "ocr_lang": "eng", + "vlm_model": "gpt-4-vision", + "max_dimension": 2048 + }, + "audio": { + "enable_transcription": true, + "transcription_model": "whisper-large-v3", + "language": null, + "extract_metadata": true + }, + "video": { + "extract_frames": true, + "frame_interval": 10.0, + "enable_transcription": true, + "enable_vlm_description": false, + "max_duration": 3600.0 + }, + "markdown": { + "preserve_links": true, + "extract_frontmatter": true, + "include_metadata": true, + "max_heading_depth": 3 + }, + "html": { + "extract_text_only": false, + "preserve_structure": true, + "clean_html": true, + "extract_metadata": true + }, + "text": { + "detect_language": true, + "split_by_paragraphs": true, + "max_paragraph_length": 1000, + "preserve_line_breaks": false + } + } +} +``` + +### Configuration Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `server.host` | string | `"0.0.0.0"` | Server bind address | +| `server.port` | int | `1933` | Server port | +| `server.api_key` | string | `null` | API key for authentication | +| `storage.workspace` | string | `"./data"` | Main data directory | +| `storage.vectordb.backend` | string | `"local"` | Vector DB backend: local, volcengine | +| `storage.agfs.backend` | string | `"local"` | AGFS backend: local, s3 | +| `embedding.dense.provider` | string | `"volcengine"` | Embedding provider | +| `embedding.dense.dimension` | int | `1024` | Vector dimension | +| `vlm.provider` | string | `"volcengine"` | VLM provider | +| `vlm.temperature` | float | `0.0` | Model temperature | +| `auto_generate_l0` | bool | `true` | Auto-generate abstracts | +| `auto_generate_l1` | bool | `true` | Auto-generate overviews | +| `log.level` | string | `"INFO"` | Log level: DEBUG, INFO, WARN, ERROR | + +### Environment Variables + +```bash +# Set config file location +export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf + +# Or set config directory (looks for ov.conf in that dir) +export OPENVIKING_CONFIG_DIR=~/.openviking + +# Set CLI config location +export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf +``` + +--- + +## Alternative Installation Methods + +### Using pip (not recommended) + +While uv is the recommended method, you can also use pip: + +```bash +pip install openviking +``` + +### Development Installation + +Install from source for development: + +```bash +git clone https://github.com/volcengine/OpenViking.git +cd OpenViking +uv pip install -e ".[dev,test]" +``` + +### Virtual Environment (manual) + +If not using uv's automatic virtualenv: + +```bash +python -m venv venv +source venv/bin/activate # Linux/macOS +# or +venv\Scripts\activate # Windows + +pip install openviking +``` + +--- + +## Cloud Deployment + +### Volcengine ECS (Recommended) + +See detailed guide: `docs/en/getting-started/03-quickstart-server.md` + +Quick setup: + +```bash +# 1. Create ECS instance with veLinux 2.0 +# 2. Mount data disk to /data +mkdir -p /data + +# 3. Install uv and openviking +curl -LsSf https://astral.sh/uv/install.sh | sh +uv tool install openviking + +# 4. Configure +mkdir -p ~/.openviking +# Create ov.conf with your API keys + +# 5. Start with nohup +export OPENVIKING_CONFIG_DIR=~/.openviking +nohup openviking-server > /data/openviking.log 2>&1 & +``` + +### AWS/GCP/Azure + +General cloud VM setup: + +```bash +# Update system +sudo apt update && sudo apt upgrade -y # Ubuntu/Debian +# or +sudo yum update -y # CentOS/RHEL + +# Install dependencies +sudo apt install -y curl git # Ubuntu/Debian + +# Install uv +curl -LsSf https://astral.sh/uv/install.sh | sh +source $HOME/.cargo/env + +# Install openviking +uv tool install openviking + +# Configure firewall (example for UFW) +sudo ufw allow 1933/tcp + +# Setup systemd service (see below) +``` + +### Systemd Service + +Create `/etc/systemd/system/openviking.service`: + +```ini +[Unit] +Description=OpenViking Server +After=network.target + +[Service] +Type=simple +User=openviking +Environment=OPENVIKING_CONFIG_DIR=/home/openviking/.openviking +ExecStart=/home/openviking/.cargo/bin/openviking-server +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable openviking +sudo systemctl start openviking +sudo systemctl status openviking +``` + +--- + +## Docker/Container Setup + +### Docker Run + +```bash +docker run -d \ + --name openviking \ + -p 1933:1933 \ + -v $(pwd)/data:/data \ + -v $(pwd)/ov.conf:/app/ov.conf \ + -e OPENVIKING_CONFIG_FILE=/app/ov.conf \ + volcengine/openviking:latest +``` + +### Docker Compose + +```yaml +version: '3.8' + +services: + openviking: + image: volcengine/openviking:latest + ports: + - "1933:1933" + volumes: + - ./data:/data + - ./ov.conf:/app/ov.conf + environment: + - OPENVIKING_CONFIG_FILE=/app/ov.conf + restart: unless-stopped +``` + +### Kubernetes + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: openviking +spec: + replicas: 1 + selector: + matchLabels: + app: openviking + template: + metadata: + labels: + app: openviking + spec: + containers: + - name: openviking + image: volcengine/openviking:latest + ports: + - containerPort: 1933 + env: + - name: OPENVIKING_CONFIG_FILE + value: /app/ov.conf + volumeMounts: + - name: config + mountPath: /app/ov.conf + subPath: ov.conf + - name: data + mountPath: /data + volumes: + - name: config + configMap: + name: openviking-config + - name: data + persistentVolumeClaim: + claimName: openviking-data +--- +apiVersion: v1 +kind: Service +metadata: + name: openviking +spec: + selector: + app: openviking + ports: + - port: 1933 + targetPort: 1933 +``` + +--- + +## Multiple Model Providers + +### OpenAI Configuration + +```json +{ + "embedding": { + "dense": { + "provider": "openai", + "model": "text-embedding-3-large", + "api_key": "sk-...", + "api_base": "https://api.openai.com/v1", + "dimension": 3072 + } + }, + "vlm": { + "provider": "openai", + "model": "gpt-4-vision-preview", + "api_key": "sk-...", + "api_base": "https://api.openai.com/v1" + } +} +``` + +### Anthropic Configuration + +```json +{ + "vlm": { + "provider": "anthropic", + "model": "claude-3-opus-20240229", + "api_key": "sk-ant-...", + "api_base": "https://api.anthropic.com" + } +} +``` + +### Local vLLM + +```bash +# Start vLLM server +vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +``` + +```json +{ + "vlm": { + "provider": "vllm", + "model": "meta-llama/Llama-3.1-8B-Instruct", + "api_key": "dummy", + "api_base": "http://localhost:8000/v1" + } +} +``` + +--- + +## Authentication and Security + +### Enable API Key Authentication + +```json +{ + "server": { + "host": "0.0.0.0", + "port": 1933, + "api_key": "your-secure-api-key", + "cors_origins": ["https://yourdomain.com"] + } +} +``` + +### CLI with Authentication + +```json +{ + "url": "http://localhost:1933", + "api_key": "your-secure-api-key" +} +``` + +### HTTPS/SSL + +Use a reverse proxy like Nginx or Caddy: + +```nginx +server { + listen 443 ssl; + server_name openviking.yourdomain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:1933; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } +} +``` + +--- + +## Advanced Troubleshooting + +### Debug Logging + +```json +{ + "log": { + "level": "DEBUG", + "output": "file", + "file_path": "/data/openviking.log" + } +} +``` + +### Vector DB Issues + +**Reset local vector DB:** + +```bash +# Stop server +pkill openviking-server + +# Remove vector DB data +rm -rf ~/.openviking/data/vectordb + +# Restart server +openviking-server +``` + +### Memory Issues + +For large deployments, adjust: + +```json +{ + "parsers": { + "pdf": { + "max_content_length": 50000, + "max_section_size": 2000 + }, + "code": { + "max_token_limit": 25000 + } + } +} +``` + +### Port Conflicts + +If port 1933 is taken: + +```json +{ + "server": { + "port": 8080 + }, + "storage": { + "agfs": { + "port": 8081 + } + } +} +``` + +### Connection Issues from Remote Clients + +1. Check firewall rules +2. Verify server binds to `0.0.0.0` (not `127.0.0.1`) +3. Test with curl from remote machine: + ```bash + curl http://server-ip:1933/health + ``` + +--- + +## Performance Tuning + +### For High Throughput + +```json +{ + "server": { + "workers": 4 + }, + "storage": { + "vectordb": { + "backend": "volcengine" + } + } +} +``` + +### For Low Memory + +```json +{ + "embedding": { + "dense": { + "dimension": 512 + } + }, + "auto_generate_l1": false +} +``` + +--- + +## Migration Guides + +### From Vector-only RAG + +See migration guide in documentation. + +### From Other Memory Systems + +Use import scripts to migrate existing data: + +```python +import openviking as ov + +client = ov.SyncOpenViking(path="./data") +client.initialize() + +# Import from existing source +client.add_resource(path="/path/to/existing/data") +``` From 2b5bc5ed960a0ae20c5462ddd3c7010bc775029e Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Tue, 24 Feb 2026 09:47:56 +0800 Subject: [PATCH 06/10] docs: rename install files and simplify README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename INSTALLATION.md → INSTALL.md - Rename INSTALLATION_ADVANCED.md → INSTALL_ADVANCED.md - Simplify README installation section to point to INSTALL.md - Add 'Building from Source' section to INSTALL_ADVANCED.md with Go/AGFS details - Remove build-from-source details from quick install guide --- INSTALLATION.md => INSTALL.md | 5 +- ...LLATION_ADVANCED.md => INSTALL_ADVANCED.md | 62 ++- README.md | 411 +++++------------- 3 files changed, 163 insertions(+), 315 deletions(-) rename INSTALLATION.md => INSTALL.md (97%) rename INSTALLATION_ADVANCED.md => INSTALL_ADVANCED.md (90%) diff --git a/INSTALLATION.md b/INSTALL.md similarity index 97% rename from INSTALLATION.md rename to INSTALL.md index 29a3e1b2..b01a1381 100644 --- a/INSTALLATION.md +++ b/INSTALL.md @@ -1,4 +1,4 @@ -# OpenViking Installation Guide +# Install OpenViking Quick installation guide for OpenViking - the Context Database for AI Agents. @@ -175,7 +175,7 @@ ov search "OpenViking working" For advanced setup options (cloud deployment, custom storage, multiple model providers, etc.), see: -**[INSTALLATION_ADVANCED.md](./INSTALLATION_ADVANCED.md)** +**[INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md)** This includes: - Full configuration reference @@ -190,7 +190,6 @@ This includes: ## Requirements - Python 3.10+ -- Rust (for building ov CLI) - API keys for VLM and embedding models **Supported Model Providers:** Volcengine, OpenAI, Anthropic, DeepSeek, Google, Moonshot, Zhipu, DashScope, MiniMax, OpenRouter, vLLM diff --git a/INSTALLATION_ADVANCED.md b/INSTALL_ADVANCED.md similarity index 90% rename from INSTALLATION_ADVANCED.md rename to INSTALL_ADVANCED.md index 96bbda25..bd8c86b3 100644 --- a/INSTALLATION_ADVANCED.md +++ b/INSTALL_ADVANCED.md @@ -1,8 +1,8 @@ -# OpenViking Installation Guide (Advanced) +# Advanced Installation & Configuration Detailed configuration and deployment options for OpenViking. -For the quick start guide, see **[INSTALLATION.md](./INSTALLATION.md)**. +For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. --- @@ -10,6 +10,7 @@ For the quick start guide, see **[INSTALLATION.md](./INSTALLATION.md)**. - [Full Configuration Reference](#full-configuration-reference) - [Alternative Installation Methods](#alternative-installation-methods) +- [Building from Source](#building-from-source) - [Cloud Deployment](#cloud-deployment) - [Docker/Container Setup](#dockercontainer-setup) - [Multiple Model Providers](#multiple-model-providers) @@ -198,7 +199,7 @@ export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf ## Alternative Installation Methods -### Using pip (not recommended) +### Using pip While uv is the recommended method, you can also use pip: @@ -231,6 +232,61 @@ pip install openviking --- +## Building from Source + +> ⚠️ **Note:** Building from source is only needed for development or if you need to modify the code. For regular use, use `uv tool install` or `pip install` to get pre-built wheels. + +### Prerequisites + +- Python 3.10+ +- Rust (for ov CLI) +- Go 1.21+ (for AGFS server) +- CMake 3.15+ +- GCC/G++ or Clang + +### Build Steps + +```bash +git clone https://github.com/volcengine/OpenViking.git +cd OpenViking + +# Install Python package (builds AGFS and C++ extensions) +pip install . + +# Or with uv +uv pip install . + +# Install ov CLI +cargo install --path crates/ov_cli +``` + +### AGFS Build Details + +The AGFS (Agent Filesystem) server is written in Go and is automatically built during installation: + +```bash +# AGFS source location +third_party/agfs/agfs-server/ + +# To build manually: +cd third_party/agfs/agfs-server +go build -o build/agfs-server cmd/server/main.go +``` + +### C++ Extensions + +OpenViking includes C++ extensions for high-performance vector operations: + +```bash +# CMake is used automatically during pip install +# To build manually: +mkdir build && cd build +cmake .. +make -j$(nproc) +``` + +--- + ## Cloud Deployment ### Volcengine ECS (Recommended) diff --git a/README.md b/README.md index bed8fb71..0f22549c 100644 --- a/README.md +++ b/README.md @@ -53,45 +53,42 @@ With OpenViking, developers can build an Agent's brain just like managing local --- -## Quick Start +## Installation -### Prerequisites +**Quick Start (5 minutes):** -Before starting with OpenViking, please ensure your environment meets the following requirements: +```bash +# Install uv +curl -LsSf https://astral.sh/uv/install.sh | sh -- **Python Version**: 3.10 or higher -- **Operating System**: Linux, macOS, Windows -- **Network Connection**: A stable network connection is required (for downloading dependencies and accessing model services) +# Install OpenViking server +uv tool install openviking -### 1. Installation +# Install ov CLI for skills +curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash -#### Python Package +# Configure and start +mkdir -p ~/.openviking +# Create ~/.openviking/ov.conf with your API keys +# See INSTALL.md for full config template -```bash -pip install openviking +export OPENVIKING_CONFIG_DIR=~/.openviking +openviking-server ``` -#### Rust CLI (Optional) - -```bash -curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash -``` +📖 **[Full Installation Guide →](./INSTALL.md)** -Or build from source: +For advanced configuration (cloud deployment, Docker, multiple model providers), see **[INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md)**. -```bash -cargo install --git https://github.com/volcengine/OpenViking ov_cli -``` +--- -### 2. Model Preparation +## Model Preparation OpenViking requires the following model capabilities: - **VLM Model**: For image and content understanding - **Embedding Model**: For vectorization and semantic retrieval -#### Supported VLM Providers - -OpenViking supports multiple VLM providers: +### Supported VLM Providers | Provider | Model | Get API Key | |----------|-------|-------------| @@ -109,7 +106,7 @@ OpenViking supports multiple VLM providers: > 💡 **Tip**: OpenViking uses a **Provider Registry** for unified model access. The system automatically detects the provider based on model name keywords, so you can switch between providers seamlessly. -#### Provider-Specific Notes +### Provider-Specific Notes
Volcengine (Doubao) @@ -122,7 +119,7 @@ Volcengine supports both model names and endpoint IDs. Using model names is reco "provider": "volcengine", "model": "doubao-seed-1-6-240615", "api_key": "your-api-key", - "api_base" : "https://ark.cn-beijing.volces.com/api/v3", + "api_base" : "https://ark.cn-beijing.volces.com/api/v3" } } ``` @@ -135,7 +132,7 @@ You can also use endpoint IDs (found in [Volcengine ARK Console](https://console "provider": "volcengine", "model": "ep-20241220174930-xxxxx", "api_key": "your-api-key", - "api_base" : "https://ark.cn-beijing.volces.com/api/v3", + "api_base" : "https://ark.cn-beijing.volces.com/api/v3" } } ``` @@ -201,121 +198,9 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
-### 3. Environment Configuration - -#### Configuration Template - -Create a configuration file `~/.openviking/ov.conf`: - -```json -{ - "embedding": { - "dense": { - "api_base" : "", // API endpoint address - "api_key" : "", // Model service API Key - "provider" : "", // Provider type: "volcengine" or "openai" (currently supported) - "dimension": 1024, // Vector dimension - "model" : "" // Embedding model name (e.g., doubao-embedding-vision-250615 or text-embedding-3-large) - } - }, - "vlm": { - "api_base" : "", // API endpoint address - "api_key" : "", // Model service API Key - "provider" : "", // Provider type (volcengine, openai, deepseek, anthropic, etc.) - "model" : "" // VLM model name (e.g., doubao-seed-1-8-251228 or gpt-4-vision-preview) - } -} -``` - -> **Note**: For embedding models, currently `volcengine` (Doubao), `openai`, and `jina` providers are supported. For VLM models, we support multiple providers including volcengine, openai, deepseek, anthropic, gemini, moonshot, zhipu, dashscope, minimax, and more. - -#### Configuration Examples - -👇 Expand to see the configuration example for your model service: - -
-Example 1: Using Volcengine (Doubao Models) - -```json -{ - "embedding": { - "dense": { - "api_base" : "https://ark.cn-beijing.volces.com/api/v3", - "api_key" : "your-volcengine-api-key", - "provider" : "volcengine", - "dimension": 1024, - "model" : "doubao-embedding-vision-250615" - } - }, - "vlm": { - "api_base" : "https://ark.cn-beijing.volces.com/api/v3", - "api_key" : "your-volcengine-api-key", - "provider" : "volcengine", - "model" : "doubao-seed-1-8-251228" - } -} -``` - -
- -
-Example 2: Using OpenAI Models - -```json -{ - "embedding": { - "dense": { - "api_base" : "https://api.openai.com/v1", - "api_key" : "your-openai-api-key", - "provider" : "openai", - "dimension": 3072, - "model" : "text-embedding-3-large" - } - }, - "vlm": { - "api_base" : "https://api.openai.com/v1", - "api_key" : "your-openai-api-key", - "provider" : "openai", - "model" : "gpt-4-vision-preview" - } -} -``` - -
- -#### Set Environment Variable - -After creating the configuration file, set the environment variable to point to it (Linux/macOS): - -```bash -export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf -``` - -On Windows, use one of the following: - -PowerShell: - -```powershell -$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" -``` - -Command Prompt (cmd.exe): - -```bat -set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" -``` - -> 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable. - -### 4. Run Your First Example - -> 📝 **Prerequisite**: Ensure you have completed the environment configuration in the previous step. - -Now let's run a complete example to experience the core features of OpenViking. - -#### Create Python Script +--- -Create `example.py`: +## Quick Example ```python import openviking as ov @@ -365,225 +250,135 @@ except Exception as e: print(f"Error: {e}") ``` -#### Run the Script - -```bash -python example.py -``` - -#### Expected Output - -``` -Directory structure: -... - -Content preview: ... +--- -Wait for semantic processing... -Abstract: -... +## Skills -Overview: -... +Skills enable agents to use OpenViking through simple keywords: -Search results: - viking://resources/... (score: 0.8523) - ... -``` +| Keyword | Skill | What It Does | +|---------|-------|--------------| +| `ovm` | adding-memory | Extracts and stores insights from conversation | +| `ovr` | adding-resource | Imports files/URLs into OpenViking | +| `ovs` | searching-context | Searches stored memories and resources | -Congratulations! You have successfully run OpenViking 🎉 +See [INSTALL.md](./INSTALL.md) for skill installation instructions. --- ## Server Deployment -For production environments, we recommend running OpenViking as a standalone HTTP service to provide persistent, high-performance context support for your AI Agents. +For production environments, we recommend running OpenViking as a standalone HTTP service: -🚀 **Deploy OpenViking on Cloud**: -To ensure optimal storage performance and data security, we recommend deploying on **Volcengine Elastic Compute Service (ECS)** using the **veLinux** operating system. We have prepared a detailed step-by-step guide to get you started quickly. +```bash +# Start server +export OPENVIKING_CONFIG_DIR=~/.openviking +openviking-server -👉 **[View: Server Deployment & ECS Setup Guide](./docs/en/getting-started/03-quickstart-server.md)** +# Or run in background +nohup openviking-server > ~/.openviking/server.log 2>&1 & +``` + +🚀 For cloud deployment (ECS, Docker, Kubernetes), see **[INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md)**. --- ## Core Concepts -After running the first example, let's dive into the design philosophy of OpenViking. These five core concepts correspond one-to-one with the solutions mentioned earlier, together building a complete context management system: - ### 1. Filesystem Management Paradigm → Solves Fragmentation We no longer view context as flat text slices but unify them into an abstract virtual filesystem. Whether it's memories, resources, or capabilities, they are mapped to virtual directories under the `viking://` protocol, each with a unique URI. -This paradigm gives Agents unprecedented context manipulation capabilities, enabling them to locate, browse, and manipulate information precisely and deterministically through standard commands like `ls` and `find`, just like a developer. This transforms context management from vague semantic matching into intuitive, traceable "file operations". Learn more: [Viking URI](./docs/en/concepts/04-viking-uri.md) | [Context Types](./docs/en/concepts/02-context-types.md) - ``` viking:// -├── resources/ # Resources: project docs, repos, web pages, etc. -│ ├── my_project/ -│ │ ├── docs/ -│ │ │ ├── api/ -│ │ │ └── tutorials/ -│ │ └── src/ -│ └── ... -├── user/ # User: personal preferences, habits, etc. +├── resources/ # Resources: project docs, repos, web pages, etc. +│ └── my_project/ +│ ├── docs/ +│ └── src/ +├── user/ # User: personal preferences, habits, etc. │ └── memories/ -│ ├── preferences/ -│ │ ├── writing_style -│ │ └── coding_habits -│ └── ... -└── agent/ # Agent: skills, instructions, task memories, etc. +│ └── preferences/ +└── agent/ # Agent: skills, instructions, task memories, etc. ├── skills/ - │ ├── search_code - │ ├── analyze_data - │ └── ... - ├── memories/ - └── instructions/ + └── memories/ ``` +Learn more: [Viking URI](./docs/en/concepts/04-viking-uri.md) | [Context Types](./docs/en/concepts/02-context-types.md) + ### 2. Tiered Context Loading → Reduces Token Consumption -Stuffing massive amounts of context into a prompt all at once is not only expensive but also prone to exceeding model windows and introducing noise. OpenViking automatically processes context into three levels upon writing: -- **L0 (Abstract)**: A one-sentence summary for quick retrieval and identification. -- **L1 (Overview)**: Contains core information and usage scenarios for Agent decision-making during the planning phase. -- **L2 (Details)**: The full original data, for deep reading by the Agent when absolutely necessary. +OpenViking automatically processes context into three levels upon writing: -Learn more: [Context Layers](./docs/en/concepts/03-context-layers.md) +- **L0 (Abstract)**: A one-sentence summary for quick retrieval and identification (~100 tokens) +- **L1 (Overview)**: Contains core information and usage scenarios for Agent decision-making (~2k tokens) +- **L2 (Details)**: The full original data, for deep reading when absolutely necessary -``` -viking://resources/my_project/ -├── .abstract # L0 Layer: Abstract (~100 tokens) - Quick relevance check -├── .overview # L1 Layer: Overview (~2k tokens) - Understand structure and key points -├── docs/ -│ ├── .abstract # Each directory has corresponding L0/L1 layers -│ ├── .overview -│ ├── api/ -│ │ ├── .abstract -│ │ ├── .overview -│ │ ├── auth.md # L2 Layer: Full content - Load on demand -│ │ └── endpoints.md -│ └── ... -└── src/ - └── ... -``` +Learn more: [Context Layers](./docs/en/concepts/03-context-layers.md) ### 3. Directory Recursive Retrieval → Improves Retrieval Effect -Single vector retrieval struggles with complex query intents. OpenViking has designed an innovative **Directory Recursive Retrieval Strategy** that deeply integrates multiple retrieval methods: +Single vector retrieval struggles with complex query intents. OpenViking uses an innovative Directory Recursive Retrieval Strategy: -1. **Intent Analysis**: Generate multiple retrieval conditions through intent analysis. -2. **Initial Positioning**: Use vector retrieval to quickly locate the high-score directory where the initial slice is located. -3. **Refined Exploration**: Perform a secondary retrieval within that directory and update high-score results to the candidate set. -4. **Recursive Drill-down**: If subdirectories exist, recursively repeat the secondary retrieval steps layer by layer. -5. **Result Aggregation**: Finally, obtain the most relevant context to return. +1. **Intent Analysis**: Generate multiple retrieval conditions +2. **Initial Positioning**: Use vector retrieval to locate high-score directories +3. **Refined Exploration**: Perform secondary retrieval within directories +4. **Recursive Drill-down**: Repeat for subdirectories +5. **Result Aggregation**: Return the most relevant context -This "lock high-score directory first, then refine content exploration" strategy not only finds the semantically best-matching fragments but also understands the full context where the information resides, thereby improving the globality and accuracy of retrieval. Learn more: [Retrieval Mechanism](./docs/en/concepts/07-retrieval.md) +Learn more: [Retrieval Mechanism](./docs/en/concepts/07-retrieval.md) ### 4. Visualized Retrieval Trajectory → Observable Context -OpenViking's organization uses a hierarchical virtual filesystem structure. All context is integrated in a unified format, and each entry corresponds to a unique URI (like a `viking://` path), breaking the traditional flat black-box management mode with a clear hierarchy that is easy to understand. - -The retrieval process adopts a directory recursive strategy. The trajectory of directory browsing and file positioning for each retrieval is fully preserved, allowing users to clearly observe the root cause of problems and guide the optimization of retrieval logic. Learn more: [Retrieval Mechanism](./docs/en/concepts/07-retrieval.md) +The retrieval trajectory is fully preserved, allowing users to clearly observe the root cause of issues and guide retrieval logic optimization. ### 5. Automatic Session Management → Context Self-Iteration -OpenViking has a built-in memory self-iteration loop. At the end of each session, developers can actively trigger the memory extraction mechanism. The system will asynchronously analyze task execution results and user feedback, and automatically update them to the User and Agent memory directories. +At the end of each session, the system asynchronously analyzes task execution results and automatically updates User and Agent memory directories, making the Agent "smarter with use." -- **User Memory Update**: Update memories related to user preferences, making Agent responses better fit user needs. -- **Agent Experience Accumulation**: Extract core content such as operational tips and tool usage experience from task execution experience, aiding efficient decision-making in subsequent tasks. - -This allows the Agent to get "smarter with use" through interactions with the world, achieving self-evolution. Learn more: [Session Management](./docs/en/concepts/08-session.md) +Learn more: [Session Management](./docs/en/concepts/08-session.md) --- ## Project Architecture -The OpenViking project adopts a clear modular architecture design. The main directory structure is as follows: - ``` OpenViking/ -├── openviking/ # Core source code directory -│ ├── core/ # Core modules: client, engine, filesystem, etc. -│ ├── models/ # Model integration: VLM and Embedding model encapsulation -│ ├── parse/ # Resource parsing: file parsing, detection, OVPack handling -│ ├── retrieve/ # Retrieval module: semantic retrieval, directory recursive retrieval -│ ├── storage/ # Storage layer: vector DB, filesystem queue, observers -│ ├── session/ # Session management: history, memory extraction -│ ├── message/ # Message processing: formatting, conversion -│ ├── prompts/ # Prompt templates: templates for various tasks -│ ├── utils/ # Utilities: config, helpers -│ └── bin/ # Command line tools -├── docs/ # Project documentation -│ ├── zh/ # Chinese documentation -│ ├── en/ # English documentation -│ └── images/ # Documentation images -├── examples/ # Usage examples -├── tests/ # Test cases -│ ├── client/ # Client tests -│ ├── engine/ # Engine tests -│ ├── integration/ # Integration tests -│ ├── session/ # Session tests -│ └── vectordb/ # Vector DB tests -├── src/ # C++ extensions (high-performance index and storage) -│ ├── common/ # Common components -│ ├── index/ # Index implementation -│ └── store/ # Storage implementation -├── third_party/ # Third-party dependencies -├── pyproject.toml # Python project configuration -├── setup.py # Setup script -├── LICENSE # Open source license -├── CONTRIBUTING.md # Contributing guide -├── AGENT.md # Agent development guide -└── README.md # Project readme +├── openviking/ # Core source code +│ ├── core/ # Client, engine, filesystem +│ ├── models/ # VLM and Embedding model integration +│ ├── parse/ # Resource parsing +│ ├── retrieve/ # Semantic and directory retrieval +│ ├── storage/ # Vector DB, filesystem queue +│ └── session/ # History, memory extraction +├── docs/ # Documentation +├── examples/ # Usage examples +├── tests/ # Test cases +└── src/ # C++ extensions ``` - ---- - -## Advanced Reading - -For more details, please visit our [Full Documentation](./docs/en/). - --- ## Community & Team ### About Us -OpenViking is an open-source context database initiated and maintained by the **ByteDance Volcengine Viking Team**. - -The Viking team focuses on unstructured information processing and intelligent retrieval, accumulating rich commercial practical experience in context engineering technology: - -- **2019**: VikingDB vector database supported large-scale use across all ByteDance businesses. -- **2023**: VikingDB sold on Volcengine public cloud. -- **2024**: Launched developer product matrix: VikingDB, Viking KnowledgeBase, Viking MemoryBase. -- **2025**: Created upper-layer application products like AI Search and Vaka Knowledge Assistant. -- **Oct 2025**: Open-sourced [MineContext](https://github.com/volcengine/MineContext), exploring proactive AI applications. -- **Jan 2026**: Open-sourced OpenViking, providing underlying context database support for AI Agents. +OpenViking is an open-source context database initiated and maintained by the ByteDance Volcengine Viking Team. -For more details, please see: **[About Us](./docs/en/about/01-about-us.md)** +The Viking team focuses on unstructured information processing and intelligent retrieval: ---- +- **2019**: VikingDB vector database supported large-scale use across all ByteDance businesses +- **2023**: VikingDB sold on Volcengine public cloud +- **2024**: Launched developer product matrix: VikingDB, Viking KnowledgeBase, Viking MemoryBase +- **2025**: Created upper-layer application products like AI Search and Vaka Knowledge Assistant +- **Oct 2025**: Open-sourced [MineContext](https://github.com/volcengine/MineContext) +- **Jan 2026**: Open-sourced OpenViking ### Join the Community -OpenViking is still in its early stages, and there are many areas for improvement and exploration. We sincerely invite every developer passionate about AI Agent technology: - -- Light up a precious **Star** for us to give us the motivation to move forward. -- Visit our [**Website**](https://www.openviking.ai) to understand the philosophy we convey, and use it in your projects via the [**Documentation**](https://www.openviking.ai/docs). Feel the change it brings and give us feedback on your truest experience. -- Join our community to share your insights, help answer others' questions, and jointly create an open and mutually helpful technical atmosphere: - - 📱 **Lark Group**: Scan the QR code to join → [View QR Code](./docs/en/about/01-about-us.md#lark-group) - - 💬 **WeChat Group**: Scan the QR code to add assistant → [View QR Code](./docs/en/about/01-about-us.md#wechat-group) - - 🎮 **Discord**: [Join Discord Server](https://discord.com/invite/eHvx8E9XF3) - - 🐦 **X (Twitter)**：[Follow us](https://x.com/openvikingai) -- Become a **Contributor**, whether submitting a bug fix or contributing a new feature, every line of your code will be an important cornerstone of OpenViking's growth. - -Let's work together to define and build the future of AI Agent context management. The journey has begun, looking forward to your participation! - ---- - -### Star Trend - -[![Star History Chart](https://api.star-history.com/svg?repos=volcengine/OpenViking&type=timeline&legend=top-left)](https://www.star-history.com/#volcengine/OpenViking&type=timeline&legend=top-left) +- 📱 **Lark Group**: [Join here](./docs/en/about/01-about-us.md#lark-group) +- 💬 **WeChat**: [Join here](./docs/en/about/01-about-us.md#wechat-group) +- 🎮 **Discord**: [Join here](https://discord.com/invite/eHvx8E9XF3) +- 🐦 **X (Twitter)**: [Follow us](https://x.com/openvikingai) --- @@ -591,18 +386,16 @@ Let's work together to define and build the future of AI Agent context managemen This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. - - - -[release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square + +[release-shield]: https://img.shields.io/github/v/release/volcengine/OpenViking?style=flat-square [release-link]: https://github.com/volcengine/OpenViking/releases -[license-shield]: https://img.shields.io/badge/license-apache%202.0-white?labelColor=black&style=flat-square -[license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE -[last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square -[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main -[github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47 -[github-stars-link]: https://github.com/volcengine/OpenViking -[github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb +[github-stars-shield]: https://img.shields.io/github/stars/volcengine/OpenViking?style=flat-square +[github-stars-link]: https://github.com/volcengine/OpenViking/stargazers +[github-issues-shield]: https://img.shields.io/github/issues/volcengine/OpenViking?style=flat-square [github-issues-shield-link]: https://github.com/volcengine/OpenViking/issues -[github-contributors-shield]: https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square +[github-contributors-shield]: https://img.shields.io/github/contributors/volcengine/OpenViking?style=flat-square [github-contributors-link]: https://github.com/volcengine/OpenViking/graphs/contributors +[license-shield]: https://img.shields.io/github/license/volcengine/OpenViking?style=flat-square +[license-shield-link]: https://github.com/volcengine/OpenViking/blob/main/LICENSE +[last-commit-shield]: https://img.shields.io/github/last-commit/volcengine/OpenViking?style=flat-square +[last-commit-shield-link]: https://github.com/volcengine/OpenViking/commits/main From 698fb920a5bc494a50e27d1b4259613fd8b9bb3d Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Tue, 24 Feb 2026 09:48:40 +0800 Subject: [PATCH 07/10] docs: add agent prompt for skill installation confirmation --- INSTALL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/INSTALL.md b/INSTALL.md index b01a1381..49391909 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -102,6 +102,8 @@ EOF Skills enable agents to use OpenViking. Install them to your agent's skill directory: +> 🤖 **For AI Agents reading this:** Ask your user if they want to install the OpenViking skills (adding-memory, adding-resource, searching-context). Proceed only if they confirm. + ```bash mkdir -p ~/.openclaw/skills From 447535c815e48cb2cfdffd369c1074ec00463763 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Tue, 24 Feb 2026 09:52:11 +0800 Subject: [PATCH 08/10] docs: fix storage config in quick install example - Remove unsupported storage.workspace field - Use working storage.vectordb/agfs.backend format - Add note about data directory location --- INSTALL.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 49391909..718b2d80 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -67,7 +67,8 @@ cat > ~/.openviking/ov.conf << 'EOF' "api_base": "https://ark.cn-beijing.volces.com/api/v3" }, "storage": { - "workspace": "~/.openviking/data" + "vectordb": { "backend": "local" }, + "agfs": { "backend": "local" } } } EOF @@ -75,6 +76,8 @@ EOF **Replace `your-api-key` with your actual API key.** +> 💡 **Note:** Data is stored in `./data` by default. You can change this by setting the `OPENVIKING_CONFIG_DIR` environment variable before starting the server. + Start the server in background: ```bash From ed6e6127a3e0e728277022ac7f18ffa8d75672a4 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Wed, 25 Feb 2026 10:37:36 +0800 Subject: [PATCH 09/10] docs: update install guide with natural language triggers and port changes - Guide users to say 'remember this' and similar phrases - Keep keyword triggers in skill files for agent detection - Change default ports to 11933 (server) and 11944 (agfs) - Remove export OPENVIKING_CONFIG_DIR since default is ~/.openviking - Support OpenClaw, Claude Code, and other agents in skills section - Move Rust CLI build instructions to advanced doc - Fix data dir note to reference storage.workspace - Remove migration guide from advanced doc --- INSTALL.md | 91 ++++++++++++++++++++++++--------------------- INSTALL_ADVANCED.md | 55 +++++++++------------------ 2 files changed, 65 insertions(+), 81 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 718b2d80..992fa12a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -34,12 +34,7 @@ This installs `openviking-server` as a standalone tool you can run anywhere. curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash ``` -Or install from source: -```bash -git clone https://github.com/volcengine/OpenViking.git -cd OpenViking -cargo install --path crates/ov_cli -``` +See [INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md) for building from source. ### 4. Configure and Start Server @@ -76,18 +71,17 @@ EOF **Replace `your-api-key` with your actual API key.** -> 💡 **Note:** Data is stored in `./data` by default. You can change this by setting the `OPENVIKING_CONFIG_DIR` environment variable before starting the server. +> 💡 **Note:** Data is stored in `~/.openviking/data` by default (set via `storage.workspace` in ov.conf). See [INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md) to customize data location. Start the server in background: ```bash -export OPENVIKING_CONFIG_DIR=~/.openviking nohup openviking-server > ~/.openviking/server.log 2>&1 & ``` Check it's running: ```bash -curl http://localhost:1933/health +curl http://localhost:11933/health # Should return: {"status": "ok"} ``` @@ -96,7 +90,7 @@ curl http://localhost:1933/health ```bash cat > ~/.openviking/ovcli.conf << 'EOF' { - "url": "http://localhost:1933" + "url": "http://localhost:11933" } EOF ``` @@ -107,55 +101,67 @@ Skills enable agents to use OpenViking. Install them to your agent's skill direc > 🤖 **For AI Agents reading this:** Ask your user if they want to install the OpenViking skills (adding-memory, adding-resource, searching-context). Proceed only if they confirm. +**For OpenClaw:** ```bash mkdir -p ~/.openclaw/skills -# Copy skills from OpenViking examples -cp -r /path/to/openviking/examples/skills/adding-memory ~/.openclaw/skills/ -cp -r /path/to/openviking/examples/skills/adding-resource ~/.openclaw/skills/ -cp -r /path/to/openviking/examples/skills/searching-context ~/.openclaw/skills/ +# Download skills +for skill in adding-memory adding-resource searching-context; do + mkdir -p "$HOME/.openclaw/skills/$skill" + curl -o "$HOME/.openclaw/skills/$skill/SKILL.md" \ + "https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/$skill/SKILL.md" +done ``` -Or download directly: +**For Claude Code:** ```bash -mkdir -p ~/.openclaw/skills/adding-memory -curl -o ~/.openclaw/skills/adding-memory/SKILL.md \ - https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-memory/SKILL.md +mkdir -p ~/.claude/skills + +# Download skills +for skill in adding-memory adding-resource searching-context; do + mkdir -p "$HOME/.claude/skills/$skill" + curl -o "$HOME/.claude/skills/$skill/SKILL.md" \ + "https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/$skill/SKILL.md" +done +``` -mkdir -p ~/.openclaw/skills/adding-resource -curl -o ~/.openclaw/skills/adding-resource/SKILL.md \ - https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-resource/SKILL.md +**For other agents:** Install to your agent's skill/tools directory. -mkdir -p ~/.openclaw/skills/searching-context -curl -o ~/.openclaw/skills/searching-context/SKILL.md \ - https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/searching-context/SKILL.md +Or copy from a local clone: +```bash +# Set your agent's skill directory +SKILL_DIR=~/.openclaw/skills # adjust for your agent + +cp -r /path/to/openviking/examples/skills/adding-memory "$SKILL_DIR/" +cp -r /path/to/openviking/examples/skills/adding-resource "$SKILL_DIR/" +cp -r /path/to/openviking/examples/skills/searching-context "$SKILL_DIR/" ``` --- -## Using Skills +## Using OpenViking Memory -Once installed, agents can use these keywords during chat: +Once skills are installed, you can use natural language to trigger OpenViking actions: -| Keyword | Skill | What It Does | -|---------|-------|--------------| -| `ovm` | adding-memory | Extracts and stores insights from conversation | -| `ovr` | adding-resource | Imports files/URLs into OpenViking | -| `ovs` | searching-context | Searches stored memories and resources | +### Storing Memories +Say things like: +- "**Remember this**" — after sharing something worth remembering +- "**Save this to memory**" — to persist an insight or decision +- "**Keep this in mind**" — to store context for future reference -**Example chat flow:** -``` -User: I prefer using vim for coding -User: ovm -→ Agent extracts and stores: "User prefers vim for coding" +### Adding Resources +Say things like: +- "**Add this to OpenViking**" — when sharing a URL or file +- "**Import https://example.com/docs**" — to add external knowledge +- "**Save this resource**" — to store documents for later retrieval -User: Please add https://example.com/docs -User: ovr -→ Agent imports and processes the URL +### Searching Context +Say things like: +- "**Search my memory for...**" — to find previously stored information +- "**What do I know about...**" — to query your OpenViking context +- "**Find in OpenViking...**" — to search across memories and resources -User: ovs What's my editor preference? -→ Agent searches and returns: "User prefers vim for coding" -``` +The agent will automatically detect these intents and use the appropriate OpenViking skills. --- @@ -209,7 +215,6 @@ uv tool install openviking curl -fsSL .../install.sh | bash # ov CLI # Start server (background) -export OPENVIKING_CONFIG_DIR=~/.openviking nohup openviking-server > ~/.openviking/server.log 2>&1 & # Stop server diff --git a/INSTALL_ADVANCED.md b/INSTALL_ADVANCED.md index bd8c86b3..f7837e77 100644 --- a/INSTALL_ADVANCED.md +++ b/INSTALL_ADVANCED.md @@ -27,7 +27,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. { "server": { "host": "0.0.0.0", - "port": 1933, + "port": 11933, "api_key": null, "cors_origins": ["*"] }, @@ -44,7 +44,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. } }, "agfs": { - "port": 1833, + "port": 11944, "log_level": "warn", "backend": "local", "timeout": 10, @@ -169,9 +169,10 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. | Field | Type | Default | Description | |-------|------|---------|-------------| | `server.host` | string | `"0.0.0.0"` | Server bind address | -| `server.port` | int | `1933` | Server port | +| `server.port` | int | `11933` | Server port | | `server.api_key` | string | `null` | API key for authentication | | `storage.workspace` | string | `"./data"` | Main data directory | +| `storage.agfs.port` | int | `11944` | AGFS server port | | `storage.vectordb.backend` | string | `"local"` | Vector DB backend: local, volcengine | | `storage.agfs.backend` | string | `"local"` | AGFS backend: local, s3 | | `embedding.dense.provider` | string | `"volcengine"` | Embedding provider | @@ -334,7 +335,7 @@ source $HOME/.cargo/env uv tool install openviking # Configure firewall (example for UFW) -sudo ufw allow 1933/tcp +sudo ufw allow 11933/tcp # Setup systemd service (see below) ``` @@ -378,7 +379,7 @@ sudo systemctl status openviking ```bash docker run -d \ --name openviking \ - -p 1933:1933 \ + -p 11933:11933 \ -v $(pwd)/data:/data \ -v $(pwd)/ov.conf:/app/ov.conf \ -e OPENVIKING_CONFIG_FILE=/app/ov.conf \ @@ -394,7 +395,7 @@ services: openviking: image: volcengine/openviking:latest ports: - - "1933:1933" + - "11933:11933" volumes: - ./data:/data - ./ov.conf:/app/ov.conf @@ -424,7 +425,7 @@ spec: - name: openviking image: volcengine/openviking:latest ports: - - containerPort: 1933 + - containerPort: 11933 env: - name: OPENVIKING_CONFIG_FILE value: /app/ov.conf @@ -450,8 +451,8 @@ spec: selector: app: openviking ports: - - port: 1933 - targetPort: 1933 + - port: 11933 + targetPort: 11933 ``` --- @@ -521,7 +522,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 { "server": { "host": "0.0.0.0", - "port": 1933, + "port": 11933, "api_key": "your-secure-api-key", "cors_origins": ["https://yourdomain.com"] } @@ -532,7 +533,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 ```json { - "url": "http://localhost:1933", + "url": "http://localhost:11933", "api_key": "your-secure-api-key" } ``` @@ -550,7 +551,7 @@ server { ssl_certificate_key /path/to/key.pem; location / { - proxy_pass http://localhost:1933; + proxy_pass http://localhost:11933; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; @@ -609,16 +610,16 @@ For large deployments, adjust: ### Port Conflicts -If port 1933 is taken: +If port 11933 is taken: ```json { "server": { - "port": 8080 + "port": 11934 }, "storage": { "agfs": { - "port": 8081 + "port": 11945 } } } @@ -630,7 +631,7 @@ If port 1933 is taken: 2. Verify server binds to `0.0.0.0` (not `127.0.0.1`) 3. Test with curl from remote machine: ```bash - curl http://server-ip:1933/health + curl http://server-ip:11933/health ``` --- @@ -664,25 +665,3 @@ If port 1933 is taken: "auto_generate_l1": false } ``` - ---- - -## Migration Guides - -### From Vector-only RAG - -See migration guide in documentation. - -### From Other Memory Systems - -Use import scripts to migrate existing data: - -```python -import openviking as ov - -client = ov.SyncOpenViking(path="./data") -client.initialize() - -# Import from existing source -client.add_resource(path="/path/to/existing/data") -``` From 83c713c4941779138bfe80be13f3742f5f42d846 Mon Sep 17 00:00:00 2001 From: ZaynJarvis Date: Wed, 25 Feb 2026 21:38:58 +0800 Subject: [PATCH 10/10] docs: revert ports to 1933/1833, use 11933 only as fallback - Default ports: 1933 (server) and 1833 (agfs) - 11933/11944 mentioned only in port conflict section as alternatives - Docker/Compose/K8s examples use standard 1933 port --- INSTALL.md | 4 ++-- INSTALL_ADVANCED.md | 34 +++++++++++++++++----------------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 992fa12a..0493a4a5 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -81,7 +81,7 @@ nohup openviking-server > ~/.openviking/server.log 2>&1 & Check it's running: ```bash -curl http://localhost:11933/health +curl http://localhost:1933/health # Should return: {"status": "ok"} ``` @@ -90,7 +90,7 @@ curl http://localhost:11933/health ```bash cat > ~/.openviking/ovcli.conf << 'EOF' { - "url": "http://localhost:11933" + "url": "http://localhost:1933" } EOF ``` diff --git a/INSTALL_ADVANCED.md b/INSTALL_ADVANCED.md index f7837e77..54dc23d5 100644 --- a/INSTALL_ADVANCED.md +++ b/INSTALL_ADVANCED.md @@ -27,7 +27,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. { "server": { "host": "0.0.0.0", - "port": 11933, + "port": 1933, "api_key": null, "cors_origins": ["*"] }, @@ -44,7 +44,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. } }, "agfs": { - "port": 11944, + "port": 1833, "log_level": "warn", "backend": "local", "timeout": 10, @@ -169,10 +169,10 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**. | Field | Type | Default | Description | |-------|------|---------|-------------| | `server.host` | string | `"0.0.0.0"` | Server bind address | -| `server.port` | int | `11933` | Server port | +| `server.port` | int | `1933` | Server port | | `server.api_key` | string | `null` | API key for authentication | | `storage.workspace` | string | `"./data"` | Main data directory | -| `storage.agfs.port` | int | `11944` | AGFS server port | +| `storage.agfs.port` | int | `1833` | AGFS server port | | `storage.vectordb.backend` | string | `"local"` | Vector DB backend: local, volcengine | | `storage.agfs.backend` | string | `"local"` | AGFS backend: local, s3 | | `embedding.dense.provider` | string | `"volcengine"` | Embedding provider | @@ -335,7 +335,7 @@ source $HOME/.cargo/env uv tool install openviking # Configure firewall (example for UFW) -sudo ufw allow 11933/tcp +sudo ufw allow 1933/tcp # Setup systemd service (see below) ``` @@ -379,7 +379,7 @@ sudo systemctl status openviking ```bash docker run -d \ --name openviking \ - -p 11933:11933 \ + -p 1933:1933 \ -v $(pwd)/data:/data \ -v $(pwd)/ov.conf:/app/ov.conf \ -e OPENVIKING_CONFIG_FILE=/app/ov.conf \ @@ -395,7 +395,7 @@ services: openviking: image: volcengine/openviking:latest ports: - - "11933:11933" + - "1933:1933" volumes: - ./data:/data - ./ov.conf:/app/ov.conf @@ -425,7 +425,7 @@ spec: - name: openviking image: volcengine/openviking:latest ports: - - containerPort: 11933 + - containerPort: 1933 env: - name: OPENVIKING_CONFIG_FILE value: /app/ov.conf @@ -451,8 +451,8 @@ spec: selector: app: openviking ports: - - port: 11933 - targetPort: 11933 + - port: 1933 + targetPort: 1933 ``` --- @@ -522,7 +522,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 { "server": { "host": "0.0.0.0", - "port": 11933, + "port": 1933, "api_key": "your-secure-api-key", "cors_origins": ["https://yourdomain.com"] } @@ -533,7 +533,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 ```json { - "url": "http://localhost:11933", + "url": "http://localhost:1933", "api_key": "your-secure-api-key" } ``` @@ -551,7 +551,7 @@ server { ssl_certificate_key /path/to/key.pem; location / { - proxy_pass http://localhost:11933; + proxy_pass http://localhost:1933; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; @@ -610,16 +610,16 @@ For large deployments, adjust: ### Port Conflicts -If port 11933 is taken: +If port 1933 is taken, use alternative ports like 11933: ```json { "server": { - "port": 11934 + "port": 11933 }, "storage": { "agfs": { - "port": 11945 + "port": 11944 } } } @@ -631,7 +631,7 @@ If port 11933 is taken: 2. Verify server binds to `0.0.0.0` (not `127.0.0.1`) 3. Test with curl from remote machine: ```bash - curl http://server-ip:11933/health + curl http://server-ip:1933/health ``` ---