为 Claude Code 接入 OpenViking 记忆插件安装、验证、配置与工作原理全解析【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本篇技术指南以 OpenViking 官方文档 docs/images/agents/en/claude-code.md 为骨架结合完整集成指南 docs/en/agent-integrations/02-claude-code.md 与仓库内的插件源码 examples/claude-code-memory-plugin系统讲解如何在 Claude Code 中安装、验证并调优 OpenViking 记忆插件。读完本文你将掌握一键/手动两种安装方式、插件健康验证三连命令、完整的环境变量配置体系以及插件在 Claude Code 生命周期钩子中的底层工作原理。OpenViking 是一个面向 AI Agent 的自进化上下文数据库统一了 Agent 记忆、知识 RAG 与技能Skills。Claude Code 记忆插件openviking-memory正是将这套能力接入 Claude Code 的官方途径安装之后每次对话前自动召回相关记忆每次回复后自动捕获新内容模型无需显式调用任何 MCP 工具即可获得跨项目、跨会话的长期记忆。第一步安装因为 Claude Code 可能会拦截来源未知的安装脚本自动安装可能无法顺利完成官方推荐优先执行下面的手动终端步骤。一键安装器推荐在终端运行官方安装器指定 harness 为claude、分发渠道为 TOS 镜像bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness claude --dist tos安装器会依次交互询问语言English / 中文OpenViking 凭据是否启用 StatusLine输入框下方的状态条。在 OpenViking 凭据步骤选择VolcEngine OpenViking Cloud Service [api.vikingdb.cn-beijing.volces.com]并输入 API KEY{{OPENVIKING_API_KEY}}Claude Code 与 Codex 共用同一个安装器去掉--harness claude即可交互式选择它会询问语言、要安装的 harness、下载源以及 OpenViking 凭据每一步都是幂等的重复运行完全安全。在 GitHub 访问困难的区域可以改用 Volcengine TOS 镜像运行同一安装器或在下载源提示处选择 TOS mirrorbash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)TOS 渠道对 Claude Code 的注意事项TOS 渠道注册的是一个本地目录 marketplace无法自动更新——需要重新运行安装器来升级。Codex 在 TOS 上安装自 TOS 托管的 git 仓库可保持远程更新。值得强调的是不再需要 shell 包装脚本插件自带一个 stdio MCP 代理运行时直接读取~/.openviking/ovcli.conf或OPENVIKING_*环境变量与 hooks 使用同一套配置来源。安装并实际使用一段时间后可以开启一个新会话询问之前提到过的内容——它会记得。OpenViking StatusLineStatusLine 是输入框下方的状态条实时展示记忆插件的运行状态。例如OV ✓ │ Fable 5 · ctx 42% │ ↪ 6 mem (0.92) · 50ms │ ✎ 573/20k · 2 arch你可以根据偏好启用或跳过它。关于状态条各分段的完整语义与个性化配方见 examples/claude-code-memory-plugin/STATUSLINE.md后文StatusLine 状态条一节也会展开讲解。手动安装可选如果倾向手动搭建可参考 02-claude-code.md 文档的 Manual setup 折叠块1. 配置连接——写入~/.openviking/ovcli.conf包含url、api_key可选account/user或在安装后运行插件自带的向导node plugin-dir/scripts/setup.mjs{ url: https://your-openviking-server.example.com, api_key: your-api-key, account: my-team, user: alice }2. 从远程 marketplace 安装插件无需 clone 仓库claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json claude plugin install openviking-memoryopenviking若为开发目的可注册本地 checkoutclaude plugin marketplace add repo/examples后安装同一个插件 ID。两种模式注册的 marketplace 都叫openviking因此插件 ID 始终是openviking-memoryopenviking。3. 启动 Claude Code并运行/mcp验证 OpenViking 条目已连接。相关前提还没有ovcli.conf参见 Deployment Guide → CLI。纯本地模式http://127.0.0.1:1933无认证可跳过第 1 步——插件会自动回退到本地默认配置。运行 Claude Code 2.0安装器检测到旧版本后会自动回退为claude mcp add hooks 合并的方式详见插件 README 的 Legacy mode 一节。Legacy 模式Claude Code 2.0claude plugin自 Claude Code 2.02025 年 10 月起可用旧版本仍可通过claude mcp add与 hooks 系统手工接线大致流程如下PLUGIN_DIR$(pwd)/examples/claude-code-memory-plugin # stdio MCP 代理——自行读取 ovcli.conf / OPENVIKING_*无需手工接 header claude mcp remove openviking -s user 2/dev/null claude mcp add --scope user openviking -- node $PLUGIN_DIR/servers/mcp-proxy.mjs # 将插件 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一键安装器检测到 pre-2.0 构建时会自动执行上述操作它会在~/.openviking/openviking-repo保留一份源码 checkout 以支撑上面的绝对路径。第二步验证重启 Claude Code然后依次执行三条命令确认插件与 MCP 均已就绪。1. 运行/plugins确认已安装列表中出现openviking-memory且openvikingMCP 已连接User ❯ openviking-memory Plugin · openviking · ✔ enabled └ openviking MCP · ✔ connected2. 运行/mcp确认显示如下Built-in MCPs (always available) ❯ plugin:openviking-memory:openviking · ✔ connected · 10 tools3. 运行/openviking-memory:ov确认服务状态健康OpenViking Memory Status ✅ Status: OpenViking server is healthy and running/openviking-memory:ov命令除了展示服务健康状态还会展示身份信息、召回/注入统计以及开关状态。如果插件看起来没有激活设置OPENVIKING_DEBUG1并查看日志~/.openviking/logs/cc-hooks.log。插件工作原理hooks 生命周期插件通过钩住 Claude Code 的生命周期事件实现零工具调用的记忆能力来源docs/en/agent-integrations/02-claude-code.md每次 prompt 之前——检索 OpenViking 并注入相关记忆每次回复之后——捕获新的对话轮次会话启动时——注入你的 profile 与记忆索引压缩compact之前与会话结束时——提交挂起的消息每个子代理subagent——分配独立的隔离记忆会话。所有写操作均为异步执行绝不会阻塞你的对话。工具调用与结果会作为专门的toolpart 被捕获tool_output原样上报。截断是服务端的职责超过tool_output_externalization.threshold_chars默认20000的输出会被写入会话的 tool-result 存储part 中仅保留摘要 stub 加tool_output_ref原始内容仍可通过/api/v1/sessions/{id}/tool-results读取。Hook 注册与职责从 examples/claude-code-memory-plugin/hooks/hooks.json 可以看到全部 9 个 hook 的注册与超时配置Hook触发时机动作超时UserPromptSubmit每个用户轮次检索 OV → 排序 → 在 token 预算内注入openviking-context块60sStopClaude 完成回复解析 transcript → 将新用户轮次推入 OV 会话 → 挂起 token 越过阈值时提交45sSessionStart新会话 / 恢复 / 压缩后在resume/compact时拉取最新归档概览并注入为附加上下文120sPreCompactClaude Code 改写 transcript 之前提交挂起消息使其在 CC 改写 transcript 前成为归档30sSessionEndClaude Code 会话关闭最终提交使最后一个窗口被归档30sSubagentStart父代理通过 Task 工具派生子代理为子代理派生隔离的 OV 会话 ID持久化起始状态10sSubagentStop子代理结束读取子代理 transcript → 推入带子代理 peer 身份的隔离会话 → 提交45sPreToolUse原生Read/Glob/Grep命中viking://URI拒绝调用并引导 Claude 使用对应的 OpenViking MCP 工具5sPostToolUse读取SKILL.md文件可选默认关闭当 OV 有相关技能经验记忆时注入经验块5s异步写路径Stop、SessionEnd、SubagentStop使用分离工作进程模式父 hook 读完 stdin 后立即输出{decision:approve}解除 Claude Code 阻塞再派生一个分离的克隆进程去执行 HTTP 写操作——用户永远不会等待 OV。PreCompact保持同步因为 Claude Code 紧接着就会改写 transcript。调试期如需确定性顺序可通过claude_code.writePathAsync: false关闭该机制。记忆污染防护auto-capture在推送每一轮之前会剥离openviking-context、system-reminder、relevant-memories与[Subagent Context]块。若不做这一步插件本轮注入的召回上下文会在下一轮被当作用户消息的一部分重新捕获形成自引用的污染循环。召回实现的源码级细节以 examples/claude-code-memory-plugin/scripts/auto-recall.mjs 为例可以看清召回的真实数据流多源检索同时检索viking://~/memories记忆与viking://~/skills技能两个源viking://~是 home 别名由服务端展开为调用者自己的用户空间无需客户端改写服务端优先优先走服务端上下文组装接口可带 OV session ID解锁服务端的查询扩展与跨轮去重账本无结果时才回退到本地searchAllSources 排序客户端排序在基础分数上叠加叶节点 boostlevel 2或.md结尾 0.12、事件/偏好意图 boost、词法重叠 boost并对 events/cases 类记忆按 URI 去重token 预算注入预算内的高分项携带完整内容超出预算的项降级为URI 分数提示行首项即使超预算也强制包含——保证注入块格式如openviking-context…/openviking-context始终可控。配置体系解析优先级每个插件字段按以下链路解析高 → 低环境变量OPENVIKING_*见下方表格Workspace registry——本机针对当前仓库的条目~/.openviking/workspaces/slot.jsonrepo-root/.openviking/config.local.json——私有、gitignore 的工作区设置repo-root/.openviking/config.json——团队提交的工作区设置ovcli.conf——CLI 客户端配置~/.openviking/ovcli.conf或OPENVIKING_CLI_CONFIG_FILE连接字段url、api_key、account、user加plugin段plugin.claude_code优先于共享的pluginov.conf——服务端配置~/.openviking/ov.conf或OPENVIKING_CONFIG_FILE插件读取server.url、server.root_api_key及遗留的claude_code块内置默认值http://127.0.0.1:1933无认证。三个 workspace 层只承载 Workspace configuration files 中列出的设置连接与凭据绝不会从它们中读取。同一套连接与身份字段也同时被 stdio MCP 代理使用。环境变量速查表所有插件行为都可通过环境变量设置连接/身份变量同时影响 hooks 与 MCP 代理调优变量只影响 hooks。连接 / 身份环境变量说明OPENVIKING_URL/OPENVIKING_BASE_URL完整服务端 URL如https://remote.example.comOPENVIKING_API_KEY/OPENVIKING_BEARER_TOKENAPI Key以Authorization: Bearer key发送OPENVIKING_ACCOUNT多租户账户X-OpenViking-AccountheaderOPENVIKING_USER多租户用户X-OpenViking-UserheaderOPENVIKING_PEER_ID可选的稳定 peer用于召回与捕获的会话消息OPENVIKING_PEER_SOURCEworkspace peer 的推导方式git默认、cwd、none或模板OPENVIKING_WORKSPACE_PEER默认从当前 workspace 推导 peer设为0关闭召回调优环境变量默认值说明OPENVIKING_AUTO_RECALLtrue每个用户 prompt 自动召回OPENVIKING_RECALL_LIMIT10旧的宽度覆盖参数会转换为按类别拆分的编码配额不再是最终上限OPENVIKING_RECALL_TOKEN_BUDGET2000最终 raw-find 回退的内联 token 预算OPENVIKING_RECALL_MAX_CONTENT_CHARS500单条内容上限OPENVIKING_RECALL_PREFER_ABSTRACTtrue有 abstract 时优先于完整正文OPENVIKING_RECALL_PEER_SCOPEallall可召回其他项目记忆带分数惩罚actor仅见全局 当前项目OPENVIKING_RECALL_MAX_TOKENS1600服务端组装上下文块的 token 预算独立于本地压缩限制OPENVIKING_RECALL_DEDUP_TURNS5跨轮冷却最近 N 轮提供过的 URI 被跳过OPENVIKING_RECALL_QUERY_EXPANSIONautoauto让服务端用会话上下文扩写短 promptoff关闭OPENVIKING_RECALL_COMPRESSauto摘要压缩off、client宿主 CLI、server、auto本地优先服务端兜底OPENVIKING_RECALL_COMPRESS_MAX_BULLETS6摘要 bullet 上限OPENVIKING_SCORE_THRESHOLD0.35最低相关分数0–1OPENVIKING_MIN_QUERY_LENGTH3过短查询跳过召回OPENVIKING_LOG_RANKING_DETAILSfalse逐候选打分日志冗长捕获调优环境变量默认值说明OPENVIKING_AUTO_CAPTUREtrue启用自动捕获同时是写 hooksPreCompact / SessionEnd / SubagentStop的总开关OPENVIKING_CAPTURE_MODEsemanticsemantic总是捕获或keyword触发式OPENVIKING_CAPTURE_MAX_LENGTH24000捕获决策使用的最大清洗后文本长度OPENVIKING_CAPTURE_ASSISTANT_TURNStrue包含助手轮次文本 工具 I/O设为0仅用户OPENVIKING_CAPTURE_TOOL_MAX_CHARS1000000单个工具 part 的tool_output保护上限超大输出由服务端外部化OPENVIKING_COMMIT_TOKEN_THRESHOLD20000客户端驱动提交的挂起 token 阈值OPENVIKING_RESUME_CONTEXT_BUDGET32000会话恢复时拉取归档概览的 token 预算生命周期 / 行为 / 杂项环境变量默认值说明OPENVIKING_TIMEOUT_MS15000召回 常规请求的 HTTP 超时msOPENVIKING_CAPTURE_TIMEOUT_MS30000捕获路径的 HTTP 超时必须低于Stophook 超时OPENVIKING_WRITE_PATH_ASYNCtrue将写 hooks 分离到后台 workerCC 不阻塞在提交 RTT 上OPENVIKING_BYPASS_SESSIONfalse一次性1/true跳过当前进程的所有 hooksOPENVIKING_BYPASS_SESSION_PATTERNS与session_id或cwd匹配的 glob 模式 CSVOPENVIKING_MEMORY_ENABLED(auto)0/false/no强制关闭1/true/yes强制开启OPENVIKING_DEBUGfalse1/true向~/.openviking/logs/cc-hooks.log写 hook 日志OPENVIKING_DEBUG_LOG~/.openviking/logs/cc-hooks.log覆盖日志路径OPENVIKING_CONFIG_FILE~/.openviking/ov.conf覆盖ov.conf路径OPENVIKING_CLI_CONFIG_FILE~/.openviking/ovcli.conf覆盖ovcli.conf路径纯环境变量示例无需任何配置文件OPENVIKING_MEMORY_ENABLED1 \ OPENVIKING_URLhttps://openviking.example.com \ OPENVIKING_API_KEYsk-xxx \ OPENVIKING_ACCOUNTmy-team \ OPENVIKING_USERalice \ OPENVIKING_RECALL_LIMIT8 \ claude启用 / 关闭三种控制手段插件 README 的 Enable / disable 一节OPENVIKING_MEMORY_ENABLED环境变量——0/false/no强制关闭1/true/yes强制开启强制开启且无配置文件时连接信息必须来自环境变量ov.conf中的claude_code.enabled——设为false关闭配置文件存在性——存在ov.conf或ovcli.conf即启用否则静默关闭不报错hooks 直接透传。跳过某个会话在/tmpPoC 目录中使用 Claude Code 且不想污染长期记忆# 持久生效任何 session_id 或 cwd 匹配模式的会话 export OPENVIKING_BYPASS_SESSION_PATTERNS/tmp/**,**/scratch/**,/Users/me/Dev/throwaway/* # 或一次性 OPENVIKING_BYPASS_SESSION1 claudebypass 生效时每个 hook 都会立即 approve不联系 OpenViking。ovcli.conf中的插件设置客户端侧的调优属于~/.openviking/ovcli.conf的plugin段。共享键对所有 harness 生效per-harness 对象覆盖它们{ url: http://127.0.0.1:1933, plugin: { recallCompress: auto } }解析顺序环境变量 → workspace 层 →plugin.claude_code→plugin→ov.conf中遗留的claude_code块 → 内置默认值。除非显式覆盖插件会省略服务端自有的 Context 默认值如limit10、max_tokens1600、query_expansionauto。显式的遗留recallLimit会转换为按类别拆分的编码配额1~5 之间取值会产生总计 6 的有效配额即每个编码域一个检索槽而非强制性的最终结果上限新的直接 API 集成应改用quotas配置。摘要压缩Digest compressionrecallCompress决定摘要由谁生成默认autoclient——总是通过claude -p本地压缩默认 Sonnet 低 effortHaiku 忽略 effort 旋钮其延迟不可控token 成本留在你自己的订阅上server——由 OpenViking 生成摘要auto——本地优先找不到健康的宿主 CLI 时回退到服务端。压缩执行或输出校验失败时回退到未压缩的上下文块任一压缩器返回精确的NO_RELEVANT_MEMORY都视为成功的空结果不注入任何内容。压缩子进程运行时会禁用所有 OpenViking hooks避免递归。旧的环境变量OPENVIKING_RECALL_REWRITE与配置键recallRewrite仍作为低优先级兼容别名受支持。ov.conf中的遗留claude_code块早期版本在~/.openviking/ov.conf的claude_code块下配置调优字段目前仍为向后兼容而支持——每个环境变量都有对应的 camelCase 形式OPENVIKING_RECALL_LIMIT→claude_code.recallLimit、OPENVIKING_BYPASS_SESSION_PATTERNS→claude_code.bypassSessionPatterns为 JSON 数组等。环境变量优先。新部署应优先使用环境变量与 shell rc——服务端配置文件不应携带逐开发者机器的调优。Workspace 配置文件仓库可以携带自己的插件设置repo-root/.openviking/config.json团队提交与repo-root/.openviking/config.local.json私有、gitignored。第三层——本机在~/.openviking/workspaces/下的条目——优先于两者。{ version: 1, peer: { source: git }, recall: { peer_scope: actor }, bypass: { session_patterns: [**/fixtures/**] } }version: 1是必需的声明其他版本的文件会被跳过并告警。Schema v1 支持peer.source、peer.id、recall.enabled、recall.peer_scope、recall.dedup_turns、recall.max_items、recall.score_threshold、capture.enabled、capture.commit_token_threshold、bypass.session_patterns与labels。列表跨层取并集前导!reset丢弃继承值未知键保留并忽略。由于 hook 是非交互式的逐 workspace 的审批门会导致每个命令都要确认这些文件被直接信任被拒绝的是结构性问题连接与凭据键url、api_key、account、user、extra_headers等会被剥离并告警且其中的${VAR}永不展开。完整 schema 见 Client Configuration → Workspace Configuration。注意.gitignore不要整体忽略.openviking/否则config.json永远无法提交应把规则收窄到.openviking/media/与.openviking/downloads/。Workspace Peer一个项目一份记忆记忆归档在由当前仓库推导出的 peer 之下因此一个项目在克隆、worktree、子目录之间共享同一份记忆。默认peer.source: git使用仓库归一化后的originURL——例如origin gitgithub.com:volcengine/OpenViking.git对应的 peer 是github.com-volcengine-openviking——回退到仓库根路径仓库之外则不发送 peer此时的记忆进入用户级空间viking://user/you/memories。fork 有自己的origin因此保持独立 peer。可通过OPENVIKING_PEER_SOURCE、ovcli.conf中的plugin.peerSource、或 workspace 的.openviking/config.json中的peer.source修改取值含义git默认。等同[{git_remote}, {git_root}]归一化 origin否则仓库根。仓库外不发送。不加前缀cwd旧行为逐字节一致——每个非字母数字字符替换为-如/Users/x/Dev/OpenViking→-Users-x-Dev-OpenVikingnone完全不发送 peer模板如git-{git_remote}、team-{dir}或按序尝试的列表模板中变量为空时落到下一个模板变量为{git_remote}、{git_root}、{cwd}、{dir}详见 memory-plugin-shared 的 Workspace Peers。推导是纯文件系统操作、不派生git子进程因此在git不在 PATH 或拒绝 dubious ownership 仓库时依然成立。想给非仓库目录独立的 peer在该目录创建.openviking/config.json{version: 1, peer: {id: my-project}}。从旧路径推导 peer 升级无需任何操作旧 ID 下写入的记忆仍可被召回默认peer_scope: all时服务端的跨 peer 清扫已覆盖actor作用域下插件会单独询问旧 peer。OPENVIKING_PEER_SOURCEcwd可彻底恢复旧 ID。StatusLine 状态条插件在 Claude Code 输入框下方渲染一行 OpenViking 状态指示让你一眼看到连接健康度、召回数、捕获进度与会话状态。完整分段术语表与个性化配方见 examples/claude-code-memory-plugin/STATUSLINE.md。各分段的常见形态来自插件 README 与 STATUSLINE.mdOV ✓ │ Fable 5 · ctx 42% │ ↩ 6 mem · 50ms 6 条记忆已注入模型 上下文用量 OV ⚠ slow probe 超过 1s 预算服务端可能滞后 OV ✗ offline 服务端不可达 OV ⚡ bypass │ Fable 5 · ctx 42% 命中 OPENVIKING_BYPASS_SESSION* OV ✓ │ ✎ 573/20k · 2 arch 挂起捕获本会话已产生两个归档 OV ✓ │ resumed │ 3 today 会话已补水今天已提交 3 个归档要点ctx百分比复刻 Claude Code 原生上下文指示自定义 statusLine 会替换原生指示沿用原生颜色阈值70%暗色、70–89%黄色、≥90%红色可用OPENVIKING_STATUSLINE_CTXoff隐藏数据流auto-recall.mjs/auto-capture.mjs/session-start.mjs每轮把小型快照写入~/.openviking/state/{last-recall,last-capture,last-session-event,daily-stats}.jsonscripts/statusline.mjs读取这些快照外加 5 秒共享缓存的GET /health网络调用有硬性的 1s 超时缓存跨 CC 会话共享以防惊群整行硬性上限 100 个可见字符超出尾部截断为…停用/自定义OPENVIKING_STATUSLINEoff静默保留注册NO_COLOR1或非 TTY自动去除 ANSI 颜色彻底移除用jq del(.statusLine) ~/.claude/settings.json已有自定义 statusline 时安装器会提示替换/跳过/手工合成。调试与排障调试日志在ov.conf设置claude_code.debug: true或设置OPENVIKING_DEBUG1hook 日志写入~/.openviking/logs/cc-hooks.log。auto-recall默认记录关键阶段加一份紧凑的ranking_summary仅在排查逐候选打分时开启claude_code.logRankingDetails: true输出冗长深度诊断建议对样例输入运行独立脚本scripts/debug-recall.mjs与scripts/debug-capture.mjs而不是长期开启 hook 日志。自带 Doctor先运行插件自带的诊断脚本ov-memory-doctor它会检查安装marketplace、启用状态、hooks、MCP 接线、解析后的配置哪个文件胜出、API key 掩码显示、连接可达性、认证、/mcp以及最近的 hook 活动并为每个发现打印修复建议node $(jq -r .plugins[openviking-memoryopenviking][0].installPath ~/.claude/plugins/installed_plugins.json)/scripts/ov-memory-doctor.mjs也可以直接让 Claude 检查插件ov-memory-doctorskill 会运行同一脚本并解读报告。常见问题速查综合关联文档与集成指南的排障表问题原因修复插件未激活缺少ov.conf或ovcli.conf重跑安装器或设置OPENVIKING_MEMORY_ENABLED1加 URL/API_KEY 环境变量也可检查~/.openviking/ovcli.confHooks 触发了但召回为空服务端未运行或 URL 错误检查服务健康curl $(jq -r .url ~/.openviking/ovcli.conf)/health本地模式为curl http://localhost:1933/health自动捕获提取出 0 条记忆ov.conf中的 embedding/VLM 模型配置错误检查embedding/vlm配置查看服务端日志MCP 工具命中127.0.0.1而非远程服务端~/.openviking/ovcli.conf无url代理回退到本地默认值修正ovcli.conf或运行node plugin-dir/scripts/setup.mjs重启 Claude CodeMCP 调用认证失败当前 ovcli 配置对已认证服务端缺少有效api_key更新ovcli.conf的api_keystdio 代理在认证失败后会重新读取远程认证 401 / 403API key 错误或缺少租户 header核对OPENVIKING_API_KEY多租户场景还需检查OPENVIKING_ACCOUNT与OPENVIKING_USERStophook 超时服务端慢 同步写路径保持writePathAsync: true默认或在hooks/hooks.json中调大Stop超时旧上下文反复出现在 OV 中旧版本把召回块又捕获回 OV升级到当前版本——auto-capture现在推送前会剥离openviking-context日志过吵遗留logRankingDetails: true设为false一次性排查用debug-recall.mjs/debug-capture.mjs与 Claude Code 内置记忆的对比Claude Code 自带MEMORY.md文件系统。本插件与其是互补关系特性内置MEMORY.mdOpenViking 插件存储扁平 Markdown向量数据库 结构化提取检索整段载入上下文语义相似度 排序 token 预算范围单项目跨项目、跨会话、peer 作用域容量约 200 行上下文限制无限服务端存储提取手工规则LLM 驱动的实体 / 偏好 / 事件提取子代理与父代理相同隔离会话 peer 作用域捕获架构总览┌────────────────────────────────────────────────────────────┐ │ Claude Code │ │ │ │ SessionStart UserPromptSubmit Stop PreCompact │ │ SessionEnd SubagentStart SubagentStop │ └────┬───────────────┬───────────────┬───────────┬───────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ │ hook scripts (.mjs) │ │ │ ┌──────────────┐ │ │ read transcript │───┼───────────┼────►│ │ │ │ call OV HTTP API │ │ │ │ OpenViking │ │ └───────────────────────┘ │ │ │ Server │ │ │ │ │ (Python) │ │ ┌────────────▼───────────▼───►│ │ │ │ MCP tools (stdio proxy → /mcp) │ │ │ find/search/recall/remember/… │ │ └─────────────────►│ │ │ OV session └─────────────────────────────► │ context inject └──────────────┘关键架构事实插件 README 的 Architecture 一节无 TypeScript 构建步骤、无运行时 npm 引导。hooks 是纯.mjs文件通过 HTTP 与 OpenViking 通信MCP 使用servers/mcp-proxy.mjs作为零依赖 stdio 桥接到服务端原生/mcp端点持久 OV 会话首次联系时创建并复用整个 Claude Code 会话OV 会话 ID 为cc-cc_session_idCC session_id 原样、不做哈希因此 resume / compact / 多 hook 事件都指向同一会话客户端触发归档 记忆提取Stophook 在服务端上报的挂起 token 越过commitTokenThreshold默认 20000时提交PreCompact/SessionEnd/SubagentStop无条件提交。插件目录结构examples/claude-code-memory-pluginclaude-code-memory-plugin/ ├── hooks/hooks.json # 9 个 hook 注册 ├── commands/ov.md # /ov 状态命令 ├── skills/ # openviking-memory / ov-experience-memory / ov-memory-doctor ├── servers/mcp-proxy.mjs # stdio - OpenViking /mcp 桥 ├── scripts/ │ ├── config.mjs # 共享配置加载器env ovcli.conf ov.conf │ ├── auto-recall.mjs # UserPromptSubmit │ ├── auto-capture.mjs # Stop │ ├── session-start.mjs / session-end.mjs │ ├── pre-compact.mjs │ ├── subagent-start.mjs / subagent-stop.mjs │ ├── debug-recall.mjs / debug-capture.mjs # 独立诊断 │ ├── ov-status.mjs / ov-memory-doctor.mjs │ └── lib/ # ov-session.mjs / async-writer.mjs 等 ├── .mcp.json # MCP 服务配置本地 stdio 代理 └── package.json # 仅 type:module 标记无运行时依赖MCP 侧可用的工具来自服务端原生/mcp端点检索、记忆、资源、watch、文件系统、代码导航等规范工具清单与参数见 MCP 集成指南 与 Capability Reference。继续阅读Claude Code Memory Plugin 集成文档——完整的环境变量表、hook 细节与架构图插件 README——配置优先级、Legacy 模式、排障细节StatusLine 指南——分段术语表与个性化配方Agent 集成总览——低延迟召回等进阶主题Client Configuration——workspace 配置文件完整 schemaMCP Clients——MCP 工具参数与其他客户端【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考