OpenViking Memory Doctor

Client-side troubleshooting for the OpenViking memory plugin. The plugin has three moving parts and each fails silently in its own way:

• Install — marketplace registration, plugin enablement, the nine hooks, the stdio MCP proxy. When these are wrong, hooks never run and nothing is logged anywhere.
• Configuration — ~/.openviking/ovcli.conf, ~/.openviking/ov.conf and OPENVIKING_* environment variables, resolved as env → ovcli.conf → ov.conf → defaults. A malformed file reads as "no config", which silently disables the plugin; a stray env var silently overrides the file.
• Connection — on a self-hosted server /health answers 200 even with a bad key, so the statusline can be green while every real request 401s. On OpenViking Cloud the gateway authenticates /health and /ready too, so the same probe answers 401 without a key and says nothing about the url.

When the resolved url is loopback, the server runs on this machine and the doctor adds a Server health section: whether anything listens on the port, plugin-only keys in ov.conf (a top-level block named after any harness: claude_code, codex, cursor, trae, trae_cn, zcode, opencode, dsh, pi, plus server.url) that make the server refuse to start, and GET /ready — the server's own per-subsystem verdict (agfs, vectordb, api keys, embedding, ollama). For a remote server only /ready is probed. Everything else on the server side — config validation, live embedding probe, native engine, disk — is openviking-server doctor, run in the server's Python environment.

Step 1 — run the doctor

node ${CLAUDE_PLUGIN_ROOT}/scripts/ov-memory-doctor.mjs

Options: --json (machine-readable), --offline (skip network probes), --timeout <ms> (per probe, default 5000), --no-color.

The report has six sections — Environment, Plugin install, Configuration, Connection, Server health, Recent activity — and a Summary listing every ✗/⚠ with a fix. Read the whole report before acting: a single root cause usually shows up in several sections (for example a bad key → "api key rejected" + "system/status → 401" + turns_failed > 0).

If the report says "this script is not running from the registered install", rerun it from the path it prints — Claude Code executes hooks from that copy.

The API key is never printed in full. Three-segment keys are shown as account=<a> user=<u> secret=abcd…wxyz (the first two segments are just base64url identity, decoded so the user can see which account/user the key claims). Other shapes are shown as abcd…wxyz (N chars, unsupported format). Keep it that way in anything you show the user.

Step 2 — map findings to causes

Work top-down; fix the first ✗ and rerun before chasing the next.

More symptoms, exact error strings and log stage names: reference.md.

Step 3 — targeted checks (only when the report is not conclusive)

Prove hooks run at all. OPENVIKING_DEBUG=1 must reach Claude Code's own process — a shell export does not, the env block in ~/.claude/settings.json does. Then send one prompt in a new session and read ~/.openviking/logs/cc-hooks.log (JSONL; grep "error" and "hook":"mcp-proxy","stage":"start"). A subagent-stop transcript_read ENOENT line is harmless noise.

Prove the key and identity by hand (Bearer is case-sensitive with exactly one space):

URL=<url>; KEY=<key>
curl -sS "$URL/health"                                  # reachability, version, auth_mode (401 on Cloud: the gateway gates /health)
curl -sS -H "Authorization: Bearer $KEY" "$URL/health"  # 200 without account_id/user_id/role ⇒ key invalid
curl -sS -w '\n%{http_code}\n' -H "Authorization: Bearer $KEY" "$URL/api/v1/system/status"  # real 401/403

Prove /mcp directly (stateless — no initialize needed):

curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$URL/mcp" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $KEY" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Prove Claude Code's MCP wiring: claude mcp list (slow, 30–60s) must show plugin:openviking-memory:openviking: node <installPath>/servers/mcp-proxy.mjs - ✔ Connected; claude mcp get 'plugin:openviking-memory:openviking' needs the full quoted name. /mcp inside a session reconnects the proxy.

Prove a capture landed: take ov_session_id from ~/.openviking/state/last-capture.json and GET $URL/api/v1/sessions/<id> (or ov session get <id>); total_message_count should be ≥ the captured turns, commit_count > 0 proves extraction ran.

Second opinion from the CLI: ov health and ov config validate read the same ~/.openviking/ovcli.conf (they show account/user/role for the key). ov config list reveals whether a different profile was switched in with ov config switch — that also retargets the plugin.

Server side (only meaningful when the server runs on this machine):

curl -sS "$URL/ready"                       # agfs / vectordb / api_key_manager / embedding (live probe, ≤10s) / ollama
openviking-server doctor                    # in the server's own environment: config, native engine, embedding probe, VLM key, disk
lsof -nP -iTCP:1933 -sTCP:LISTEN            # who owns the port
docker logs --tail 100 openviking           # container deployments

log.output defaults to stdout, so the server log is the terminal/tmux pane it runs in, the nohup file, journalctl -u openviking, or docker logs; with "file" it is <storage.workspace>/log/openviking.log. A server that exits at startup prints the reason right there — running openviking-server in the foreground is the quickest way to see it. It is the user's process: ask before stopping or restarting it.

Fixing

• Edit ~/.openviking/ovcli.conf only with the user's agreement; show the change, keep unknown keys, keep mode 0600, never echo the key.
• Prefer env vars in the env block of ~/.claude/settings.json for machine-wide overrides; a shell rc export only reaches sessions started from that shell and silently outranks the file everywhere.
• After changing url, installing or updating the plugin: restart Claude Code. Hooks re-read config per invocation, the MCP proxy does not.
• Updates: GitHub installs → claude plugin marketplace update openviking && claude plugin update openviking-memory@openviking; TOS installs on Claude Code 2.1.224+ (a url marketplace) auto-update in the background, or on demand with claude plugin update openviking-memory@openviking; older TOS, archive and dev-checkout installs → re-run the installer.
• Confirm the fix by rerunning the doctor, then by observing an <openviking-context> block on the next prompt.

Documentation

• Source and issues: https://github.com/volcengine/OpenViking — plugin code lives under examples/, the shared installer under examples/memory-plugin-shared/.
• Documentation index (LLM-friendly): https://docs.openviking.ai/llms.txt; the harness integration pages under it cover install paths, configuration keys and known limitations.
• https://api.vikingdb.cn-beijing.volces.com/openviking is the Volcengine-hosted OpenViking Service (OpenViking Cloud): the path prefix is part of the base url, it accepts Authorization: Bearer only, and its keys are issued from the Volcengine console rather than by a self-hosted admin.

Rules

• Never print a full API key or the raw contents of ovcli.conf; the doctor's masked forms are the limit.
• scripts/setup.mjs needs a TTY and, on older plugin versions, an existing ovcli.conf; on a fresh machine write the file directly or re-run the installer.
• Never pipe claude plugin list into grep -q; capture the output first (early exit under pipefail reads as "not installed").
• /health returning 200 proves reachability only. Auth is proven by the identity fields with a key, or by /api/v1/system/status.
• ov doctor is openviking-server doctor: it validates the server's own config and providers in the server's Python environment, makes a live embedding call, and says nothing about this plugin. Run it for provider-level failures, not first.
• The doctor only reads. Never stop, restart or kill the user's server, or edit ov.conf, without asking.
• Older proxy versions say "check that 'ov serve' is running" — there is no such command; the server is started with openviking-server.
• OPENVIKING_MEMORY_ENABLED=0 disables the hooks but not the MCP tools; OPENVIKING_MCP_URL has no effect on this plugin.