Cursor 接入 OpenViking一条命令为 AI 编程助手装上跨会话长期记忆【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本文介绍如何在 Cursor 中安装并验证 OpenViking 记忆插件memory-plugin让 Cursor 的每个新会话自动获得项目与用户级的长期记忆注入并通过 MCP 工具显式检索、阅读和管理记忆。读完本文你将掌握安装命令与凭证配置、Hooks/MCP/Rule/Skill 四类产物的验证方法、会话生命周期各阶段 Hook 的底层调用链以及常见故障的定位手段。OpenViking 是一个面向 AI Agent 的自进化上下文数据库Self-evolving Context Database for AI Agents统一承载 Agent 的记忆Memory、知识库 RAGKnowledge与技能Skills。Cursor 集成是官方提供的 Agent 集成方案之一其实现代码位于仓库 examples/cursor-memory-plugin完整指南见 Cursor Memory Integration。一、集成方案概览一次安装四类产物Cursor 记忆插件一次安装即注入四类产物无需单独配置 MCP也无需市场marketplace上架产物作用生命周期 Hooks会话启动加载画像、请求前召回上下文、响应后捕获对话、压缩/结束前提交会话并保护viking://虚拟 URIMCP Server提供search、read、remember等工具其中search的modecontext模式直接返回拼装好的上下文摘要常驻 Rule始终生效的规则告诉 Agent 如何对待注入的上下文与何时调用记忆工具记忆 Skill描述记忆、资源、技能三类持久上下文的用法与边界指导 Agent 检索与写入插件清单由 openviking.integration.json 声明schemaVersion: 1id: openviking-memoryversion: 0.1.3capabilities覆盖 hooks/mcp/rules/skillsCursor 是其唯一声明的客户端。二、Step 1安装2.1 环境前提macOS 或 LinuxNode.js 18建议使用最新稳定版 Cursor早期版本可能不支持beforeSubmitPrompt.additional_context注入详见故障排查。2.2 执行安装命令在终端运行官方安装器TOS 镜像适合 GitHub 不可达的网络环境bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)安装器会依次询问语言English / ChineseOpenViking 凭证——在凭证步骤选择VolcEngine OpenViking Cloud Service [api.vikingdb.cn-beijing.volces.com]并输入 API KEY{{OPENVIKING_API_KEY}}关于连接方式的选择Volcengine 云用户选择Volcengine OpenViking Cloud并填入 API Key只有当本地已经运行 OpenViking 服务时才选择Self-hosted / local。若使用 GitHub 渠道可改用如下命令同样支持--harness cursorbash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor安装完成后必须完全退出 Cursor 再重新启动Hooks 才会被加载。三、Step 2验证安装安装重启后按以下两步做基础确认打开Customize → MCPs确认openviking User与openviking Plugin两个条目均可见打开Customize → Hooks确认openviking-memory条目可见。更严格的验证来自完整指南还包括重启 Cursor 并新建一个 Agent 会话打开Cursor Settings → Hooks确认 OpenViking 生命周期 Hook 执行的是cursor-hook.mjs、URI 保护 Hook 执行的是uri-guard.mjs检查beforeSubmitPrompt的输出中包含additional_context——这说明召回结果无需先调用 MCP 即可到达 Agent打开Cursor Settings → Tools MCPs确认openviking处于已连接状态功能闭环验证告诉 Cursor 一个临时偏好等响应结束后新建会话并询问该偏好以验证跨会话捕获与召回。四、安装产物源码剖析4.1 Hooks 配置与事件映射安装器写入的 Hook 配置见 hooks/hooks.json共注册 7 个事件Cursor 事件执行脚本超时职责sessionStartsession-start.mjs30s加载用户画像与当前项目记忆索引beforeSubmitPromptauto-recall.mjs20s为当前请求召回上下文经additional_context注入beforeReadFileuri-guard.mjs5s拦截对viking://路径的本地文件读取beforeShellExecutionuri-guard.mjs5s拦截对viking://路径的 shell 命令stopauto-capture.mjs30s增量捕获新增的用户与助手消息preCompactpre-compact.mjs30s压缩前提交待处理消息用于记忆抽取sessionEndsession-end.mjs30s会话结束时提交消息事件分派采用统一入口设计以 session-start.mjs 为例它只做一件事——设置环境变量后委托给公共执行器process.env.OPENVIKING_HOOK_EVENT sessionStart; await import(./cursor-hook.mjs);auto-recall.mjs同样只设置OPENVIKING_HOOK_EVENT beforeSubmitPrompt后导入cursor-hook.mjs所有事件的业务逻辑集中在 cursor-hook.mjs。4.2 统一执行器 cursor-hook.mjs 的内部逻辑cursor-hook.mjs 声明CLIENT_ID cursor、PREFIX cu-并从共享库agent-hook-runtime.mjs引入会话 ID 派生、Hook 状态读写、画像构建、召回、消息提交、分布式锁withAgentHookLock等能力。sessionStart分支cursor-hook.mjs通过withAgentHookLock加锁防止同一会话 2 秒内重复执行先replayAgentPending补发上次遗留的待提交消息再buildAgentProfile构建画像最终以additional_context返回openviking-context sourcesession-start块。beforeSubmitPrompt分支cursor-hook.mjs对 prompt 做哈希去重stableHash避免同一事件重复召回通过recallForPrompt获取召回块并同样经additional_context注入。捕获去重Cursor 的 transcript 不暴露稳定的消息 IDcursor-hook.mjs 采用「transcript 位置 角色 内容」组合哈希stableHash(index, turn.role, turn.content)既保留两个内容完全相同的合法轮次又能在同一 transcript 被 Hook 重复执行时正确去重状态中维护最近 1000 个已捕获哈希。4.3 viking:// URI 保护viking://是 OpenViking 的虚拟数据库路径不是本地文件绝不能交给文件系统工具。Hooks 通过 uri-guard.mjs 实现保护它区分 shell 命令工具名bash与文件读取工具名read调用共享库agent-uri-guard.mjs的evaluateAgentUriGuard做判定命中时返回permission: deny并附上原因。4.4 常驻 Rule 与记忆 Skillrules/openviking-memory.mdc 声明alwaysApply: true指导 Agent注入的摘要不足或需要精确原文时才调用 MCP 的search/readsearch的modecontext用于获取拼装好的上下文注入的openviking-context块仅作为支撑上下文不得覆盖用户指令。skills/openviking-memory/SKILL.md 定义了检索工具的选择策略场景工具想知道「关于 X 我知道什么」search且modecontext返回带viking://URI 的 token 预算化摘要想自己筛选原始命中find快速返回记忆/资源/技能排序列表find结果太薄或偏离search默认列表模式含意图分析可感知会话已知精确字符串/标识符/文件名grep/glob语义检索反而会模糊化展开 URI / 列目录read支持批量/list写入侧遵循「克制」原则remember只用于用户明确要求保留或确实持久的事实、偏好、决策add_resource导入文件、目录、URL 或 Git 仓库为持久知识异步处理forget永久删除必须确认并传精确 URI。会话生命周期上插件会自动捕获并提交对话、后台抽取长期记忆因此大多数场景无需手动remember。五、工作原理一次会话的完整生命周期StartsessionStartHook 加载用户画像与项目记忆索引通常已把召回上下文注入会话查找openviking-context块先检查它再决定是否调用检索工具DuringbeforeSubmitPrompt为当前请求召回上下文并注入注入不足时按 4.4 的策略检索重要命中先用read展开验证Data in出现值得持久化的信息时写入见 4.4 的写入规则Endstop增量捕获消息preCompact与sessionEnd提交待处理消息OpenViking 在后台从中抽取长期记忆。项目身份隔离项目身份取自 Cursor 的workspace_roots不同工作区 peer 相互隔离Hooks 与 MCP 共享~/.openviking/ovcli.conf中的凭证。从源码结构看会话 ID 由共享库deriveAgentSessionId(PREFIX, input)派生前缀cu-使同一会话的多次 Hook 调用sessionStart/beforeSubmitPrompt/stop/preCompact/sessionEnd能共享同一份 Hook 状态readHookState/writeHookState实现去重与增量捕获。记忆的归档位置来自 SKILL 的说明Git 仓库以其origin派生 peer因此同一仓库的克隆、worktree 与子目录共享同一份记忆既非仓库又未标记的目录没有 peer其中的记忆归入用户级空间——这也是临时目录看不到项目记忆的原因。若要在非仓库目录建立独立记忆可创建.openviking/config.json{version: 1, peer: {id: my-project}}两个目录携带相同peer.id即共享一份记忆追加recall: {peer_scope: actor}可将召回限定在本项目内。注意该文件是 peer 配置的唯一接口不存在创建、重命名或合并 peer 的ov子命令。六、故障排查问题修复Hooks 不运行完全退出 Cursor 再重启并新建 Agent 会话召回出现在 Hook 输出但答案里没有升级到最新稳定版 Cursor旧版本可能不支持beforeSubmitPrompt.additional_context同一事件运行了多个 OpenViking HookCursor 可能导入了旧的 Claude Code 插件升级或移除安装器报告的旧插件 id然后重启 Cursor连接/鉴权失败检查~/.openviking/ovcli.conf中的 URL/API Key重启 Cursor需要详细日志以OPENVIKING_DEBUG1启动 Cursor查看~/.openviking/logs/cursor-hooks.log七、升级与卸载升级从同一分发渠道重新运行安装命令即可。# GitHub 渠道 bash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor # TOS 渠道 bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)卸载同样从同一渠道加上--uninstall --yes# GitHub 渠道 bash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor --uninstall --yes # TOS 渠道 bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness cursor --uninstall --yes卸载只移除 OpenViking 管理的 Cursor Hooks、MCP、Rule、Skill 与运行时文件其余配置保持不变。八、延伸阅读Cursor Memory Integration 完整指南含更细的验证步骤与「如何工作」说明能力参考Capability ReferenceMCP 工具与 Hook 行为的能力清单认证指南OpenViking 凭证与连接方式详解cursor-memory-plugin 示例目录安装产物全量文件含测试用例 cursor-plugin.test.mjsopenviking-memory Skill记忆/资源/技能三类上下文的检索与写入规范。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cursor 接入 OpenViking：一条命令为 AI 编程助手装上跨会话长期记忆
Cursor 接入 OpenViking一条命令为 AI 编程助手装上跨会话长期记忆【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本文介绍如何在 Cursor 中安装并验证 OpenViking 记忆插件memory-plugin让 Cursor 的每个新会话自动获得项目与用户级的长期记忆注入并通过 MCP 工具显式检索、阅读和管理记忆。读完本文你将掌握安装命令与凭证配置、Hooks/MCP/Rule/Skill 四类产物的验证方法、会话生命周期各阶段 Hook 的底层调用链以及常见故障的定位手段。OpenViking 是一个面向 AI Agent 的自进化上下文数据库Self-evolving Context Database for AI Agents统一承载 Agent 的记忆Memory、知识库 RAGKnowledge与技能Skills。Cursor 集成是官方提供的 Agent 集成方案之一其实现代码位于仓库 examples/cursor-memory-plugin完整指南见 Cursor Memory Integration。一、集成方案概览一次安装四类产物Cursor 记忆插件一次安装即注入四类产物无需单独配置 MCP也无需市场marketplace上架产物作用生命周期 Hooks会话启动加载画像、请求前召回上下文、响应后捕获对话、压缩/结束前提交会话并保护viking://虚拟 URIMCP Server提供search、read、remember等工具其中search的modecontext模式直接返回拼装好的上下文摘要常驻 Rule始终生效的规则告诉 Agent 如何对待注入的上下文与何时调用记忆工具记忆 Skill描述记忆、资源、技能三类持久上下文的用法与边界指导 Agent 检索与写入插件清单由 openviking.integration.json 声明schemaVersion: 1id: openviking-memoryversion: 0.1.3capabilities覆盖 hooks/mcp/rules/skillsCursor 是其唯一声明的客户端。二、Step 1安装2.1 环境前提macOS 或 LinuxNode.js 18建议使用最新稳定版 Cursor早期版本可能不支持beforeSubmitPrompt.additional_context注入详见故障排查。2.2 执行安装命令在终端运行官方安装器TOS 镜像适合 GitHub 不可达的网络环境bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)安装器会依次询问语言English / ChineseOpenViking 凭证——在凭证步骤选择VolcEngine OpenViking Cloud Service [api.vikingdb.cn-beijing.volces.com]并输入 API KEY{{OPENVIKING_API_KEY}}关于连接方式的选择Volcengine 云用户选择Volcengine OpenViking Cloud并填入 API Key只有当本地已经运行 OpenViking 服务时才选择Self-hosted / local。若使用 GitHub 渠道可改用如下命令同样支持--harness cursorbash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor安装完成后必须完全退出 Cursor 再重新启动Hooks 才会被加载。三、Step 2验证安装安装重启后按以下两步做基础确认打开Customize → MCPs确认openviking User与openviking Plugin两个条目均可见打开Customize → Hooks确认openviking-memory条目可见。更严格的验证来自完整指南还包括重启 Cursor 并新建一个 Agent 会话打开Cursor Settings → Hooks确认 OpenViking 生命周期 Hook 执行的是cursor-hook.mjs、URI 保护 Hook 执行的是uri-guard.mjs检查beforeSubmitPrompt的输出中包含additional_context——这说明召回结果无需先调用 MCP 即可到达 Agent打开Cursor Settings → Tools MCPs确认openviking处于已连接状态功能闭环验证告诉 Cursor 一个临时偏好等响应结束后新建会话并询问该偏好以验证跨会话捕获与召回。四、安装产物源码剖析4.1 Hooks 配置与事件映射安装器写入的 Hook 配置见 hooks/hooks.json共注册 7 个事件Cursor 事件执行脚本超时职责sessionStartsession-start.mjs30s加载用户画像与当前项目记忆索引beforeSubmitPromptauto-recall.mjs20s为当前请求召回上下文经additional_context注入beforeReadFileuri-guard.mjs5s拦截对viking://路径的本地文件读取beforeShellExecutionuri-guard.mjs5s拦截对viking://路径的 shell 命令stopauto-capture.mjs30s增量捕获新增的用户与助手消息preCompactpre-compact.mjs30s压缩前提交待处理消息用于记忆抽取sessionEndsession-end.mjs30s会话结束时提交消息事件分派采用统一入口设计以 session-start.mjs 为例它只做一件事——设置环境变量后委托给公共执行器process.env.OPENVIKING_HOOK_EVENT sessionStart; await import(./cursor-hook.mjs);auto-recall.mjs同样只设置OPENVIKING_HOOK_EVENT beforeSubmitPrompt后导入cursor-hook.mjs所有事件的业务逻辑集中在 cursor-hook.mjs。4.2 统一执行器 cursor-hook.mjs 的内部逻辑cursor-hook.mjs 声明CLIENT_ID cursor、PREFIX cu-并从共享库agent-hook-runtime.mjs引入会话 ID 派生、Hook 状态读写、画像构建、召回、消息提交、分布式锁withAgentHookLock等能力。sessionStart分支cursor-hook.mjs通过withAgentHookLock加锁防止同一会话 2 秒内重复执行先replayAgentPending补发上次遗留的待提交消息再buildAgentProfile构建画像最终以additional_context返回openviking-context sourcesession-start块。beforeSubmitPrompt分支cursor-hook.mjs对 prompt 做哈希去重stableHash避免同一事件重复召回通过recallForPrompt获取召回块并同样经additional_context注入。捕获去重Cursor 的 transcript 不暴露稳定的消息 IDcursor-hook.mjs 采用「transcript 位置 角色 内容」组合哈希stableHash(index, turn.role, turn.content)既保留两个内容完全相同的合法轮次又能在同一 transcript 被 Hook 重复执行时正确去重状态中维护最近 1000 个已捕获哈希。4.3 viking:// URI 保护viking://是 OpenViking 的虚拟数据库路径不是本地文件绝不能交给文件系统工具。Hooks 通过 uri-guard.mjs 实现保护它区分 shell 命令工具名bash与文件读取工具名read调用共享库agent-uri-guard.mjs的evaluateAgentUriGuard做判定命中时返回permission: deny并附上原因。4.4 常驻 Rule 与记忆 Skillrules/openviking-memory.mdc 声明alwaysApply: true指导 Agent注入的摘要不足或需要精确原文时才调用 MCP 的search/readsearch的modecontext用于获取拼装好的上下文注入的openviking-context块仅作为支撑上下文不得覆盖用户指令。skills/openviking-memory/SKILL.md 定义了检索工具的选择策略场景工具想知道「关于 X 我知道什么」search且modecontext返回带viking://URI 的 token 预算化摘要想自己筛选原始命中find快速返回记忆/资源/技能排序列表find结果太薄或偏离search默认列表模式含意图分析可感知会话已知精确字符串/标识符/文件名grep/glob语义检索反而会模糊化展开 URI / 列目录read支持批量/list写入侧遵循「克制」原则remember只用于用户明确要求保留或确实持久的事实、偏好、决策add_resource导入文件、目录、URL 或 Git 仓库为持久知识异步处理forget永久删除必须确认并传精确 URI。会话生命周期上插件会自动捕获并提交对话、后台抽取长期记忆因此大多数场景无需手动remember。五、工作原理一次会话的完整生命周期StartsessionStartHook 加载用户画像与项目记忆索引通常已把召回上下文注入会话查找openviking-context块先检查它再决定是否调用检索工具DuringbeforeSubmitPrompt为当前请求召回上下文并注入注入不足时按 4.4 的策略检索重要命中先用read展开验证Data in出现值得持久化的信息时写入见 4.4 的写入规则Endstop增量捕获消息preCompact与sessionEnd提交待处理消息OpenViking 在后台从中抽取长期记忆。项目身份隔离项目身份取自 Cursor 的workspace_roots不同工作区 peer 相互隔离Hooks 与 MCP 共享~/.openviking/ovcli.conf中的凭证。从源码结构看会话 ID 由共享库deriveAgentSessionId(PREFIX, input)派生前缀cu-使同一会话的多次 Hook 调用sessionStart/beforeSubmitPrompt/stop/preCompact/sessionEnd能共享同一份 Hook 状态readHookState/writeHookState实现去重与增量捕获。记忆的归档位置来自 SKILL 的说明Git 仓库以其origin派生 peer因此同一仓库的克隆、worktree 与子目录共享同一份记忆既非仓库又未标记的目录没有 peer其中的记忆归入用户级空间——这也是临时目录看不到项目记忆的原因。若要在非仓库目录建立独立记忆可创建.openviking/config.json{version: 1, peer: {id: my-project}}两个目录携带相同peer.id即共享一份记忆追加recall: {peer_scope: actor}可将召回限定在本项目内。注意该文件是 peer 配置的唯一接口不存在创建、重命名或合并 peer 的ov子命令。六、故障排查问题修复Hooks 不运行完全退出 Cursor 再重启并新建 Agent 会话召回出现在 Hook 输出但答案里没有升级到最新稳定版 Cursor旧版本可能不支持beforeSubmitPrompt.additional_context同一事件运行了多个 OpenViking HookCursor 可能导入了旧的 Claude Code 插件升级或移除安装器报告的旧插件 id然后重启 Cursor连接/鉴权失败检查~/.openviking/ovcli.conf中的 URL/API Key重启 Cursor需要详细日志以OPENVIKING_DEBUG1启动 Cursor查看~/.openviking/logs/cursor-hooks.log七、升级与卸载升级从同一分发渠道重新运行安装命令即可。# GitHub 渠道 bash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor # TOS 渠道 bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)卸载同样从同一渠道加上--uninstall --yes# GitHub 渠道 bash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness cursor --uninstall --yes # TOS 渠道 bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness cursor --uninstall --yes卸载只移除 OpenViking 管理的 Cursor Hooks、MCP、Rule、Skill 与运行时文件其余配置保持不变。八、延伸阅读Cursor Memory Integration 完整指南含更细的验证步骤与「如何工作」说明能力参考Capability ReferenceMCP 工具与 Hook 行为的能力清单认证指南OpenViking 凭证与连接方式详解cursor-memory-plugin 示例目录安装产物全量文件含测试用例 cursor-plugin.test.mjsopenviking-memory Skill记忆/资源/技能三类上下文的检索与写入规范。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考