Hindsight Cursor 记忆插件版本演进解析从 0.1.0 到 0.2.0 的 Hooks 架构、MCP 集成与安装实践【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文围绕 Hindsight 官方 Cursor 集成hindsight-cursor的版本变更记录展开系统梳理 0.1.0 与 0.2.0 两个里程碑带来的核心能力基于 Cursor Plugin Hooks 的自动会话召回与自动留存、Cursor 原生的 always-on 规则与按需 skill、以及本地 daemon / 外部 API / 原生 MCP 三条集成路径。读完本文你将掌握该插件的安装初始化流程、Hook 事件驱动的记忆读写原理、全部配置项含义以及如何在当前仓库的源码与测试中验证其实现细节。该 changelog 原文位于 skills/hindsight-docs/references/changelog/integrations/cursor.md配套的完整使用文档见 Cursor 集成指南实现代码位于 hindsight-integrations/cursor/。版本演进总览一次 changelog 里的两段里程碑这个 changelog 很短只记录了两个版本但两代版本恰好勾勒出插件从实验性集成走向可发布包的完整路径版本定位关键变化0.1.0插件骨架成型引入 Cursor Plugin Hooks 自动召回/留存附带 always-on rule 与hindsight-recallskill支持本地 daemon、外部 API、原生 MCP 三种路径并配套自动化测试0.2.0官方发布形态以hindsight-cursor包形式正式发布提供init/uninstallCLI插件文件随 wheel 打包见 pyproject.toml 中[tool.hatch.build.targets.wheel.force-include]的打包清单从仓库元数据看当前 pyproject.toml 中version 0.2.0与 changelog 最新条目一致说明 0.2.0 即当前仓库所对应的发布版本。0.1.0 核心能力基于 Cursor Plugin Hooks 的自动记忆0.1.0 奠定了插件的核心架构用 Cursor 的 Hook 体系实现自动召回 自动留存用规则rule和技能skill提供 Cursor 原生形态的辅助入口。会话开始自动召回sessionStart插件把session_start.py注册到 Cursor 的sessionStart事件。该事件在每次新会话开始时触发一次插件会从 hook 输入stdin JSON读取workspace_roots、conversation_id、cwd解析 API 地址外部服务、已有本地服务或自动拉起 daemon推导 bank ID 并确保 bank mission 已设置以工作区上下文项目名 bank mission构造一个宽泛的项目级查询调用 Hindsight recall API把召回的记忆格式化为hindsight_memories上下文块注入给 agent。完整的执行流程见 scripts/session_start.py。该脚本始终以退出码 0 结束任何错误都优雅降级避免拖垮 Cursor 的会话启动。任务结束自动留存stop / sessionEnd 双事件插件把retain.py同时注册到stop与sessionEnd两个事件见 hooks/hooks.jsonstop在每次 agent 循环结束时触发是按轮次周期性留存的正确粒度sessionEnd在会话结束时触发一次作为最终冲刷final flush。两者缺一不可若只有stop默认retainEveryNTurns 10时一段只有 7 轮对话的会话会触发 7 次stop、被轮次闸门拒绝 7 次最终一条都不存sessionEnd绕过轮次窗口保证会话尾巴必然入库。而两个事件在会话末尾重叠插件通过retained.json记录每个会话已留存的 message 数watermark无新增内容时直接 no-op因此不会重复存储。这一设计的实现细节见 scripts/retain.py 与 cli.py 中_project_hooks_block()的注释。retain.py还能兼容 Cursor 3.x 的三种 transcript 形态扁平结构、type 嵌套结构、以及 Cursor 3.6.31 实际写入~/.cursor/projects/workspace/agent-transcripts/的 role 嵌套 类型化 content 块结构后者会通过_normalize_blocks_to_text()把text/tool_use/tool_result块压平成可识别的文本。双通道记忆投递additionalContext 与 rules 文件回退0.1.0 的一个关键技术决策是解决 CursorsessionStarthook 的additionalContext原生通道不可靠的问题。Cursor 3.x 中该通道存在已知竞态官方论坛已确认且直至 Cursor 3.6.31 仍未修复仅靠additionalContext会让召回的记忆永远到不了模型。插件的解决办法是双通道通道一原生前向兼容仍向 stdout 输出additionalContextJSON等 Cursor 修复上游 bug 后无需改代码即可走原生路径通道二rules 文件回退默认开启把召回记忆写入工作区的.cursor/rules/hindsight-session.mdcfrontmatter 带alwaysApply: true由 Cursor 的 rules 引擎可靠注入到 agent 上下文。由此带来几个可验证的行为每次sessionStart顶部都会先轮换删除上一会话生成的 rules 文件避免陈旧记忆残留该文件会被自动追加进.gitignore仅限 git 工作区手动删除也安全下次会话会自动重建。这些逻辑封装在 scripts/lib/rules_file.py 中。Cursor 原生的 always-on rule 与 on-demand skill0.1.0 附带了两件 Cursor 原生形态的外设always-on rulerules/hindsight-memory.mdc常驻规则指导 agent 利用hindsight_memories块中的会话记忆并在需要时调用 MCP 的recall/retain/reflect工具同时约定记忆与当前上下文冲突时以当前上下文为准。on-demand skillskills/hindsight-recall/SKILL.mdhindsight-recall技能定义触发条件用户询问历史决策、项目上下文、偏好等、工作流先检查上下文中的hindsight_memories不足时用 MCPrecall需要推理时用reflect以及护栏不向用户暴露原始记忆元数据。0.1.0 的三种集成路径Daemon、外部 API 与原生 MCP0.1.0 引入了三种互补的连接/集成方式0.2.0 的init命令将它们统一编排。1. 本地 daemon 模式auto-managed插件自动通过uvx启停hindsight-embedhindsight-embed是 Hindsight 的本地嵌入服务实现在 hindsight-embed/。该模式要求设置 LLM 提供方 API Key如OPENAI_API_KEY或ANTHROPIC_API_KEY由本地 daemon 完成事实抽取。daemon 生命周期启动/停止/健康检查封装在 scripts/lib/daemon.py空闲 300 秒daemonIdleTimeout自动回收。2. 外部 API 模式生产环境推荐直接连接已运行的 Hindsight 服务端云服务或自托管无需本地 LLM事实抽取由服务端完成{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }需要说明的是源码中默认hindsightApiUrl为空字符串且内置了托管后端地址https://api.hindsight.vectorize.io作为空值回退见 scripts/lib/config.py 的DEFAULT_HINDSIGHT_API_URL与useLocalDaemon注释若希望空 URL 时自动拉起本地 daemon可显式设置useLocalDaemon: true。3. 原生 MCP按需工具init会写.cursor/mcp.json把 Cursor 原生 MCP 指向 Hindsight 的单 bank 端点形如{api_url}/mcp/{bank_id}/从而为 agent 提供recall、retain、reflect三个显式工具用于会话中段需要超出会话开始注入范围时的定向查询。MCP 配置写入逻辑见 cli.py 的_setup_mcp()。三路对照维度Plugin Hooks自动MCP Tools按需安装pip install hindsight-cursor hindsight-cursor init由init自动配置.cursor/mcp.json召回会话开始经 rules 文件 /additionalContext注入agent 会话中调用recall工具留存任务结束stop/sessionEnd自动执行agent 显式调用retain工具反思hooks 不提供reflect工具可用适用场景无需人工干预的环境式项目记忆定向查询与显式记忆操作两者只需一条hindsight-cursor init命令即可同时就绪用--no-mcp可跳过 MCP 部分仅保留 hooks。0.2.0正式发布为可安装的 hindsight-cursor 包0.2.0 的意义在于把 0.1.0 的实验代码固化为可分发、可安装、可卸载的正式集成。插件文件通过 hatchling 的force-include机制随 wheel 打包为hindsight_cursor/plugin_data/见 pyproject.tomlCLI 在init时从中复制。安装与初始化pip install hindsight-cursor cd /path/to/your-project # 连接 Hindsight 云服务 hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN # 或连接本地 Hindsight 服务 hindsight-cursor init --api-url http://localhost:8888也可以直接用uvx hindsight-cursor init避免常驻安装。安装后必须完全退出并重新打开 Cursor——插件在启动时加载仅刷新窗口不够。本地起一个 Hindsight 服务端以官方 Docker 镜像为例配置值取自 Cursor 集成指南export OPENAI_API_KEYyour-key docker run --rm -it --pull always -p 8888:8888 \ -e HINDSIGHT_API_LLM_API_KEY$OPENAI_API_KEY \ -e HINDSIGHT_API_LLM_MODELgpt-4o-mini \ -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latestinit命令究竟做了什么对照 cli.py 的cmd_init()初始化共四步复制插件文件到.cursor-plugin/hindsight-memory/共 16 个文件包含 plugin.json、hooks.json、rule、全部脚本与 skill。复制前会校验打包载荷完整性任何缺失都直接报错退出——因为session_start.py导入每个lib/模块缺一个文件就会让每次 hook 调用变成静默 ImportError注册 hooks把sessionStart/stop/sessionEnd三个条目合并进项目.cursor/hooks.json。这是必需步骤——Cursor 只从工作区.cursor/hooks.json或用户级~/.cursor/hooks.json加载 hooks.cursor-plugin/下的文件本身不被 IDE 识别。合并是幂等的已有的 Hindsight 条目被替换用户自己的其他 hooks 全部保留Windows 下解释器名自动用python无python3创建用户配置~/.hindsight/cursor.json已存在则跳过写入bankId、hindsightApiUrl、hindsightApiToken写 MCP 配置.cursor/mcp.json除非指定--no-mcp端点使用单 bank 形式并携带Authorization: Bearer token头。hindsight-cursor uninstall则反向清理全部产物插件目录、hooks.json 中 Hindsight 自己的条目、mcp.json 中的hindsight服务、生成的会话 rules 文件以及.gitignore中的对应行见cmd_uninstall()与_remove_session_rules()。init还支持--force覆盖既有安装与--bank-id指定记忆 bank ID默认cursor。配置全景~/.hindsight/cursor.json所有设置集中存放于~/.hindsight/cursor.json每项都可用环境变量覆盖插件自带合理默认值。加载顺序后者覆盖前者已在 scripts/lib/config.py 的load_config()中实现内置默认值硬编码于DEFAULTS插件自带settings.jsonCURSOR_PLUGIN_ROOT/settings.json即 settings.json用户配置~/.hindsight/cursor.json环境变量覆盖ENV_OVERRIDES映射表。Connection Daemon连接与守护进程设置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL空外部 Hindsight API 地址为空时按源码默认回退托管后端或按useLocalDaemon走本地 daemonhindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 认证 token仅在设置hindsightApiUrl时需要apiPortHINDSIGHT_API_PORT9077本地hindsight-embeddaemon 端口embedVersionHINDSIGHT_EMBED_VERSIONlatest通过uvx安装的hindsight-embed版本embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed源码路径开发调试用daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT300daemon 空闲回收秒数useLocalDaemonHINDSIGHT_USE_LOCAL_DAEMONfalse空hindsightApiUrl时是否自动拉起本地 daemonLLM Provider仅本地 daemon 模式生效连接外部 API 时这些设置被忽略。llmProvider支持openai、anthropic、gemini、groq、ollama默认按环境变量中的 API Key 自动探测。设置项环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDER自动探测本地 daemon 使用的 LLM 提供方llmModelHINDSIGHT_LLM_MODEL提供方默认覆盖默认模型llmApiKeyEnv—提供方标准非标准环境变量名时指定 Key 所在变量Memory Bank记忆库bank 是隔离的记忆存储单元可理解为独立的大脑。静态与动态两种模式的推导逻辑见 scripts/lib/bank.py静态模式直接使用bankId动态模式按dynamicBankGranularity中列出的字段合法值agent、project、session、channel、user拼接URL 编码后用::连接出唯一 bank ID支持按 agent、按项目、按会话隔离记忆。bankIdPrefix可为所有 bank ID 加命名空间前缀。ensure_bank_mission()只在首次使用时为 bank 设置 mission记录于本地状态文件避免重复请求。设置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为 false 时的 bank IDbankMissionHINDSIGHT_BANK_MISSION通用助手提示词描述 agent 身份与使命首次使用时设置retainMission—null自定义留存使命如抽取技术决策、架构选择、用户偏好忽略寒暄dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse是否从上下文字段动态推导 bank IDdynamicBankGranularity—[agent, project]参与推导的字段组合bankIdPrefix—所有 bank ID 的前缀命名空间agentNameHINDSIGHT_AGENT_NAMEcursor动态推导中agent字段取值Session Recall会话召回会话召回在每次会话开始时执行一次把召回结果经 rules 文件 /additionalContext注入 agent 上下文不可见于聊天窗口但对 agent 可见。查询由项目名、工作区根目录与 bank mission 组合而成超过recallMaxQueryChars会截断。设置项环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue会话召回的总体开关recallBudgetHINDSIGHT_RECALL_BUDGETmid搜索深度low/mid/highrecallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024召回记忆块的最大 token 数recallTypes—[world, experience]召回的记忆类型recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800查询最大字符数recallPromptPreamble—内置提示词拼接在召回记忆前的引导文本useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue是否写.cursor/rules/hindsight-session.mdc作为 Cursor 原生通道的替代appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue写 rules 文件时幂等追加其路径到.gitignore非 git 工作区为 no-opAuto-Retain自动留存自动留存提取会话 transcript 发送给 Hindsight。retainMode chunked时每次周期留存按retainEveryNTurns retainOverlapTurns的窗口切片slice_last_turns_by_user_boundary()按用户边界对齐sessionEnd冲刷时则只取 watermark 之后的尾部消息保证各 chunk 不重叠。retainTags与retainMetadata支持{session_id}、{bank_id}、{timestamp}模板变量。document ID 采用{session_id}-{毫秒时间戳}保证同一会话内多次留存累积为多个文档而非互相覆盖。设置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动留存总开关retainModeHINDSIGHT_RETAIN_MODEfull-session留存策略full-session或chunkedretainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10每 N 轮留存一次1 每轮retainOverlapTurns—2chunk 间包含的上一轮额外消息数chunked 模式retainContextHINDSIGHT_RETAIN_CONTEXTcursor留存记忆的来源标签retainToolCalls—false是否把工具调用消息纳入留存 transcriptretainTags—[{session_id}]应用于留存文档的标签retainMetadata—{}附加到留存文档的元数据Debug设置项环境变量默认值说明debugHINDSIGHT_DEBUGfalse向 stderr 输出[Hindsight]前缀的详细日志环境变量的完整清单含类型转换逻辑布尔值接受true/1/yes见 scripts/lib/config.py 的ENV_OVERRIDES。自动化测试覆盖changelog 承诺的实现证据0.1.0 声称添加了覆盖 config loading、bank derivation、content formatting 和 hook behavior 的自动化测试这在仓库中可直接验证hindsight-integrations/cursor/tests/下共有 10 个测试文件逐一对应test_config.py——配置加载与合并顺序test_bank.py——bank ID 推导静态/动态/前缀/字段校验test_content.py——内容格式化与 transcript 解析test_hooks.py——hook 行为召回/留存状态写入、轮次闸门、sessionEnd 冲刷test_daemon.py——daemon 生命周期test_rules_file.py——rules 文件回退与 .gitignore 幂等test_cli.py 与 test_e2e.py——CLI 安装/卸载与端到端行为。运行方式见 README.mdpip install pytest python -m pytest tests/ -v其中标记为requires_real_llm的用例需要真实 Hindsight 服务按pytest -m requires_real_llm单独运行见 pyproject.toml 的 markers 配置。验证插件 Hooks 是否生效插件在每次hook 调用时都会写状态文件——即使没有召回结果或留存被跳过。这是排查插件到底有没有跑的最快途径# 未设置 CURSOR_PLUGIN_DATA 时的默认位置 cat ~/.hindsight/cursor-state/state/last_recall.json cat ~/.hindsight/cursor-state/state/last_retain.json每个文件包含saved_at——最近一次调用的时间戳status——success/empty/skipped/error之一bank_id——所用 banksuccess与empty时存在mode——恒为pluginhook——召回文件为sessionStartresult_count召回或message_count留存——仅success时存在。只要使用 Cursor 后saved_at在更新就说明 hooks 在触发再结合status判断具体发生了什么如skipped的reason字段会给出turn_window、no_new_messages、disabled、empty_transcript等原因。常见问题排查插件未激活确认插件目录存在.cursor-plugin/plugin.json在~/.hindsight/cursor.json中开启debug: true观察 stderr 输出。在 Agent 窗口看到Ran Recall in hindsight那是 MCP 工具调用不是插件。插件式召回是静默的——通过additionalContext/ rules 文件注入上下文不产生可见工具调用。若看到显式 Hindsight 工具调用说明.cursor/mcp.json配置了 MCP两者可同时工作。召回返回空结果确认 Hindsight 服务可达本地模式可检查 daemon 健康端点记忆需要至少完成一次留存周期才会存在。daemon 未启动确保已设置 LLM API Key查看 daemon 日志~/.hindsight/profiles/cursor.log。会话启动延迟高sessionStarthook 有 15 秒超时见 hooks/hooks.json可将recallBudget调为low或降低recallMaxTokens。想在非 git 工作区使用rules 文件回退依然可用appendToGitignore对非 git 工作区是 no-op不会报错见ensure_gitignored()的.git检测逻辑。总结从 changelog 的两条记录看hindsight-cursor在 0.1.0 阶段完成了hooks 自动记忆 rule/skill 原生形态 三条集成路径 自动化测试的完整功能拼图0.2.0 则把它固化为一个可pip install、可init/uninstall的正式集成。实际使用中一条hindsight-cursor init即可同时获得会话开始自动召回、任务结束自动留存的 ambient 记忆能力以及recall / retain / reflect三个按需 MCP 工具而 hooks 状态文件、debug 日志与测试目录则是验证和排查这套机制的可靠抓手。若需更完整的集成说明可继续阅读 Cursor 集成指南 与插件自身 README。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考