The Practical Guide

Should you use OpenViking?

OpenViking is a durable, semantic-vector memory store. An agent writes facts, events, and digests into it once; every future session can retrieve them by meaning — not by exact text match. If your agent forgets things between sessions, this is the fix. Here is the honest scoreboard first, detail below.

What OpenViking is

OpenViking is a context database for AI agents: a vector-backed store with an HTTP API. Two kinds of data live in it — resources (large operational digests, cheap to keep) and memories (high-signal facts that get injected into relevant conversations). The diagram below shows the full write/read path.

Resources vs Memories

The single most important decision in OpenViking: where a write goes determines whether it costs tokens later. Memories are injected into relevant conversations — that is a feature when the fact matters, a tax when the data is routine.

Taxonomy — the rules that keep it sane

Two violations cause most long-term pain. Fragmentation: 10 tiny hash files where one digest belongs. Wrong scope: operational data in memories/, silently taxing every relevant conversation. The decision tree:

Semantic search — and its sharp edges

OpenViking search is pure cosine similarity against query embeddings. That means newer is not higher — relevance outranks recency, with no time decay. Observed in production: a June digest (score 0.638) outranks a June 20 digest (0.584) for the same query. If you need the newest dated resource, sort by filename date yourself.

Which models power the memory

OpenViking uses two model roles. Knowing them matters because each is a different failure surface, and the /ready probe reports on exactly one of them.

Reading and writing — the proven patterns

Use the HTTP API directly. The Python SDK has binary compatibility issues across Python versions; curl or urllib is the reliable path. Three write modes, one reindex endpoint, and the directory trap:

# Write a new memory file — mode:"create" is mandatory for new URIs
curl -s -X POST -H "Authorization: Bearer $OV_KEY" \
  -H "Content-Type: application/json" \
  "http://<openviking-host>:1933/api/v1/content/write" \
  -d '{"uri": "viking://user/peers/hermes/memories/<category>/<file>.md",
       "content": "<content>", "mode": "create"}'

# Daily files written twice/day: try create, on 409 retry with replace
# (the shared write_resource() does exactly this)

# Read back
curl -s -H "Authorization: Bearer $OV_KEY" \
  "http://<openviking-host>:1933/api/v1/content/read?uri=viking://user/peers/hermes/memories/<category>/<file>.md"

txt = res.get("result")
txt = txt.get("content", "") if isinstance(txt, dict) else (txt or "")

Cron writes: deterministic, never LLM tool calls

The biggest production lesson: LLM agents in cron hallucinate tool calls. They report "28 headlines stored" without a single write landing. The fix is structural — move all writes into Python scripts that call the HTTP API directly, and let the cron agent only run the script and report.

The mistake feedback loop

An agent that cannot record its own errors repeats them. The loop: catch the correction → 5 Whys to root cause → store in OpenViking → search before acting next time. The key standard: holistic patterns, not one-off logs. Trace every mistake to a repeatable reasoning bias.

Making your coding agent learn

Six evidence-based patterns for a coding-enabled agent stack — proven on a production box, not theory.

How this powers pi.dev in a real workflow

pi.dev is a minimal, stateless coding agent: it executes the spec it is given and remembers nothing between sessions. That is a feature — but it means all institutional knowledge must arrive in the prompt or the rails. OpenViking is the declarative layer that makes the loop self-improving:

The API key hierarchy — the #1 "it's broken" cause

Three key levels exist. The root key can manage accounts but cannot touch data — a gateway configured with the root key passes health checks while every read and write fails silently with PERMISSION_DENIED. This is the most common false alarm in the system.

# Create account + admin user in one call (returns the USER key)
curl -s -X POST -H "Authorization: Bearer $ROOT_KEY" \
  -H "Content-Type: application/json" \
  "http://<openviking-host>:1933/api/v1/admin/accounts" \
  -d '{"account_id": "hermes", "admin_user_id": "default"}'

# The user_key from that response is what the gateway must use.
# Never configure the root key in the gateway.

Fast diagnosis of the common failures

Related skills worth loading

These companion skills carry the full procedures behind this guide. Load them when the trigger condition appears.

Before you consider a write done

• Content consolidated — one digest, not fragmented tiny files
• Correct scope — operational data in resources/, facts in memories/
• Descriptive filename — never a bare hash for canonical entities
• No duplicate writes — checked existing content first
• Searchable after write — verified via viking_search or reindex