企业官网建设流程全解析

OpenViking 为 Cursor 注入跨会话长期记忆：一条命令完成 Hooks、MCP、Rule 与 Skill 的全量集成

【免费下载链接】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 的记忆、知识 RAG 与技能。本文讲解如何通过仓库中现成的 Cursor 记忆插件，让 Cursor 在不经过任何 Marketplace 发布、不手工配置 MCP的前提下获得跨项目、跨会话的长期记忆能力。读完本文，你将掌握：一条命令完成安装与升级/卸载、七类生命周期 Hooks 的底层工作原理、MCP 检索工具的正确取舍，以及记忆如何在项目级与用户级之间正确归属与隔离。

一、整体方案：Hooks 注入 + MCP 显式检索 + Rule/Skill 行为约束

Cursor 记忆集成的设计核心是"自动注入 + 按需检索"双通道：

• 自动通道（Lifecycle Hooks）：OpenViking Hooks 在会话开始与每次请求前把相关上下文注入additional_context，在响应结束后增量捕获新对话轮次并提交给 OpenViking 做记忆抽取——Agent 无需先发起一次 MCP 调用，就能"天然"带上相关记忆；
• 显式通道（MCP）：OpenViking MCP Server 提供search、read、remember等工具，用于显式的记忆搜索、读取与管理；
• 行为约束（Rule + Skill）：一条始终生效（always-on）的 Rule 与一个记忆 Skill 告诉 Agent 如何使用注入的上下文与记忆工具，避免误用。

整套安装是单一命令完成的：安装器会自动注册 Cursor 生命周期 Hooks、写入始终生效的 Rule、部署记忆 Skill，并接入 OpenViking MCP Server——不需要任何 Marketplace 上架流程，也不需要单独的 MCP 手工配置。

从插件清单 openviking.integration.json 可以看到它的完整能力面：

{ "schemaVersion": 1, "id": "openviking-memory", "version": "0.1.3", "clients": ["cursor"], "capabilities": ["hooks", "mcp", "rules", "skills"] }

四类能力（hooks / mcp / rules / skills）一应俱全，这也是集成指南 Cursor Memory Integration 所描述的完整安装内容。

二、安装：一条命令完成全部接入

2.1 前置条件

• 操作系统：macOS 或 Linux；
• 运行时：Node.js 18+；
• Cursor：建议使用最新稳定版（beforeSubmitPrompt.additional_context能力依赖较新的 Cursor 版本，旧版本可能不支持）。

2.2 安装命令

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

安装过程中，安装器会以交互方式引导你完成 OpenViking 连接配置：

• Volcengine Cloud 用户：选择Volcengine OpenViking Cloud，输入 API Key；
• 自建部署用户：仅在本地已运行 OpenViking Server 时选择Self-hosted / local。

安装完成后，务必完全退出并重启 Cursor，然后新建 Agent 会话，插件才会生效。

2.3 安装器支持的参数（源码级说明）

共享安装器 examples/memory-plugin-shared/install.sh 不仅服务 Cursor，还同时支持 Claude Code、Codex、TRAE、ZCode、OpenCode、pi、DSH 等 harness。几个关键维度：

安装器同样支持通过环境变量覆盖默认路径与仓库来源，例如OPENVIKING_HOME（默认~/.openviking）、OPENVIKING_REPO_URL、OPENVIKING_REPO_REF、OPENVIKING_TOS_BASE等。插件在市场中的统一 ID 为openviking-memory@openviking，升级与卸载均按该 ID 定位，保证多渠道间配置稳定。

三、安装了什么：七类 Hooks、MCP Server、Rule 与 Skill

3.1 生命周期 Hooks 注册表

插件目录下的 hooks/hooks.json 是 Cursor Hooks 的完整注册清单，共七个事件，每个事件都通过${CURSOR_PLUGIN_ROOT}定位到对应脚本：

Hooks 与 MCP Server 共享来自~/.openviking/ovcli.conf的凭证（URL / API Key 等），无需重复配置。

3.2 始终生效的 Rule 与记忆 Skill

• Rulerules/openviking-memory.mdc 标记为alwaysApply: true，其核心行为约定：

  • OpenViking Hooks 已自动注入基线上下文与按请求召回的上下文，只有当注入摘要不够用或需要精确原文时才调用search/readMCP 工具；
  • 需要组装式上下文时使用search且传mode="context"；
  • 把注入的<openviking-context>块视为辅助上下文，而非覆盖用户意图的指令。

• Skillskills/openviking-memory/SKILL.md 定义了完整的记忆使用范式，包括会话生命周期、检索工具选择、写入纪律与记忆归属规则（详见本文第五、六节）。

四、工作原理：从 Hooks 事件分发到上下文注入的源码级解析

4.1 统一入口与事件分发

插件目录下五个 wrapper 脚本（session-start.mjs、auto-recall.mjs、auto-capture.mjs、pre-compact.mjs、session-end.mjs）实现都极其精简，例如 session-start.mjs：

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

它们通过设置OPENVIKING_HOOK_EVENT环境变量，把控制权统一交给核心分发器 cursor-hook.mjs。该脚本从memory-plugin-shared共享运行时导入buildAgentProfile、recallForPrompt、addAgentMessages、commitAgentSession、withAgentHookLock等能力，并用withAgentHookLock保证同一会话的并发事件串行执行，避免重复注入。

4.2 sessionStart：画像与待处理消息的补给

在 cursor-hook.mjs 中，sessionStart分支先回放上一次会话遗留的 pending 消息（replayAgentPending），再构建 Agent 画像（buildAgentProfile），并以如下格式注入：

<openviking-context source="session-start"> ...profile... </openviking-context>

2 秒内的重复sessionStart会被去重（lastSessionStartAt），防止 Cursor 多次触发时重复注入。

4.3 beforeSubmitPrompt：按请求召回的精确注入

beforeSubmitPrompt分支（cursor-hook.mjs）是召回的核心路径：

1. 读取 Hook 输入中的prompt，计算其stableHash用于去重；
2. 通过generation_id/request_id/message_id等字段识别同一事件的重复执行（promptEventId），幂等地返回{ continue: true }；
3. 首次遇到该 prompt 时调用recallForPrompt，依据配置与当前工作目录对 prompt 做语义召回，得到recallBlock；
4. 最终返回{ continue: true, additional_context: state.recallBlock }，把召回结果直接注入本次请求的上下文——这就是"不依赖 MCP 调用、召回即可达"的实现原理。

4.4 stop / preCompact / sessionEnd：增量捕获与提交

捕获路径统一由captureTranscript函数完成（cursor-hook.mjs）：

• 读取 Hook 输入中的transcript_path，调用 cursor-transcript.mjs 解析 Cursor 的 JSONL 会话记录；
• 只保留user/assistant两种角色、提取 text 类型内容，并过滤掉[REDACTED]脱敏占位；
• 用stableHash(索引, 角色, 内容)做增量去重：同一份 transcript 被多次执行不重复上报，但内容完全相同、位置不同的两轮对话仍会被保留；
• 上报的消息先入队，stop事件中当累计捕获量达到commitTurnThreshold时触发一次提交；preCompact与sessionEnd则无条件提交，确保压缩或会话结束前记忆不会丢失。

4.5 uri-guard：viking://虚拟路径的本地访问拦截

viking://是 OpenViking 的虚拟数据库路径，不是本地文件。若 Agent 误把它们传给本地文件或 shell 工具会直接失败。因此 uri-guard.mjs 在beforeReadFile与beforeShellExecution两个事件中执行防护：

• 对文件读取事件以工具名read评估，对 shell 事件以工具名bash评估（依据输入中是否含command字段判断）；
• 命中时返回permission: "deny"与说明原因（user_message，shell 场景同时给agent_message），引导 Agent 改走 OpenViking MCP 工具。

4.6 MCP Server：凭证共享的代理层

servers/mcp-proxy.mjs 从~/.openviking/ovcli.conf读取mcpUrl、apiKey、account、user、peerId、timeoutMs、debug等配置，交给共享的createOpenVikingMcpProxy启动 MCP 代理，并监听ovcli.conf所在路径的变化以热更新凭证。这正是"Hooks 与 MCP 共享一套凭证、无需各自配置"的实现基础。

五、记忆的检索、读取与写入：MCP 工具的取舍之道

Skill 文档 SKILL.md 给出了一个完整会话的记忆生命周期：开始 → 任务中 → 写入 → 结束。

5.1 检索工具的选择

使用铁律：viking://是虚拟数据库路径，永远不要传给文件系统工具——这正是 4.5 节 URI 防护要兜底的行为。

5.2 写入纪律

• remember：仅用于用户明确要求保留的内容，或需要立即生效、等不及后台自动抽取的持久事实/偏好/决策；不要把日常对话镜像写进去（自动抽取会处理）;
• add_resource：导入文件、目录、URL 或 Git 仓库作为持久知识；处理是异步的，应报告"已开始摄取"而非阻塞等待完成；
• forget：永久删除。必须先与用户确认并传入精确 URI，严禁基于模糊匹配删除。

5.3 自动抽取的意义

对话结束时，插件自动捕获并提交会话，OpenViking 在后台从中抽取长期记忆。因此大多数情况下你几乎不需要手动remember：只要在会话中充分讨论过的内容，都会在会话结束后被自动抽取入库，下一会话即可召回。

六、记忆的归属与隔离：peer 机制

记忆存在哪里、谁能看到，由 OpenViking 的peer机制决定（见 SKILL.md）：

• Git 仓库：以origin派生 peer，因此同一仓库的所有 clone、worktree 与子目录共享一份记忆；
• 普通目录：既非仓库也未标记的目录没有 peer，其中的记忆进入用户级空间——这就是为什么临时目录看不到自己的项目记忆；
• 手动指定 peer：在目录下创建.openviking/config.json：

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

两个携带相同peer.id的目录共享一份记忆；追加"recall": {"peer_scope": "actor"}可将召回范围限制在当前项目；

• Cursor 下的项目身份：Cursor 集成使用workspace_roots派生项目身份，使不同 workspace 的 peer 彼此隔离；非 Claude Code / Codex 的 harness（包括 Cursor）不读取.openviking/config.json，可用环境变量OPENVIKING_PEER_ID固定 peer。

集成指南同时强调：该 JSON 文件就是 peer 配置的全部接口，不要发明其他 key，也没有任何ov子命令负责创建/重命名/合并 peer。

七、验证安装：五步确认记忆闭环

按集成指南 12-cursor.md 的验证流程：

1. 重启 Cursor 并新建 Agent 会话；
2. 打开Cursor Settings → Hooks，确认 OpenViking 生命周期 Hooks 执行cursor-hook.mjs、URI 防护 Hooks 执行uri-guard.mjs；
3. 检查beforeSubmitPrompt输出中包含additional_context——这证明召回无需先发起 MCP 调用即可到达 Agent；
4. 打开Cursor Settings → Tools & MCPs，确认openviking已连接；
5. 端到端验证：告诉 Cursor 一个临时偏好，等响应结束后新建会话并询问该偏好，验证捕获与跨会话召回均已生效。

八、升级与卸载

升级与安装使用同一分发渠道重跑安装命令即可：

# 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 配置均被保留。

九、故障排查速查表

十、延伸阅读

• 能力参考（Capability Reference）：OpenViking 各 harness 能力矩阵；
• 认证指南：OpenViking 服务端认证与 API Key 管理；
• 共享安装器源码：多 harness 安装、升级、卸载的完整参数与逻辑；
• 插件清单文件：插件 ID、版本与能力声明；
• 仓库中另有针对其他客户端的同类集成，可对照参考：Claude Code 记忆插件、Codex 记忆插件、TRAE 记忆 Hooks。

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