Cursor 记忆集成

为 Cursor 添加跨项目、跨会话的长期记忆。安装完成后，OpenViking Hook 会在会话启动和用户提交问题时注入相关上下文，在回复结束后捕获新对话；MCP 仅用于主动搜索、读取和管理记忆。

安装

前置条件：macOS 或 Linux、Node.js 18+，并建议使用最新稳定版 Cursor。安装过程中会引导配置 OpenViking 连接信息。

安装器询问连接方式时，火山引擎云服务用户请选择 火山引擎 OpenViking 云服务 并填写 API Key。只有本机已运行 OpenViking 服务时才选择 自建 / 本地。

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness cursor

GitHub 访问受限时使用 TOS 镜像：

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

安装完成后完全退出并重新启动 Cursor。

安装内容

• 生命周期 Hook：自动加载画像、按问题召回、捕获对话、提交会话并保护 viking:// URI。
• OpenViking MCP Server：提供 search、recall、read、remember 等工具。
• always-on Rule 和记忆 Skill：告诉 Agent 如何使用已注入的上下文和记忆工具。

验证

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 一个临时偏好，等待本轮回复完成；新建会话后询问该偏好，确认捕获和跨会话召回均生效。

工作原理

• sessionStart：加载用户画像和当前项目的记忆索引。
• beforeSubmitPrompt：根据当前问题召回记忆并通过 additional_context 注入。
• beforeReadFile 和 beforeShellExecution：阻止把 viking:// 虚拟路径当作本地文件访问，并提示改用 OpenViking MCP 工具。
• stop：增量捕获本轮新增的用户与助手消息。
• preCompact / sessionEnd：提交尚未处理的消息，触发记忆抽取。

项目身份优先使用 Cursor 提供的 workspace_roots，因此不同项目会使用不同的 workspace peer。连接信息统一读取 ~/.openviking/ovcli.conf。

升级与卸载

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

# 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 和运行文件，保留其他配置。

故障排查

现象	原因与处理
Hook 没有触发	完全退出 Cursor 后重新启动，并新建 Agent 会话。
Hook 返回召回内容，但回答未使用	更新到最新稳定版 Cursor；旧版本可能不支持 beforeSubmitPrompt.additional_context。
同一事件出现多个 OpenViking Hook	Cursor 可能导入了旧 Claude Code 插件。升级或移除安装器列出的旧 OpenViking plugin id，然后重启 Cursor。
MCP 未连接	检查 ~/.openviking/ovcli.conf 中的 URL/API Key，并重启 Cursor。
需要详细日志	设置 OPENVIKING_DEBUG=1 后启动 Cursor，查看 ~/.openviking/logs/cursor-hooks.log。

参见

• 鉴权
• Cursor Hooks 文档