OpenViking × TRAE 记忆集成:为 TRAE、TRAE CN 与 TraeCode CLI 2.0 打通跨项目、跨会话长期记忆

原创2026-09-09 18:47:062,329 阅读
文章标签:人工智能RAGAI AgentAgent 记忆向量数据库数据库LLM 网关EmbeddingRerank可观测性

OpenViking × TRAE 记忆集成:为 TRAE、TRAE CN 与 TraeCode CLI 2.0 打通跨项目、跨会话长期记忆

本篇技术指南讲解如何在 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、Stop Hook 的 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-cli

GitHub 访问受限时,使用 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 插件使用的是同一套上下文组装管线。

验证:五个步骤确认记忆闭环

  1. 重启 TRAE、TRAE CN 或 TraeCode CLI 2.0,并新建 Agent 会话;
  2. 在客户端的 MCP 设置中确认 openviking 已连接;
  3. 提问一个与已有项目或个人偏好相关的问题,确认回答使用了已有记忆(可在会话开头观察到 <openviking-context> / <relevant-memories> 注入);
  4. 告诉 Agent 一个临时偏好,等待回复完成;新建会话后再次询问,确认捕获、提交和跨会话召回均生效;
  5. 对 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)还是鉴权阶段。

关联资料

登录后查看全文
OpenViking