OpenViking × TRAE 记忆集成：为 TRAE、TRAE CN 与 TraeCode CLI 2.0 打通跨项目、跨会话长期记忆
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
本篇技术指南讲解如何在 TRAE、TRAE CN 与 TraeCode CLI 2.0 中安装并启用 OpenViking 记忆集成，让这些编码 Agent 具备跨项目、跨会话的长期记忆能力。读完本文，你将掌握从一键安装、Hook 与 MCP 双层架构原理，到验证、升级、卸载与故障排查的完整实战方案，并能在源码层面理解每条记忆管线的底层调用关系。
集成原理：Hook 负责"喂"记忆，MCP 负责"取"记忆
TRAE 系列的记忆集成采用"生命周期 Hook + MCP Server"的双层架构：
- Hook 层：借助 TRAE/TRAE CN 支持的
SessionStart、UserPromptSubmit、PreToolUse、Stop四个生命周期事件，自动加载上下文、捕获每轮对话并提交给 OpenViking 记忆抽取器； - MCP 层：OpenViking MCP Server 透传服务端完整 MCP 工具集，供 Agent 主动搜索、读取和管理记忆。
该设计的关键点在于 TRAE 的捕获逻辑不复用 Claude Code 的 transcript 解析，而是直接从Stop事件中读取prompt、text_content与last_assistant_message字段，并以tr-（TRAE）或trcn-（TRAE CN）前缀存储会话（见 trae-memory-hooks/README.md）。也就是说，每条记忆在服务端都带有明确的客户端来源标记，多客户端共存时不会互相污染。
前置条件
- 操作系统：macOS 或 Linux；
- 运行时：Node.js 18+；
- 客户端版本：支持
SessionStart、UserPromptSubmit、PreToolUse、StopHook 的 TRAE / TRAE CN 版本；TraeCode CLI 2.0 则直接使用兼容 Codex 的插件格式接入，无需单独适配； - OpenViking 服务：本机已运行 OpenViking 服务，或持有火山引擎 OpenViking 云服务账号与 API Key。
安装过程中安装器会引导配置 OpenViking 连接信息（URL / API Key）。连接方式二选一，切勿选错：
- 火山引擎云服务用户：选择火山引擎 OpenViking 云服务并填写 API Key；
- 本机已运行 OpenViking 服务：选择自建 / 本地。
安装：一条命令完成三个客户端的接入
安装脚本位于仓库 examples/memory-plugin-shared/install.sh，通过--harness参数指定目标客户端。从脚本源码可见，--harness支持逗号分隔的多目标列表（claude, codex, cursor, trae, trae-cn, trae-cli, zcode, opencode, pi, dsh），且脚本会主动探测本机已安装的 TRAE 系列客户端（install.sh中分别检查/Applications/Trae.app、/Applications/Trae CN.app及trae-cli/traecli/traex等命令），便于交互式选择。
# TRAE bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness trae # TRAE CN bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness trae-cn # 同时安装 bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness trae,trae-cn # TraeCode CLI 2.0 bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness trae-cliGitHub 访问受限时，使用 TOS 镜像（--dist tos）：
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness trae,trae-cn --dist tos # TraeCode CLI 2.0 bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness trae-cli --dist tos安装完成后，完全退出并重启对应客户端，让新写入的 Hook 与 MCP 配置生效。
安装内容逐项拆解：四个 Hook 与 15 个 MCP 工具
Hook 清单
安装器会在用户级与项目级配置中注册以下四个生命周期 Hook，具体声明可参见 trae-memory-hooks/hooks/hooks.json：
| Hook 事件 | 动作 | 默认超时 |
|---|---|---|
SessionStart | 加载用户画像和当前项目记忆 | 30s |
UserPromptSubmit | 根据当前问题召回并注入相关内容 | 20s |
PreToolUse | 阻止把viking://虚拟路径当作本地文件访问，提示改用 MCP 工具 | 5s |
Stop | 捕获本轮消息并立即提交，短会话也能进入记忆抽取流程 | 30s |
在 trae-hook.mjs 中可以看到每个事件的具体处理逻辑：
- SessionStart：进入
withAgentHookLock临界区后，先回放上次中断遗留的待提交消息（replayAgentPending），再通过buildAgentProfile构建用户画像，最终把结果以<openviking-context source="session-start">标签注入会话。源码中用 2 秒窗口去重，避免重复触发； - UserPromptSubmit：对用户输入做
cleanTraeText清洗（剔除上一轮注入的<openviking-context>与<relevant-memories>标签），再调用recallForPrompt完成召回，结果作为additionalContext注入。同时记录 prompt 哈希与事件 ID，防止同一 prompt 被重复召回； - Stop：由 trae-turns.mjs 从
Stop事件中提取user（来自input.prompt或待提交的 pendingPrompt）与assistant（来自last_assistant_message或text_content）两个角色的一轮对话，去重后调用addAgentMessages写入会话，随后立即调用commitAgentSession触发记忆抽取——这正是"短会话也能入库"的实现原理； - PreToolUse：通过 uri-guard.mjs 内的
evaluateAgentUriGuard判断工具与输入，若命中viking://虚拟路径则返回permissionDecision: "deny"并附带原因提示，把 Agent 引导回 OpenViking MCP 工具；Hook 配置中该事件只匹配Read|Glob|Grep|Bash|RunCommand这类可能触碰文件系统的工具，开销极小（5s 超时）。
OpenViking MCP Server：15 个工具
MCP Server 透传 OpenViking 服务端的完整 MCP 工具集，共 15 个工具：find、search、read、list、tree、remember、write、edit、add_resource、list_watches、cancel_watch、grep、glob、forget、health。
其中值得关注的是search的mode="context"：该模式返回组装后的上下文而非原始命中片段。在 recall-core.mjs 的buildContextSearchBody中可以看到，插件声明mode: "context"、purpose: "coding"与score_threshold（默认 0.35），把配额分配、层级降级、跨轮次去重等机制交给服务端默认策略处理；同时支持按需携带quotas、max_tokens、session_id、query_expansion、dedup_turns（默认 5 轮）等参数精细控制召回行为。这意味着你在 TRAE 中获得的召回结果，与 CLI、其他 IDE 插件使用的是同一套上下文组装管线。
验证：五个步骤确认记忆闭环
- 重启 TRAE、TRAE CN 或 TraeCode CLI 2.0，并新建 Agent 会话；
- 在客户端的 MCP 设置中确认
openviking已连接； - 提问一个与已有项目或个人偏好相关的问题，确认回答使用了已有记忆（可在会话开头观察到
<openviking-context>/<relevant-memories>注入）； - 告诉 Agent 一个临时偏好，等待回复完成；新建会话后再次询问，确认捕获、提交和跨会话召回均生效；
- 对 TraeCode CLI 2.0，运行
trae-cli plugin list，确认openviking-memory已启用。
查看 Hook 调试日志
需要排查 Hook 时，设置OPENVIKING_DEBUG=1后启动客户端，然后查看对应日志：
| 客户端 | 日志路径 |
|---|---|
| TRAE | ~/.openviking/logs/trae-hooks.log |
| TRAE CN | ~/.openviking/logs/trae-cn-hooks.log |
| TraeCode CLI 2.0 | ~/.openviking/logs/codex-hooks.log |
日志由createAgentLogger按客户端与事件维度写入，能够区分profile、recall、pending、uncaught等不同阶段的错误，是定位问题的一手依据。
升级与卸载
升级：重复运行对应安装命令即可，安装器会覆盖更新由 OpenViking 管理的 Hook 条目与脚本。
卸载：务必使用原安装渠道（GitHub 或 TOS），避免残留：
# GitHub，以 TRAE CN 为例 bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \ --harness trae-cn --uninstall --yes # TOS，以 TRAE CN 为例 bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) \ --harness trae-cn --uninstall --yes将trae-cn替换为trae即可管理 TRAE 集成。TraeCode CLI 2.0 请执行：
trae-cli plugin uninstall openviking-memory@openviking注意：安装器的--harness trae-cli --uninstall只用于移除旧安装中已弃用的独立 Hooks 集成；TraeCode CLI 2.0 的当前安装形态是 Codex 兼容插件，应按插件方式卸载。
故障排查
| 现象 | 原因与处理 |
|---|---|
| 安装后没有自动召回 | 完全退出客户端后重新启动，并新建 Agent 会话。 |
| MCP 未连接 | 检查~/.openviking/ovcli.conf中的 URL/API Key，然后重启客户端。 |
| 新会话无法回忆上一轮内容 | 查看 Hook 日志，确认Stop已执行且/commit没有连接或鉴权错误。 |
| 同一内容被捕获多次 | 检查用户级与项目级 Hook 中是否仍有旧版trae-auto-recall.mjs或trae-auto-capture.mjs；重跑安装器会移除由 OpenViking 管理的旧条目。 |
| TraeCode CLI 2.0 未列出插件 | 运行trae-cli plugin list；若没有openviking-memory，使用--harness trae-cli重跑安装器。 |
若上述步骤无法解决，建议先开OPENVIKING_DEBUG=1复现问题，再结合对应客户端的 Hook 日志（见上文日志路径）定位具体环节是发生在召回（recall）、画像（profile）、待提交回放（pending）还是鉴权阶段。
关联资料
- 集成能力参考：查看各客户端支持能力矩阵与 Hook/MCP 能力边界；
- 鉴权：配置 OpenViking 连接与 API Key 的完整说明；
- TRAE 记忆 Hook 源码：TRAE / TRAE CN 专用生命周期适配器实现；
- TraeCode CLI 记忆 Hook 源码：TraeCode CLI 2.0（Codex 兼容插件）实现；
- 共享安装器：支持多客户端的一键安装/升级/卸载脚本。
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
