OpenViking × Cursor 记忆集成实战：一条命令为 Cursor 接入跨会话、跨项目的长期记忆

OpenViking × Cursor 记忆集成实战：一条命令为 Cursor 接入跨会话、跨项目的长期记忆

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是一款面向 AI Agent 的自进化上下文数据库，统一承载 Agent 记忆（Memory）、知识 RAG（Resources）与技能（Skills）。本文以仓库内的 Cursor 集成指南（docs/images/agents/zh/cursor.md）为骨架，完整讲解如何为 Cursor 编辑器安装 OpenViking 记忆插件：从一条命令完成安装与凭据配置，到验证 Hook 与 MCP 是否生效，再到故障排查与日常使用。读完本文，你将掌握 Cursor 下 OpenViking 生命周期 Hook 的触发时机、additional_context上下文注入机制，以及何时该用search/find/remember等记忆工具，让 Cursor 像人一样记住"上次是怎么决定的"。

前置条件

在开始安装前，请确认环境满足以下条件：

• 操作系统：macOS 或 Linux；
• Node.js 18 及以上（Hook 与 MCP 脚本均基于 Node 运行，见 examples/cursor-memory-plugin）；
• Cursor 建议使用最新稳定版（旧版本可能不支持beforeSubmitPrompt.additional_context字段）；
• 准备一个可用的 OpenViking 凭据：火山引擎 OpenViking 云服务的 API Key，或本机自建 OpenViking 服务的访问地址。

步骤 1：一条命令完成安装

在终端执行如下安装命令：

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)

安装器（install.sh）会依次询问以下信息：

1. 语言：English / 中文；

2. OpenViking 凭据：在凭据配置中，选择连接至「火山引擎 OpenViking 云服务 [api.vikingdb.cn-beijing.volces.com]」，并填入 API KEY：

   {{OPENVIKING_API_KEY}}

安装器同时提供自建 / 本地选项（默认地址http://127.0.0.1:1933）与自定义 URL / 保持当前选项，且会展示当前已存在的~/.openviking/ovcli.conf配置（url、api_key、account、user），允许你选择沿用现有凭据或重新配置（install.sh）。只有本机已运行 OpenViking 服务时才选择「自建 / 本地」。

如果你的网络环境访问 GitHub 受限，可显式指定渠道与 Harness 重新安装：

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness cursor --dist tos

安装完成后完全退出并重新启动 Cursor，让 Hook 注册生效。

提示：上述命令中{{OPENVIKING_API_KEY}}为占位符，请替换为你自己的 API Key；凭据最终写入~/.openviking/ovcli.conf（配置文件名可用环境变量OPENVIKING_CLI_CONFIG_FILE覆盖，见 install.sh）。

步骤 2：验证安装结果

1. 点击Customize → MCPs，确认可以看到「openviking User」和「openviking Plugin」两项；
2. 点击Customize → Hooks，确认可以看到「openviking-memory」条目。

更完整的验证路径（对应 docs/zh/agent-integrations/12-cursor.md 的官方指南）：

1. 重启 Cursor 并新建 Agent 会话；
2. 打开Cursor Settings → Hooks，确认 OpenViking 生命周期 Hook 执行了cursor-hook.mjs，URI 保护 Hook 执行了uri-guard.mjs；
3. 查看beforeSubmitPrompt输出，确认存在additional_context——这表示当前问题的召回结果已直接交给 Agent，无需先调用 MCP；
4. 打开Cursor Settings → Tools & MCPs，确认openviking已连接；
5. 告诉 Cursor 一个临时偏好，等待本轮回复完成；新建会话后询问该偏好，确认捕获与跨会话召回均生效。

安装内容与文件布局

安装器在 Cursor 中落地的内容与 examples/cursor-memory-plugin 目录一一对应：

插件的元数据声明见 openviking.integration.json：客户端为cursor，能力包含hooks、mcp、rules、skills，版本0.1.3。也就是说，一条命令同时装好了四类集成，无需再手动配置 MCP 或 Marketplace 条目。

Hook 事件与脚本映射

hooks.json 将 7 个 Cursor Hook 事件映射到对应脚本：

每个脚本只是设置OPENVIKING_HOOK_EVENT环境变量后转发到统一的 cursor-hook.mjs，例如：

process.env.OPENVIKING_HOOK_EVENT = "sessionStart"; await import("./cursor-hook.mjs");

工作原理：Hook 如何让记忆"长"在 Cursor 上

会话启动：注入基线上下文

sessionStart事件触发后，Hook 会做三件事（cursor-hook.mjs）：

1. 重放挂起消息（replayAgentPending）：把上次未提交的对话片段补发到 OpenViking；
2. 构建用户画像（buildAgentProfile）：加载用户级记忆与当前项目记忆索引；
3. 注入基线：将画像以如下形式写入 Hook 输出：

<openviking-context source="session-start"> ...用户画像与项目索引摘要... </openviking-context>

为防止重复执行，2 秒内的重复sessionStart会被去重（lastSessionStartAt时间戳判断）。

提交问题：按问题召回并直传 Agent

beforeSubmitPrompt事件是记忆价值的核心（cursor-hook.mjs）：

• 对当前prompt计算稳定哈希stableHash(prompt)；
• 通过recallForPrompt向 OpenViking 发起语义召回；
• 将召回结果通过 Hook 输出的additional_context直接注入本次请求——Agent 无需先调用 MCP 就能看到相关记忆；
• 同一 prompt 的重复事件在 500ms 内会被去重（promptHash/promptAt判断），避免重复召回。

回复结束：增量捕获对话

stop事件读取 Cursor 的 transcript 文件，用 cursor-transcript.mjs 解析出用户与助手消息，逐条计算stableHash(index, role, content)后增量发送（cursor-hook.mjs）。由于 Cursor transcript 不暴露稳定消息 ID，脚本用"序号 + 角色 + 内容"的哈希来去重：合法的重复消息会被保留，而同一 transcript 上重复执行的 Hook 不会重复发送。

压缩 / 会话结束：提交并触发抽取

preCompact与sessionEnd事件会调用commitAgentSession，把累积的捕获消息一次性提交给 OpenViking，触发后台的长期记忆抽取。stop事件也会在累积消息数达到commitTurnThreshold时提前提交（cursor-hook.mjs）。

URI 保护：viking://不是本地文件

beforeReadFile与beforeShellExecution共用 uri-guard.mjs：一旦发现目标路径是viking://虚拟路径，就返回permission: "deny"并提示改用 OpenViking MCP 工具，防止 Agent 把数据库虚拟路径误当作本地文件读取或执行（底层判定逻辑见 examples/memory-plugin-shared/lib/agent-uri-guard.mjs）。

项目身份与连接配置

• 项目身份：优先使用 Cursor 提供的workspace_roots派生 workspace peer，因此不同项目使用不同的 peer，记忆天然按项目隔离（peer 派生规则与peer.source配置见 examples/memory-plugin-shared/README.md）；
• 连接信息：统一读取~/.openviking/ovcli.conf（url/api_key等），Hook 与 MCP 共享同一份凭据。

记忆 Skill：Agent 该何时检索、何时写入

安装器同时写入的记忆 Skill（skills/openviking-memory/SKILL.md）为 Agent 定义了完整的记忆工作流：

一次会话的生命周期：

1. 启动——插件通常已在对话中注入<openviking-context>块，先检查它是否已回答当前问题，够用就跳过工具调用；
2. 任务中——注入上下文不够时再检索，命中后用read展开确认，因为摘要可能比原文旧或薄；
3. 写入——出现值得长期保存的信息时再写入，写入要克制：噪声越多，检索质量越差；
4. 结束——插件自动捕获并提交会话，OpenViking 在后台抽取长期记忆，所以日常很少需要手动remember。

检索工具的选择：

• search的mode="context"：查"关于 X 我知道什么"的首选，服务端直接组装带 token 预算的摘要，每条附viking://URI，可随时用read展开；
• find：快速返回记忆/资源/技能的排序列表，适合想自己筛选原始命中；
• search默认列表模式：比find更深，含意图分析、可选会话感知，find结果稀疏时使用；
• grep/glob：按字面文本或文件名精确匹配，知道确切字符串、标识符或文件名时使用；
• read/list：展开文件 URI（支持批量）/ 列出目录。

写入的边界：remember只用于用户明确要求保存的内容或明显的长期事实/偏好/决策；add_resource用于导入文件、目录、URL 或 Git 仓库作为持久知识（处理是异步的，告知"已开始导入"即可）；forget永久删除，必须确认并传精确 URI，绝不按模糊匹配删除。

记忆归属：git 仓库从其origin派生 peer，因此同一仓库的所有 clone、worktree、子目录共享一份记忆；非仓库目录不派生 peer，记忆落在用户级空间。给非仓库目录单独建记忆，可在该目录创建.openviking/config.json：

{"version": 1, "peer": {"id": "my-project"}}

两个目录使用相同peer.id即共享记忆；追加"recall": {"peer_scope": "actor"}可将召回限制在本项目内。

升级与卸载

重复运行对应渠道的安装命令即可升级。卸载时也使用原安装渠道：

# 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 Hook、MCP、Rule、Skill 与运行文件，保留其他配置（详见 docs/zh/agent-integrations/12-cursor.md）。

故障排查

结合原文档与官方指南，常见问题处理如下：

参考

• 完整集成指南：docs/zh/agent-integrations/12-cursor.md
• 插件源码与 README：examples/cursor-memory-plugin
• 共享运行库（Hook 运行时、workspace peer 派生、URI 保护）：examples/memory-plugin-shared/README.md
• 鉴权说明：docs/zh/guides/04-authentication.md

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking