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)

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

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

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_uri returned 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/