# Openviking

> Manages AI agent context via OpenViking — a context database that unifies Memory, Resource, and Skill into a directory structure with semantic search and progressive content loading (L0/L1/L2). Use when adding or searching external knowledge resources, managing agent sessions and memories, operating the virtual filesystem (ls/tree/read/write/mkdir/rm/mv), registering skills, or performing vector retrieval. Not for general file storage, relational databases, or full-text search engines without semantic capabilities.

- Skill: `znuaibot/openviking` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add znuaibot/openviking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/znuaibot/openviking/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: znuaibot (https://skillmd.com/u/znuaibot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/znuaibot/openviking

---


# 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):
```bash
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**:
```python
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
```python
client.add_resource("https://example.com/doc.pdf", to="viking://resources/docs/",
                    tags=["team=backend", "type=api-doc"])
```

### Search
```python
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
```python
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
```python
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_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/`