企业官网建设流程全解析

Zed 编辑器 AI 助手接入 Hindsight 持久记忆：hindsight-zed 完整实战指南

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Zed 是一款以 Rust 构建的高性能编辑器，其 Agent Panel 内置的 AI 助手在单个任务内表现出色，却在会话之间彻底失忆。本文基于 Hindsight 开源仓库中的hindsight-zed集成（hindsight-integrations/zed/README.md），系统讲解如何用一条命令为 Zed 的 Agent 接入跨会话的持久记忆：通过 MCP 提供recall、retain、reflect三个工具，并结合全局指令文件实现"先回忆、后沉淀"的自动化记忆闭环。读完本文，你将掌握完整的安装配置、命令用法、底层实现原理与排错思路。

问题本质：出色的助手，却没有"昨天"

大多数编码 Agent 都面临同一个问题：关闭面板、第二天开启新对话后，它完全不记得这个仓库用的是 pnpm、你上周刚确定的仓储（repository）模式、以及你习惯把测试文件和源码放在一起这些约定。模型本身能力不差，缺的只是连续性——于是每次新会话，你都要重新解释技术栈、重申约定、再次讨论已经拍板的决策。你成了那个替 Agent 记事的"人肉内存"。

持久记忆的意义正在于此：你告诉过 Agent 的事、Agent 自己推敲出来的结论，在下一次会话中依然存在。这正是把"按会话工作的工具"变成"真正懂你项目的助手"的关键一步。

原理解析：Zed 没有 pre-prompt，但有两个可用构件

Zed 没有暴露 pre-prompt 钩子，因此无法在每轮对话前自动注入上下文。但hindsight-zed巧妙地利用了 Zed 提供的两个构件（源码见 hindsight-integrations/zed/src/zedSettings.js 与 hindsight-integrations/zed/src/rulesFile.js）：

其一：MCP context servers。Zed 会运行settings.json中context_servers字段声明的 MCP 服务器，并将其工具暴露给 Agent Panel。hindsight-zed把 Hindsight MCP 服务器注册到这里，为 Agent 提供recall、retain、reflect三个工具。

其二：全局指令文件。Zed 会在每一次 Agent 对话中都引入~/.config/zed/AGENTS.md。集成工具把一条简短规则写入该文件，且严格包裹在<!-- HINDSIGHT:BEGIN -->与<!-- HINDSIGHT:END -->围栏块内（见 rulesFile.js 中BEGIN_MARKER/END_MARKER/RULE_TEXT的定义），绝不触碰你自己的规则。规则内容为：每次任务开始时调用recall加载相关的决策、偏好与项目上下文；每当学到值得跨会话记住的持久事实（架构决策、用户偏好、约定等）就调用retain存储。

查询时回忆，零滞后

这样设计带来的结果是：回忆发生在查询时（query time），直接针对你真正发送的消息执行。它不像定时任务那样在固定时间点运行，而是当你提问时按需检索，因此能拉取与当前请求最相关的记忆。从你的视角看，这一切是自动的：你输入，Agent 静默查一次记忆，然后作答。

传输层说明：为什么只需要 Node.js

Zed 目前尚未内置 HTTP MCP 传输能力，因此服务器通过mcp-remote这个 stdio 桥接器（经npx运行）连接。由于桥接器运行在 Node.js 上，而设置 CLI 本身也是 Node 工具，所以Node.js 是唯一的环境要求——不需要 Python（cli.js 中还会在init时检测npx是否在 PATH 上并给出提示）。

安装与快速开始

hindsight-zed是零依赖的 Node CLI，直接通过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-memory

init会在~/.config/zed/settings.json中加入hindsightMCP 服务器，并向~/.config/zed/AGENTS.md写入 recall/retain 规则。之后重启 Zed、打开 Agent Panel，hindsight服务器应显示绿色圆点——整个配置即告完成。

整个设置的底层形态如下（这也是init实际写入settings.json的内容，完整构建逻辑见 buildContextServer）：

{ "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" ] } } }

注意几点实现细节：

• bank 会作为 URL 最后一段路径：mcpEndpointUrl会把 base URL 末尾的斜杠归一化后拼出/mcp/<bankId>/（见 zedSettings.js），并有对应单元测试覆盖（见 test/zedSettings.test.js）。
• 未设置 token 时不添加--header：自托管开放服务器无需令牌，buildContextServer只在有 token 时才追加 Bearer 头（test/zedSettings.test.js 对两种情形都有断言）。
• JSONC 保护机制：如果settings.json含注释（JSONC），init不会重写文件，而是打印出完整的context_servers条目供你手动粘贴。任何时候想再查看该片段，可执行hindsight-zed init --print-only。这一"宁可交给用户手动粘贴，也不冒险破坏配置"的设计，对应applyToSettings返回的manual动作分支（zedSettings.js）。
• 幂等合并：重复运行init时，若配置已一致会报告unchanged，换 bank 时会merged合并而不会清掉settings.json中其他键（测试覆盖见 test/zedSettings.test.js）。

命令速查

若未全局安装，请为以上命令统一加上npx前缀。命令分发逻辑见 cli.js，其中init支持的全部参数（--api-url、--api-token、--bank-id、--print-only及测试/高级场景用的--settings-path、--rules-path、--config-path）都在OPTIONS中声明（cli.js）。

uninstall时同样遵守 JSONC 保护：若settings.json含注释会提示你手动删除hindsight条目；AGENTS.md中的规则块则通过clearRule精确移除，若移除后文件为空会被删除（rulesFile.js）。

云服务还是自托管

Hindsight Cloud：从控制台获取 API key 传入即可。API URL 默认是https://api.hindsight.vectorize.io，无需额外设置。

自托管服务器：用--api-url指向自己的地址，例如：

hindsight-zed init --api-url http://localhost:8888 --bank-id my-memory

开放的本地服务器不需要 token。

配置解析优先级

配置按"内置默认值 →~/.hindsight/zed.json（由init写入）→ 环境变量 → CLI 参数"的优先级解析，后者覆盖前者（实现见 config.js，CLI 参数覆盖见 cli.js）：

~/.hindsight/zed.json的键名与上述属性一一对应（hindsightApiUrl、hindsightApiToken、bankId），映射关系见 config.js。

关于 bank：一套记忆，所有工具共享

bank 是一个隔离的存储空间。让 Zed 和其他工具指向同一个 bank id，它们就共享同一份记忆——这正是"one memory for every AI tool"（对应文档见 hindsight-docs/blog/2026-04-07-one-memory-for-every-ai-tool.md）的理念。在服务端，bank 对应一组独立的 HTTP 路由：recall、retain、reflect分别映射到/banks/{bank_id}/memories/recall/、/banks/{bank_id}/memories/与/banks/{bank_id}/reflect/（路由注册见 hindsight-api-slim/hindsight_api/api/http.py）。

验证记忆是否生效

在第一个会话中给 Agent 一个持久事实，例如："This repo uses pnpm, never npm."（这个仓库用 pnpm，绝不用 npm）。然后新开一个会话，提出相关请求，比如"add the date-fns dependency"。具备记忆能力的 Agent 会在回答前通过recall检索到这条约定，无需你提醒就自动使用 pnpm——因为该事实已被retain存入 Hindsight，并在新的请求中被recall命中。

你也可以从另一侧观察验证：打开你的 Hindsight bank，第一个会话结束后，就能看到这条约定已作为一条存储记忆出现。

更完整的验证流程（与官方指南 hindsight-docs/guides/2026-07-17-guide-zed-memory-with-hindsight.md 一致）：

1. 运行hindsight-zed status确认服务器与规则均已配置；
2. 打开 Zed Agent Panel，确认hindsight服务器显示绿点；
3. 在会话一中告诉 Agent 一条约定/事实，让它 retain；
4. 新开会话二；
5. 就此前的事实提问，观察 Agent 能否 recall 到。

三个 MCP 工具的分工

• recall：查询时检索。以你当前的消息为输入，拉取相关的决策、偏好与项目上下文。对应服务端路由/banks/{bank_id}/memories/recall/（http.py）。
• retain：写入沉淀。Agent 学到值得跨会话保留的持久事实时调用。对应POST /banks/{bank_id}/memories/（http.py）。
• reflect：归纳整合。Agent 可调用它对自己已存储的记忆进行整合与推理，使记忆随着积累不断改善，而不是沦为平铺直叙的笔记堆。对应POST /banks/{bank_id}/reflect/（http.py）。

常见问题

Agent 会自动 recall 吗？recall 是 Agent 主动调用的工具，全局规则会指示它在每个任务开始时调用。因此实际使用中它是自动执行的；又因为发生在查询时，它会用你真实的输入去检索相关记忆。

需要安装什么？只需要 Node.js（18.3 或更新版本，见 package.json 的engines字段）。hindsight-zed是零依赖 Node CLI，Zed 的 MCP 桥接器mcp-remote也通过npx在 Node 上运行，无需 Python。

会覆盖我的 Zed 配置吗？不会。规则位于AGENTS.md中围栏的HINDSIGHT块内，init不触碰其余内容；若settings.json含注释，init改为打印片段而非重写文件。

reflect是做什么的？与recall、retain并列，Agent 可调用reflect对已存储内容做整合归纳，让记忆随积累而进化，而不是变成一摞扁平的笔记。

常见坑（来自官方指南的排错清单）：

• Node.js 未安装：MCP 服务器经npx mcp-remote运行，Node 缺失则hindsight服务器无法连接（cli.js 会在init时检测并告警）。
• 编辑了 JSONC 的 settings 文件：含注释时init不重写，改用--print-only获取片段手动粘贴。
• 忘记重启 Zed：服务器与规则在重启后生效，绿点未出现请重启并重开 Agent Panel。
• 误以为编辑器会强制 recall：recall 依赖 Agent 遵循"先回忆"的常驻规则，而非编辑器强制。某次任务没 recall 时，提醒 Agent 回忆即可。

补充阅读

• Zed 集成的独立文档页：同一集成在官方文档站的版本，含"recall/retain 依赖 Agent 遵循规则而非编辑器强制"的权衡说明。
• Add Zed Memory with Hindsight 官方指南：逐步操作、验证流程与常见错误清单。
• Cursor persistent memory：同一思路在另一个 AI-first 编辑器上的实现（对应文档 hindsight-docs/blog/2026-06-12-cursor-persistent-memory.md）。
• One memory for every AI tool：让 Zed 与其他 Agent 指向同一 bank，共享一套记忆。
• 集成源码与测试：hindsight-integrations/zed/src 与 hindsight-integrations/zed/test（可用node --test运行测试套件）。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight