Viking is an optional hierarchical memory system that Ryvos integrates with for advanced long-term memory. Based on OpenViking (by ByteDance, Apache 2.0), it provides three-tier context loading that reduces token costs by 83-96% compared to loading full memory into every conversation.

Why Viking?

The default SQLite memory works well for keyword search and simple recall. Viking adds:

• Tiered loading — Only load the detail level you need (L0: 100 tokens, L1: 2,000 tokens, L2: full content)
• Hierarchical organization — Memory organized in a virtual filesystem with directories
• Semantic retrieval — Directory-recursive retrieval that preserves both relevance and structure
• Self-iteration — Automatic memory extraction and organization at session end
• Observable retrieval — Full browsing trajectory for debugging how context was found

Three-Tier Context Loading

Viking stores every memory at three detail levels:

This means a memory about "PostgreSQL migration guide" might look like:

L0: "Guide for migrating from PostgreSQL 14 to 15 with zero downtime."

L1: "Step-by-step PostgreSQL 14→15 migration. Key steps: pg_upgrade with
    --link flag, logical replication setup, sequence reset, extension
    compatibility check. Estimated downtime: 0 with logical replication,
    5-15 min with pg_upgrade. Requires PostgreSQL 15 installed alongside 14."

L2: [Full 5,000-word guide with commands, config files, rollback procedures...]

When the agent is working on a database task, it first sees L0 summaries of all memories, drills into L1 for relevant ones, and only loads L2 when it needs the exact commands.

The viking:// Protocol

Viking organizes memory as a virtual filesystem:

viking://
├── resources/          # Project docs, repos, web pages
│   ├── postgres-migration/
│   └── api-documentation/
├── user/               # User profile and preferences
│   ├── profile
│   ├── preferences
│   └── entities
└── agent/              # Agent's learned knowledge
    ├── events          # What happened
    ├── cases           # Problem-solving patterns
    ├── patterns        # Recurring behaviors
    └── skills          # Learned capabilities

The agent interacts with Viking memory using filesystem-like operations: list, read, write, search. This makes memory browsable and debuggable.

Setup

Enable Viking in Config

[openviking]
enabled = true
url = "http://localhost:1933"       # Viking server endpoint
auto_start = true                   # Auto-start with daemon mode
dual_write = true                   # Write to both SQLite and Viking

Start the Viking Server

Viking runs as a separate server on port 1933:

Auto (Daemon)

When auto_start = true, the Viking server starts automatically with ryvos daemon:

ryvos daemon --gateway
# Viking server starts on port 1933 automatically

Manual

Start the Viking server separately:

ryvos viking-server

Or use the standalone OpenViking server:

# Via cargo
cargo install ov_cli
ov serve
 
# Via pip
pip install openviking
openviking-server

Configure Embeddings

Viking requires an embedding provider for semantic retrieval:

[embedding]
provider = "openai"
model = "text-embedding-3-small"
api_key = "${OPENAI_API_KEY}"

Viking Tools

Ryvos provides 4 built-in Viking tools:

viking_search

Semantic search across all Viking memory:

{
  "query": "database migration procedures",
  "tier": "L1",
  "limit": 5
}

Returns results at the requested tier level. Start with L0 for broad scanning, drill into L1/L2 for details.

viking_read

Read a specific memory path:

{
  "path": "viking://resources/postgres-migration",
  "tier": "L2"
}

viking_write

Write or update a memory:

{
  "path": "viking://agent/cases/auth-bug-fix",
  "content": "When JWT validation fails with 'token expired' but the token is fresh, check the server clock sync. NTP drift > 30s causes this.",
  "metadata": {
    "category": "debugging",
    "confidence": 0.95
  }
}

Viking automatically generates L0 and L1 summaries from the full L2 content.

viking_list

Browse the memory filesystem:

{
  "path": "viking://agent/cases/",
  "recursive": false
}

Returns directory listings with L0 summaries for each entry.

Dual-Write Mode

When dual_write = true, every memory_write call writes to both SQLite and Viking:

memory_write("deploy_process", "...")
    ├── SQLite: stored in memory table with FTS5 index
    └── Viking: stored at viking://agent/events/deploy_process with L0/L1/L2

This provides:

• Resilience — If Viking is down, SQLite still has the data
• Backward compatibility — Existing memory_search still works
• Gradual migration — Move to Viking at your own pace

Memory Self-Iteration

At the end of each session, Viking automatically extracts long-term memories:

1. User Memory — Profile updates, preference changes, entity mentions
2. Agent Memory — Events that happened, problem-solving patterns, learned skills

These are organized into the viking:// directory structure automatically. Over time, the agent builds a rich knowledge base that makes it more effective.

Directory Recursive Retrieval

When searching, Viking does not just do flat vector search. It uses hierarchical retrieval:

1. Initial retrieval — Vector search identifies high-scoring directories
2. Secondary retrieval — Search within the most relevant directories
3. Recursive drill-down — Follow subdirectory structure for context
4. Result assembly — Combine results preserving both relevance and hierarchy

This preserves the structural relationships between memories. A search for "authentication" finds not just the auth fix, but also the related user preferences and project conventions stored nearby in the hierarchy.

Migration

Move existing SQLite memories to Viking:

ryvos migrate-memory --from sqlite --to viking

This reads all memory entries from SQLite and writes them to Viking with auto-generated L0/L1/L2 tiers. The reverse is also supported:

ryvos migrate-memory --from viking --to sqlite

Performance

Based on OpenViking benchmarks (LoCoMo10):

The token cost reduction comes from L0/L1 tiering: most memories are represented by their ~100 token L0 summary instead of their full content.

Graceful Fallback

If the Viking server is unavailable, Ryvos falls back gracefully:

• Viking tools return an error message explaining the server is down
• memory_search and memory_write continue to work via SQLite
• The agent can still function with SQLite-only memory
• When Viking comes back, dual-write resumes automatically

:::note Viking is entirely optional. The SQLite memory system is fully functional on its own. Viking adds hierarchical organization and token-efficient retrieval for power users with large knowledge bases. :::

Next Steps

• Memory System — The SQLite foundation
• Context Management — How memory feeds into the 3-layer context stack
• Configuration — Viking and embedding config options