Contents

OpenViking is an open-source context database that brings AI agents’ knowledge, memories from conversations, and skills into a single virtual file system. You can find, read, and write stored content using viking:// URIs and connect it to your own agents.

Key Points#

  • Organize knowledge, user memories, and task procedures under viking://.
  • Load the information you need in stages using directory-level searches and summaries.
  • Host the server yourself with Python 3.10 or later, uv, an embedding model, and a VLM.
  • Install memory plugins for Claude Code, Codex, Cursor, and other agents.
  • Avoid exposing the server publicly without configuring authentication.

What Can OpenViking Do?#

OpenViking manages project documents and similar materials as resources, user preferences and experiences as memories, and work procedures as skills. Each has a URI, allowing agents to navigate storage locations and read or search their contents.

Unlike typical vector search systems, where you register information and only view search results, OpenViking lets you open directories to inspect and edit stored content. Committing a session archives the conversation and lets you review the memories extracted from it as Markdown.

From Summaries to Source Content#

Directories can include summaries at different levels of detail. L0 is a one-sentence overview, L1 describes structure and purpose, and L2 contains detailed content such as the original text. This lets agents check relevance through an overview first, then open only the files they need.

Search also uses the storage structure. For example, you can narrow a search to a specific project or area of user memory, so you do not have to search a large collection containing loosely related information every time. In the CLI, use ov ls or ov tree to inspect contents, ov find for semantic search, and ov grep for text search.

Set Up the Server#

To run your own server, you need uv, Python 3.10 or later, and a supported model provider and models. Configure the models through the initial setup wizard and start the server.

setup.sh
uv tool install openviking --upgrade
openviking-server init

The wizard supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama. Settings are written to ~/.openviking/ov.conf, and the server runs in the foreground. If you already have a server, proceed to configuring CLI or agent connections.

Try Searching#

Once the server is running, add a repository as a resource. Registration runs as a task, so check its completion status using the returned ID before searching.

example.sh
ov status
ov add-resource https://github.com/volcengine/OpenViking
ov task status TASK_ID
ov ls viking://resources/
ov find "what is openviking"

Replace TASK_ID with the ID displayed when you added the resource. Results from ov find include URIs for matching context. Follow those URIs to access the information you need. Python, Go, and TypeScript SDKs and an HTTP API also let you connect your own applications.

Agent Integration and Considerations#

An installer lets you add memory plugins to supported agents, including Claude Code, Codex, and Cursor. After the first launch, ask the agent to remember a preference, then test whether it can recall it in another session. Memory processing can take time, so it may not appear in search results immediately.

The self-hosted version is available under AGPLv3. If you allow external connections, configure authentication and check account and user isolation, along with resource ACLs as needed. Published benchmarks include LoCoMo and tau2-bench results using OpenViking 0.3.22, but results vary depending on the models and evaluation conditions. Test it with the data and models you plan to use.

Next Steps#

Start by checking the current setup instructions in OpenViking’s GitHub repository, then choose where to run the server and which models to use. Next, add one small repository and test whether ov find returns the information you want.

Source: https://github.com/volcengine/OpenViking

Contents