为 Roo Code 接入 Hindsight 持久化长期记忆MCP 安装、配置与源码原理详解【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南围绕 Hindsight 官方为 Roo Code 提供的集成方案展开讲解如何通过一条命令将 Hindsight 的 MCP 服务器与自定义规则注入 Roo Code让其在每个任务开始前自动召回相关记忆、任务结束后沉淀经验从而实现跨会话的持久化长期记忆。读完本文你将掌握hindsight-roo-code的安装、项目级/全局级两种安装模式、.roo/mcp.json与规则文件的配置细节、recall/retain两个 MCP 工具的调用时机以及该集成在仓库中的源码级实现与测试依据。Roo Code 为什么需要长期记忆Roo Code 是基于 VS Code 的开源 AI 编程助手本仓库不包含其源码仅作为集成目标它借助MCPModel Context Protocol服务器提供工具能力借助自定义规则Custom Rules注入系统提示词。然而默认状态下Roo Code 的每次会话都是“失忆”的——上次任务中做过的技术决策、踩过的坑、用户的偏好在下一次会话中并不会自动出现。Hindsight仓库根目录README.md中定位为 Agent Memory That Learns正是为解决这一问题而生。本集成利用 Roo Code 的两种扩展机制在会话之间架起一座记忆桥梁MCP 服务器将 Hindsight 的/mcp端点注册为名为hindsight的 MCP 服务器暴露recall召回记忆与retain存储记忆两个工具自定义规则通过.roo/rules/hindsight-memory.md把使用这两个工具的指令注入到每一次 Roo Code 系统提示词中让 Agent 自动形成“任务前召回、任务中沉淀、任务后总结”的记忆闭环。工作原理一次完整的记忆闭环集成安装完成后Roo Code 中每个任务的记忆生命周期如下新任务开始 └─ 规则文件指示 Roo 调用 recall └─ 相关记忆自动注入上下文 Agent 工作过程中… └─ Agent 对重要决策/发现调用 retain 任务结束 └─ 规则文件指示 Roo 调用 retain 并附上总结 └─ 总结存入 Hindsight供未来会话使用安装器installer向项目写入两个文件共同构成这套机制.roo/mcp.json将 Hindsight 的/mcp端点注册为 MCP 服务器并将recall、retain两个工具设为自动放行auto-approved.roo/rules/hindsight-memory.md注入到每次 Roo Code 系统提示词中的记忆使用规则。在源码层面这两个工具确实由 Hindsight 服务端提供recall与retain在 engine/memory_engine.py 中有对应实现retain/retain_async/retain_batch_async与recall/recall_async并通过内置/mcp端点以 MCP 工具形式暴露给客户端接口定义见 engine/interface.py。前置条件准备一个可用的 Hindsight 实例Hindsight Cloud推荐无需自建基础设施注册即可获得 API Key直接跳过下面的自托管步骤。安装集成时默认指向 Cloud 端点https://api.hindsight.vectorize.io。自托管 Hindsight在本机先启动 Hindsight 服务pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api # 默认监听 http://localhost:8888HINDSIGHT_API_LLM_API_KEY用于配置底层 LLM 的 API KeyHindsight 依靠它完成记忆的抽取、总结与召回等需要模型参与的环节。快速开始一条命令接入记忆# 1. 安装 CLI pip install hindsight-roo-code # 2. 在项目目录中安装集成默认指向 Hindsight Cloud hindsight-roo-code install # 3. 重启 Roo Code —— 记忆即刻生效自托管替代方案先按上文启动本地 Hindsight再指定本地地址安装# 先启动本地 Hindsight pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api # 再用本地 URL 安装 hindsight-roo-code install --api-url http://localhost:8888该 CLI 的入口定义在 hindsight_roo_code/cli.py通过pyproject.toml中的[project.scripts]声明注册为控制台命令hindsight-roo-code。安装器本身零运行时依赖Python 版本要求3.10见 pyproject.toml。安装选项详解项目级安装默认在当前目录下写入.roo/记忆作用域限定于当前项目hindsight-roo-code install hindsight-roo-code install --api-url https://api.hindsight.vectorize.io # 默认值Hindsight Cloud hindsight-roo-code install --api-url http://localhost:8888 # 自托管 hindsight-roo-code install --project-dir /path/to/project全局安装写入~/.roo/对所有项目生效hindsight-roo-code install --global各命令行参数与 CLI 实现一一对应见 cli.py参数默认值说明--api-url环境变量HINDSIGHT_API_URL未设置时取https://api.hindsight.vectorize.ioHindsight API 基础地址--project-dir.当前目录安装目标项目目录--global关闭安装到~/.roo/而非项目目录值得注意的是--api-url的默认值会优先读取环境变量HINDSIGHT_API_URL这意味着你可以在不修改命令的情况下通过环境变量切换记忆后端。目标目录的解析逻辑在 install.py 的get_roo_dir中全局安装返回~/.roo否则返回project_dir/.roo。配置解析.roo/mcp.json安装器写入的 MCP 配置如下{ mcpServers: { hindsight: { type: streamable-http, url: http://localhost:8888/mcp, timeout: 30, alwaysAllow: [recall, retain] } } }各字段含义与源码实现build_mcp_entry见 install.pytype: streamable-httpRoo Code 通过流式 HTTP 方式与 MCP 服务器通信urlHindsight API 地址 /mcp路径。源码会对传入的 API URL 做rstrip(/)处理因此无论你传http://localhost:8888还是带尾斜杠的http://localhost:8888/最终都会规整为http://localhost:8888/mcptimeout: 30MCP 请求超时秒数。测试用例 test_install.py 验证了该值处于 Roo Code 可接受的 13600 秒区间内alwaysAllow: [recall, retain]两个记忆工具自动放行Agent 调用时无需用户逐一确认保证记忆流程顺畅无打断。修改 API 地址安装完成后若要更换后端例如从 Cloud 切换到自托管两种方式任选——重新运行安装器hindsight-roo-code install --api-url 新地址或直接编辑.roo/mcp.json。另外安装器对已存在的.roo/mcp.json采用合并而非覆盖策略见install_mcpinstall.py它会保留你已有的其他 MCP 服务器条目只新增或更新hindsight一项重复运行安装不会产生重复条目。对应测试用例test_merge_preserves_existing_servers与test_merge_does_not_duplicate在 test_install.py 中验证了这一行为。若既有文件损坏JSON 解析失败安装器会输出警告并覆盖重写。MCP 工具recall 与 retainHindsight 通过其/mcp端点暴露两个核心工具工具说明recall基于查询在记忆中搜索相关上下文retain立即将内容存入记忆规则文件指示 Roo 在任务开始与结束时自动调用这两个工具在任务进行中Agent 也可以随时显式调用它们。由于二者被列入alwaysAllow整个调用过程无需人工审批。规则文件记忆行为如何注入系统提示词.roo/rules/hindsight-memory.md是记忆行为的“行为契约”其完整内容与仓库中的 hindsight-memory.md 一致核心指令如下每个新任务开始时以总结任务的查询调用recallhindsight 服务器并将召回的相关记忆纳入回答上下文后再继续工作任务进行中出现重要决策、发现或用户偏好时立即调用retain存储不要拖到任务结束任务结束时调用retain附上本次完成内容的精炼总结、所做决策以及值得在未来任务中记住的模式。文件末尾强调“记忆跨会话持久存在用它避免重复劳动并在过往上下文之上继续构建。”——这正是整套集成的价值所在。规则文件被打包为 Python 包数据通过importlib.resources读取见 install.py因此无论以 wheel 安装还是从源码运行规则内容都能被正确解析。针对规则内容的测试 test_rules.py 验证了规则文件非空、同时引用recall与retain、包含任务开始召回与任务结束存储的指令——从测试断言即可看出规则文件的核心约束就是这三点。验证安装是否生效按以下步骤确认集成工作正常启动 Hindsighthindsight-api或 Hindsight Cloud在项目目录运行安装器hindsight-roo-code install在项目中打开 Roo Code检查Settings → MCP Servers——hindsight应显示为已连接connected发起一个新任务——在工具调用日志中应能看到recall被自动调用。安装器本身也会在安装结束时打印指引install.py重启 Roo Code 使变更生效然后到 Settings → MCP Servers 确认hindsight处于连接状态。从源码看安装器的完整行为整个安装过程由run_installinstall.py编排共两步install_mcp确保.roo/目录存在合并写入mcp.json打印配置文件路径install_rules创建.roo/rules/目录将打包的规则文件写入hindsight-memory.md。两个步骤都是幂等的——重复执行不会报错、不会产生重复条目可安全地用于更新 API 地址或重新安装。run_install会打印目标 API URL 与 Roo 配置目录便于确认安装落点。对 CLI 行为的端到端验证位于 test_cli.py 与 test_smoke.py测试通过临时目录模拟项目验证了从命令行参数到磁盘文件的完整链路。如需在本地运行测试可进入 hindsight-integrations/roo-code 目录执行uv sync uv run pytest tests/ -v小结Hindsight × Roo Code 集成用最轻量的方式一个 Python 包 一次安装命令解决了 AI 编程助手最棘手的会话失忆问题recall让每次任务站在历史记忆的肩膀上开始retain让每次任务的沉淀自动汇入记忆库而.roo/mcp.json与规则文件的组合则把这一切变成了 Roo Code 的默认行为。无论是使用 Hindsight Cloud 开箱即用还是通过--api-url指向自托管实例这套方案都能在不改动 Roo Code 本体的情况下为项目注入可持续累积的长期记忆。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考