Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(cc-plugin): drop --scope from plugin commands, add legacy install path (#1876)
t0saki5576bb284222
diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.mdindex 884dc5fb1..8378067e0 100644--- a/docs/en/agent-integrations/02-claude-code.md+++ b/docs/en/agent-integrations/02-claude-code.md@@ -54,11 +54,15 @@ Inside Claude Code, run `/mcp` after the next start — the OpenViking entry shoFrom the OpenViking repo root:```bash-claude plugin marketplace add "$(pwd)/examples" --scope local-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope local+claude plugin marketplace add "$(pwd)/examples"+claude plugin install claude-code-memory-plugin@openviking-plugins-local```-> Local install points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin.+> The plugin installs at user scope by default — active from any directory. We don't pass `--scope` because older Claude Code 2.0.x builds (e.g. 2.0.76) reject the flag.+>+> The marketplace entry points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin.+>+> **Claude Code < 2.0?** `claude plugin` shipped in 2.0 (Oct 2025). Older builds still expose `claude mcp add` + the hooks system — the [plugin README's Legacy mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20) shows how to wire the same functionality by hand, and the one-line installer detects the version and offers it automatically.#### 3. Start Claude Codediff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.mdindex 9ec9c7cb4..0a5dd5a38 100644--- a/docs/zh/agent-integrations/02-claude-code.md+++ b/docs/zh/agent-integrations/02-claude-code.md@@ -54,11 +54,15 @@ type claude # 期望输出:claude is a shell function在 OpenViking 仓库根目录执行:```bash-claude plugin marketplace add "$(pwd)/examples" --scope local-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope local+claude plugin marketplace add "$(pwd)/examples"+claude plugin install claude-code-memory-plugin@openviking-plugins-local```-> 本地安装让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会让插件失效。+> 默认装在 user scope —— 任何目录下都生效。这里**不显式传 `--scope`**,因为老的 Claude Code 2.0.x(比如 2.0.76)不识别这个 flag 会直接报错。+>+> marketplace 条目让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会让插件失效。+>+> **Claude Code < 2.0?** `claude plugin` 是 2.0(2025-10)才引入的。更老的版本仍然有 `claude mcp add` 和 hooks 系统,可以走[插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)手动接同样的功能。一键安装脚本会自动检测版本并询问你是否走这条路径。#### 3. 启动 Claude Codediff --git a/examples/claude-code-memory-plugin/README.md b/examples/claude-code-memory-plugin/README.mdindex 5b9f35c78..29061b1d9 100644--- a/examples/claude-code-memory-plugin/README.md+++ b/examples/claude-code-memory-plugin/README.md@@ -51,14 +51,41 @@ If `ov.conf` is what you already maintain, the plugin reads it too — see [ConfThe repo's `examples/.claude-plugin/marketplace.json` exposes the plugin as a local marketplace entry. From the OpenViking repo root:```bash-claude plugin marketplace add "$(pwd)/examples" --scope user-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user+claude plugin marketplace add "$(pwd)/examples"+claude plugin install claude-code-memory-plugin@openviking-plugins-local```-> `--scope user` makes the plugin active from any directory. Using `--scope local` ties enablement to the current dir and the plugin shows up disabled the moment you `cd` elsewhere.+> Both commands install at user scope by default — the plugin is active from any directory. We don't pass `--scope user` explicitly because older Claude Code 2.0.x builds (e.g. 2.0.76) reject the flag. On newer builds that do accept `--scope`, you can lift a local-scoped install to user scope with `claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user`.>> The marketplace entry points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin. A public marketplace listing for one-click install will follow.+##### Legacy mode (Claude Code < 2.0)++`claude plugin` ships in Claude Code 2.0+ (Oct 2025). Older builds still have `claude mcp add` and the hooks system, so the same functionality can be wired up by hand:++```bash+PLUGIN_DIR="$(pwd)/examples/claude-code-memory-plugin"++claude mcp remove openviking -s user 2>/dev/null+claude mcp add --scope user --transport http openviking \+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}'++# Merge plugin hooks into ~/.claude/settings.json (with backup).+mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json+cp -p ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s)+sed "s|\${CLAUDE_PLUGIN_ROOT}|$PLUGIN_DIR|g" "$PLUGIN_DIR/hooks/hooks.json" > /tmp/ov-hooks.json+jq --slurpfile h /tmp/ov-hooks.json '.hooks = ((.hooks // {}) * $h[0].hooks)' \+ ~/.claude/settings.json > /tmp/ov-settings.json+jq -e . /tmp/ov-settings.json >/dev/null && mv /tmp/ov-settings.json ~/.claude/settings.json+rm -f /tmp/ov-hooks.json+```++The single-quoted `${VAR}` literals in `claude mcp add` are intentional — Claude Code expands them at MCP launch time using whatever the shell wrapper injects. Don't switch to double quotes; your shell would expand them to empty strings before the command runs. The one-line installer does all of this for you and prompts before touching `~/.claude/settings.json`.+#### 4. Start Claude Code```bashdiff --git a/examples/claude-code-memory-plugin/README_CN.md b/examples/claude-code-memory-plugin/README_CN.mdindex 2864e2e6e..a567231ed 100644--- a/examples/claude-code-memory-plugin/README_CN.md+++ b/examples/claude-code-memory-plugin/README_CN.md@@ -51,14 +51,41 @@ curl http://localhost:1933/health # 或者你的远程 URL仓库的 `examples/.claude-plugin/marketplace.json` 把本插件暴露为一个本地 marketplace 条目。在 OpenViking 仓库根目录:```bash-claude plugin marketplace add "$(pwd)/examples" --scope user-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user+claude plugin marketplace add "$(pwd)/examples"+claude plugin install claude-code-memory-plugin@openviking-plugins-local```-> `--scope user` 让插件在任意目录下都启用。用 `--scope local` 会把启用状态绑死在当前目录,一旦 `cd` 到别处插件就显示 disabled,需要手动 enable。+> 两条命令默认都装在 user scope —— 插件在任何目录下都生效。这里**不显式传 `--scope user`**,因为老的 Claude Code 2.0.x(比如 2.0.76)不识别这个 flag 会直接报错。在支持 `--scope` 的新版本上,如果装完发现落到了 local scope,可以跑一次 `claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user` 提升到 user scope。>> marketplace 条目让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会立刻让插件失效。后续会发布公开 marketplace 以支持一键安装。+##### 兼容模式(Claude Code < 2.0)++`claude plugin` 子命令是 Claude Code 2.0(2025-10)才引入的。再老的版本只有 `claude mcp add` 和 hooks 系统,但仍然能手动接出同样的功能:++```bash+PLUGIN_DIR="$(pwd)/examples/claude-code-memory-plugin"++claude mcp remove openviking -s user 2>/dev/null+claude mcp add --scope user --transport http openviking \+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}'++# 把插件 hooks 合并进 ~/.claude/settings.json(自动备份)+mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json+cp -p ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s)+sed "s|\${CLAUDE_PLUGIN_ROOT}|$PLUGIN_DIR|g" "$PLUGIN_DIR/hooks/hooks.json" > /tmp/ov-hooks.json+jq --slurpfile h /tmp/ov-hooks.json '.hooks = ((.hooks // {}) * $h[0].hooks)' \+ ~/.claude/settings.json > /tmp/ov-settings.json+jq -e . /tmp/ov-settings.json >/dev/null && mv /tmp/ov-settings.json ~/.claude/settings.json+rm -f /tmp/ov-hooks.json+```++`claude mcp add` 的所有参数**必须用单引号**保留 `${VAR}` 字面量 —— Claude Code 在启动 MCP server 时才展开它们,用的就是 shell wrapper 注入的环境变量。换成双引号 shell 会提前把它们展开成空串,配置就废了。一键安装脚本会自动做这一切,并在改 `~/.claude/settings.json` 前提示你。+#### 4. 启动 Claude Code```bashdiff --git a/examples/claude-code-memory-plugin/setup-helper/install.sh b/examples/claude-code-memory-plugin/setup-helper/install.shindex 6b255aace..bc4ef305f 100755--- a/examples/claude-code-memory-plugin/setup-helper/install.sh+++ b/examples/claude-code-memory-plugin/setup-helper/install.sh@@ -10,7 +10,10 @@# 2. Set up ~/.openviking/ovcli.conf — reuse if present, prompt otherwise.# 3. Clone (or refresh) the OpenViking repo to ~/.openviking/openviking-repo.# 4. Add a `claude` shell function to your rc that injects creds at invocation.-# 5. Install the plugin via `claude plugin marketplace add` + `claude plugin install`.+# 5. Install the plugin. On Claude Code >= 2.0 (with `claude plugin` support) we+# use marketplace + plugin install. On older builds — or if marketplace is+# unavailable — we fall back to legacy mode: `claude mcp add` + a merge into+# ~/.claude/settings.json.## Env overrides:# OPENVIKING_HOME default: $HOME/.openviking@@ -205,37 +208,153 @@ EOFfi# ----- 5. Plugin install -----+#+# `claude plugin` was introduced in Claude Code 2.0 (2025-10). Older builds only+# expose `claude mcp add` and the hooks system. We detect the major version and+# offer a legacy install path that wires the same functionality through+# `claude mcp add` + a merge into ~/.claude/settings.json.+#+# Note on `--scope`:+# - `claude mcp add --scope user` has been supported since MCP first shipped,+# and the default (`local`) ties the server to one project, so we DO pass it.+# - `claude plugin install` / `claude plugin marketplace add` already default to+# user scope, and the `--scope` flag is rejected by older 2.0.x builds (e.g.+# 2.0.76). We omit it.heading '5. Plugin install'-if [ "$CLAUDE_AVAILABLE" -eq 1 ]; then- # Use --scope user so the plugin is active from any directory, not just $REPO_DIR.- # `local` scope binds enablement to $REPO_DIR's .claude/settings.local.json, which- # surfaces as "disabled" the moment the user `cd`s elsewhere and forces a manual- # `claude plugin enable` post-install.+# Probe for `claude plugin` support directly rather than parsing --version output.+# The version-string format isn't a stable contract; the subcommand's existence is.+has_plugin_subcommand() {+ claude plugin --help >/dev/null 2>&1+}++install_legacy() {+ local plugin_dir="$REPO_DIR/examples/claude-code-memory-plugin"+ local hooks_src="$plugin_dir/hooks/hooks.json"+ local settings="$HOME/.claude/settings.json"+ local ts; ts=$(date +%Y%m%d-%H%M%S)++ info "Legacy mode: registering MCP server + merging hooks into $settings"++ # 1) MCP server. Single-quoted ${VAR} literals so Claude Code expands them at+ # MCP launch time using whatever the rc wrapper has injected.+ info 'claude mcp add openviking (user scope)'+ claude mcp remove openviking -s user >/dev/null 2>&1 || true+ claude mcp add --scope user --transport http openviking \+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}' || {+ err 'claude mcp add failed'+ return 1+ }++ # 2) Hooks: replace ${CLAUDE_PLUGIN_ROOT} (only expanded by 2.0+ plugin loader)+ # with an absolute path, then merge into ~/.claude/settings.json. Back up+ # first; verify the merged JSON before overwriting.+ if [ ! -f "$hooks_src" ]; then+ err "hooks source not found: $hooks_src"+ return 1+ fi+ mkdir -p "$HOME/.claude"+ [ -f "$settings" ] || echo '{}' > "$settings"+ cp -p "$settings" "$settings.bak.$ts"+ info "Backup: $settings.bak.$ts"++ # mktemp instead of `$$` — predictable PID-based names are vulnerable to+ # symlink races on shared /tmp.+ local tmp_h tmp_s+ tmp_h=$(mktemp "${TMPDIR:-/tmp}/ov-hooks.XXXXXX") || { err 'mktemp failed'; return 1; }+ tmp_s=$(mktemp "${TMPDIR:-/tmp}/ov-settings.XXXXXX") || { err 'mktemp failed'; rm -f "$tmp_h"; return 1; }++ # Replace ${CLAUDE_PLUGIN_ROOT} via jq, not sed — $plugin_dir comes from a+ # user-configurable env var and may contain &, |, or \ which would corrupt+ # sed substitution.+ if ! jq --arg root "$plugin_dir" \+ 'walk(if type == "string" then gsub("\\$\\{CLAUDE_PLUGIN_ROOT\\}"; $root) else . end)' \+ "$hooks_src" > "$tmp_h" 2>/dev/null; then+ err "expanding CLAUDE_PLUGIN_ROOT in $hooks_src failed"+ rm -f "$tmp_h" "$tmp_s"+ return 1+ fi++ # Shallow merge — keep user's other hook events; same-event keys get overwritten.+ # Explicit error branch so a malformed settings.json doesn't kill the whole+ # script via `set -e` and skip our cleanup.+ if ! jq --slurpfile h "$tmp_h" '.hooks = ((.hooks // {}) * $h[0].hooks)' \+ "$settings" > "$tmp_s" 2>/dev/null; then+ err "merging hooks into $settings failed; original untouched (intermediate: $tmp_s)"+ rm -f "$tmp_h"+ return 1+ fi+ mv "$tmp_s" "$settings"+ rm -f "$tmp_h"+ info 'hooks merged'+}++install_modern() {+ # `--scope` intentionally omitted. Default scope is already user; passing it+ # breaks older 2.0.x builds that don't recognize the flag.info 'claude plugin marketplace add'- ( cd "$REPO_DIR" && claude plugin marketplace add "$REPO_DIR/examples" --scope user ) || \+ ( cd "$REPO_DIR" && claude plugin marketplace add "$REPO_DIR/examples" ) || \warn 'marketplace add returned non-zero (likely already added) — continuing'info 'claude plugin install'- ( cd "$REPO_DIR" && claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user )- # Belt-and-suspenders: make sure it ends up enabled even if `install` left it- # in a disabled state (observed on some Claude Code versions).- claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user >/dev/null 2>&1 || true+ ( cd "$REPO_DIR" && claude plugin install claude-code-memory-plugin@openviking-plugins-local ) || {+ warn 'plugin install failed — falling back to legacy mode'+ install_legacy+ return $?+ }+ # Belt-and-suspenders: ensure enabled even if `install` left it disabled.+ claude plugin enable claude-code-memory-plugin@openviking-plugins-local >/dev/null 2>&1 || true+}++USE_LEGACY=0+if [ "$CLAUDE_AVAILABLE" -eq 1 ] && ! has_plugin_subcommand; then+ warn "This Claude Code build doesn't expose 'claude plugin' (introduced in 2.0)."+ ask 'Use legacy compatibility mode (claude mcp add + settings.json merge)? [Y/n] '+ read -r reply || reply=""+ case "$reply" in+ n|N|no|No|NO)+ warn "Skipping plugin install. Upgrade to Claude Code >= 2.0 and re-run."+ CLAUDE_AVAILABLE=0+ ;;+ *) USE_LEGACY=1 ;;+ esac+fi++if [ "$CLAUDE_AVAILABLE" -eq 1 ]; then+ if [ "$USE_LEGACY" -eq 1 ]; then+ install_legacy+ else+ install_modern+ fielsewarn "Run these manually after installing Claude Code:"warn " cd \"$REPO_DIR\""- warn ' claude plugin marketplace add "$(pwd)/examples" --scope user'- warn ' claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user'+ warn ' claude plugin marketplace add "$(pwd)/examples"'+ warn ' claude plugin install claude-code-memory-plugin@openviking-plugins-local'fi# ----- Done -----+#+# We can't auto-source the rc into the user's shell — this script runs in a+# subshell (e.g. `bash <(curl ...)`), so any export/source we do here dies+# when the script exits. The user has to run `source` themselves, hence the+# bold callout below. (`source <(curl ...)` would work but is unsafe to+# recommend — it pipes remote code straight into the user's interactive shell.)heading 'Done!'info "Source: $REPO_DIR"info "Config: $OVCLI_CONF"[ -n "$RC" ] && info "Shell rc: $RC"printf '\n'-info 'Next:'-[ -n "$RC" ] && info " source $RC # or open a new shell"+if [ -n "$RC" ]; then+ printf '%s%sNext — run this in your shell to pick up the wrapper:%s\n' "$BOLD" "$YELLOW" "$RESET"+ printf ' %s%ssource %s%s\n' "$BOLD" "$CYAN" "$RC" "$RESET"+ printf ' (or just open a new terminal window)\n\n'+fi+info 'Then:'info ' claude # start Claude Code'info ' /mcp # inside Claude Code, verify the OpenViking entry'