OpenViking: an AGPL-3.0 context database that gives AI agents a viking:// filesystem for memory, knowledge and skills

Context lives as a virtual filesystem under viking://, so memory can be browsed and edited

The central idea is that most agent memory is a black box: text goes in, embeddings come out, and nobody can see what was stored. OpenViking organises context as a virtual filesystem under viking:// instead. Agents navigate it like files with ls, tree, read, write and grep, and you can open any directory to inspect and edit what the agent knows.

The tree has resources for project documents, code and web pages, and a user area with memories such as preferences and coding habits, private resources, skills such as search_code, and peers. The consequence is that memory becomes something you can review and correct by hand, which suits debugging an agent that remembers something wrong. The cost is that you manage a directory structure, with the naming and organisation decisions that implies.

Three loading tiers let an agent read a summary before opening the source

Directories that have been semantically processed carry generated summaries. L0 is the abstract, a one-sentence summary for quick relevance checks. L1 is the overview, with core information and usage scenarios for planning. L2 is the details, the full original data read only when needed. The layout looks like this:

viking://resources/my_project/
├── .abstract.md           # L0: quick relevance check
├── .overview.md           # L1: structure and key points
└── docs/
    ├── .abstract.md
    ├── .overview.md
    └── api/
        ├── auth.md         # L2: full content, loaded on demand
        └── endpoints.md

The retrieval consequence is that the find command runs a query directly while search plans retrieval from session context, and semantic search can be scoped to a project or memory subtree. The price is that the summaries are generated, so they cost model calls, and an agent that relies on an L0 line alone only sees as much as that sentence says.

The server needs both an embedding model and a VLM from a model provider

The quick start says that deploying your own needs uv, Python 3.10 or newer, and a model provider with an embedding model and a VLM. The package depends on openai, litellm and the Volcengine SDKs, so several providers can be reached.

The consequence is that OpenViking is not usable offline from a bare install. Two model roles have to be filled before the first directory is summarised, and every ingestion and summary then incurs calls to them. The provider choice affects both cost and the quality of the L0 and L1 text. The Docker setup is the other route: a compose file runs the image ghcr.io/volcengine/openviking:latest, with a comment offering a mirror hosted by Volcengine if ghcr is hard to reach, and a volume mounted at ~/.openviking for the data.

The benchmark results come from a version older than the current release and from the vendor's own models

The README reports that OpenViking 0.3.22 was evaluated on LoCoMo for long-conversation user memory and on tau2-bench for multi-turn agent tasks. With OpenViking, three agent integrations reach 80 to 83 percent accuracy, up from 24 to 57 percent on their native memory, while input tokens drop by 34.3 to 91.0 percent and query latency by 58.45 to 66.10 percent. Experience memory lifts task success by 6.87 points on retail and 11.87 points on airline over the same LLM without memory.

Two caveats follow from the text. The evaluated version is 0.3.22, while the current releases are in the 0.5 series. And the memory evaluation used Doubao 2.0 Pro as the VLM and Doubao-embedding-vision as the embedding model, both Volcengine products. Results may differ with other models. Reproduction scripts are in the benchmark directory, so run them on your own conversations.

AGPL-3.0 and an Alpha classifier are the two adoption flags

The repository is licensed under AGPL-3.0 and the pyproject repeats that licence. It also carries the classifier Development Status 3 - Alpha. AGPL is a strong copyleft licence, so using OpenViking inside a product you offer to others raises obligations that your legal advisers should review before you build on it.

The Alpha label matches the release cadence. The recent releases are v0.5.3 and python-sdk 0.1.18, both on 2026-11-02, and v0.5.2.1 on 2026-10-27, and the last push was the same day as the newest tag. Expect interfaces to change between versions. Pin the server and the SDK together, because the SDK has its own version number, and read the notes before each upgrade.

Sessions become Markdown memories, and ov compile builds wikis, graphs or reports

Committing a session archives the conversation and extracts memories as Markdown that you can inspect, edit and merge. With VikingBot enabled, the ov compile command organises source material into a wiki, a knowledge graph or a report. The pyproject workspace includes Rust crates named ov_cli and ragfs, and a ragfs-python binding, which are the pieces behind the command line and the filesystem layer.

The benefit is that what the agent learned from a session is a set of files you can diff and merge, which fits normal review habits. The dependency is that compile needs VikingBot to be enabled, so it is not available from the base install alone. The repository's examples show plugins for Claude Code, Codex, OpenCode, OpenClaw, Open WebUI and Hermes, plus Grafana, Kubernetes Helm and multi-tenant examples.

Deployment puts Caddy in front, with 1934 as the recommended entry point

The docker-compose file maps the server port 1933 by default and notes that the Caddy port 1934 is the recommended single entry point, with the direct port optional and to be commented out once Caddy is the only ingress. A gateway can be enabled with an environment variable, and a management key and an encryption key are read from the environment. A public HTTPS setup needs OPENVIKING_PUBLIC_BASE_URL and an ACME email in a .env file, for cases such as OAuth and MCP clients on the internet.

The lesson is that exposing the port directly is a fallback, and a reverse proxy with HTTPS is the intended shape for anything reachable from outside. Treat the management and encryption keys as secrets, since the compose file reads them from the environment. A health check runs the entrypoint with a healthcheck flag every 30 seconds.

Editorial conclusion

OpenViking suits teams building agents who want inspectable, editable memory organised as files, and who can accept an AGPL-3.0 licence, an Alpha classification and a need for both an embedding model and a VLM. It does not suit products that cannot take on AGPL obligations, or anyone who treats its benchmark numbers as independent proof. Before adopting it, read the licence with counsel, repeat the memory evaluation on your own conversations, and pin a release since versions move several times a week.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes