Context,
with a filesystem
attached.
OpenViking is an open-source context database for AI agents. It brings memory, knowledge and skills together under one navigable viking:// namespace.
It gives an agent a place to remember, browse and improve.
OpenViking unifies three kinds of context — user memory, project resources and reusable skills — into a virtual filesystem. The agent can navigate that context with familiar operations such as ls, tree and find.
Less context waste
Three information layers let an agent check relevance before loading full detail.
Better context shape
Directory-level summaries preserve where information belongs, not just what it says.
More observable recall
Retrieval trajectories show how the system arrived at a result.
Agents don’t just need answers.
They need context operations.
A long-running agent has to locate the right knowledge, decide how much to load, reuse skills, retain useful experience and explain its path. OpenViking treats those as one context system.
One namespace.
Three context types.
OpenViking presents context as a virtual filesystem. The important shift is structural: memory, resources and skills can live alongside one another, with stable viking:// URIs.
Project docs, repositories, web pages and other source material the agent may need.
Don’t pour the whole archive into the prompt.
OpenViking creates a three-layer information model. An agent can start with a short abstract, orient itself with an overview, then open the original detail only when the task warrants it.
A quick relevance check. Enough to decide whether this directory is worth opening.
Short semantic signal for vector retrieval and quick filtering.
Broader directory summary for reranking and navigation.
Original files and subdirectories, loaded on demand.
Search becomes a path.
OpenViking uses two retrieval modes. find() is the low-latency option for a simple query. search() can analyse a complex task, create typed queries and retrieve across context types.
Use when you already know the kind of thing you want and need a lower-latency query.
OAuth authenticationA context database with a clean centre.
The client delegates to services for filesystem operations, retrieval, sessions, resource import and debugging. Content lives in AGFS; the vector index stores references, vectors and metadata rather than the file content.
A good session doesn’t have to disappear.
When a session commits, OpenViking can compress the conversation, archive older history, extract memories according to policy and write them back into storage.
That makes memory a write path, not a separate afterthought.
The repository reports measurable gains in its own evaluations.
The README describes OpenViking 0.3.22 evaluations on long-conversation memory and multi-turn agent tasks. Read these as reported benchmark results, not universal guarantees.
Reported memory accuracy with OpenViking versus native memory.
Reported reduction across the three agent integrations.
Reported task-success lift from experience memory.
The README also reports query-latency reductions of 58.45–66.10% and other integration-specific results. Models, datasets and setup details are part of the benchmark context.
Keep papers, notes, experiments and reusable analysis skills in one browseable context space — then retrieve the right level of detail for the next question.
These are design patterns inferred from the repository’s context types, retrieval, session and multimodal capabilities. They are examples, not product claims.
A practical first run, from zero to first retrieval.
The simplest route is a local Python installation. The official quick start also documents Docker for running OpenViking as an independent service.
Prepare Python
Use Python 3.10 or higher. A stable network connection is needed for dependencies and model services.
python --versionInstall the package
Choose a package manager. The docs recommend uv; pip and pipx are also documented.
uv tool install openviking --upgradeInitialise and diagnose
The wizard writes the config and helps choose provider/model settings. Doctor checks setup before the server runs.
openviking-server init
openviking-server doctorRun the local server
Start OpenViking, then use a second terminal for the client or CLI.
openviking-server
curl http://localhost:1933/healthAdd a resource
Import a URL, file or directory, and wait for semantic processing before inspecting it.
ov add-resource \
https://github.com/volcengine/OpenViking --waitBrowse and search
Use the filesystem view to learn the shape of the context, then run a semantic query.
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"Start with a context service.
Then give your agent a memory contract.
OpenViking documents integrations for developer tools and agent frameworks including Claude Code, Codex, Cursor, OpenCode, Hermes, LangChain / LangGraph, MCP clients and more.
from openviking_sdk import SyncHTTPClient
client = SyncHTTPClient(
url="http://localhost:1933"
)
client.initialize()
results = client.find(
query="how to use openviking",
target_uri="viking://resources/"
)
client.close()Decide what belongs in memory, resources and skills before you ingest everything.
Evaluate retrieval quality, token usage, latency and the paths that produced results.
Set provider, access, storage and privacy boundaries before a shared deployment.
Useful infrastructure still needs boundaries.
OpenViking makes context more navigable and observable. It does not remove the need for good ingestion, model selection, access control, evaluation or data governance.
- Model services
Semantic processing and retrieval quality depend on configured VLM, embedding and optional rerank services. - Async processing
After ingestion, semantic processing may need to finish before the context is ready to inspect. - Deployment shape
Local, standalone HTTP and Docker paths have different operational and network considerations. - Licensing
The repository states that its main project is AGPLv3, with different licences for some components.
Treat provenance, permissions, retention, prompt injection and benchmark design as first-class product work.