[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2308":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":40,"readmeContent":41,"aiSummary":42,"trendingCount":16,"starSnapshotCount":16,"syncStatus":43,"lastSyncTime":44,"discoverSource":45},2308,"OpenViking","volcengine\u002FOpenViking","volcengine","OpenViking is an open-source context database designed specifically for AI Agents(such as openclaw). OpenViking unifies the management of context (memory, resources, and skills) that Agents need through a file system paradigm, enabling hierarchical context delivery and self-evolving.","https:\u002F\u002Fopenviking.ai",null,"Python",25504,1973,72,66,0,50,367,1714,257,44.89,"GNU Affero General Public License v3.0",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39],"agent","agentic-rag","ai-agents","clawbot","context-database","context-engineering","filesystem","llm","memory","openclaw","opencode","rag","skill","2026-06-12 02:00:40","\u003Cdiv align=\"center\">\n\n\u003Ca href=\"https:\u002F\u002Fopenviking.ai\u002F\" target=\"_blank\">\n  \u003Cpicture>\n    \u003Cimg alt=\"OpenViking\" src=\"docs\u002Fimages\u002Fov-logo.png\" width=\"200px\" height=\"auto\">\n  \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n### OpenViking: The Context Database for AI Agents\n\nEnglish \u002F [中文](README_CN.md) \u002F [日本語](README_JA.md)\n\n\u003Ca href=\"https:\u002F\u002Fwww.openviking.ai\">Website\u003C\u002Fa> · \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\">GitHub\u003C\u002Fa> · \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Fissues\">Issues\u003C\u002Fa> · \u003Ca href=\".\u002Fdocs\">Docs\u003C\u002Fa>\n\n[![](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fvolcengine\u002FOpenViking?color=369eff\\&labelColor=black\\&logo=github\\&style=flat-square)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Freleases)\n[![](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fvolcengine\u002FOpenViking?labelColor\\&style=flat-square\\&color=ffcb47)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking)\n[![](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002Fvolcengine\u002FOpenViking?labelColor=black\\&style=flat-square\\&color=ff80eb)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Fissues)\n[![](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002Fvolcengine\u002FOpenViking?color=c4f042\\&labelColor=black\\&style=flat-square)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Fgraphs\u002Fcontributors)\n[![](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-AGPLv3-white?labelColor=black\\&style=flat-square)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Fblob\u002Fmain\u002FLICENSE)\n[![](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002Fvolcengine\u002FOpenViking?color=c4f042\\&labelColor=black\\&style=flat-square)](https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\u002Fcommits\u002Fmain)\n\n👋 Join our Community\n\n📱 \u003Ca href=\".\u002Fdocs\u002Fen\u002Fabout\u002F01-about-us.md#lark-group\">Lark Group\u003C\u002Fa> · \u003Ca href=\".\u002Fdocs\u002Fen\u002Fabout\u002F01-about-us.md#wechat-group\">WeChat\u003C\u002Fa> · \u003Ca href=\"https:\u002F\u002Fdiscord.com\u002Finvite\u002FeHvx8E9XF3\">Discord\u003C\u002Fa> · \u003Ca href=\"https:\u002F\u002Fx.com\u002Fopenvikingai\">X\u003C\u002Fa>\n\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F19668\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Ftrendshift.io\u002Fapi\u002Fbadge\u002Frepositories\u002F19668\" alt=\"volcengine%2FOpenViking | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n\n***\n\n## Overview\n\n### Challenges in Agent Development\n\nIn the AI era, data is abundant, but high-quality context is hard to come by. When building AI Agents, developers often face these challenges:\n\n- **Fragmented Context**: Memories are in code, resources are in vector databases, and skills are scattered, making them difficult to manage uniformly.\n- **Surging Context Demand**: An Agent's long-running tasks produce context at every execution. Simple truncation or compression leads to information loss.\n- **Poor Retrieval Effectiveness**: Traditional RAG uses flat storage, lacking a global view and making it difficult to understand the full context of information.\n- **Unobservable Context**: The implicit retrieval chain of traditional RAG is like a black box, making it hard to debug when errors occur.\n- **Limited Memory Iteration**: Current memory is just a record of user interactions, lacking Agent-related task memory.\n\n### The OpenViking Solution\n\n**OpenViking** is an open-source **Context Database** designed specifically for AI Agents.\n\nWe aim to define a minimalist context interaction paradigm for Agents, allowing developers to completely say goodbye to the hassle of context management. OpenViking abandons the fragmented vector storage model of traditional RAG and innovatively adopts a **\"file system paradigm\"** to unify the structured organization of memories, resources, and skills needed by Agents.\n\nWith OpenViking, developers can build an Agent's brain just like managing local files:\n\n- **Filesystem Management Paradigm** → **Solves Fragmentation**: Unified context management of memories, resources, and skills based on a filesystem paradigm.\n- **Tiered Context Loading** → **Reduces Token Consumption**: L0\u002FL1\u002FL2 three-tier structure, loaded on demand, significantly saving costs.\n- **Directory Recursive Retrieval** → **Improves Retrieval Effect**: Supports native filesystem retrieval methods, combining directory positioning with semantic search to achieve recursive and precise context acquisition.\n- **Visualized Retrieval Trajectory** → **Observable Context**: Supports visualization of directory retrieval trajectories, allowing users to clearly observe the root cause of issues and guide retrieval logic optimization.\n- **Automatic Session Management** → **Context Self-Iteration**: Automatically compresses content, resource references, tool calls, etc., in conversations, extracting long-term memory, making the Agent smarter with use.\n\n***\n\n## Quick Start\n\n### Prerequisites\n\nBefore starting with OpenViking, please ensure your environment meets the following requirements:\n\n- **Python Version**: 3.10 or higher\n- **Rust Toolchain**: Cargo (Required for building RAGFS and CLI components from source)\n- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions)\n- **Operating System**: Linux, macOS, Windows\n- **Network Connection**: A stable network connection is required (for downloading dependencies and accessing model services)\n\n### 1. Installation\n\n#### Python Package\n\n```bash\npip install openviking --upgrade --force-reinstall\n```\n\n#### Rust CLI (Optional)\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fvolcengine\u002FOpenViking\u002Fmain\u002Fcrates\u002Fov_cli\u002Finstall.sh | bash\n```\n\nOr build from source:\n\n```bash\ncargo install --git https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking ov_cli\n```\n\n### 2. Model Preparation\n\nOpenViking requires the following model capabilities:\n\n- **VLM Model**: For image and content understanding\n- **Embedding Model**: For vectorization and semantic retrieval\n\n#### Supported VLM Providers\n\nOpenViking supports multiple VLM providers:\n\n| Provider       | Description              | Setup                                                                                                                                                                                                              |\n| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `volcengine`   | Volcengine Doubao Models | [Volcengine Console](https:\u002F\u002Fconsole.volcengine.com\u002Fark\u002Fregion:ark+cn-beijing\u002Foverview?briefPage=0\\&briefType=introduce\\&type=new\\&utm_content=OpenViking\\&utm_medium=devrel\\&utm_source=OWO\\&utm_term=OpenViking) |\n| `openai`       | OpenAI Official API      | [OpenAI Platform](https:\u002F\u002Fplatform.openai.com)                                                                                                                                                                     |\n| `openai-codex` | Codex VLM                | Use `openviking-server init`                                                                                                                                                                                       |\n| `kimi`         | Kimi Code Membership     | Use `openviking-server init`                                                                                                                                                                                       |\n| `glm`          | GLM Coding Plan          | Use `openviking-server init`                                                                                                                                                                                       |\n\n#### Provider-Specific Notes\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Volcengine (Doubao)\u003C\u002Fb>\u003C\u002Fsummary>\n\nVolcengine supports both model names and endpoint IDs. Using model names is recommended for simplicity:\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"volcengine\",\n    \"model\": \"doubao-seed-2-0-pro-260215\",\n    \"api_key\": \"your-api-key\",\n    \"api_base\": \"https:\u002F\u002Fark.cn-beijing.volces.com\u002Fapi\u002Fv3\"\n  }\n}\n```\n\nYou can also use endpoint IDs (found in [Volcengine ARK Console](https:\u002F\u002Fconsole.volcengine.com\u002Fark\u002Fregion:ark+cn-beijing\u002Foverview?briefPage=0\\&briefType=introduce\\&type=new\\&utm_content=OpenViking\\&utm_medium=devrel\\&utm_source=OWO\\&utm_term=OpenViking):\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"volcengine\",\n    \"model\": \"ep-20241220174930-xxxxx\",\n    \"api_key\": \"your-api-key\",\n    \"api_base\": \"https:\u002F\u002Fark.cn-beijing.volces.com\u002Fapi\u002Fv3\"\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>OpenAI\u003C\u002Fb>\u003C\u002Fsummary>\n\nUse OpenAI's official API:\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"openai\",\n    \"model\": \"gpt-4o\",\n    \"api_key\": \"your-api-key\",\n    \"api_base\": \"https:\u002F\u002Fapi.openai.com\u002Fv1\"\n  }\n}\n```\n\nYou can also use a custom OpenAI-compatible endpoint:\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"openai\",\n    \"model\": \"gpt-4o\",\n    \"api_key\": \"your-api-key\",\n    \"api_base\": \"https:\u002F\u002Fyour-custom-endpoint.com\u002Fv1\"\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>OpenAI Codex (OAuth)\u003C\u002Fb>\u003C\u002Fsummary>\n\nUse this provider when you want OpenViking to call Codex VLM through your ChatGPT\u002FCodex OAuth session instead of a standard OpenAI API key:\n\n```bash\nopenviking-server init\n# choose OpenAI Codex when prompted\nopenviking-server doctor\n```\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"openai-codex\",\n    \"model\": \"gpt-5.3-codex\",\n    \"api_base\": \"https:\u002F\u002Fchatgpt.com\u002Fbackend-api\u002Fcodex\",\n    \"temperature\": 0.0,\n    \"max_retries\": 2\n  }\n}\n```\n\n> 💡 **Tip**:\n>\n> - `openai-codex` does not require `vlm.api_key` when Codex OAuth is available\n> - OpenViking stores its own Codex auth state at `~\u002F.openviking\u002Fcodex_auth.json`\n> - `openviking-server doctor` validates that the current Codex auth is usable\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Kimi Coding (Subscription)\u003C\u002Fb>\u003C\u002Fsummary>\n\nUse this provider when you want OpenViking to call the dedicated Kimi Coding subscription endpoint directly:\n\n```bash\nopenviking-server init\n# choose Kimi Coding when prompted\nopenviking-server doctor\n```\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"kimi\",\n    \"model\": \"kimi-code\",\n    \"api_key\": \"your-kimi-subscription-api-key\",\n    \"api_base\": \"https:\u002F\u002Fapi.kimi.com\u002Fcoding\",\n    \"temperature\": 0.0,\n    \"max_retries\": 2\n  }\n}\n```\n\n> 💡 **Tip**:\n>\n> - `kimi` applies the recommended Kimi Coding defaults automatically, including the default Kimi Coding user agent\n> - `kimi-code` and `kimi-coding` are accepted aliases for the provider name\n> - `kimi-code` is normalized to Kimi's upstream coding model automatically\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>GLM Coding Plan (Subscription)\u003C\u002Fb>\u003C\u002Fsummary>\n\nUse this provider when you want OpenViking to call Z.AI's OpenAI-compatible Coding Plan endpoint directly:\n\n```bash\nopenviking-server init\n# choose GLM Coding Plan when prompted\nopenviking-server doctor\n```\n\n```json\n{\n  \"vlm\": {\n    \"provider\": \"glm\",\n    \"model\": \"glm-4.6v\",\n    \"api_key\": \"your-zai-api-key\",\n    \"api_base\": \"https:\u002F\u002Fapi.z.ai\u002Fapi\u002Fcoding\u002Fpaas\u002Fv4\",\n    \"temperature\": 0.0,\n    \"max_retries\": 2\n  }\n}\n```\n\n> 💡 **Tip**:\n>\n> - `glm`, `zhipu`, `zai`, `z-ai`, and `z.ai` all resolve to the same first-class GLM provider\n> - The default endpoint is the Coding Plan endpoint, not the general Z.AI endpoint\n> - Use a vision-capable model such as `glm-4.6v` or `glm-5v-turbo` for multimodal parsing\n\n\u003C\u002Fdetails>\n\n### 3. Environment Configuration\n\n#### Quick Setup for Local Models (Ollama)\n\nIf you want to run OpenViking with local models via [Ollama](https:\u002F\u002Follama.ai), the interactive setup wizard handles everything automatically:\n\n```bash\nopenviking-server init\n```\n\nThe wizard will:\n\n- Detect and install Ollama if needed\n- Recommend and pull suitable embedding and VLM models for your hardware\n- Generate a ready-to-use `ov.conf` configuration file\n\nTo validate your setup at any time:\n\n```bash\nopenviking-server doctor\n```\n\n`doctor` checks local prerequisites (config file, Python version, embedding\u002FVLM provider connectivity, disk space) without requiring a running server.\n\n> For cloud API providers (Volcengine, OpenAI, Gemini, etc.), continue with the manual configuration below.\n\n#### Server Configuration Template\n\nThe recommended first-time flow is:\n\n```bash\nopenviking-server init\nopenviking-server doctor\n```\n\nIf you choose `OpenAI Codex` inside `openviking-server init`, the wizard can import existing Codex auth or start the Codex sign-in flow for you.\n\nIf you prefer manual configuration, create `~\u002F.openviking\u002Fov.conf`, remove the comments before copy:\n\n```json\n{\n  \"storage\": {\n    \"workspace\": \"\u002Fhome\u002Fyour-name\u002Fopenviking_workspace\"\n  },\n  \"log\": {\n    \"level\": \"INFO\",\n    \"output\": \"stdout\"                 \u002F\u002F Log output: \"stdout\" or \"file\"\n  },\n  \"embedding\": {\n    \"dense\": {\n      \"api_base\" : \"\u003Capi-endpoint>\",   \u002F\u002F API endpoint address\n      \"api_key\"  : \"\u003Cyour-api-key>\",   \u002F\u002F Model service API Key\n      \"provider\" : \"\u003Cprovider-type>\",  \u002F\u002F Provider type: \"volcengine\" or \"openai\" (currently supported)\n      \"dimension\": 1024,               \u002F\u002F Vector dimension\n      \"model\"    : \"\u003Cmodel-name>\"      \u002F\u002F Embedding model name (e.g., doubao-embedding-vision-251215 or text-embedding-3-large)\n    },\n    \"max_concurrent\": 10,              \u002F\u002F Max concurrent embedding requests (default: 10)\n    \"text_source\": \"content_only\",     \u002F\u002F Text file vectorization source: content_only|summary_first|summary_only\n    \"max_input_tokens\": 4096           \u002F\u002F Max estimated raw text tokens sent to embedding\n  },\n  \"vlm\": {\n    \"api_base\" : \"\u003Capi-endpoint>\",     \u002F\u002F API endpoint address\n    \"api_key\"  : \"\u003Cyour-api-key>\",     \u002F\u002F Model service API Key (optional for openai-codex)\n    \"provider\" : \"\u003Cprovider-type>\",    \u002F\u002F Provider type (volcengine, openai, openai-codex, kimi, glm, etc.)\n    \"model\"    : \"\u003Cmodel-name>\",       \u002F\u002F VLM model name (e.g., doubao-seed-2-0-pro-260215 or gpt-4-vision-preview)\n    \"max_concurrent\": 100              \u002F\u002F Max concurrent LLM calls for semantic processing (default: 100)\n  }\n}\n```\n\n> **Note**: For embedding models, supported providers are `volcengine` (Doubao), `openai`, `azure`, `jina`, `ollama`, `voyage`, `dashscope`, `minimax`, `cohere`, `vikingdb`, `gemini` (requires `pip install \"google-genai>=1.0.0\"`), `litellm`, and `local`. For VLM models, common providers include `volcengine`, `openai`, `openai-codex`, `kimi`, and `glm`.\n\n#### Server Configuration Examples\n\n👇 Expand to see the configuration example for your model service:\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Example 1: Using Volcengine (Doubao Models)\u003C\u002Fb>\u003C\u002Fsummary>\n\n```json\n{\n  \"storage\": {\n    \"workspace\": \"\u002Fhome\u002Fyour-name\u002Fopenviking_workspace\"\n  },\n  \"log\": {\n    \"level\": \"INFO\",\n    \"output\": \"stdout\"                 \u002F\u002F Log output: \"stdout\" or \"file\"\n  },\n  \"embedding\": {\n    \"dense\": {\n      \"api_base\" : \"https:\u002F\u002Fark.cn-beijing.volces.com\u002Fapi\u002Fv3\",\n      \"api_key\"  : \"your-volcengine-api-key\",\n      \"provider\" : \"volcengine\",\n      \"dimension\": 1024,\n      \"model\"    : \"doubao-embedding-vision-251215\"\n    },\n    \"max_concurrent\": 10\n  },\n  \"vlm\": {\n    \"api_base\" : \"https:\u002F\u002Fark.cn-beijing.volces.com\u002Fapi\u002Fv3\",\n    \"api_key\"  : \"your-volcengine-api-key\",\n    \"provider\" : \"volcengine\",\n    \"model\"    : \"doubao-seed-2-0-pro-260215\",\n    \"max_concurrent\": 100\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Example 2: Using OpenAI Models\u003C\u002Fb>\u003C\u002Fsummary>\n\n```json\n{\n  \"storage\": {\n    \"workspace\": \"\u002Fhome\u002Fyour-name\u002Fopenviking_workspace\"\n  },\n  \"log\": {\n    \"level\": \"INFO\",\n    \"output\": \"stdout\"                 \u002F\u002F Log output: \"stdout\" or \"file\"\n  },\n  \"embedding\": {\n    \"dense\": {\n      \"api_base\" : \"https:\u002F\u002Fapi.openai.com\u002Fv1\",\n      \"api_key\"  : \"your-openai-api-key\",\n      \"provider\" : \"openai\",\n      \"dimension\": 3072,\n      \"model\"    : \"text-embedding-3-large\"\n    },\n    \"max_concurrent\": 10\n  },\n  \"vlm\": {\n    \"api_base\" : \"https:\u002F\u002Fapi.openai.com\u002Fv1\",\n    \"api_key\"  : \"your-openai-api-key\",\n    \"provider\" : \"openai\",\n    \"model\"    : \"gpt-4-vision-preview\",\n    \"max_concurrent\": 100\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Example 3: Using Google Gemini Embedding\u003C\u002Fb>\u003C\u002Fsummary>\n\nInstall the required package first:\n\n```bash\npip install \"google-genai>=1.0.0\"\n```\n\n```json\n{\n  \"storage\": {\n    \"workspace\": \"\u002Fhome\u002Fyour-name\u002Fopenviking_workspace\"\n  },\n  \"embedding\": {\n    \"dense\": {\n      \"provider\": \"gemini\",\n      \"api_key\": \"your-google-api-key\",\n      \"model\": \"gemini-embedding-2-preview\",\n      \"dimension\": 3072\n    },\n    \"max_concurrent\": 10\n  },\n  \"vlm\": {\n    \"api_base\" : \"https:\u002F\u002Fapi.openai.com\u002Fv1\",\n    \"api_key\"  : \"your-openai-api-key\",\n    \"provider\" : \"openai\",\n    \"model\"    : \"gpt-4o\",\n    \"max_concurrent\": 100\n  }\n}\n```\n\nGet your Google API key at \u003Chttps:\u002F\u002Faistudio.google.com\u002Fapikey>\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Example 4: Using Volcengine Embedding + Codex VLM\u003C\u002Fb>\u003C\u002Fsummary>\n\nUse `openviking-server init` and choose `OpenAI Codex`, then run `openviking-server doctor`.\n\n```json\n{\n  \"storage\": {\n    \"workspace\": \"\u002Fhome\u002Fyour-name\u002Fopenviking_workspace\"\n  },\n  \"embedding\": {\n    \"dense\": {\n      \"api_base\" : \"https:\u002F\u002Fark.cn-beijing.volces.com\u002Fapi\u002Fv3\",\n      \"api_key\"  : \"your-volcengine-api-key\",\n      \"provider\" : \"volcengine\",\n      \"dimension\": 1024,\n      \"model\"    : \"doubao-embedding-vision-251215\"\n    }\n  },\n  \"vlm\": {\n    \"api_base\" : \"https:\u002F\u002Fchatgpt.com\u002Fbackend-api\u002Fcodex\",\n    \"provider\" : \"openai-codex\",\n    \"model\"    : \"gpt-5.3-codex\",\n    \"max_concurrent\": 100\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n#### Set Server Configuration Environment Variable\n\nAfter creating the configuration file, set the environment variable to point to it (Linux\u002FmacOS):\n\n```bash\nexport OPENVIKING_CONFIG_FILE=~\u002F.openviking\u002Fov.conf # by default\n```\n\nOn Windows, use one of the following:\n\nPowerShell:\n\n```powershell\n$env:OPENVIKING_CONFIG_FILE = \"$HOME\u002F.openviking\u002Fov.conf\"\n```\n\nCommand Prompt (cmd.exe):\n\n```bat\nset \"OPENVIKING_CONFIG_FILE=%USERPROFILE%\\.openviking\\ov.conf\"\n```\n\n> 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable.\n\n#### CLI\u002FClient Configuration Examples\n\n👇 Expand to see the configuration example for your CLI\u002FClient:\n\nExample: ovcli.conf for visiting localhost server\n\n```json\n{\n  \"url\": \"http:\u002F\u002Flocalhost:1933\",\n  \"timeout\": 60.0\n}\n```\n\nAfter creating the configuration file, set the environment variable to point to it (Linux\u002FmacOS):\n\n```bash\nexport OPENVIKING_CLI_CONFIG_FILE=~\u002F.openviking\u002Fovcli.conf # by default\n```\n\nOn Windows, use one of the following:\n\nPowerShell:\n\n```powershell\n$env:OPENVIKING_CLI_CONFIG_FILE = \"$HOME\u002F.openviking\u002Fovcli.conf\"\n```\n\nCommand Prompt (cmd.exe):\n\n```bat\nset \"OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\\.openviking\\ovcli.conf\"\n```\n\n### 4. Run Your First Example\n\n> 📝 **Prerequisite**: Ensure you have completed the configuration (ov.conf and ovcli.conf) in the previous step.\n\nNow let's run a complete example to experience the core features of OpenViking.\n\n#### Launch Server\n\n```bash\nopenviking-server doctor\nopenviking-server\n```\n\nIf you configured `provider=openai-codex`, `openviking-server doctor` already validates Codex auth.\n\nor you can run in background\n\n```bash\nnohup openviking-server > \u002Fdata\u002Flog\u002Fopenviking.log 2>&1 &\n```\n\n#### Run the CLI\n\n```bash\nov status\nov add-resource https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking # --wait\nov ls viking:\u002F\u002Fresources\u002F\nov tree viking:\u002F\u002Fresources\u002Fvolcengine -L 2\n# wait some time for semantic processing if not --wait\nov find \"what is openviking\"\nov grep \"openviking\" --uri viking:\u002F\u002Fresources\u002Fvolcengine\u002FOpenViking\u002Fdocs\u002Fzh\n```\n\nCongratulations! You have successfully run OpenViking 🎉\n\n### VikingBot Quick Start\n\nVikingBot is an AI agent framework built on top of OpenViking. Here's how to get started:\n\n```bash\n# Option 1: Install VikingBot from PyPI (recommended for most users)\npip install \"openviking[bot]\"\n\n# Option 2: Install VikingBot from source (for development)\nuv pip install -e \".[bot]\"\n\n# Start OpenViking server with Bot enabled\nopenviking-server --with-bot\n\n# In another terminal, start interactive chat\nov chat\n```\n\nIf you use the official Docker image, `vikingbot` is already bundled in the image and starts by default together with the OpenViking server and console UI. You can disable it at runtime with either `--without-bot` or `-e OPENVIKING_WITH_BOT=0`.\n\n***\n\n## Server Deployment Details\n\nFor production environments, we recommend running OpenViking as a standalone HTTP service to provide persistent, high-performance context support for your AI Agents.\n\n🚀 **Deploy OpenViking on Cloud**:\nTo 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.\n\n👉 **[View: Server Deployment & ECS Setup Guide](.\u002Fdocs\u002Fen\u002Fgetting-started\u002F03-quickstart-server.md)**\n\n## OpenClaw Context Plugin Details\n\n- Test Dataset: Effect testing based on LoCoMo10 (\u003Chttps:\u002F\u002Fgithub.com\u002Fsnap-research\u002Flocomo>) long-range dialogues (1,540 cases in total after removing category5 without ground truth)\n- Experimental Groups: Since users may not disable OpenClaw's native memory when using OpenViking, we added experimental groups with native memory enabled or disabled\n- OpenViking Version: 0.1.18\n- Model: seed-2.0-code\n- Evaluation Script: \u003Chttps:\u002F\u002Fgithub.com\u002FZaynJarvis\u002Fopenclaw-eval\u002Ftree\u002Fmain>\n\n| Experimental Group                          | Task Completion Rate | Cost: Input Tokens (Total) |\n| ------------------------------------------- | -------------------- | -------------------------- |\n| OpenClaw(memory-core)                       | 35.65%               | 24,611,530                 |\n| OpenClaw + LanceDB (-memory-core)           | 44.55%               | 51,574,530                 |\n| OpenClaw + OpenViking Plugin (-memory-core) | 52.08%               | 4,264,396                  |\n| OpenClaw + OpenViking Plugin (+memory-core) | 51.23%               | 2,099,622                  |\n\n- Experimental Conclusions:\n  After integrating OpenViking:\n\n* With native memory enabled: 43% improvement over original OpenClaw with 91% reduction in input token cost; 15% improvement over LanceDB with 96% reduction in input token cost.\n* With native memory disabled: 49% improvement over original OpenClaw with 83% reduction in input token cost; 17% improvement over LanceDB with 92% reduction in input token cost.\n\n👉 **[View: OpenClaw Context Plugin](examples\u002Fopenclaw-plugin\u002FREADME.md)**\n\n👉 **[View: OpenCode Memory Plugin Example](examples\u002Fopencode-memory-plugin\u002FREADME.md)**\n\n👉 **[View: Claude Code Memory Plugin Example](examples\u002Fclaude-code-memory-plugin\u002FREADME.md)**\n\n\\--\n\n## Core Concepts\n\nAfter 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:\n\n### 1. Filesystem Management Paradigm → Solves Fragmentation\n\nWe 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:\u002F\u002F` protocol, each with a unique URI.\n\nThis 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](.\u002Fdocs\u002Fen\u002Fconcepts\u002F04-viking-uri.md) | [Context Types](.\u002Fdocs\u002Fen\u002Fconcepts\u002F02-context-types.md)\n\n```\nviking:\u002F\u002F\n├── resources\u002F              # Resources: project docs, repos, web pages, etc.\n│   ├── my_project\u002F\n│   │   ├── docs\u002F\n│   │   │   ├── api\u002F\n│   │   │   └── tutorials\u002F\n│   │   └── src\u002F\n│   └── ...\n├── user\u002F                   # User: personal preferences, habits, etc.\n│   └── memories\u002F\n│       ├── preferences\u002F\n│       │   ├── writing_style\n│       │   └── coding_habits\n│       └── ...\n└── agent\u002F                  # Agent: skills, instructions, task memories, etc.\n    ├── skills\u002F\n    │   ├── search_code\n    │   ├── analyze_data\n    │   └── ...\n    ├── memories\u002F\n    └── instructions\u002F\n```\n\n### 2. Tiered Context Loading → Reduces Token Consumption\n\nStuffing 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:\n\n- **L0 (Abstract)**: A one-sentence summary for quick retrieval and identification.\n- **L1 (Overview)**: Contains core information and usage scenarios for Agent decision-making during the planning phase.\n- **L2 (Details)**: The full original data, for deep reading by the Agent when absolutely necessary.\n\nLearn more: [Context Layers](.\u002Fdocs\u002Fen\u002Fconcepts\u002F03-context-layers.md)\n\n```\nviking:\u002F\u002Fresources\u002Fmy_project\u002F\n├── .abstract               # L0 Layer: Abstract (~100 tokens) - Quick relevance check\n├── .overview               # L1 Layer: Overview (~2k tokens) - Understand structure and key points\n├── docs\u002F\n│   ├── .abstract          # Each directory has corresponding L0\u002FL1 layers\n│   ├── .overview\n│   ├── api\u002F\n│   │   ├── .abstract\n│   │   ├── .overview\n│   │   ├── auth.md        # L2 Layer: Full content - Load on demand\n│   │   └── endpoints.md\n│   └── ...\n└── src\u002F\n    └── ...\n```\n\n### 3. Directory Recursive Retrieval → Improves Retrieval Effect\n\nSingle vector retrieval struggles with complex query intents. OpenViking has designed an innovative **Directory Recursive Retrieval Strategy** that deeply integrates multiple retrieval methods:\n\n1. **Intent Analysis**: Generate multiple retrieval conditions through intent analysis.\n2. **Initial Positioning**: Use vector retrieval to quickly locate the high-score directory where the initial slice is located.\n3. **Refined Exploration**: Perform a secondary retrieval within that directory and update high-score results to the candidate set.\n4. **Recursive Drill-down**: If subdirectories exist, recursively repeat the secondary retrieval steps layer by layer.\n5. **Result Aggregation**: Finally, obtain the most relevant context to return.\n\nThis \"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](.\u002Fdocs\u002Fen\u002Fconcepts\u002F07-retrieval.md)\n\n### 4. Visualized Retrieval Trajectory → Observable Context\n\nOpenViking'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:\u002F\u002F` path), breaking the traditional flat black-box management mode with a clear hierarchy that is easy to understand.\n\nThe 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](.\u002Fdocs\u002Fen\u002Fconcepts\u002F07-retrieval.md)\n\n### 5. Automatic Session Management → Context Self-Iteration\n\nOpenViking 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.\n\n- **User Memory Update**: Update memories related to user preferences, making Agent responses better fit user needs.\n- **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.\n\nThis allows the Agent to get \"smarter with use\" through interactions with the world, achieving self-evolution. Learn more: [Session Management](.\u002Fdocs\u002Fen\u002Fconcepts\u002F08-session.md)\n\n***\n\n## Advanced Reading\n\n### Documentation\n\nFor more details, please visit our [Full Documentation](.\u002Fdocs\u002Fen\u002F).\n\n### Community & Team\n\nFor more details, please see: **[About Us](.\u002Fdocs\u002Fen\u002Fabout\u002F01-about-us.md)**\n\n### Join the Community\n\nOpenViking 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:\n\n- Light up a precious **Star** for us to give us the motivation to move forward.\n- Visit our **[Website](https:\u002F\u002Fwww.openviking.ai)** to understand the philosophy we convey, and use it in your projects via the **[Documentation](https:\u002F\u002Fwww.openviking.ai\u002Fdocs)**. Feel the change it brings and give us feedback on your truest experience.\n- Join our community to share your insights, help answer others' questions, and jointly create an open and mutually helpful technical atmosphere:\n  - 📱 **Lark Group**: Scan the QR code to join → [View QR Code](.\u002Fdocs\u002Fen\u002Fabout\u002F01-about-us.md#lark-group)\n  - 💬 **WeChat Group**: Scan the QR code to add assistant → [View QR Code](.\u002Fdocs\u002Fen\u002Fabout\u002F01-about-us.md#wechat-group)\n  - 🎮 **Discord**: [Join Discord Server](https:\u002F\u002Fdiscord.com\u002Finvite\u002FeHvx8E9XF3)\n  - 🐦 **X (Twitter)**：[Follow us](https:\u002F\u002Fx.com\u002Fopenvikingai)\n- 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.\n\nLet's work together to define and build the future of AI Agent context management. The journey has begun, looking forward to your participation!\n\n### Star Trend\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=volcengine\u002FOpenViking\\&type=timeline\\&legend=top-left)](https:\u002F\u002Fwww.star-history.com\u002F#volcengine\u002FOpenViking\\&type=timeline\\&legend=top-left)\n\n## Security and privacy\n\nThis project takes security seriously.\nFor vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md)\n\n## License\n\nThe OpenViking project uses different licenses for different components:\n\n- **Main Project**: AGPLv3 - see the [LICENSE](.\u002FLICENSE) file for details\n- **crates\u002Fov\\_cli**: Apache 2.0 - see the [LICENSE](.\u002Fcrates\u002Fov_cli\u002FLICENSE) for details\n- **examples**: Apache 2.0 - see the [LICENSE](.\u002Fexamples\u002FLICENSE) for details\n- **third\\_party**: Respective original licenses of third-party projects\n\n\u003C!-- Link Definitions -->\n","OpenViking 是一个专为AI代理（如openclaw）设计的开源上下文数据库。它通过文件系统范式统一管理代理所需的上下文（记忆、资源和技能），支持层次化的上下文传递和自我进化。项目采用Python编写，具备强大的上下文管理和检索功能，解决了传统方法中上下文碎片化、检索效果差等问题。适用于需要高效管理和利用上下文信息的AI代理应用场景，例如复杂的多轮对话系统或任务执行助手等。",2,"2026-06-11 02:49:25","top_language"]