OpenViking × TRAE 记忆接入指南Hooks 自动召回与跨会话记忆实战【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 为 TRAE国际版与 TRAE 中国版提供了开箱即用的长期记忆接入方案通过一条命令即可安装生命周期 Hooks 与 MCP 代理实现会话开始自动加载上下文、提问前自动召回记忆、回答结束后自动捕获并提交本轮对话让 AI 编程助手获得跨项目、跨会话的持久记忆。本文以仓库内 TRAE 接入文档为核心结合 examples/trae-memory-hooks 的源码实现完整讲解安装、验证、故障排查与升级卸载流程读完即可在本地 TRAE 中复现并深入理解这套 Hooks 机制。接入原理一览TRAE 记忆闭环OpenViking 的 TRAE 集成不依赖额外插件市场而是基于 TRAE 原生的四个生命周期 HookSessionStart、UserPromptSubmit、PreToolUse、Stop自动工作SessionStart会话开始时加载 Agent 画像与当前项目记忆UserPromptSubmit用户提交问题时召回相关记忆并注入上下文PreToolUse拦截误指向viking://虚拟路径的本地文件/Shell 工具调用引导 Agent 回到 OpenViking MCP 工具Stop在回答结束后捕获本轮对话用户提问 助手回复并立即提交用于记忆提取即使是很短的会话也不会漏掉。同时安装器还会注册一个 OpenViking MCP 服务器透明暴露完整的服务端 MCP 工具集供显式检索、读取与管理记忆使用。整体架构在 examples/trae-memory-hooks/README.md 中有清晰说明TRAE 捕获不依赖 Claude Code 的转录解析而是直接从Stop事件的prompt、text_content、last_assistant_message字段读取对话内容并以tr-TRAE或trcn-TRAE CN前缀存储会话。步骤 1一键安装国际版与中文版安装命令根据你所使用的 TRAE 版本在终端执行对应的安装命令。TRAE 国际版bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae --dist tosTRAE 中国版bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae-cn --dist tos其中--harness指定接入的客户端trae对应 TRAE 国际版trae-cn对应 TRAE 中国版--dist tos指定从火山引擎 TOS 镜像分发GitHub 不可用时使用。若需同时安装国际版与中文版可一次性传入多个 harness--harness trae,trae-cn。安装器examples/memory-plugin-shared/install.sh支持的--harness取值还包括claude、codex、cursor、trae-cliTraeCode CLI 2.0、zcode、opencode、pi、dsh等覆盖主流 AI 编程客户端trae-cli通过 TraeCode CLI 2.0 的 Codex 兼容插件格式安装。安装器交互说明安装过程中安装器会依次询问以下信息语言选择English或中文OpenViking 凭据在凭据配置中选择连接方式并填入 API KEY。对于火山引擎云服务用户应选择「火山引擎 OpenViking 云服务 [api.vikingdb.cn-beijing.volces.com]」并填入 API KEY{{OPENVIKING_API_KEY}}仅在本地已运行 OpenViking 服务器时才选择自建/本地Self-hosted / local连接。安装器还支持通过--url参数直接指定自建服务地址并以向导形式将连接信息写入~/.openviking/ovcli.conf可通过环境变量OPENVIKING_CLI_CONFIG_FILE覆盖该路径见 install.sh。前提条件macOS 或 Linux 系统、Node.js 18且 TRAE 版本支持上述四个生命周期 Hook。安装完成后需完全退出并重启对应客户端。步骤 2理解安装产物四个 Hook 与一个 MCP 代理hooks.jsonTRAE 生命周期到 OpenViking 脚本的映射安装器会把 examples/trae-memory-hooks/hooks/hooks.json 模板中的占位符__OPENVIKING_TRAE_ROOT__插件安装目录与__OPENVIKING_CLIENT_ID__客户端标识替换为实际值写入~/.trae/hooks.json中国版为~/.trae-cn/hooks.json。其核心映射关系如下Hook 事件匹配范围触发的脚本超时职责SessionStart全部scripts/session-start.mjs30s回放待处理消息、构建并注入 Agent 画像UserPromptSubmit全部matcher 为空scripts/auto-recall.mjs20s为当前提问召回记忆并注入上下文PreToolUseRead\|Glob\|Grep\|Bash\|RunCommandscripts/uri-guard.mjs5s拦截viking://虚拟路径的本地误访问Stop全部scripts/auto-capture.mjs30s捕获本轮对话并提交记忆每个入口脚本如 auto-recall.mjs、session-start.mjs、auto-capture.mjs本质上只是通过环境变量OPENVIKING_HOOK_EVENT声明事件类型随后统一导入 trae-hook.mjs 执行核心逻辑。trae-hook.mjs统一的 Hook 处理核心trae-hook.mjs 是所有事件的汇聚点从源码可以看到几个关键设计客户端与前缀区分通过OPENVIKING_HOOK_SOURCE即传入的__OPENVIKING_CLIENT_ID__判定当前是trae还是trae-cn并分别使用tr-与trcn-会话前缀避免两类客户端的数据互相干扰trae-hook.mjs。去重与防抖UserPromptSubmit阶段基于stableHash(prompt)与promptEventId判断重复事件Stop阶段用capturedHashes集合记录已捕获内容的哈希最多保留最近 1000 条保证同一轮对话不会被重复入库trae-hook.mjs。即时提交捕获到新消息后立即调用commitAgentSession提交会话capturedSinceCommit归零若提交失败则保留计数等待下次重试trae-hook.mjs。上下文净化注入的回溯块以openviking-context与relevant-memories标签包裹cleanTraeText会在下一轮提问时剥离这些标签避免记忆污染提示词trae-turns.mjs。URI 守卫拦截 viking:// 虚拟路径TRAE 本地 Agent 可能会把viking://这类虚拟路径误传给Read、Bash等本地工具。uri-guard.mjs 在PreToolUse阶段调用evaluateAgentUriGuard做判定一旦命中就返回permissionDecision: deny并附上拒绝原因把 Agent 引导回 OpenViking MCP 工具而不是在本地文件系统上执行无效访问。MCP 代理与完整工具集servers/mcp-proxy.mjs 从ovcli.conf读取mcpUrl、apiKey、account、user、peerId等连接信息并启动 MCP 代理向 TRAE 透明暴露完整的服务端工具集共 15 个find、search、read、list、tree、remember、write、edit、add_resource、list_watches、cancel_watch、grep、glob、forget、health。其中search配合modecontext可返回组装好的上下文方便在对话中直接引用。步骤 3验证接入安装并重启 TRAE 后按以下方式确认接入成功打开「设置 → MCP → 已配置的 MCP Servers」确认能够看到openviking条目即表示 MCP 接入成功新建一个 Agent 会话询问已有项目或已知偏好确认回答确实使用了存储的记忆让 Agent 记住一条临时偏好例如「以后回复我时用中文」等待本轮回答结束后新建会话再次提问验证「捕获 → 提交 → 跨会话召回」的完整链路如需排查 Hook 问题可设置环境变量OPENVIKING_DEBUG1后启动客户端再查看对应日志TRAE~/.openviking/logs/trae-hooks.logTRAE 中国版~/.openviking/logs/trae-cn-hooks.log故障排查问题处理没有自动召回完全退出 TRAE重启再建会话连接 / 鉴权失败检查~/.openviking/ovcli.conf中的服务地址与 API KEY重启 TRAE需要日志查看~/.openviking/logs/trae-hooks.log或trae-cn-hooks.logMCP 未连接检查~/.openviking/ovcli.conf的 URL/API KEY 后重启客户端新会话无法召回上一轮检查 Hook 日志确认Stop阶段的/commit调用没有连接或鉴权错误同一内容被重复捕获检查用户级/项目级 Hooks 中是否残留旧的trae-auto-recall.mjs/trae-auto-capture.mjs条目重新运行安装器可清理 OpenViking 管理的遗留配置TraeCode CLI 2.0 不显示插件运行trae-cli plugin list若缺少openviking-memory重新以--harness trae-cli运行安装器升级与卸载升级重新运行对应的安装命令即可覆盖升级。卸载使用与安装相同的分发渠道追加--uninstall --yes参数。以 TRAE 中国版 TOS 镜像为例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-memoryopenviking以--harness trae-cli --uninstall运行安装器只会移除旧版本中遗留的独立 Hooks 集成。深入阅读TRAE 完整集成文档英文docs/en/agent-integrations/13-trae.mdTRAE Hooks 插件源码与 READMEexamples/trae-memory-hooksHook 事件映射模板hooks/hooks.jsonHook 核心处理逻辑scripts/trae-hook.mjs对话轮次解析与净化scripts/trae-turns.mjsviking://URI 守卫scripts/uri-guard.mjsMCP 代理入口servers/mcp-proxy.mjs多客户端安装器examples/memory-plugin-shared/install.shTraeCode CLI 2.0 变体examples/trae-cli-memory-hooks【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking × TRAE 记忆接入指南：Hooks 自动召回与跨会话记忆实战
OpenViking × TRAE 记忆接入指南Hooks 自动召回与跨会话记忆实战【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 为 TRAE国际版与 TRAE 中国版提供了开箱即用的长期记忆接入方案通过一条命令即可安装生命周期 Hooks 与 MCP 代理实现会话开始自动加载上下文、提问前自动召回记忆、回答结束后自动捕获并提交本轮对话让 AI 编程助手获得跨项目、跨会话的持久记忆。本文以仓库内 TRAE 接入文档为核心结合 examples/trae-memory-hooks 的源码实现完整讲解安装、验证、故障排查与升级卸载流程读完即可在本地 TRAE 中复现并深入理解这套 Hooks 机制。接入原理一览TRAE 记忆闭环OpenViking 的 TRAE 集成不依赖额外插件市场而是基于 TRAE 原生的四个生命周期 HookSessionStart、UserPromptSubmit、PreToolUse、Stop自动工作SessionStart会话开始时加载 Agent 画像与当前项目记忆UserPromptSubmit用户提交问题时召回相关记忆并注入上下文PreToolUse拦截误指向viking://虚拟路径的本地文件/Shell 工具调用引导 Agent 回到 OpenViking MCP 工具Stop在回答结束后捕获本轮对话用户提问 助手回复并立即提交用于记忆提取即使是很短的会话也不会漏掉。同时安装器还会注册一个 OpenViking MCP 服务器透明暴露完整的服务端 MCP 工具集供显式检索、读取与管理记忆使用。整体架构在 examples/trae-memory-hooks/README.md 中有清晰说明TRAE 捕获不依赖 Claude Code 的转录解析而是直接从Stop事件的prompt、text_content、last_assistant_message字段读取对话内容并以tr-TRAE或trcn-TRAE CN前缀存储会话。步骤 1一键安装国际版与中文版安装命令根据你所使用的 TRAE 版本在终端执行对应的安装命令。TRAE 国际版bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae --dist tosTRAE 中国版bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness trae-cn --dist tos其中--harness指定接入的客户端trae对应 TRAE 国际版trae-cn对应 TRAE 中国版--dist tos指定从火山引擎 TOS 镜像分发GitHub 不可用时使用。若需同时安装国际版与中文版可一次性传入多个 harness--harness trae,trae-cn。安装器examples/memory-plugin-shared/install.sh支持的--harness取值还包括claude、codex、cursor、trae-cliTraeCode CLI 2.0、zcode、opencode、pi、dsh等覆盖主流 AI 编程客户端trae-cli通过 TraeCode CLI 2.0 的 Codex 兼容插件格式安装。安装器交互说明安装过程中安装器会依次询问以下信息语言选择English或中文OpenViking 凭据在凭据配置中选择连接方式并填入 API KEY。对于火山引擎云服务用户应选择「火山引擎 OpenViking 云服务 [api.vikingdb.cn-beijing.volces.com]」并填入 API KEY{{OPENVIKING_API_KEY}}仅在本地已运行 OpenViking 服务器时才选择自建/本地Self-hosted / local连接。安装器还支持通过--url参数直接指定自建服务地址并以向导形式将连接信息写入~/.openviking/ovcli.conf可通过环境变量OPENVIKING_CLI_CONFIG_FILE覆盖该路径见 install.sh。前提条件macOS 或 Linux 系统、Node.js 18且 TRAE 版本支持上述四个生命周期 Hook。安装完成后需完全退出并重启对应客户端。步骤 2理解安装产物四个 Hook 与一个 MCP 代理hooks.jsonTRAE 生命周期到 OpenViking 脚本的映射安装器会把 examples/trae-memory-hooks/hooks/hooks.json 模板中的占位符__OPENVIKING_TRAE_ROOT__插件安装目录与__OPENVIKING_CLIENT_ID__客户端标识替换为实际值写入~/.trae/hooks.json中国版为~/.trae-cn/hooks.json。其核心映射关系如下Hook 事件匹配范围触发的脚本超时职责SessionStart全部scripts/session-start.mjs30s回放待处理消息、构建并注入 Agent 画像UserPromptSubmit全部matcher 为空scripts/auto-recall.mjs20s为当前提问召回记忆并注入上下文PreToolUseRead\|Glob\|Grep\|Bash\|RunCommandscripts/uri-guard.mjs5s拦截viking://虚拟路径的本地误访问Stop全部scripts/auto-capture.mjs30s捕获本轮对话并提交记忆每个入口脚本如 auto-recall.mjs、session-start.mjs、auto-capture.mjs本质上只是通过环境变量OPENVIKING_HOOK_EVENT声明事件类型随后统一导入 trae-hook.mjs 执行核心逻辑。trae-hook.mjs统一的 Hook 处理核心trae-hook.mjs 是所有事件的汇聚点从源码可以看到几个关键设计客户端与前缀区分通过OPENVIKING_HOOK_SOURCE即传入的__OPENVIKING_CLIENT_ID__判定当前是trae还是trae-cn并分别使用tr-与trcn-会话前缀避免两类客户端的数据互相干扰trae-hook.mjs。去重与防抖UserPromptSubmit阶段基于stableHash(prompt)与promptEventId判断重复事件Stop阶段用capturedHashes集合记录已捕获内容的哈希最多保留最近 1000 条保证同一轮对话不会被重复入库trae-hook.mjs。即时提交捕获到新消息后立即调用commitAgentSession提交会话capturedSinceCommit归零若提交失败则保留计数等待下次重试trae-hook.mjs。上下文净化注入的回溯块以openviking-context与relevant-memories标签包裹cleanTraeText会在下一轮提问时剥离这些标签避免记忆污染提示词trae-turns.mjs。URI 守卫拦截 viking:// 虚拟路径TRAE 本地 Agent 可能会把viking://这类虚拟路径误传给Read、Bash等本地工具。uri-guard.mjs 在PreToolUse阶段调用evaluateAgentUriGuard做判定一旦命中就返回permissionDecision: deny并附上拒绝原因把 Agent 引导回 OpenViking MCP 工具而不是在本地文件系统上执行无效访问。MCP 代理与完整工具集servers/mcp-proxy.mjs 从ovcli.conf读取mcpUrl、apiKey、account、user、peerId等连接信息并启动 MCP 代理向 TRAE 透明暴露完整的服务端工具集共 15 个find、search、read、list、tree、remember、write、edit、add_resource、list_watches、cancel_watch、grep、glob、forget、health。其中search配合modecontext可返回组装好的上下文方便在对话中直接引用。步骤 3验证接入安装并重启 TRAE 后按以下方式确认接入成功打开「设置 → MCP → 已配置的 MCP Servers」确认能够看到openviking条目即表示 MCP 接入成功新建一个 Agent 会话询问已有项目或已知偏好确认回答确实使用了存储的记忆让 Agent 记住一条临时偏好例如「以后回复我时用中文」等待本轮回答结束后新建会话再次提问验证「捕获 → 提交 → 跨会话召回」的完整链路如需排查 Hook 问题可设置环境变量OPENVIKING_DEBUG1后启动客户端再查看对应日志TRAE~/.openviking/logs/trae-hooks.logTRAE 中国版~/.openviking/logs/trae-cn-hooks.log故障排查问题处理没有自动召回完全退出 TRAE重启再建会话连接 / 鉴权失败检查~/.openviking/ovcli.conf中的服务地址与 API KEY重启 TRAE需要日志查看~/.openviking/logs/trae-hooks.log或trae-cn-hooks.logMCP 未连接检查~/.openviking/ovcli.conf的 URL/API KEY 后重启客户端新会话无法召回上一轮检查 Hook 日志确认Stop阶段的/commit调用没有连接或鉴权错误同一内容被重复捕获检查用户级/项目级 Hooks 中是否残留旧的trae-auto-recall.mjs/trae-auto-capture.mjs条目重新运行安装器可清理 OpenViking 管理的遗留配置TraeCode CLI 2.0 不显示插件运行trae-cli plugin list若缺少openviking-memory重新以--harness trae-cli运行安装器升级与卸载升级重新运行对应的安装命令即可覆盖升级。卸载使用与安装相同的分发渠道追加--uninstall --yes参数。以 TRAE 中国版 TOS 镜像为例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-memoryopenviking以--harness trae-cli --uninstall运行安装器只会移除旧版本中遗留的独立 Hooks 集成。深入阅读TRAE 完整集成文档英文docs/en/agent-integrations/13-trae.mdTRAE Hooks 插件源码与 READMEexamples/trae-memory-hooksHook 事件映射模板hooks/hooks.jsonHook 核心处理逻辑scripts/trae-hook.mjs对话轮次解析与净化scripts/trae-turns.mjsviking://URI 守卫scripts/uri-guard.mjsMCP 代理入口servers/mcp-proxy.mjs多客户端安装器examples/memory-plugin-shared/install.shTraeCode CLI 2.0 变体examples/trae-cli-memory-hooks【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考