企业官网建设流程全解析

Hindsight 集成 GitHub Copilot：为 VS Code Agent 接入持久化长期记忆

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

导读：本文围绕 Hindsight 仓库中hindsight-integrations/github-copilot这一官方集成，完整讲解如何让 GitHub Copilot（VS Code）的 Agent 模式通过 Hindsight MCP 服务器获得recall/retain/reflect记忆工具：从安装初始化、mcp.json与copilot-instructions.md的自动接线原理，到配置优先级、命令参数、自托管与 Cloud 两种接入方式，再到源码级实现与测试验证。读完本文，你可以在一分钟内让 Copilot 在任务开始时自动回忆相关项目记忆、并在工作中持久化沉淀事实。

Hindsight 为 AI Agent 提供"会学习"的长期记忆层。hindsight-copilot是它的官方 GitHub Copilot 集成包：一个纯配置型（configuration-only）的接线工具，不介入任何运行时推理，只负责把 Hindsight MCP 服务器写进 VS Code 的.vscode/mcp.json，并在.github/copilot-instructions.md中写入一条"先回忆、再沉淀"的规则，让 Copilot 的 Agent 模式自动使用 Hindsight 的记忆能力。完整源码位于 hindsight-integrations/github-copilot，对应实现见 hindsight_copilot/。

工作原理：两个 VS Code Copilot 原生机制

该集成依赖 VS Code Copilot 已支持的两项能力，因此不需要任何桥接进程或代理：

1. MCP 服务器（HTTP 类型）：VS Code Copilot 的 Agent 模式从.vscode/mcp.json的servers键读取 MCP 服务器配置，且原生支持type: "http"的远程 HTTP MCP 端点并允许携带请求头。Hindsight MCP 端点因此可以直接连接，例如：

{ "servers": { "hindsight": { "type": "http", "url": "https://api.hindsight.vectorize.io/mcp/my-project/", "headers": { "Authorization": "Bearer hsk_..." } } } }

2. .github/copilot-instructions.md：Copilot 会把该文件作为工作区级别的"项目说明"应用到每一次聊天请求中。集成把"回忆/沉淀规则"写在这里，从而让 Copilot 在 Agent 模式下自动使用记忆工具，而无需用户每次手动调用。

从源码看，MCP 端点的拼装逻辑集中在 mcp_config.py 的mcp_endpoint_url：

def mcp_endpoint_url(api_url: str, bank_id: str) -> str: """The Hindsight MCP endpoint for a bank (bank is the last path segment).""" return f"{api_url.rstrip('/')}/mcp/{bank_id}/"

即端点为<api_url>/mcp/<bank_id>/，bank_id 是端点 URL 的最后一个路径段，这决定了 MCP 服务器只会操作你所指定的那个记忆银行（memory bank）。相应的服务器条目由build_http_server生成：有 token 时输出headers（Authorization: Bearer <token>），无 token（开放的自托管服务器）时则完全省略headers字段。

安装与初始化

pip install hindsight-copilot cd your-project hindsight-copilot init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-project

init命令做两件事（实现见 cli.py 的build_install）：

• 把servers.hindsight条目合并进./.vscode/mcp.json（文件不存在则创建）；
• 把 recall/retain 规则写入./.github/copilot-instructions.md。

之后只需重载 VS Code，在 Copilot Chat 中切到Agent 模式，从聊天的工具菜单中启动hindsightMCP 服务器即可。build_install是本集成的"可测试核心"，test_cli.py 验证了它会同时写出 MCP 条目（URL 与 Bearer 头正确）以及带HINDSIGHT:BEGIN标记的规则文件。

选择 Cloud 还是自托管

• Hindsight Cloud：使用https://hindsight.vectorize.io生成的 API Key，必须通过--api-token（或环境变量 / 配置文件）提供，默认 API 地址为https://api.hindsight.vectorize.io；
• 自托管服务器：追加--api-url http://localhost:8888指向本地开放服务，此时无需 token（build_http_server 会省略认证头）。

关于mcp.json含注释（JSONC）的特别处理

VS Code 的.vscode/mcp.json允许 JSONC 注释，而 Python 标准库 JSON 解析器无法保留注释往返。因此集成采取了"绝不冒险动用户文件"的策略（见 mcp_config.py 的apply_to_mcp）：

• 文件是严格 JSON → 原地合并（created/merged/unchanged）；
• 文件含注释（无法按严格 JSON 解析）→ 返回manual，不改动原文件，仅在终端打印一段可直接粘贴的servers片段。

对应测试 test_mcp_config.py 明确断言：JSONC 场景下文件内容保持原样且snippet中包含hindsight条目。任何时刻你也可以用hindsight-copilot init --print-only只打印配置片段而不写入任何文件。

命令一览

init的完整参数

根据 cli.py 的参数定义，init支持：

status与uninstall同样支持--mcp-path/--instructions-path覆盖默认路径，便于在非标准目录的仓库或测试场景使用。test_cli.py 的test_init_status_uninstall演示了init → status → uninstall的完整生命周期：init 后服务器已安装，status 输出installed，uninstall 后服务器条目与规则文件均被移除。

uninstall的清理行为

remove_from_mcp只删除hindsight一个条目，保留其他服务器与文件中的其余键（如inputs）；若删除后servers为空，则会一并移除空的servers键。规则清理见 instructions.py 的clear_rule：仅剥离 Hindsight 的标记块，保留用户自写内容；若文件只剩标记块则整文件删除（对应测试 test_instructions.py）。JSONC 场景下同样走manual提示，由用户手动移除。

配置体系：文件、环境变量与 CLI 的优先级

集成支持三层配置，解析逻辑在 config.py 的load_config中实现，层级为"内置默认值 →~/.hindsight/copilot.json→ 环境变量 → CLI 参数"，后者覆盖前者。

• 用户配置文件位于~/.hindsight/copilot.json（常量USER_CONFIG_FILE，见 config.py），init首次运行时还会用当前解析结果自动脚手架出该文件（见 cli.py 的_scaffold_user_config）；
• 环境变量优先于文件：load_config先读文件、再读环境变量逐项覆盖；
• CLI 参数最优先：_resolve_config在load_config之后用--api-url/--api-token/--bank-id再次覆盖（见 cli.py）；
• 容错：配置文件损坏（JSON 解析失败）时静默回退到默认值，不阻断安装（test_config.py）。

写入的规则长什么样

init写入.github/copilot-instructions.md的规则原文定义于 instructions.py 的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 user's request to load relevant decisions, preferences, and project context before you answer. Use what's 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（架构决策、用户偏好、约定等跨会话值得记住的内容）、除非用户询问否则不提及记忆操作。

标记块：不打扰用户内容的写入策略

规则被包裹在<!-- HINDSIGHT:BEGIN -->…<!-- HINDSIGHT:END -->的 HTML 注释块中（常量见 instructions.py），这样集成可以精确替换或移除自己的内容而不干扰用户原有说明：

• write_rule保留文件原有内容，仅重写标记块，并把块置于文件顶部让记忆规则引领说明（instructions.py）；
• 重复init不会产生重复块（count(BEGIN_MARKER) == 1，见 test_instructions.py）；
• 规则文本中recall、retain、reflect三个工具名均有测试断言覆盖（test_instructions.py）。

端到端验证：MCP 端点确实暴露记忆工具

除确定性单元测试外，集成还提供了门控的端到端测试 test_e2e.py，用requires_real_llm标记隔离：

uv run pytest tests -v -m 'not requires_real_llm' # 确定性测试套件 uv run pytest tests -v -m requires_real_llm # 门控的 MCP 端点检查

e2e 测试会先探测<api_url>/health是否可达（默认http://localhost:8888，也可用HINDSIGHT_API_URL/HINDSIGHT_API_TOKEN覆盖），然后通过urllib发起标准 MCP JSON-RPC 握手（initialize→notifications/initialized→tools/list），断言返回的tools/list中确实包含recall与retain——这从协议层验证了"Copilot 在 Agent 模式下能拿到 Hindsight 记忆工具"这一核心链路。

小结

hindsight-copilot的接入成本极低：一条pip install、一条init，Copilot 的 Agent 模式便自动获得跨会话的持久记忆能力。其实现哲学是"纯配置接线"——运行时记忆操作全部经由 Hindsight MCP 服务器完成，本地工具只负责安全地生成配置与规则，并通过 JSONC 探测、标记块、三层配置优先级等设计保证了不破坏用户既有配置。相关实现与测试均可直接在仓库中查阅：

• 包入口与 CLI：hindsight_copilot/cli.py
• 配置解析：hindsight_copilot/config.py
• MCP 配置读写：hindsight_copilot/mcp_config.py
• 规则写入：hindsight_copilot/instructions.py
• 测试：tests/
• 打包与入口点声明：pyproject.toml

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