使用 hindsight-zed 为 Zed 接入 Hindsight 长期记忆MCP 接线、规则注入与验证指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个会学习的 Agent 记忆系统它通过recall/retain/reflect三组 MCP 工具让 AI 助手在任务开始时召回相关记忆、在过程中沉淀持久事实从而摆脱每次对话都从零开始。本文以 官方指南 为骨架结合仓库中 hindsight-zed 集成实现 的源码完整讲解如何把 Zed 编辑器的 Agent Panel 接入 Hindsight MCP 服务器从安装、init接线、配置文件逐字段解析到命令级验证与常见坑位排查。读完你将掌握一套可复现的Zed Hindsight记忆增强方案并理解 MCP context server 与全局指令文件这两条接入路径的底层原理。快速上手指南如果你只想最快跑通按下面五步操作即可安装hindsight-zed见下文Step 1以仓库实现的 npm/npx 方式为准。运行hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory。重启 Zed 并打开 Agent Panel——hindsight服务器应显示绿点。全局指令规则会告诉 agent先recall再干活学到持久事实就retain。用新对话能想起旧对话存的事实来验证记忆确实生效。这一方案非常适合 Zed原因在于 Zed 虽然没有 pre-prompt 钩子但它支持MCP context servers和全局指令文件global instructions file两处扩展点。集成正好各用其一在settings.json的context_servers中注册 Hindsight MCP 服务器给 agent 暴露recall/retain/reflect工具同时在~/.config/zed/AGENTS.md中追加一条先召回、后保留的规则。由于召回发生在查询时query time、针对你当前的真实消息执行因此没有延迟从使用者视角看完全是自动的。前置条件开始之前请确认环境满足Zed 已安装且带 AI assistant / Agent Panel 功能Node.js 已安装——Zed 目前还没有原生 HTTP-MCP 传输MCP 服务器通过mcp-remotestdio 桥经npx运行连接而hindsight-zed本身也是 Node CLI所以 Node.js 是唯一硬性依赖仓库package.json声明engines.node 18.3.0见 package.json一个可达的 Hindsight 后端Hindsight Cloud或自托管服务器本地起在http://localhost:8888的开放实例无需 token。Step 1安装 hindsight-zed官方指南最初给出的是 pip 安装方式pip install hindsight-zed需要说明的是当前仓库中hindsight-zed的实现是一个Node.js CLInpm 包vectorize-io/hindsight-zed零依赖、无构建步骤package.json中scripts.build仅为占位说明见 package.json因此以仓库实际实现为准推荐以下两种安装方式。方式一直接用 npx 运行无需全局安装npx vectorize-io/hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory方式二全局安装为常驻命令npm install -g vectorize-io/hindsight-zed hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memoryhindsight-zed是一个纯配置型CLI它不改动 Zed 的任何工作方式只做两件事——把 Agent Panel 接到 Hindsight MCP 服务器、写入一条 recall/retain 规则。正如 cli.js 顶部注释所述There is no background process——集成没有常驻后台进程记忆操作全部在运行时经由 MCP 工具完成。Step 2用 init 把 Zed 接到 Hindsight运行init传入你的 Hindsight API key 和要使用的 bankhindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memoryinit会做三件事对应 cli.js 中的 buildInstall 与 cmdInit把hindsightMCP 服务器写入~/.config/zed/settings.json的context_servers把 recall/retain 规则写入~/.config/zed/AGENTS.md把连接参数持久化到~/.hindsight/zed.json供重跑时复用见 scaffoldConfig。完成后重启 Zed、打开 Agent Panelhindsight服务器应显示绿点。自托管场景用--api-url指向你自己的服务器即可hindsight-zed init --api-url http://localhost:8888 --bank-id my-memory开放的本地服务器不需要 token。从源码看token 为空时buildContextServer会直接省略Authorization请求头见 zedSettings.js。JSONC 保护机制Zed 的settings.json是 JSONC 格式允许注释与尾逗号严格的 JSON 解析器无法在保留用户注释的前提下安全回写。因此init在检测到文件无法按严格 JSON 解析时绝不重写文件而是打印出精确的context_servers片段让你手动粘贴对应 applyToSettings 返回的action: manual。任何时刻想只看不写运行hindsight-zed init --print-only--print-only会把settings.json片段和AGENTS.md规则一并打印到 stdout 且不写任何文件——这一点由测试 init --print-only writes nothing 明确验证断言两个文件均未创建。Step 3用 status 确认接线结果hindsight-zed status该命令分别检查 MCP 服务器与规则是否已配置见 cmdStatus。可用命令一览命令说明hindsight-zed init添加 MCP 服务器 recall/retain 规则hindsight-zed status显示服务器 规则是否已配置hindsight-zed uninstall移除服务器 规则hindsight-zed init --print-only仅打印待手动添加的配置片段未全局安装时以上命令前均需加npx前缀。uninstall会从settings.json删除context_servers.hindsight条目、并从AGENTS.md移除规则块若规则块删空后文件无其他内容文件本身会被删除见 clearRule。集成原理两条 Zed 扩展点 mcp-remote 桥Zed 没有 pre-prompt 钩子所以集成工作在 Zed 实际暴露的两个扩展点上MCP context serversZed 会运行settings.json中context_servers下配置的 MCP 服务器并在 Agent Panel 中暴露其工具。hindsight-zed在此注册 Hindsight MCP 服务器从而让 agent 获得recall/retain/reflect三个工具。这三个工具正是 Hindsight 后端 MCP 服务在 mcp_tools.py 中登记的核心工具集并在 L590-L599 按需条件注册。因为 Zed 尚无原生 HTTP-MCP 传输服务器通过mcp-remotestdio 桥npx运行接入——这就是 Node.js 成为必需依赖的原因。全局指令文件~/.config/zed/AGENTS.mdZed 会把该文件纳入每一次对话。集成在这里追加一条短规则置于围栏!-- HINDSIGHT:BEGIN -- … !-- HINDSIGHT:END --块内不触碰文件中用户自己的其他规则见 rulesFile.js 的 writeRule先剥离旧块、再置顶写入新块。规则内容源码 RULE_TEXT为You have persistent long-term memory through the Hindsight MCP server (recall, retain, and reflect tools). - At the start of each task, call recall with the users request to load relevant decisions, preferences, and project context before you answer. Use whats relevant and ignore the rest. - When you learn a durable fact — an architectural decision, a user preference, a convention, or anything worth remembering across sessions — call retain to store it. - Do not mention these memory operations unless the user asks about them.工作流recall/retain经由 agent 调用的 MCP 工具执行由常驻规则引导。这使得召回在查询时精确执行——针对你的真实消息、零延迟代价是它依赖 agent 遵循先 recall的指令而非编辑器强制。如果你想深入底层行为仓库中 Hindsight MCP 服务端实现 是完整的参考实现。配置文件逐字段解析~/.config/zed/settings.jsoninit写入或指导你粘贴的context_servers片段Cloud 场景为{ context_servers: { hindsight: { source: custom, command: npx, args: [ -y, mcp-remote, https://api.hindsight.vectorize.io/mcp/my-memory/, --header, Authorization: Bearer YOUR_HINDSIGHT_API_KEY, ], }, }, }字段与生成逻辑对应关系如下见 zedSettings.jssource: custom、command: npx以自定义命令方式启动 MCP 服务器MCP 端点 URL 由mcpEndpointUrl(apiUrl, bankId)拼接apiUrl/mcp/bankId/——bank 是 URL 的最后一段例如默认 Cloud 地址 my-memory即得https://api.hindsight.vectorize.io/mcp/my-memory/设置了 token 时追加--header Authorization: Bearer token本地开放服务器则省略该参数若settings.json已存在同名 server 且完全一致applyToSettings返回unchanged不会重复写入L95-L97。~/.config/zed/AGENTS.md写入规则块!-- HINDSIGHT:BEGIN --起、!-- HINDSIGHT:END --止置于文件顶部升级或卸载时只重写该围栏块用户自己的规则原样保留。连接配置的优先级hindsight-zed的配置按后者覆盖前者分层解析见 config.js内置默认值 →~/.hindsight/zed.json由 init 写入→ 环境变量 → CLI 显式参数。核心项配置项环境变量默认值API URLHINDSIGHT_API_URLhttps://api.hindsight.vectorize.ioAPI tokenHINDSIGHT_API_TOKEN无Cloud 必需Bank idHINDSIGHT_ZED_BANK_IDzedCLI 参数优先级最高任何情况下--api-url/--api-token/--bank-id都会覆盖文件与环境变量见 resolveConfig。验证记忆确实在工作推荐按以下顺序验证运行hindsight-zed status确认服务器与规则均已配置在 Zed 中打开 Agent Panel确认hindsight服务器显示绿点在对话一中告诉 agent 一个持久事实或约定并让它 retain新开一个对话对话二向对话二询问之前的事实。例如对话一确立一条 auth 约定并要求 agent 记住它对话二询问当前项目的 auth 约定是什么。如果对话二的 agent 能召回对话一存入的事实说明整条链路MCP 工具 常驻规则 Hindsight 后端已经打通。这套交互行为同样被仓库测试覆盖cli.test.js 验证了init后 settings.json 中出现npx命令、mcp-remote、/mcp/proj/端点与 Bearer tokenAGENTS.md 中出现规则标记zed.json中持久化了 bank 与 token。常见错误排查Node.js 未安装MCP 服务器经由mcp-remotestdio 桥npx运行启动因此 Node.js 必须可用否则hindsight服务器无法连接。init甚至会主动检测npx是否在 PATH 上缺失时打印警告见 commandExists 检查。手改 JSONC settings 文件如果settings.json含注释init不会重写它而是打印待粘贴片段。粘贴该片段或随时运行hindsight-zed init --print-only重新查看。忘记重启 Zed服务器与规则在重启后才被 Zed 拾取。若绿点未出现重启 Zed 并重新打开 Agent Panel。误以为编辑器会强制召回召回依赖 agent 遵循常驻的先 recall规则而非编辑器强制执行。如果某次任务没有召回直接提醒 agent 先 recall 即可。FAQ必须用 Hindsight Cloud 吗不需要。自托管服务器同样可行——用--api-url http://localhost:8888指向即可开放的本地服务器无需 token。这会影响我原有的 Zed 使用方式吗不会。集成只接线 Agent Panel 与 Hindsight MCP 服务器、添加一条规则你仍以原有方式使用 Zed 的 AI assistant。记忆的作用域如何划分按 bank 划分。在init时通过--bank-id指定默认 bank id 为zed。不同 bank 的记忆彼此隔离MCP 端点 URL 中的最后一段路径就是 bank。与其他 coding-agent 集成类似吗精神上一致。Zed 用的是 MCP context servers 全局指令文件而非 wrapper 或 hook但任务前 recall / 任务后 retain的模式与仓库中其他 coding-agent 集成如 claude-code、codex 等见 hindsight-integrations完全相同。进一步阅读本集成的完整 README 与命令说明hindsight-integrations/zed/README.mdCLI 入口与命令实现hindsight-integrations/zed/src/cli.jsZed settings 的读写与 mcp-remote 拼接逻辑hindsight-integrations/zed/src/zedSettings.js全局指令规则块的写入/清理hindsight-integrations/zed/src/rulesFile.js配置分层解析hindsight-integrations/zed/src/config.js集成行为测试hindsight-integrations/zed/test/cli.test.jsHindsight 后端 MCP 服务中recall/retain/reflect工具的实现hindsight-api-slim/hindsight_api/mcp_tools.py若使用 Hindsight Cloud可直接从 Cloud 控制台获取 API key若自托管参照仓库中 hindsight-api 服务 或 docker-compose 部署示例 启动后端后以--api-url指向对应地址即可。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考