ov-memory-doctor

name	ov-memory-doctor
description	Diagnose and fix the OpenViking memory plugin on this machine: the plugin install (marketplace, enablement, hooks, MCP server), the client configuration (ovcli.conf / ov.conf / OPENVIKING_* env — which one wins, what the API key claims) and the connection to the OpenViking server (reachability, 401/403, /mcp). Use whenever memory "isn't working": no <openviking-context> block appears, recall is always empty, captures don't land, MCP memory tools are missing or fail, 401/403 errors, the statusline says offline, right after installing/updating the plugin or switching servers/keys, or when the user asks for the plugin's status. Trigger phrases include "memory not working", "check OpenViking", "plugin status", "记忆没生效", "插件状态", "连不上 OpenViking", "recall 为空", "401", "0 memories extracted". When the server runs on this machine (loopback url) it also checks the port, plugin-only keys in ov.conf that stop the server from starting, and `GET /ready`; everything else server-side stays with `openviking-server doctor`.
allowed-tools	Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/ov-memory-doctor.mjs *)

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 — /health answers 200 even with a bad key, so the statusline can be green while every real request 401s.

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 (claude_code, codex, 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); legacy keys as abcd…wxyz (64 chars). 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.

Doctor finding	Meaning	Action
plugin disabled — every hook exits immediately	No parseable config, OPENVIKING_MEMORY_ENABLED=0, or claude_code.enabled: false in ov.conf	Fix the reason it names. Fresh machine: create ~/.openviking/ovcli.conf with url + api_key (chmod 600).
ovcli.conf cannot be parsed	Trailing comma/comment; the plugin treats the file as absent	Fix the JSON. This is the most common "installed but nothing happens".
not registered in installed_plugins.json / claude plugin list does not show …	Plugin never installed, or installed under an old id	Re-run the one-line installer (bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness claude; add --dist tos where GitHub is blocked).
plugin is disabled in ~/.claude/settings.json	Installed but enabledPlugins is false/missing	claude plugin enable openviking-memory@openviking, restart Claude Code.
marketplace 'openviking' … missing directory / registered as a file	The checkout/archive moved, or a file-type marketplace (fails marketplace update with EISDIR)	claude plugin marketplace remove openviking then re-run the installer.
no skills/ directory in this plugin copy / registered version behind the repo	Stale version-keyed cache; claude plugin update is a no-op when the version string did not change	claude plugin marketplace update openviking && claude plugin uninstall openviking-memory@openviking && claude plugin install openviking-memory@openviking.
legacy openviking hooks … settings.json / extra plugin ids / user-scope MCP openviking	Pre-2.0 install residue; every hook fires twice, MCP server registered twice	Remove the openviking entries from .hooks in ~/.claude/settings.json (back it up), , .

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
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.

Recall corpus probe: node ${CLAUDE_PLUGIN_ROOT}/scripts/debug-recall.mjs "<query>" prints config, health and raw /search/find hits. It is a connectivity and corpus check, not a replay of the hook's exact ranking.

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/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.
• Never run scripts/debug-capture.mjs with a live Claude Code session id — it overwrites that session's capture cursor and uses an obsolete API flow.
• 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.