Hindsight 接入 GitHub CopilotVS Code基于 MCP 的长期记忆集成hindsight-copilot实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读hindsight-copilot是 Hindsight 项目为 GitHub CopilotVS Code 版本提供的官方集成一条命令即可把 Hindsight 的MCPModel Context Protocol服务器接入 VS Code 的.vscode/mcp.json并把一条recall / retain 规则写入.github/copilot-instructions.md让 Copilot 的 Agent 模式在任务开始时自动回忆相关记忆、在工作中沉淀持久事实。本文基于该集成在仓库中的源码、README 与测试完整讲解安装初始化、配置层级、三个 CLI 命令的用法并深入分析其背后的实现原理帮助你在 Cloud 与自托管两种场景下快速落地。版本依据hindsight-copilot当前版本为 0.1.0见 pyproject.toml集成源码位于 hindsight-integrations/github-copilot其引入记录见 GitHub Copilot 集成变更日志。一、集成概览Copilot 如何获得 Hindsight 记忆hindsight-copilot的定位是配置型集成——它不做记忆运算本身只负责把 Hindsight 的 MCP 端点接进 VS Code并让 Copilot 知道该怎么用记忆工具。整个集成建立在 VS Code Copilot 支持的两个能力之上.vscode/mcp.json中的 MCP 服务器Copilot Agent 模式支持在此文件中声明 MCP 服务器且直接支持 HTTP 类型的服务器与请求头headers因此 Hindsight 的 MCP 端点可以零桥接直连无需本地代理进程。接入后Copilot Agent 模式即可使用 Hindsight 暴露的recall/retain/reflect等记忆工具。.github/copilot-instructions.mdVS Code Copilot 会对工作区内的每一次对话自动应用该文件中的指令。集成会把一条记忆使用规则写入其中指导 Copilot任务开始时先 recall、学到持久事实时 retain。一次hindsight-copilot init完成后最终产生的效果是Copilot 在 Agent 模式下既拥有记忆工具又知道如何主动使用它们——任务开头自动回忆相关决策与偏好工作过程中把值得跨会话记住的架构决策、用户偏好、约定等沉淀进 Hindsight 记忆库bank。记忆工具的底层实现位于 mcp_tools.py其中retain/recall/reflect分别通过_register_retain、_register_recall、_register_reflect注册见该文件第 590-600 行的按需注册逻辑。在 MCP 工具注解层面recall与reflect属于只读工具、retain属于写入工具见 mcp_tools.py 的_READ_ONLY_TOOLS集合这便于客户端对安全读取类操作进行分组与自动批准。二、安装与一键初始化2.1 安装集成以 PyPI 包hindsight-copilot发布依赖为空dependencies []见 pyproject.toml安装轻量pip install hindsight-copilot安装后即获得hindsight-copilot命令其入口在 pyproject.toml 中声明为hindsight_copilot.cli:main。2.2 初始化Cloud 场景进入目标项目目录后执行cd your-project hindsight-copilot init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-projectinit会完成两件事将servers中的hindsight条目合并进./.vscode/mcp.json文件不存在则新建将记忆规则写入./.github/copilot-instructions.md文件不存在则新建。完成后重新加载 VS Code在 Copilot Chat 中打开Agent 模式并从聊天的工具菜单中启动hindsight这个 MCP 服务器即可开始使用。2.3 初始化自托管场景若使用自托管的 Hindsight 服务通过--api-url指定地址即可开放的本机服务无需 tokenhindsight-copilot init --api-url http://localhost:8888 --bank-id my-project从源码结构看build_http_server只在设置了 token 时才附加Authorization: Bearer ...请求头未设置时生成的 MCP 条目只有type与url两个字段见 mcp_config.py对应的测试用例test_open_server_omits_headers也验证了这一行为见 test_mcp_config.py。2.4 两条安全兜底路径JSONC 兼容如果mcp.json中含有注释即 JSONC 格式标准库 JSON 解析器无法安全地往返改写init不会动你的文件而是打印出一段可粘贴的 JSON 片段由你手动合并--print-only任何时候都可以用hindsight-copilot init --print-only只打印 MCP 片段与规则文本、不写任何文件便于在 CI、审查或手动配置场景使用。三、配置详解三层优先级与全部参数3.1 配置层级后读取者生效配置解析逻辑位于 config.py采用内置默认值 → 用户配置文件 → 环境变量的覆盖顺序环境变量优先级最高。用户配置文件默认位于~/.hindsight/copilot.json键名为驼峰式{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: hsk_..., bankId: my-project }值得注意的实现细节当配置文件 JSON 解析失败如语法损坏时load_config会静默回退到其余层级不会导致 CLI 崩溃——对应测试test_malformed_file_falls_back见 test_config.py。3.2 配置项一览配置项环境变量默认值说明API URLHINDSIGHT_API_URLhttps://api.hindsight.vectorize.ioHindsight 服务地址自托管时改为http://localhost:8888API tokenHINDSIGHT_API_TOKEN无Cloud 必填用于 Cloud 鉴权映射为 MCP 请求头Authorization: Bearer tokenBank idHINDSIGHT_COPILOT_BANK_IDcopilot记忆库标识也是 MCP 端点 URL 的最后一个路径段3.3 CLI 参数init 子命令参数默认值说明--api-urlCloud 地址覆盖 Hindsight API URL--api-token无覆盖 API tokenCloud 场景--bank-idcopilot覆盖记忆库 ID--print-only关闭只打印配置与规则不写文件--mcp-path./.vscode/mcp.json自定义 MCP 配置文件路径--instructions-path./.github/copilot-instructions.md自定义指令文件路径--user-config-path~/.hindsight/copilot.json自定义用户配置文件路径隐藏参数从 cli.py 的_resolve_config实现看CLI 参数的优先级高于环境变量与配置文件init会在load_config解析完毕后用非空的命令行参数覆盖对应字段形成最终生效的CopilotConfig。四、命令手册init / status / uninstall命令功能hindsight-copilot init添加 MCP 服务器条目 recall/retain 规则hindsight-copilot status显示服务器与规则当前是否已配置hindsight-copilot uninstall移除服务器条目与规则4.1 status验证安装状态hindsight-copilot status输出示例MCP server in .vscode/mcp.json: installed Recall/retain rule in .github/copilot-instructions.md: installedstatus通过is_installed分别检查 MCP 配置中是否存在名为hindsight的服务器、指令文件中是否包含!-- HINDSIGHT:BEGIN --标记见 cli.py。4.2 uninstall干净地移除hindsight-copilot uninstall卸载逻辑同样具备安全性只删除servers中名为hindsight的条目保留mcp.json中其他 MCP 服务器与inputs等无关字段对应测试test_remove_only_our_entry见 test_mcp_config.py若servers删空则整体移除该键不影响其他顶层字段只删除指令文件中 Hindsight 标记块内的内容保留你自行编写的项目指令若指令文件仅剩规则块则删除整个文件对应测试test_clear_keeps_user_content与test_clear_deletes_if_only_block见 test_instructions.py若mcp.json为 JSONC 格式则提示你手动删除hindsight条目。五、原理深析三段式源码实现5.1 MCP 配置写入mcp_config.py端点 URL 构造mcp_endpoint_url(api_url, bank_id)将 bank_id 拼为 URL 的最后一个路径段即${api_url}/mcp/${bank_id}/。测试确认了尾斜杠会被规整rstrip(/)如http://localhost:8888/b得到http://localhost:8888/mcp/b/见 test_mcp_config.py。幂等写入apply_to_mcp对五种情况分别返回动作created/merged/unchanged/removed/manual文件不存在 → 新建created已是严格 JSON 且servers.hindsight与目标一致 → 不动unchanged已有其他内容 → 合并写入、保留无关字段merged对应测试test_merges_preserves_other_servers_and_inputs文件含注释无法用 stdlib JSON 解析 → 不改文件、返回待粘贴片段manual对应测试test_jsonc_returns_manual并验证原始文件内容分毫未动。最终 Cloud 场景生成的 MCP 条目形如{ servers: { hindsight: { type: http, url: https://api.hindsight.vectorize.io/mcp/my-project/, headers: { Authorization: Bearer hsk_... } } } }5.2 指令规则写入instructions.py规则全文即RULE_TEXT位于 instructions.py核心要点为任务开始时先调用recall加载相关决策、偏好与项目上下文再作答只取相关部分学到持久事实架构决策、用户偏好、约定、值得跨会话记住的内容时调用retain存储除非用户询问否则不在对话中提及记忆操作。实现上规则被包裹在!-- HINDSIGHT:BEGIN --…!-- HINDSIGHT:END --的 HTML 注释围栏中write_rule只替换自己的围栏块、把规则置于文件顶部并完整保留用户既有内容对应测试test_write_preserves_user_content_block_leads重复执行init不会产生重复块测试test_write_replaces_existing_block断言BEGIN_MARKER计数恒为 1clear_rule反向移除围栏块、保留用户内容。5.3 CLI 编排cli.pycli.py将上述两个模块编排成可测试的核心函数build_install(config, mcp_path, instructions_path)——先构造 HTTP 服务器条目再写入 MCP 配置、写入规则。测试test_writes_mcp_and_rule验证了端到端产物url为https://api.hindsight.vectorize.io/mcp/proj/、请求头为Bearer k、指令文件含HINDSIGHT:BEGIN见 test_cli.py。六、端到端验证与本地测试集成自带完整测试套件分为两档# 确定性测试不依赖外部服务PR/CI 常用 uv sync uv run pytest tests -v -m not requires_real_llm # 需要真实 Hindsight 服务的 MCP 端点端到端检查 uv run pytest tests -v -m requires_real_llm其中requires_real_llm标记的端到端测试见 test_e2e.py会按标准 MCP 协议走一遍完整握手initialize→notifications/initialized→tools/list并断言响应中出现recall与retain工具名从而验证Hindsight MCP 端点确实对 Copilot 暴露了记忆工具这一核心前提。该测试默认连http://localhost:8888可用HINDSIGHT_API_URL/HINDSIGHT_API_TOKEN环境变量指向远端本机 Hindsight 不可达时会自动跳过。七、常见问题与操作提示重新加载后工具不出现确保已重载 VS Code 窗口并在 Copilot Chat 的 Agent 模式下从工具菜单手动启动hindsightMCP 服务器随后可在hindsight-copilot status中确认配置落盘。mcp.json里有注释怎么办集成会拒绝改写并打印待粘贴片段或直接使用hindsight-copilot init --print-only获取完整片段手动合并即可。想换一个记忆库通过--bank-id指定或在~/.hindsight/copilot.json写入bankId由于 bank 是 MCP 端点 URL 的最后一段不同项目/团队可以用不同 bank 实现记忆隔离。只想查看配置不想落盘任何环境下执行hindsight-copilot init --print-only即可安全预览。卸载不干净uninstall只清理 Hindsight 自己的 MCP 条目与规则围栏其他 MCP 服务器与你的自定义指令均会保留。总结hindsight-copilot用一份 MCP 配置 一段指令规则的极简设计把 Hindsight 的持久记忆能力无缝接入 VS Code 的 Copilot Agent 工作流。其价值在于两层自动化一是让 Copilot拥有recall/retain/reflect记忆工具二是让 Copilot主动使用这些工具——任务开头自动回忆、过程中自动沉淀。配合status/uninstall/--print-only等命令与严格的 JSONC 安全兜底无论是 Hindsight Cloud 还是自托管服务都能在数分钟内完成接入并随时可逆。若需深入记忆工具的服务端实现可继续阅读 mcp_tools.py 中_register_recall、_register_retain、_register_reflect的注册逻辑。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考