docs/en/agent-integrations/02-claude-code.md
Give Claude Code cross-project and cross-session long-term memory. Once installed, every conversation automatically recalls relevant memories and captures new content without requiring the model to make any tool calls.
Source: examples/claude-code-memory-plugin | Blog: motivation & demo
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
The installer checks dependencies, configures your OpenViking connection, and installs the plugin. Every step is idempotent—re-running it is entirely safe.
In regions where GitHub is hard to reach, use the equivalent command below:
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/claude-code-memory-plugin/tos-install.sh)
After installation, activate the claude wrapper in your current terminal (or simply open a new terminal window):
source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh
Launch Claude Code through a custom command? A wrapper script like
cc-custom, or a multi-word launcher (a base command plus a sub-command) — list it at the installer's "Extra launch commands" step (or passOPENVIKING_CC_WRAP_EXTRA='cc-custom') to inject credentials there too.
After using it for a while, try starting a new conversation and asking about something you mentioned earlier—it will remember.
<details> <summary><b>Manual setup</b></summary>If you prefer to set it up manually:
Wrap claude: Add these two lines to the end of your ~/.zshrc (for zsh) or ~/.bashrc (for bash), replacing <repo-path> with the absolute path to your local repository. This ensures each claude invocation injects OPENVIKING_URL and OPENVIKING_API_KEY from ~/.openviking/ovcli.conf, keeping the API key scoped to the claude process tree:
_ov_wrapper="<repo-path>/examples/claude-code-memory-plugin/setup-helper/wrapper.sh"
[ -f "$_ov_wrapper" ] && source "$_ov_wrapper"
For details on the function implementation and why a global export is not used, see the plugin README → Configuring MCP.
Install the plugin from the OpenViking repository root:
claude plugin marketplace add "$(pwd)/examples"
claude plugin install claude-code-memory-plugin@openviking-plugins-local
Start Claude Code and run /mcp to verify that the OpenViking entry displays your server URL.
</details>Don't have
ovcli.confyet? See the Deployment Guide → CLI.Using pure local mode (
http://127.0.0.1:1933, no authentication)? Skip step 1—the plugin automatically defaults to the local setup.Running Claude Code < 2.0? See the Legacy mode section in the plugin README.
type claude # expect: claude is a shell function
If the previous command printed a path instead of
shell function, the wrapper isn't active yet. Re-source it (or open a new terminal) before launchingclaude, otherwise it silently connects to127.0.0.1with no auth.
Launch claude from the terminal where type claude reports a shell function, then:
/plugins → Verify that openviking-memory is listed under "Installed", with the openviking MCP connected below it./mcp → Ensure the OpenViking entry displays your server URL along with valid authentication./openviking-memory:ov → View server health, identity, recall/injection statistics, and toggle states.If the plugin does not seem to activate, set OPENVIKING_DEBUG=1 and check the logs at ~/.openviking/logs/cc-hooks.log.
The plugin hooks into the Claude Code lifecycle:
All write operations run asynchronously, ensuring they never block your conversation.
<details> <summary><b>Configuration</b></summary>Configuration priority: Environment variables > ovcli.conf > ov.conf > Built-in defaults (http://127.0.0.1:1933, no authentication).
| Env Var | Default | Description |
|---|---|---|
OPENVIKING_AUTO_RECALL | true | Auto-recall on every user prompt |
OPENVIKING_RECALL_LIMIT | 6 | Max memories to inject per turn |
OPENVIKING_RECALL_TOKEN_BUDGET | 2000 | Token budget for inline content |
OPENVIKING_AUTO_CAPTURE | true | Auto-capture after each turn |
OPENVIKING_BYPASS_SESSION | false | Skip all hooks for this session |
OPENVIKING_BYPASS_SESSION_PATTERNS | "" | CSV glob patterns to auto-bypass |
OPENVIKING_MEMORY_ENABLED | (auto) | Force on/off |
OPENVIKING_DEBUG | false | Write logs to ~/.openviking/logs/cc-hooks.log |
For multi-tenant deployments, configure OPENVIKING_ACCOUNT and OPENVIKING_USER. The complete list of environment variables is available in the plugin README.
The plugin renders an OpenViking status indicator beneath your Claude Code input box, allowing you to check connection health, recall count, capture progress, and session state at a glance. See STATUSLINE.md for a complete glossary of segments and personalization recipes.
| Issue | Cause | Solution |
|---|---|---|
| Plugin is not activating | Missing ov.conf or ovcli.conf | Run the installer, or set OPENVIKING_MEMORY_ENABLED=1 along with the URL/API_KEY environment variables |
| Hooks fire but recall is empty | Server is not running or the URL is incorrect | Check server health: curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health" |
MCP tools hit 127.0.0.1 instead of the remote server | Missing function wrapper | Ensure type claude outputs "shell function"; see Manual setup |
type claude shows a path instead of a shell function (wrapper inactive) | The rc wasn't sourced after install, or you launched from a terminal that didn't load it | Run source ~/.zshrc (or ~/.bashrc on bash), or open a new terminal |
Launching via an alias (e.g. cc) injects no credentials | The alias name was listed in OPENVIKING_CC_WRAP_EXTRA (alias names are skipped), or the alias's target command isn't wrapped | Wrap the command the alias points to, not the alias: alias cc=claude needs nothing; for alias cc=claude-custom, add claude-custom |
| Remote auth 401 / 403 | Incorrect API key or missing tenant headers | Verify OPENVIKING_API_KEY; for multi-tenant setups, also check OPENVIKING_ACCOUNT and OPENVIKING_USER |
ovcli.conf setup instructions