OpenVikingOpenViking

简体中文

English

简体中文

English

外观

中

Claude Code ​

为 Claude Code 添加跨项目、跨会话（session）的长期记忆功能。安装完成后，每轮对话均会自动召回相关记忆并捕获新内容，无需模型主动调用任何工具。

源码：examples/claude-code-memory-plugin | 博客：动机与效果展示

安装 ​

Claude Code 和 Codex 共用同一个安装脚本。它会询问要安装的 harness 和 OpenViking 凭据；所有步骤幂等，重复运行安全。

bash
curl -fsSL https://openviking.ai/install | bash
# AI agent 如不确定是否执行，可先阅读脚本头部，其中写明了它会做什么、如何核实。

插件更新：Claude Code 2.1.224 及以上版本，安装脚本注册的是 OpenViking 文档站托管的 marketplace 并开启自动更新，新版插件在后台下载，重启 Claude Code 后生效。更早的 Claude Code 注册的是本地目录 marketplace，无法自动更新——更新请重跑安装脚本。（Codex 安装自同一站点上的 git 仓库，保留远程更新能力。）

现在不再需要任何 shell wrapper：插件自带的 stdio MCP 代理会在运行时读取 ~/.openviking/ovcli.conf（或 OPENVIKING_* 环境变量），与 hooks 使用同一套配置链。

可以在新会话中询问已保存的信息，验证跨会话召回是否生效。

手动安装

如果你倾向于手动安装：

  1. 配置连接 — 手写 ~/.openviking/ovcli.conf（url、api_key，可选 account/user），或装完后运行插件自带向导 node <插件目录>/scripts/setup.mjs。

  2. 从远程 marketplace 安装插件（无需 clone 仓库）：

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

    开发场景也可注册本地 checkout：claude plugin marketplace add "<仓库路径>/examples"，插件 id 相同。

  3. 启动 Claude Code — 运行后输入 /mcp 命令，确认 OpenViking 条目已连接。

尚未创建 ovcli.conf？请先按照 部署指南 → CLI 的说明进行配置。

使用默认本地服务（http://127.0.0.1:1933，无鉴权）且没有其他连接配置时，可以跳过第 1 步。

使用 Claude Code < 2.0 版本？安装脚本会跳过它并提示升级。如需用 claude mcp add + hooks 合并手动接入，见 插件 README 的兼容模式章节。

验证 ​

启动 claude，随后：

  • 输入 /plugins → 在 Installed 列表中应能找到 openviking-memory（其子项 openviking MCP 应显示为已连接状态）。
  • 输入 /mcp → OpenViking 对应的条目应显示你的服务器 URL 及有效的认证信息。
  • 输入 /openviking-memory:ov → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。

若插件未正常工作，可设置环境变量 OPENVIKING_DEBUG=1，并查看日志文件 ~/.openviking/logs/cc-hooks.log 以排查问题。

工作原理 ​

插件通过挂载到 Claude Code 的不同生命周期节点来发挥作用：

  • 每次用户输入前 — 搜索 OpenViking 数据库并注入相关记忆。
  • 每轮回复后 — 自动捕获并存储新的对话内容。
  • 会话（session）启动时 — 注入用户画像、记忆索引和 skill 清单。
  • 上下文压缩（compact）前及会话结束时 — 提交所有待处理的消息记录。
  • 启动子代理（subagent）时 — 为其分配相互隔离的记忆会话。
  • 原生文件工具访问 viking:// 路径前 — 拦截该调用，并提示改用对应的 OpenViking MCP 工具；对 skill 路径的 Write 或 Edit 会被引导到 add_skill。

捕获在独立后台进程中执行，不阻塞当前对话轮次。PreCompact 和 SessionEnd 会在 hook 超时范围内等待会话提交完成。

skill 清单就是 <available-skills> 块，列出存放在 OpenViking 中的 skill：先列你自己在 viking://~/skills 下的，再列账号内共享在 viking://agent/skills 下的，每个附一句简短描述。要照清单里的 skill 执行前，Claude 会先用 OpenViking 的 read 工具读取它的 SKILL.md。清单有独立的 Token 预算：放不下描述时只列名称，连一个名称都放不下时缩成一行总数。插件自带的 openviking-skills skill 告诉 Claude 如何查找和使用 OpenViking 中的 skill，如何用 add_skill MCP 工具创建、安装和共享 skill，如何删除 skill，以及在你要求时如何把 ~/.claude/skills 等本地 skill 迁入 OpenViking。

工具调用和结果会作为独立的 tool part 捕获，tool_output 原样上报。截断由服务端负责：超过 tool_output_externalization.threshold_chars（默认 20000）的输出会写入 session 的 tool-result 存储，part 中只保留 synopsis stub 和 tool_output_ref，原文仍可通过 /api/v1/sessions/{id}/tool-results 读回。

配置

配置项的读取优先级为：环境变量 > ovcli.conf > ov.conf > 内置默认值（http://127.0.0.1:1933，无鉴权）。

环境变量默认值说明
OPENVIKING_AUTO_RECALLtrue每次用户输入前自动触发记忆召回
OPENVIKING_RECALL_LIMIT10遗留宽度覆盖，会转换为各分类 coding 配额
OPENVIKING_RECALL_TOKEN_BUDGET2000最终 raw-find fallback 的内联 Token 预算
OPENVIKING_AUTO_CAPTUREtrue每轮对话结束后自动捕获新记忆
OPENVIKING_SKILL_CATALOGtrue会话启动时注入 <available-skills> skill 清单
OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET1200<available-skills> 的 Token 预算，与用户画像的预算相互独立；设为 0 即关闭清单
OPENVIKING_SESSION_START_MAX_BYTES9500SessionStart 注入的总字节上限，保证整块低于 Claude Code 的 10,000 字符限制、直接进入上下文而不是被存成文件；resume 或 compact 时会话归档最多占一半。设为 0 取消上限
OPENVIKING_BYPASS_SESSIONfalse禁用当前会话的所有 Hook
OPENVIKING_BYPASS_SESSION_PATTERNS""通过 CSV 格式的 glob 模式匹配并自动跳过特定会话
OPENVIKING_RECALL_QUERY_FILTERS""CSV 格式的 sed 风格正则规则，在 prompt 变成检索 query 前生效（语法与示例）
OPENVIKING_CAPTURE_FILTERS""CSV 格式的 sed 风格正则规则，作用于每个被捕获的回合（同一套语法）
OPENVIKING_MEMORY_ENABLED(auto)强制开启或关闭插件
OPENVIKING_DEBUGfalse将调试日志输出至 ~/.openviking/logs/cc-hooks.log

这些配置大多也可以写在 ovcli.conf 的 plugin 段下——见插件配置。两个过滤器建议使用 JSON 数组，避免环境变量中的逗号被当作分隔符。

如果更看重召回响应速度，请参阅低延迟召回，其中说明了如何通过环境变量或 ovcli.conf 关闭查询扩展与结果压缩。

使用 user/admin key 时，服务端从密钥解析身份；仅在 trusted 模式下按管理员提供的信息设置 OPENVIKING_ACCOUNT 和 OPENVIKING_USER。完整的环境变量列表请参阅 插件 README。

工作区 peer ​

记忆按你所在仓库派生出的 peer 归档，因此同一个项目在不同 clone、worktree 和子目录下共用同一份记忆。默认的 peer.source: "git" 取仓库归一化后的 origin URL——origin 为 git@github.com:volcengine/OpenViking.git 时，peer 就是 github.com-volcengine-openviking——其次是仓库根路径；不在仓库中则完全不发送 peer，在那里记下的内容进入用户级空间 viking://user/<you>/memories。fork 的 origin 不同，因此默认是独立的 peer。

可通过 OPENVIKING_PEER_SOURCE、ovcli.conf 中的 plugin.peerSource，或工作区 .openviking/config.json（"version": 1 的配置文件，可提交给团队共用）中的 peer.source 修改："cwd" 恢复此前的行为——把工作目录路径中的非字母数字字符全部替换成 -；"none" 表示不发送 peer；也可以用 "team-{dir}" 这样的模板自定义。要让一个不是仓库的目录拥有独立记忆，在该目录下创建 .openviking/config.json，内容为 {"version": 1, "peer": {"id": "my-project"}}。此前按工作目录派生的 peer 下写入的记忆仍能被召回，无需迁移。分层优先级和工作区配置文件的完整 schema 见客户端配置 → 工作区配置。

状态行 ​

插件会在 Claude Code 的输入框下方显示一行 OpenViking 状态栏，用于指示：连接状态、召回条数、捕获进度以及当前会话状态。关于状态栏各部分的详细含义与自定义配置方法，请参阅 STATUSLINE.md。

来源卡片 ​

插件会在每次回答下方加一行卡片，列出这次回答用到的 OpenViking 来源：自动召回加进提示的内容，以及 Claude 自己搜索、读取的内容。例如 OV · 8 sources · 4 past events · 3 work memories · 1 team doc · 1 read in full [Expand]。用卡片上的按钮展开单张卡片，或用 /openviking-usage expand、/openviking-usage collapse 展开或折叠全部卡片。卡片默认折叠。

卡片需要 Claude Code 2.1.286 或更高版本，并启用插件 hooks 模块。版本更早或模块未启用时不显示卡片，召回、捕获等 hook 照常工作。详见插件 README 的来源卡片。

故障排查 ​

现象原因修复
插件未激活未找到 ov.conf 或 ovcli.conf 配置文件运行 安装脚本，或手动设置 OPENVIKING_MEMORY_ENABLED=1 配合 URL/API_KEY 使用。
Hook 已触发但召回结果为空服务器未启动或 URL 配置错误执行命令测试连通性：curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"
MCP 工具连接到了 127.0.0.1 而非远程服务器~/.openviking/ovcli.conf 中没有 url（代理回退到本地默认值）修正 ovcli.conf（或运行 node <插件目录>/scripts/setup.mjs）后重启 Claude Code
MCP 工具调用报认证错误当前 ovcli 配置没有 authenticated server 所需的有效 api_key更新 ovcli.conf 中的 api_key；stdio 代理在认证失败后会重新读取配置
远程认证失败 (401 / 403)凭据无效或权限不足检查当前 user/admin key 和资源权限。仅 trusted 模式需要管理员提供的 account/user Header；这些 Header 不能改变用户 Key 绑定的身份。

参见 ​

Open source under the AGPL-3.0 License. Font licenses

Copyright OpenViking contributors