znuaibot OpenViking context database
OpenViking stores all agent context (Memory / Resource / Skill) as a virtual directory structure with semantic search and L0/L1/L2 progressive loading.
Local deployment (already running)
| Item | Value |
|---|---|
| Server | http://localhost:1933 (v0.4.15, auth=trusted) |
| API key | f0295b83557506298fb9be1df4bf4be059d5c764ffb2b5d79799ae7209616073 |
| Account/User | hermes / hermer-one |
| CLI | openviking (installed at ~/.local/bin/openviking) |
| MCP endpoint | http://localhost:1933/mcp (streamable HTTP, 15 tools) |
| WorkBuddy MCP | Configured in ~/.workbuddy/mcp.json as openviking (streamableHttp) |
| Embedding | ollama qwen3-embedding:4b (dim=1024, localhost:11434) |
Three usage paths
1. CLI (already configured):
openviking find "query" --limit 5
openviking ls viking://~/
openviking read viking://resources/foo.md
2. MCP (configured in WorkBuddy — restart WorkBuddy to activate): Tools: find, search, read, list, tree, remember, write, edit, add_resource, list_watches, cancel_watch, grep, glob, forget, health
3. Python SDK:
from openviking_sdk import SyncHTTPClient
client = SyncHTTPClient(url="http://localhost:1933", api_key="f0295b...")
results = client.find("authentication", target_uri="viking://resources/docs/")
Core concepts
| Concept | Summary |
|---|---|
| Context types | Resource (external knowledge), Memory (agent cognition), Skill (agent capability) |
| L0/L1/L2 | L0 = ~256 char abstract for vector recall; L1 = ~4000 char overview for rerank; L2 = full content, loaded on demand |
| Viking URI | viking://{scope}/{path} — scopes: resources/, ~/memories/, ~/skills/, agent/skills/ |
Workflow decision tree
Adding knowledge? → See "Resource management" below
Searching existing knowledge? → See "Search" below
Managing agent memory? → See "Session & memory" below
Registering agent skills? → See "Skill management" below
Backup or migration? → See references/api-reference.md → "Snapshot & pack"
Managing accounts/users/API keys, auth modes, or server start/stop issues? → See references/admin-and-auth.md
Key operations
Resource management
client.add_resource("https://example.com/doc.pdf", to="viking://resources/docs/",
tags=["team=backend", "type=api-doc"])
Search
results = client.find("OAuth", target_uri="viking://resources/", limit=10)
overview = client.overview(results[0]["uri"]) # L1
content = client.read(results[0]["uri"]) # L2
Session & memory
session = client.session()
session.add_message("user", "How to implement JWT?")
session.add_message("assistant", "JWT involves signing, verification...")
session.commit(keep_recent_count=5) # triggers memory extraction
Skill management
client.add_skill({"name": "search-web", "description": "Search the web",
"content": "# search-web\n..."})
Error handling
| Error code | HTTP | Action |
|---|---|---|
NOT_FOUND |
404 | Check URI spelling and scope |
UNAUTHENTICATED |
401 | Verify api_key in client config |
EMBEDDING_FAILED |
500 | Retry; check model availability |
RESOURCE_EXHAUSTED |
429 | Back off and retry with delay |
Full error reference: see references/api-reference.md
Success criteria
- Resource added →
wait_processed()returns without error - Search results → relevant items in top 5 with score > 0.7
- Session commit →
archive_urireturned and task completes - L0 → L1 → L2 progression → each level has strictly more content than previous
References
- API endpoints (full):
references/api-reference.md - Architecture & data flow:
references/architecture-notes.md - Admin API, auth modes, key management, server ops:
references/admin-and-auth.md - Python SDK scenarios (10 examples):
examples/scenarios.py - TypeScript SDK examples:
examples/typescript-sdk.ts - CLI command reference:
examples/cli-examples.sh - Official docs: https://docs.openviking.ai/zh/
- Source code:
D:/work/agents/playgym/OpenViking/