OpenViking Memory Doctor — reference

Companion to SKILL.md: where things live, what the exact error strings mean, and the symptom catalogue. Paths assume the defaults; OPENVIKING_HOME, OPENVIKING_CONFIG_FILE, OPENVIKING_CLI_CONFIG_FILE, OPENVIKING_DEBUG_LOG and OPENVIKING_PENDING_DIR relocate individual pieces.

Where things live

Config resolution

Only trailing slashes are stripped from the url; no scheme check, no path normalisation. https://api.vikingdb.cn-beijing.volces.com/openviking (the Volcengine-hosted OpenViking Service) is a legitimate path prefix; /api/v1 or /mcp suffixes are not.

peer.source decides the derivation. git (the default) is the template list ["{git_remote}", "{git_root}"]: the normalized origin URL ([email protected]:volcengine/OpenViking.git → github.com-volcengine-openviking, userinfo dropped so an embedded token can never reach the id), else the repository root path (the legacy [^A-Za-z0-9] → - rule), else nothing — outside a git repository no peer is sent at all, and what is remembered there goes to the user-level space. {cwd} is still a variable but sits in no default chain, and {dir} is the workspace root's directory name, empty when the directory is not a workspace. cwd is that legacy rule alone (the pre-git behaviour); none sends no peer, which is also what OPENVIKING_WORKSPACE_PEER=0 means. Anything else is a template, or a list of templates tried in order ("git-{git_remote}", ["team-{dir}", "{cwd}"]); a template naming an empty variable falls through to the next. Derivation is filesystem-only — no git subprocess — so it survives a missing git and a dubious-ownership refusal; worktrees converge through commondir, a submodule keeps its own identity, and $HOME and / are never workspace roots. Every clone of one repository shares one peer; a fork's origin differs, so it stays separate, and gh pr checkout does not change origin.

Peers minted before this need no migration: the old cwd-derived id is recomputed locally, peer_scope: "all" already sweeps it, and under "actor" recall asks it separately. Doctor prints it as previous peer. Across the workspace layers lists union rather than replace, with a leading "!reset" dropping what the lower layers contributed; unknown keys are kept and ignored, and a file declaring a version other than 1 is skipped with a warning.

Sent headers: Authorization: Bearer <key>, X-OpenViking-Account, X-OpenViking-User, X-OpenViking-Actor-Peer, User-Agent: openviking-memory-claude-code/<version>. The open-source server also accepts X-API-Key (and prefers it when both are sent); the Volcengine-hosted OpenViking Service (https://api.vikingdb.cn-beijing.volces.com/openviking) accepts Bearer only.

Peer: giving a directory its own memory

{"version": 1, "peer": {"id": "my-project"}}

Stored as .openviking/config.json in the directory to be named; that directory and everything below it then writes to that peer, repository or not.

That file and the registry file whose path the doctor prints are the whole surface. No ov subcommand creates, renames or merges a peer. Changing the id moves no existing memory: the cross-peer sweep under peer_scope: "all" still reaches what was written before, and under "actor" the extra query still reaches the pre-git cwd-derived id.

Server auth modes (from GET /health → auth_mode)

Key formats: base64url(account).base64url(user).base64url(secret) (three segments, identity readable) or a bare 64-hex legacy key (identity only via server lookup). Both fail identically as 401 Invalid API Key when unknown — there is no "wrong account" error.

role: root keys are allowed only on /api/v1/system/status, /api/v1/admin/*, /api/v1/observer/*, /api/v1/tasks/* and a few system paths; everything the plugin uses (/api/v1/sessions, /api/v1/search, /api/v1/fs, /mcp) answers 403 ROOT API keys cannot access tenant-scoped data APIs in api_key mode.

Error strings

Server (REST): {"status":"error","error":{"code":…,"message":…}}

/mcp directly: 406 Not Acceptable: Client must accept both application/json and text/event-stream; 400 plain text Invalid Content-Type header; 401/403 as JSON-RPC -32001 with the server message; 404 → no MCP endpoint at that url.

Plugin MCP proxy (what Claude Code shows for a failing tool call):

Hook log (cc-hooks.log) stages worth grepping: health_check (connectivity), push_turns / capture_write / pending_enqueue (capture), recall_context_assembled / search_summary / injection_built (recall), mcp-proxy start (resolved mcpUrl, hasApiKey = present, not valid), uncaught (crash). Hooks: session-start, auto-recall, auto-capture, session-end, pre-compact, subagent-start, subagent-stop, skill-experience, mcp-proxy. Ordinary failed proxy requests are not logged — the JSON-RPC error on stdout is the artifact.

State file fields

last-recall.json: reason ∈ ok, no_results, filtered_out, short_query, offline, bypass, disabled, bad_stdin; plus count, latency_ms, server_url, cc_session_id, ts.

last-capture.json: turns_captured, turns_queued (retryable, will replay), turns_failed (non-retryable, dropped), pending_tokens / commit_threshold, commit_count, ov_session_id (cc-<claude session id>), ts.

Statusline: OV ✓ = /health 200 within 1s (says nothing about auth); OV ⚠ slow = probe timed out; OV ✗ offline = refused/DNS/TLS/non-2xx; OV ⚡ bypass = bypass matched; ✗ N dropped = turns_failed. Segments disappear after 30 minutes of inactivity — a bare OV ✓ means idle, not broken.

Local server (loopback url only)

Process: <python> -E …/bin/openviking-server — match openviking-server in the command line, never the process name (Python). Default bind 127.0.0.1:1933; --host/--port override server.host/server.port. The port is bound only after initialization finishes, so "connection refused" during startup is normal; /health 200 says nothing about embedding or VLM.

GET /ready (no auth, 200 or 503): {"status":"ready"|"not_ready","checks":{"agfs":{"status":…,"checks":{"filesystem":…,"multiwrite_sync":…}},"vectordb":…,"api_key_manager":…,"embedding":…,"ollama":…}}. ok, not_configured and not_supported count as healthy; embedding is a real embed call with a 10s cap. 503 {"status":"not_ready","reason":"initializing"} while booting; 404 on servers that predate the endpoint. The official docker image answers every route with 503 {"status":"pending_initialization", "fix":[…]} until it has an ov.conf.

Startup failures (printed by the server; exit 1 unless noted):

Runtime signatures in the server log: Dimension mismatch (config), Dense vector dimension mismatch (writes dropped), Credential … failed with auth and Backup VLM also failed (VLM key), Embedding circuit breaker is open (provider down, messages re-queued).

openviking-server doctor (same as ov doctor) checks Config, Python, Native Engine, AGFS, Authentication, Embedding (live probe), VLM (key presence only), Ollama, VikingBot and Disk. Text only, exit 1 on FAIL, needs the server's Python environment; the bare Rust ov binary (npm / cargo install) reports unknown command.

Symptom catalogue

Links

• Source: https://github.com/volcengine/OpenViking
• Docs index: https://docs.openviking.ai/llms.txt