How to install the OpenViking memory plugin in Claude Code

OpenViking's Claude Code plugin is the documented path for cross-project, cross-session memory. Once it is installed, every conversation recalls relevant memories before a prompt and captures new content after the turn. The model does not have to call a memory tool for either step.

Neither the integration page nor the plugin README states a launch date. Treat both as current product documentation.

What the hooks do

The plugin hooks the Claude Code lifecycle:

Before every prompt it searches OpenViking and injects relevant memories.
After each response it captures new conversation turns.
On session start it injects your profile, memory index, and skill catalog.
Before compaction and on session end it commits pending messages.
For each subagent it assigns an isolated memory session.
Before a native file tool touches a viking:// path, it blocks the call and names the OpenViking MCP tool to use instead. A Write or Edit on a skill path is pointed to add_skill.

Write operations run asynchronously, so they do not block the conversation.

Server first

The README requires an OpenViking server with viking://~ home-alias support. Recall targets viking://~/memories and viking://~/skills. Newer servers reject the uid-less viking://user/memories shorthand. The default port is 1933. A local check from the README:

curl http://localhost:1933/health   # or your remote URL

Pure local mode is http://127.0.0.1:1933 with no authentication. The docs say you can skip writing ovcli.conf in that case, because the plugin defaults to the local setup. Enablement is a separate rule: the plugin is enabled if ov.conf or ovcli.conf exists, and otherwise stays silently disabled unless OPENVIKING_MEMORY_ENABLED forces it on. Forced on without a file, connection info must come from environment variables. If local hooks never fire, check that rule before you change recall settings.

Shared installer

Claude Code and Codex share one installer, documented for macOS and Linux. It asks for language (English or 中文), which harnesses to install, the download source, and your OpenViking credentials. Re-running is safe.

The docs page recommends:

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

The README pins Claude Code:

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness claude

Where GitHub is hard to reach, pick "TOS mirror" at the download-source prompt, pass --dist tos, or run the mirror the docs publish:

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)

Claude Code on that TOS channel registers a local directory marketplace, which cannot auto-update. Re-run the installer to update. Codex on TOS installs from a TOS-hosted git repo and keeps remote updates.

No shell wrapper is required. The stdio MCP proxy reads ~/.openviking/ovcli.conf or OPENVIKING_* variables at runtime and needs Node.js 18 or newer. Update the file or the variables, then restart Claude Code. If the installer detects Claude Code older than 2.0, it falls back to claude mcp add plus a hooks merge. The README says claude plugin ships in Claude Code 2.0 and later.

Marketplace commands

Manual install needs no clone:

claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json
claude plugin install openviking-memory@openviking

From the OpenViking repo root, a local checkout uses:

claude plugin marketplace add "$(pwd)/examples"
claude plugin install openviking-memory@openviking

The docs write that development path as claude plugin marketplace add "<repo>/examples", then the same plugin id. Both modes register a marketplace named openviking, so the id is always openviking-memory@openviking. These commands install at user scope by default and do not pass --scope, because older 2.0.x builds reject that flag. On builds that accept it, claude plugin enable openviking-memory@openviking --scope user lifts a local-scoped install. Directory mode breaks if the source directory moves or a checkout drops these files. Remove the marketplace and add the other source to switch. The installer does that switch itself.

Connection

The README's remote ~/.openviking/ovcli.conf example:

{
  "url": "https://your-openviking-server.example.com",
  "api_key": "<your-api-key>",
  "account": "my-team",
  "user": "alice"
}

After the plugin is installed, node <plugin-dir>/scripts/setup.mjs is the bundled wizard for the same file.

On the docs page, connection priority is environment variables, then ovcli.conf, then ov.conf, then http://127.0.0.1:1933 with no authentication. The README also checks workspace layers before ovcli.conf: this machine's workspace registry, then <repo-root>/.openviking/config.local.json, then the committed <repo-root>/.openviking/config.json. Inside ovcli.conf, plugin.claude_code overrides the shared plugin section. Credential keys in workspace files are stripped.

A file-free start from the README:

OPENVIKING_MEMORY_ENABLED=1 \
OPENVIKING_URL=https://openviking.example.com \
OPENVIKING_API_KEY=sk-xxx \
OPENVIKING_ACCOUNT=my-team \
OPENVIKING_USER=alice \
OPENVIKING_RECALL_LIMIT=8 \
claude

OPENVIKING_API_KEY is sent as a bearer token. OPENVIKING_ACCOUNT and OPENVIKING_USER are the multi-tenant headers. Auto-recall and auto-capture default to on. OPENVIKING_SESSION_START_MAX_BYTES defaults to 9500, keeping the SessionStart block under Claude Code's 10,000-character inline limit. On resume or compact the archive takes up to half of that budget. 0 removes the cap.

One memory across clones

Memories are filed under a peer derived from the repository, so clones, worktrees, and subdirectories share one project memory. The default source is git: the normalized origin URL, else the repository root path. With origin git@github.com:volcengine/OpenViking.git, the peer is github.com-volcengine-openviking. Outside a repository no peer is sent, and memories go to viking://user/<you>/memories. A fork has its own origin, so it stays separate.

Override that with OPENVIKING_PEER_SOURCE, plugin.peerSource, or peer.source in .openviking/config.json. That file needs "version": 1. cwd restores path-derived ids, none sends no peer, and a quoted template builds your own. The integration page's example joins a team prefix to the directory variable; the README also lists a git-remote template, or a list tried in order. A directory that is not a repository can hold {"version": 1, "peer": {"id": "my-project"}}. Older path-derived memories are still recalled.

Prove it is connected

Launch claude, then:

/plugins should list openviking-memory under Installed, with the openviking MCP connected below it.
/mcp should show the OpenViking entry with your server URL and valid authentication.
/openviking-memory:ov shows server health, identity, recall and injection statistics, and toggle states.

If the plugin does not activate, set OPENVIKING_DEBUG=1 and read ~/.openviking/logs/cc-hooks.log. Empty recall with hooks firing usually means a down server or a bad URL. The docs check is curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health". Tools hitting 127.0.0.1 mean ovcli.conf has no url. Fix the file, or run node <plugin-dir>/scripts/setup.mjs, then restart Claude Code. Auth failures mean no valid api_key. The stdio proxy re-reads it after auth failures. A remote 401 or 403 is a bad key, or missing OPENVIKING_ACCOUNT and OPENVIKING_USER on a multi-tenant server.

What to do next

Run the shared installer if you want it to collect language, harness, download source, and credentials. If the server is already up, add the marketplace, install openviking-memory@openviking, start claude, and run /plugins, /mcp, and /openviking-memory:ov before you trust recall. When a check is empty, set OPENVIKING_DEBUG=1 and read ~/.openviking/logs/cc-hooks.log. The plugin README is the next read for hook timeouts, the full variable tables, and input-filter grammar.