OpenViking Setup: Long-Term Memory for Claude Code and Codex

OpenViking is an open source context database for AI agents. Instead of pushing your notes into a vector store and hoping the right chunk comes back, it stores memories, documents and skills as one virtual filesystem under a viking:// protocol, and the agent browses it with ls, tree, find and grep the way a developer works with files. It added roughly 804 stars in a single day on the way to 30,422 total, and it comes from Volcengine, ByteDance's cloud arm. A working local install takes about ten minutes: one install command, one interactive wizard, and an API key for a model provider.

• The current release is v0.4.15, published August 18, 2026. There are no binary assets; every platform installs from PyPI or runs the container image.
• It needs two model endpoints, not one: an embedding model for retrieval and a VLM for content understanding. Volcengine, OpenAI, Codex OAuth, Kimi, GLM and local Ollama are all supported.
• The server listens on port 1933 and serves a browser Studio UI at /studio, so you can inspect the context tree without writing any client code.
• It is AGPLv3, and the project states plainly that the open source edition has no feature gates, no account and no activation key.

What is OpenViking and why is it trending?

The repository opened in January 2026 and is already at 30,422 stars with 2,353 forks, which is fast even by AI tooling standards. The pitch is narrow and easy to check. Agent memory today is usually a vector store: you ask it a question, it hands back some chunks, and when the answer is wrong you have no way to see why. OpenViking replaces that with a directory structure. Resources, user memories, skills and peer records each get a viking:// URI. Retrieval runs vector search to locate the highest scoring directory first, then drills down layer by layer, so results arrive with their surrounding context attached instead of as orphaned fragments. Each query keeps the browsing trajectory it took, so a bad result is a path you can read.

RelatedStrix Setup: Run an AI Penetration Tester on Your Code

The other half of the attention is the numbers the project publishes. On LoCoMo, a long conversation memory benchmark, it reports three agent integrations moving from 24.20, 33.38 and 57.21 percent on their native memory to between 80.32 and 82.86 percent with OpenViking attached, with input tokens down 34.3 to 91.0 percent and query latency down 58.45 to 66.10 percent. On tau2-bench it reports task success up 6.87 points on retail and 11.87 points on airline. Treat all of those as vendor reported, because they are: the maker ran them on version 0.3.22 and published the reproduction scripts in the repository rather than submitting to a neutral harness. The underlying design is described in a VikingMem paper accepted to VLDB 2026, which is at least stronger provenance than a launch blog post.

How do you install it on Linux, macOS and Windows?

All three supported platforms take the same path, because there is no compiled binary to download. You need Python 3.10 or higher and a network connection. The docs offer three package managers; the project recommends uv, but pip and pipx both work.

# recommended
uv tool install openviking --upgrade

# pip, or pipx if you prefer isolated CLI tools
pip install openviking --upgrade --force-reinstall
pipx install openviking

That single package gives you two commands: openviking-server for the service and ov for the client. Run the wizard next. It asks which provider you want and writes ~/.openviking/ov.conf, and for Ollama it can detect the runtime, install it, and pull models sized to your hardware. Then check your work before you start anything.

openviking-server init
openviking-server doctor
openviking-server

doctor validates the config file, your Python version, provider connectivity and disk space without needing a running server, which makes it the right first move when something looks wrong later. To keep the server alive after you close the terminal, the README's own suggestion is the plain one.

nohup openviking-server > openviking.log 2>&1 &

With the server up, the client is immediately useful. Point it at something real, wait for semantic processing, then walk the tree.

ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

If you only need the client on a second machine, the CLI ships standalone too, either from npm or built from source with cargo.

npm i -g @openviking/cli
cargo install --git https://github.com/volcengine/OpenViking ov_cli

How do you run it in Docker instead?

Docker is the better choice on a home server, or anywhere you would rather not put a Python toolchain on the host. Create the state directory first, because config and workspace data both live under it and it gets bind mounted into the container.

mkdir -p ~/.openviking
touch ~/.openviking/ov.conf

Then write a compose file that pulls the official image from GitHub Container Registry, ghcr.io/volcengine/openviking:latest, maps port 1933 and mounts that directory at /app/.openviking. Bring it up from the same folder.

docker-compose up -d

The container starts the API server on 1933, serves the Web Studio at /studio, and also runs the bundled VikingBot gateway. If you do not want the bot, the documented switches are command: ["--without-bot"] or the environment variable OPENVIKING_WITH_BOT=0. On platforms that forbid bind mounts, you can set OPENVIKING_CONF_CONTENT to the full config JSON to bootstrap on first start.

How do you wire it into Claude Code or Codex?

This is the part most people are actually installing it for. Claude Code and Codex share one installer, which asks for your language, which harnesses to set up, a download source and your credentials, and is documented as idempotent, so re-running it is safe.

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

If you would rather do it by hand, the plugin lives in a remote marketplace and needs no clone.

RelatedUnsloth Setup: Run and Train LLMs on Your Own Machine

claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json
claude plugin install openviking-memory@openviking

Once installed it hooks the session lifecycle: it searches and injects relevant memories before every prompt, captures each response, injects your profile at session start, commits pending messages before compaction and at session end, and gives every subagent an isolated memory session. All writes run asynchronously so they never block the conversation. Verify with /plugins and /mcp inside Claude Code. If nothing seems to happen, set OPENVIKING_DEBUG=1 and read ~/.openviking/logs/cc-hooks.log. Cursor, OpenCode, TRAE, Hermes, OpenClaw, LangChain and generic MCP clients each have their own integration page.

How does it compare to a vector store or plain memory files?

Read that honestly. A markdown memory file costs nothing and works, and for a single project it is often the right answer. The case for OpenViking starts when you have more context than fits in a file, more projects than one file can serve, and enough retrieval failures that you want to see why one happened.

What are the gotchas before you rely on it?

Four worth knowing, and the first is recent enough that it should shape which version you install. Release v0.4.15, published August 18, exists specifically because v0.4.14 declared an unbounded xxhash dependency. A fresh install could pull xxhash 4.x, and newly generated vectors would then fail to persist on the local VectorDB or cuVS backend. The error was not propagated through the write pipeline, so a task looked complete and the source content stayed readable while its vector was never stored, and later searches simply missed it. If you installed during that window, rebuild the vectors for anything added since. Do not pin below v0.4.15.

Second, recent CLI versions require a saved display language before most commands will run. Interactively it prompts you, but in a script, a CI job or an agent shell any non-exempt command exits with code 2 until you set one. This is the single most likely reason an automated setup fails for no visible reason.

ov language en

Third, the server binds to 127.0.0.1 only, which is the right default but bites Docker users on macOS, where the host cannot reach localhost:1933 and you get a connection reset. The documented workaround is a socat forwarder inside the container, mapping host port 1933 to container port 1934. Fourth, the licence is AGPLv3 for the main project, with the ov_cli crate and the examples under Apache 2.0. AGPL is a real consideration if you plan to embed this inside a networked product, and irrelevant if you are running it for yourself. One more thing worth weighing: 464 open issues is a normal shape for a repository this popular, but it is not a mature tracker, and the API surface moves fast enough that the docs tell you to treat ov --help as the source of truth rather than any page they wrote.

Our take

The interesting claim here is not the benchmark table, it is the diagnosis behind it. Vector search made retrieval possible and made it opaque at the same time, and most teams have quietly accepted that when an agent forgets something, nobody can say why. Turning context back into a filesystem gives you the two things a black box cannot: a path you can inspect, and a place you can put something so it stays put. That is a design argument, and it holds whether or not the specific numbers survive contact with an independent harness.

The cost is honest too. This is a server, two model endpoints, a config file and a new protocol in your stack, in exchange for memory that outlives a session. If you use one coding agent on one project, a markdown file will keep beating it. If you run several agents across several repositories and you are tired of re-explaining the same context every morning, an afternoon with this is a reasonable trade. Just install v0.4.15 or later, run doctor before you trust it, and set the CLI language before you automate anything.

Original analysis by GenZTech. Tool documentation: volcengine/OpenViking on GitHub.