企业官网建设流程全解析

Hindsight Agent Plugin：一个插件打通 ChatGPT、Cursor 与 Copilot 的可移植长期记忆

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

导读

本文讲解 Hindsight 如何通过 Agent Plugins 开放标准，将自身的长期记忆能力打包成一个可移植插件，让 ChatGPT / Codex、Cursor、GitHub Copilot、Kiro、VS Code 等兼容客户端开箱即用。你将掌握该插件的目录结构与工作原理、两个核心环境变量的配置方式、recall/retain/reflect三类记忆工具的使用时机，以及自托管部署与常见故障排查方法，并了解仓库中真实的插件清单与校验脚本。

Agent Plugins：一次打包、处处加载的行业标准

Agent Plugins 是一个由 Amazon、Cursor、Microsoft、OpenAI 与 Vercel 等厂商共同参与的厂商中立开放标准，核心是把Agent Skills + MCP 服务器封装为单一可分发插件。对集成方而言，其价值在于"一次打包，多处加载"：客户端不再需要为每个工具单独做一套集成，只要遵循该标准即可加载同一个插件产物。

Hindsight 正是基于这一思路，在 hindsight-integrations/agent-plugin 目录下提供了标准的1.0.0布局插件。插件本身是纯传输层薄封装——所有记忆逻辑（检索、存储、推理）都留在 Hindsight 服务端执行，客户端只负责通过 MCP 协议把请求转发过去。这意味着插件在不同客户端上的行为完全一致，任何兼容 Agent Plugins 的客户端都能获得与原生集成相同质量的记忆能力。

快速开始：三步接入

官方推荐使用Hindsight Cloud作为后端，免去自托管与本地守护进程的维护成本：

1. 在ui.hindsight.vectorize.io/connect注册并获取hsk_...形式的 API Key；

2. 设置插件读取的两个环境变量：

   export HINDSIGHT_API_KEY="hsk_your_token" export HINDSIGHT_BANK_ID="my-project" # 可选，默认 "default"

3. 在客户端中安装插件——通过客户端的插件 / MCP 界面指向插件目录即可（具体安装方式由标准交给各客户端自行实现）。

安装完成后，只需向 Agent 提出一个依赖历史上下文的问题，或告知一个长期偏好，Agent 就会在随插件捆绑的 SKILL 引导下自动调用recall与retain，实现跨会话记忆。

插件内部结构拆解

仓库中的真实插件目录结构如下：

hindsight-integrations/agent-plugin/ ├── plugin.json # 插件清单（$schema + name + metadata） ├── mcp.json # Hindsight MCP 服务器声明（Streamable HTTP） ├── skills/ │ └── hindsight-memory/ │ └── SKILL.md # 教会 Agent 何时 recall / retain / reflect └── validate.py # 清单结构校验脚本

各文件职责：

• plugin.json：插件清单，声明$schema、名称、版本、作者、关键词及扩展元数据。仓库中的真实清单（plugin.json）声明插件名为hindsight、版本1.0.0、协议为 MIT，并在extensions字段中补充了 bank 选择、自托管指向与深度集成入口的说明；
• mcp.json：声明名为hindsight的 MCP 服务器，类型为streamable-http，默认指向https://api.hindsight.vectorize.io/mcp，并把两个环境变量插值进请求头（见下文"配置"）；
• skills/hindsight-memory/SKILL.md：随插件加载进 Agent 上下文，让 Agent 不仅知道"有哪些工具"，更知道何时该用记忆工具；
• validate.py：本地校验脚本，用于确认两个清单与技能文件满足 Agent Plugins1.0.0必填字段契约。

清单校验：如何确认插件合法

仓库提供了可直接运行的校验脚本：

python3 hindsight-integrations/agent-plugin/validate.py

从源码（validate.py）可以看到校验覆盖三个维度：plugin.json的$schema指向1.0.0的 plugin schema、name满足小写字母数字与点横线的命名模式、extensions命名空间必须是反向域名；mcp.json必须有非空的mcpServers，服务器type只能是stdio/streamable-http/sse三者之一且 HTTP 类型必须带url；skills/下至少存在一个SKILL.md，且必须带包含name与description的 YAML frontmatter。该脚本同时以 pytest 测试形式供 CI 复用，是集成方修改清单后的第一道自检。

配置：两个环境变量决定一切

插件仅读取两个环境变量，并被插值进mcp.json的请求头：

仓库中 mcp.json 的真实内容印证了这一点：

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "hindsight": { "type": "streamable-http", "url": "https://api.hindsight.vectorize.io/mcp", "headers": { "Authorization": "Bearer ${HINDSIGHT_API_KEY}", "X-Bank-Id": "${HINDSIGHT_BANK_ID}" } } } }

需要注意两点：

• 环境变量插值语法因客户端而异：多数客户端支持${VAR}，但 VS Code、Cursor 等使用${env:VAR}。若你的客户端不支持插值，直接把字面 Key 与 bank id 粘贴进mcp.json即可；
• 自托管场景：将mcp.json中的 host（默认https://api.hindsight.vectorize.io）替换为你自己的部署地址。若本地服务的 MCP 端点未开启鉴权，则无需 API Key——mcp_local.py 展示了本地模式通过hindsight-local-mcp入口启动、默认监听localhost:8888的用法。

服务端对应的 MCP 配置项

插件侧只负责"连过去"，服务端行为由 Hindsight API 控制，相关环境变量（见 config.py）：

• HINDSIGHT_API_MCP_ENABLED：MCP 服务器默认启用并挂在/mcp路径上，设为false可关闭；
• HINDSIGHT_MCP_BANK_ID：bank 解析的兜底默认值（默认default）；
• HINDSIGHT_API_MCP_INSTRUCTIONS：向retain/recall工具描述中追加部署级指引，例如要求使用特定 tag 规范。

bank 的解析优先级为：URL 路径中的bank_id>X-Bank-Id请求头 >HINDSIGHT_MCP_BANK_ID环境变量，这一逻辑在 mcp.py 中有对应实现。

记忆工具：recall / retain / reflect 三件套

通过 MCP 服务器，Agent 获得 Hindsight 完整的记忆能力面。插件文档重点介绍最常用的三个工具：

附带的 SKILL 如何指导 Agent

捆绑技能文件（SKILL.md）给出了具体的触发规则：

• recall：任务开始，或用户提及先前的工作、既定决策、"我们搭的那个东西"、可能已记录在案的偏好时，先调用recall再作答；检索无结果时应如实说明，而不是编造连续性；
• retain：学到"持久且可复用"的事实时写入，例如稳定的用户偏好（"偏好 pnpm，只从main分支部署"）、项目事实与决策（"staging 数据库是 Neon 上的 Postgres 16"）、结论与踩坑记录（"那个 flaky 测试是时区 bug，已在 #482 修复"）。不要记录临时闲聊、密钥或用户明确要求排除的内容——存事实而非整段转录；
• reflect：当需要综合多段记忆做出判断时使用，例如"是什么反复导致我们的 CI flaky，我们应该统一什么？"。reflect更慢且具备 disposition（性情）感知，应谨慎使用而非用于简单查询。

此外，knowledge pages（知识页）、mental models（心智模型）、documents（文档）、tags（标签）等更多工具同样通过 MCP 暴露，完整清单与参数说明见 MCP Server 参考。服务端通过 mcp_tools.py 注册全部工具，并支持用HINDSIGHT_API_MCP_ENABLED_TOOLS按 bank 做工具白名单过滤。

显式工具 vs 自动捕获

Agent Plugins1.0.0标准化的是Skills + MCP，并不包含会话生命周期钩子。因此本插件提供的是显式、由工具驱动的记忆方式：Agent 在 SKILL 引导下主动调用记忆工具，行为在全部受支持的客户端上完全一致。

如果需要全自动体验——每次提示前自动注入 recall、会话结束时自动 retain 转录——则应使用针对特定工具的原生钩子式集成，例如 Claude Code 或 Codex 的专用集成。两者共享同一批 Hindsight bank：钩子式集成写入的记忆可以通过 Agent Plugin 被召回，反之亦然，两者互补而非互斥。

故障排查

• 没有召回任何记忆：recall只有在已有内容被 retain 之后才会返回结果。先 retain 一条事实，或通过 API 快速开始 为 bank 播种数据；
• 401 Unauthorized：确认HINDSIGHT_API_KEY已设置，且客户端确实将其插值进了Authorization头（回顾上文的环境变量语法差异）；
• 记忆内容错误或为空：确认HINDSIGHT_BANK_ID指向了期望的 bank。不同工具写入不同 bank 时，彼此之间不会共享记忆。

结语

Hindsight 的 Agent Plugin 是"标准先行"思路的典型落地：用一份符合 Agent Plugins1.0.0的清单 + 技能包，替代了 N 套手写集成。它保留了与原生 IDE 集成相同的retain/recall/reflect记忆能力，同时让记忆逻辑完全留在服务端，客户端仅做传输。对于希望以最低成本在多个 AI 客户端间获得一致长期记忆的团队，这是最直接的入口。

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