Hindsight Cursor 集成指南利用 Hook 与 MCP 为 Cursor 注入仿生长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 开源仓库中的 Cursor 集成插件hindsight-cursor展开讲解如何通过 Cursor 的 Hook 插件架构实现会话开始时自动召回项目记忆、任务结束后自动保留对话内容并辅以 MCP 按需工具实现显式记忆操作。读完本文你将掌握该插件的安装、两种互补的记忆机制、三类连接模式、完整配置项以及故障排查方法并能结合源码理解其底层实现原理。两种互补的记忆机制Hindsight Cursor 插件同时提供自动机制与按需机制两条互补的路径| | 插件 Hook自动 | MCP 工具按需 | |--|--------------------------|----------------------| |安装|pip install hindsight-cursor hindsight-cursor init| 由init自动配置 | |召回Recall| 会话开始时通过additionalContext注入记忆 | Agent 可在会话中途调用recall工具 | |保留Retain| 任务停止时自动执行 | Agent 显式调用retain工具 | |反思Reflect| Hook 不提供 | 以工具形式提供 | |适用场景| 零干预的环境记忆持续伴随开发 | 定向查询与显式记忆操作 |两条路径均由一条hindsight-cursor init命令一次性完成配置若只想使用 Hook 而不需要 MCP可追加--no-mcp跳过 MCP 集成。快速开始1. 安装插件pip install hindsight-cursor cd /path/to/your-project也可以使用uvx hindsight-cursor init代替pip installhindsight-cursor init避免在环境中永久安装该包。2a. 连接 Hindsight Cloud最快无需本地服务器hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN在 Hindsight Cloud 注册账号后于Settings API Keys创建 API Key 即可获得 token。2b. 连接本地 Hindsight 服务器hindsight-cursor init --api-url http://localhost:8888若本地尚未运行 Hindsight可用 Docker 一键启动需要先导出 LLM 的 API Key用于服务端的事实抽取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:latest3. 完全退出并重新打开 Cursor插件在启动时加载仅仅重新加载窗口是不够的。若 Cursor 正处于打开状态安装后必须完全退出再重新打开。init命令做了什么从源码看cli.py 中的cmd_init依次执行以下步骤拷贝插件文件到.cursor-plugin/hindsight-memory/。源码中的_PLUGIN_FILES清单cli.py包含plugin.json、hooks/hooks.json、rules/hindsight-memory.mdc、scripts/下全部lib/模块、session_start.py、retain.py、settings.json以及skills/hindsight-recall/SKILL.md若捆绑包缺失任一文件安装会直接报错退出避免出现静默无效安装。写入/合并项目.cursor/hooks.json让 Cursor 注册三个 HooksessionStart/stop/sessionEnd。注意Cursor 只从.cursor/hooks.json工作区级或~/.cursor/hooks.json用户级加载 Hook.cursor-plugin/目录下的文件本身不会被 IDE 加载。你已有的其他 Hook 会被保留重复执行init只替换 Hindsight 自己的条目——这是通过_HOOK_MARKER .cursor-plugin/hindsight-memory标记来识别的cli.py。创建~/.hindsight/cursor.json写入连接配置若该文件已存在则跳过。写入.cursor/mcp.json配置 Hindsight MCP 端点用于按需工具。--force覆盖已有安装--no-mcp跳过 MCP 配置。生成的hooks.json中三个 Hook 均设置了timeout: 15秒命令路径为工作区相对路径因此不依赖CURSOR_PLUGIN_ROOT环境变量cli.py。hindsight-cursor uninstall会逆向撤销全部改动删除插件目录、从.cursor/hooks.json移除 Hindsight 条目、删除 MCP 服务器条目、删除生成的会话规则文件及其.gitignore条目cli.py。工作架构Hook 事件一览插件注册了三个 Hookhooks.jsonHook 脚本事件用途session_start.pysessionStart会话召回—— 查询记忆以additionalContext注入retain.pystop自动保留—— 提取对话记录POST 到 Hindsightretain.pysessionEnd最终冲刷—— 保留轮次窗口未覆盖的会话尾部sessionStart会话召回sessionStart在每个新 Cursor 会话开始、Agent 处理第一条提示词时触发一次。其完整流程session_start.py为从 stdin 读取 Hook 输入workspace_roots、conversation_id等解析 API 地址外部 API → 已有本地服务器 → 本地守护进程 → 云端默认推导 bank ID静态或基于项目上下文动态推导首次使用时设置 bank mission基于工作区上下文项目名、工作区根目录、bank mission构造一条宽泛的项目级查询并截断到recallMaxQueryChars默认 800 字符调用 Hindsight 的 recall API超时 10 秒见 client.py 中POST /v1/default/banks/{bank_id}/memories/recall将召回的记忆格式化为hindsight_memories上下文块输出additionalContext将本次召回状态写入状态文件。stopsessionEnd自动保留与最终冲刷retain.py同时注册在stop和sessionEnd两个事件上这是刻意设计retain.py 与 cli.py 中的注释都解释了这个原因stop在每次 Agent 循环结束时触发是周期性自动保留的理想粒度但每次触发都受轮次窗口约束。在默认retainEveryNTurns 10下一个只有 7 轮对话的会话会触发 7 次stop7 次都被轮次门控拒绝最终整段会话永远不会被存储。sessionEnd在会话结束时只触发一次作为最终冲刷它绕过轮次窗口无论会话结束在窗口的哪个位置尾部内容都会被保留。两个事件在会话末尾存在重叠。插件以会话为单位记录已保留的消息条数水印retained.json若自上次保留以来没有新消息则直接 no-op因此重叠不会导致重复存储retain.py。此外retain.py 的read_transcript支持三种在实际环境中见过的转录格式扁平格式{role, content}、类型嵌套{type, message}以及 Cursor 3.x 的role 嵌套格式顶层rolemessage.content为 typed blocks 列表即~/.cursor/projects/workspace/agent-transcripts/conv/conv.jsonl的形态。内容为块列表时_normalize_blocks_to_text会保留 text 块并内联[tool_use:name]、[tool_result]标记保证下游的Answer:/Thought:结构解析仍然可用。保留请求通过 client.py 以asynctrue异步 POST 到/v1/default/banks/{bank_id}/memories。文档 ID 采用{session_id}-{毫秒时间戳}形式保证同一会话内多次保留会累积成不同文档而非互相覆盖源码注释中说明旧设计使用document_idsession_id会导致多轮会话重保留时静默丢失早期轮次。Cursor 3.x 的additionalContext缺陷与规则文件回退Cursor 的sessionStartHook 原生注入通道是 stdout 上的additionalContextJSON 字段——Hook 返回记忆文本Cursor 将其放入 Agent 的系统提示词。但该通道在 Cursor 3.x 中已损坏Cursor 官方在 forum 帖 158452 中确认截至 Cursor 3.6.31 仍未修复。若additionalContext是唯一投递路径召回的记忆永远到不了模型Agent 会表现得像没装 Hindsight 一样。插件通过额外将召回记忆写入workspace/.cursor/rules/hindsight-session.mdcfrontmatter 中带alwaysApply: true来绕开该缺陷——工作区规则文件能被 Cursor 的规则引擎可靠注入因此 Agent 在新会话的第一条提示词就能看到记忆。该回退路径的实现在lib/rules_file.py模块中并由session_start.py在每次sessionStart触发时先旋转删除旧文件再重写避免残留上一会话的过期记忆。这在实践中意味着每个新 Agent 的首条提示词都带记忆Cursor 会阻塞提示词提交直到sessionStartHook 返回经验验证唯一延迟是召回本身的耗时通常 1s规则文件在每个sessionStart顶部重新生成过期记忆不会滞留在 git 工作区中规则文件会被自动加入.gitignore手动删除也安全下次会自动重新生成additionalContext仍会输出到 stdout 以保持向前兼容——若 Cursor 恢复原生通道同一插件无需改代码即可继续工作。可以通过useRulesFileFallback: false完全关闭规则文件写入此时依赖additionalContext意味着在 Cursor 修复上游 bug 前记忆不会送达。MCP 按需工具init同时配置 Cursor 原生 MCP 支持.cursor/mcp.json连接 Hindsight 的 MCP 端点。从 cli.py 可见它使用单 bank 端点{api_url}/mcp/{bank_id}/使recall/retain/reflect工具自动限定在配置的 bank 内无需每次传bank_id若配置了 API token则会附带Authorization: Bearer token头。已有mcp.json中的其他服务器配置会被保留仅合并hindsight条目。Agent 可在会话中途需要超出会话注入范围的记忆时使用这些工具。规则与技能插件还额外提供规则hindsight-memory.mdcrules/hindsight-memory.mdcalwaysApply: true的常驻规则指导 Agent 使用hindsight_memories块中的会话记忆、了解自动保留行为、并在需要时调用 MCP 工具同时要求记忆与当前上下文冲突时优先当前上下文并注明差异、不向用户暴露原始记忆元数据。技能hindsight-recallskills/hindsight-recall/SKILL.md按需记忆查询技能定义了触发条件与工作流——先检查当前上下文的hindsight_memories是否已覆盖不足时再调用 MCPrecall工具深入搜索架构决策时可使用reflect工具。连接模式1. 外部 API生产环境推荐连接运行中的 Hindsight 服务器云端或自托管。无需本地 LLM——事实抽取由服务器完成{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }2. 本地守护进程自动管理插件可通过uvx自动启动/停止hindsight-embed但需要 LLM 提供商 API Key 用于本地事实抽取。注意从源码看该模式需要显式开启useLocalDaemon: true对应环境变量HINDSIGHT_USE_LOCAL_DAEMON才会在无外部配置时自动拉起守护进程daemon.py{ hindsightApiUrl: , useLocalDaemon: true, apiPort: 9077 }设置 LLM 提供商export OPENAI_API_KEYsk-your-key # 或 export ANTHROPIC_API_KEYyour-key模型默认由 Hindsight API 自动选择可通过HINDSIGHT_LLM_MODEL覆盖。从 daemon.py 看守护进程启动分三步先通过hindsight-embed profile create cursor --merge --port port配置 profile将 LLM 环境变量与daemonIdleTimeout默认 300 秒写入 profile再执行daemon --profile cursor start最后最多轮询 30 秒等待/health就绪。在 macOS 上会自动附加HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1强制本地 embedding/reranker 走 CPU。3. 已有本地服务器如果你已经自行运行了hindsight-embed保持hindsightApiUrl为空并设置apiPort与你的服务器端口一致即可插件会自动探测到本地健康端口daemon.py 会先对http://127.0.0.1:port/health做健康检查。若以上都不满足插件最终会回退到默认云端地址https://api.hindsight.vectorize.ioconfig.py中的DEFAULT_HINDSIGHT_API_URL遵循跨集成一致的默认连云端约定。配置详解所有设置存放在~/.hindsight/cursor.json中每个设置都可通过环境变量覆盖。插件内置了合理的默认值见 settings.json你只需按需覆盖。加载顺序后加载者优先实现在 lib/config.py内置默认值硬编码在插件中即lib/config.py的DEFAULTS插件自带settings.json位于CURSOR_PLUGIN_ROOT/settings.json用户配置~/.hindsight/cursor.json推荐在这里写覆盖项环境变量优先级最高。连接与守护进程配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL空外部 Hindsight API 服务器地址。为空时插件按连接模式解析逻辑选择本地守护进程或云端默认。hindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 的认证 token仅在设置了hindsightApiUrl时需要。apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程的端口。useLocalDaemonHINDSIGHT_USE_LOCAL_DAEMONfalse是否允许插件自动拉起本地守护进程需配合 LLM API Key。daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT300守护进程空闲自动退出秒数。embedVersionHINDSIGHT_EMBED_VERSIONlatest通过uvx安装的hindsight-embed版本。embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed源码目录开发用会改用uv run --directory启动。LLM Provider仅本地守护进程模式以下设置配置本地守护进程用于事实抽取的 LLM。连接外部 API 时会被忽略。配置项环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDER自动检测LLM 提供商openai、anthropic、gemini、groq、ollama。通过检查对应 API Key 环境变量自动检测lib/llm.py。llmModelHINDSIGHT_LLM_MODEL提供商默认覆盖所选提供商的默认模型。llmApiKeyEnv—提供商标准若 API Key 所在环境变量名非标准可在此指定。Memory Bankbank是隔离的记忆存储如同一个独立的大脑。配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为false时使用的 bank ID。bankMissionHINDSIGHT_BANK_MISSION通用助手提示词对 Agent 身份与用途的描述。插件默认值为面向 Cursor 编码助手的使命见 settings.json。retainMission—null为该 bank 设置的自定义 retain mission仅首次使用时写入。dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时基于上下文字段推导唯一 bank ID见dynamicBankGranularity。dynamicBankGranularity—[agent, project]用于组合动态 bank ID 的字段agent、project、session、channel、user。从 lib/bank.py 看各字段依次取自agentName、工作区目录名、conversation_id、环境变量HINDSIGHT_CHANNEL_ID、HINDSIGHT_USER_ID用::连接并做 URL 编码。bankIdPrefix—添加到所有 bank ID 前的前缀用于命名空间隔离。agentNameHINDSIGHT_AGENT_NAMEcursor动态 bank ID 推导中agent字段使用的名称。Session Recall会话召回会话召回在每个会话开始时执行一次查询 Hindsight 中的相关项目记忆并以不可见的additionalContext注入 Agent 上下文同时写入会话规则文件作为回退通道。配置项环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue会话召回的总开关。recallBudgetHINDSIGHT_RECALL_BUDGETmid搜索充分度low、mid、high。recallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024召回记忆块的最大 token 数。recallTypes—[world, experience]检索的记忆类型。recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800查询字符串最大字符数。recallPromptPreamble—见settings.json附加在召回记忆前的提示文本指导 Agent 如何取舍记忆默认提示优先采用最近的记忆仅使用对继续对话直接有用的部分。useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue将召回记忆写入workspace/.cursor/rules/hindsight-session.mdc以便 Cursor 规则引擎注入用于绕开原生additionalContext通道的缺陷。appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue写入规则文件回退时幂等地将该路径追加到工作区.gitignore非 git 工作区为 no-op。Auto-Retain自动保留自动保留在 Agent 完成任务后执行提取对话记录并发送给 Hindsight。配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动保留的总开关。retainModeHINDSIGHT_RETAIN_MODEfull-session保留策略full-session或chunked。retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10每 N 轮保留一次1表示每轮都保留。retainOverlapTurns—2分块模式下从前一块额外包含的轮数以保证连续性。retainContextHINDSIGHT_RETAIN_CONTEXTcursor保留记忆的来源标签Hindsight 据此按来源聚类记忆。retainToolCalls—false是否在保留的记录中纳入工具调用消息。retainTags—[]附加到保留文档的标签支持{session_id}等模板变量源码中还会展开{bank_id}、{timestamp}。retainMetadata—{}附加到保留文档的额外元数据同样支持模板变量。Debug调试配置项环境变量默认值说明debugHINDSIGHT_DEBUGfalse启用 verbose 日志输出到 stderr行首以[Hindsight]前缀标记。验证 Hook 是否生效插件在每次Hook 调用时都会写入状态文件——即使没有召回任何记忆或保留被跳过也会写入。检查这些文件即可确认 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在更新说明 Hook 正在触发再查看status判断发生了什么。故障排查插件未激活检查插件目录下是否存在.cursor-plugin/plugin.json。在~/.hindsight/cursor.json中启用debug: true并查看 stderr 输出。Agent 窗口中看到 Ran Recall in hindsight那是 MCP 而非插件。插件式召回是静默的——通过additionalContext注入上下文不产生可见的工具调用。若看到显式的 Hindsight 工具调用说明.cursor/mcp.json中配置了 MCP。两者可以共存、协同工作。召回不到记忆确认 Hindsight 服务器可达curl http://localhost:9077/health。记忆至少需要经历一次完整的 retain 周期才会被召回。守护进程不启动确认已设置 LLM API KeyllmProvider自动检测依赖对应环境变量。查看守护进程日志~/.hindsight/profiles/cursor.log。会话启动高延迟sessionStart召回 Hook 有 15 秒超时。可改用recallBudget: low或调低recallMaxTokens。源码导读本集成的完整实现位于仓库 hindsight-integrations/cursor 目录各模块职责如下模块/文件职责hindsight_cursor/cli.pyinit/uninstall命令拷贝插件、合并 hooks、生成配置与 MCP 配置hooks/hooks.json三个 Hook 的声明随插件包分发scripts/session_start.pysessionStart召回流程scripts/retain.pystop/sessionEnd保留流程转录解析、轮次门控、最终冲刷scripts/lib/config.py配置默认值与环境变量覆盖表scripts/lib/daemon.pyhindsight-embed守护进程生命周期与连接模式解析scripts/lib/bank.pybank ID 推导与 mission 管理scripts/lib/client.py基于 stdliburllib的 Hindsight REST API 客户端settings.json插件默认配置rules/hindsight-memory.mdc常驻规则skills/hindsight-recall/SKILL.md按需召回技能tests/覆盖配置加载、bank 推导、内容格式化与 Hook 行为的自动化测试插件脚本仅依赖 Python 标准库HTTP 客户端用urllib、状态持久化用fcntl文件锁因此运行时零第三方依赖。其变更历史可参阅 Cursor 集成 Changelog。若想了解 Hindsight 记忆 API 的服务端实现bank、recall、retain、reflect 等可继续阅读仓库中 hindsight-api 与 hindsight-embed 的源码。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hindsight Cursor 集成指南：利用 Hook 与 MCP 为 Cursor 注入仿生长期记忆
Hindsight Cursor 集成指南利用 Hook 与 MCP 为 Cursor 注入仿生长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 开源仓库中的 Cursor 集成插件hindsight-cursor展开讲解如何通过 Cursor 的 Hook 插件架构实现会话开始时自动召回项目记忆、任务结束后自动保留对话内容并辅以 MCP 按需工具实现显式记忆操作。读完本文你将掌握该插件的安装、两种互补的记忆机制、三类连接模式、完整配置项以及故障排查方法并能结合源码理解其底层实现原理。两种互补的记忆机制Hindsight Cursor 插件同时提供自动机制与按需机制两条互补的路径| | 插件 Hook自动 | MCP 工具按需 | |--|--------------------------|----------------------| |安装|pip install hindsight-cursor hindsight-cursor init| 由init自动配置 | |召回Recall| 会话开始时通过additionalContext注入记忆 | Agent 可在会话中途调用recall工具 | |保留Retain| 任务停止时自动执行 | Agent 显式调用retain工具 | |反思Reflect| Hook 不提供 | 以工具形式提供 | |适用场景| 零干预的环境记忆持续伴随开发 | 定向查询与显式记忆操作 |两条路径均由一条hindsight-cursor init命令一次性完成配置若只想使用 Hook 而不需要 MCP可追加--no-mcp跳过 MCP 集成。快速开始1. 安装插件pip install hindsight-cursor cd /path/to/your-project也可以使用uvx hindsight-cursor init代替pip installhindsight-cursor init避免在环境中永久安装该包。2a. 连接 Hindsight Cloud最快无需本地服务器hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN在 Hindsight Cloud 注册账号后于Settings API Keys创建 API Key 即可获得 token。2b. 连接本地 Hindsight 服务器hindsight-cursor init --api-url http://localhost:8888若本地尚未运行 Hindsight可用 Docker 一键启动需要先导出 LLM 的 API Key用于服务端的事实抽取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:latest3. 完全退出并重新打开 Cursor插件在启动时加载仅仅重新加载窗口是不够的。若 Cursor 正处于打开状态安装后必须完全退出再重新打开。init命令做了什么从源码看cli.py 中的cmd_init依次执行以下步骤拷贝插件文件到.cursor-plugin/hindsight-memory/。源码中的_PLUGIN_FILES清单cli.py包含plugin.json、hooks/hooks.json、rules/hindsight-memory.mdc、scripts/下全部lib/模块、session_start.py、retain.py、settings.json以及skills/hindsight-recall/SKILL.md若捆绑包缺失任一文件安装会直接报错退出避免出现静默无效安装。写入/合并项目.cursor/hooks.json让 Cursor 注册三个 HooksessionStart/stop/sessionEnd。注意Cursor 只从.cursor/hooks.json工作区级或~/.cursor/hooks.json用户级加载 Hook.cursor-plugin/目录下的文件本身不会被 IDE 加载。你已有的其他 Hook 会被保留重复执行init只替换 Hindsight 自己的条目——这是通过_HOOK_MARKER .cursor-plugin/hindsight-memory标记来识别的cli.py。创建~/.hindsight/cursor.json写入连接配置若该文件已存在则跳过。写入.cursor/mcp.json配置 Hindsight MCP 端点用于按需工具。--force覆盖已有安装--no-mcp跳过 MCP 配置。生成的hooks.json中三个 Hook 均设置了timeout: 15秒命令路径为工作区相对路径因此不依赖CURSOR_PLUGIN_ROOT环境变量cli.py。hindsight-cursor uninstall会逆向撤销全部改动删除插件目录、从.cursor/hooks.json移除 Hindsight 条目、删除 MCP 服务器条目、删除生成的会话规则文件及其.gitignore条目cli.py。工作架构Hook 事件一览插件注册了三个 Hookhooks.jsonHook 脚本事件用途session_start.pysessionStart会话召回—— 查询记忆以additionalContext注入retain.pystop自动保留—— 提取对话记录POST 到 Hindsightretain.pysessionEnd最终冲刷—— 保留轮次窗口未覆盖的会话尾部sessionStart会话召回sessionStart在每个新 Cursor 会话开始、Agent 处理第一条提示词时触发一次。其完整流程session_start.py为从 stdin 读取 Hook 输入workspace_roots、conversation_id等解析 API 地址外部 API → 已有本地服务器 → 本地守护进程 → 云端默认推导 bank ID静态或基于项目上下文动态推导首次使用时设置 bank mission基于工作区上下文项目名、工作区根目录、bank mission构造一条宽泛的项目级查询并截断到recallMaxQueryChars默认 800 字符调用 Hindsight 的 recall API超时 10 秒见 client.py 中POST /v1/default/banks/{bank_id}/memories/recall将召回的记忆格式化为hindsight_memories上下文块输出additionalContext将本次召回状态写入状态文件。stopsessionEnd自动保留与最终冲刷retain.py同时注册在stop和sessionEnd两个事件上这是刻意设计retain.py 与 cli.py 中的注释都解释了这个原因stop在每次 Agent 循环结束时触发是周期性自动保留的理想粒度但每次触发都受轮次窗口约束。在默认retainEveryNTurns 10下一个只有 7 轮对话的会话会触发 7 次stop7 次都被轮次门控拒绝最终整段会话永远不会被存储。sessionEnd在会话结束时只触发一次作为最终冲刷它绕过轮次窗口无论会话结束在窗口的哪个位置尾部内容都会被保留。两个事件在会话末尾存在重叠。插件以会话为单位记录已保留的消息条数水印retained.json若自上次保留以来没有新消息则直接 no-op因此重叠不会导致重复存储retain.py。此外retain.py 的read_transcript支持三种在实际环境中见过的转录格式扁平格式{role, content}、类型嵌套{type, message}以及 Cursor 3.x 的role 嵌套格式顶层rolemessage.content为 typed blocks 列表即~/.cursor/projects/workspace/agent-transcripts/conv/conv.jsonl的形态。内容为块列表时_normalize_blocks_to_text会保留 text 块并内联[tool_use:name]、[tool_result]标记保证下游的Answer:/Thought:结构解析仍然可用。保留请求通过 client.py 以asynctrue异步 POST 到/v1/default/banks/{bank_id}/memories。文档 ID 采用{session_id}-{毫秒时间戳}形式保证同一会话内多次保留会累积成不同文档而非互相覆盖源码注释中说明旧设计使用document_idsession_id会导致多轮会话重保留时静默丢失早期轮次。Cursor 3.x 的additionalContext缺陷与规则文件回退Cursor 的sessionStartHook 原生注入通道是 stdout 上的additionalContextJSON 字段——Hook 返回记忆文本Cursor 将其放入 Agent 的系统提示词。但该通道在 Cursor 3.x 中已损坏Cursor 官方在 forum 帖 158452 中确认截至 Cursor 3.6.31 仍未修复。若additionalContext是唯一投递路径召回的记忆永远到不了模型Agent 会表现得像没装 Hindsight 一样。插件通过额外将召回记忆写入workspace/.cursor/rules/hindsight-session.mdcfrontmatter 中带alwaysApply: true来绕开该缺陷——工作区规则文件能被 Cursor 的规则引擎可靠注入因此 Agent 在新会话的第一条提示词就能看到记忆。该回退路径的实现在lib/rules_file.py模块中并由session_start.py在每次sessionStart触发时先旋转删除旧文件再重写避免残留上一会话的过期记忆。这在实践中意味着每个新 Agent 的首条提示词都带记忆Cursor 会阻塞提示词提交直到sessionStartHook 返回经验验证唯一延迟是召回本身的耗时通常 1s规则文件在每个sessionStart顶部重新生成过期记忆不会滞留在 git 工作区中规则文件会被自动加入.gitignore手动删除也安全下次会自动重新生成additionalContext仍会输出到 stdout 以保持向前兼容——若 Cursor 恢复原生通道同一插件无需改代码即可继续工作。可以通过useRulesFileFallback: false完全关闭规则文件写入此时依赖additionalContext意味着在 Cursor 修复上游 bug 前记忆不会送达。MCP 按需工具init同时配置 Cursor 原生 MCP 支持.cursor/mcp.json连接 Hindsight 的 MCP 端点。从 cli.py 可见它使用单 bank 端点{api_url}/mcp/{bank_id}/使recall/retain/reflect工具自动限定在配置的 bank 内无需每次传bank_id若配置了 API token则会附带Authorization: Bearer token头。已有mcp.json中的其他服务器配置会被保留仅合并hindsight条目。Agent 可在会话中途需要超出会话注入范围的记忆时使用这些工具。规则与技能插件还额外提供规则hindsight-memory.mdcrules/hindsight-memory.mdcalwaysApply: true的常驻规则指导 Agent 使用hindsight_memories块中的会话记忆、了解自动保留行为、并在需要时调用 MCP 工具同时要求记忆与当前上下文冲突时优先当前上下文并注明差异、不向用户暴露原始记忆元数据。技能hindsight-recallskills/hindsight-recall/SKILL.md按需记忆查询技能定义了触发条件与工作流——先检查当前上下文的hindsight_memories是否已覆盖不足时再调用 MCPrecall工具深入搜索架构决策时可使用reflect工具。连接模式1. 外部 API生产环境推荐连接运行中的 Hindsight 服务器云端或自托管。无需本地 LLM——事实抽取由服务器完成{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }2. 本地守护进程自动管理插件可通过uvx自动启动/停止hindsight-embed但需要 LLM 提供商 API Key 用于本地事实抽取。注意从源码看该模式需要显式开启useLocalDaemon: true对应环境变量HINDSIGHT_USE_LOCAL_DAEMON才会在无外部配置时自动拉起守护进程daemon.py{ hindsightApiUrl: , useLocalDaemon: true, apiPort: 9077 }设置 LLM 提供商export OPENAI_API_KEYsk-your-key # 或 export ANTHROPIC_API_KEYyour-key模型默认由 Hindsight API 自动选择可通过HINDSIGHT_LLM_MODEL覆盖。从 daemon.py 看守护进程启动分三步先通过hindsight-embed profile create cursor --merge --port port配置 profile将 LLM 环境变量与daemonIdleTimeout默认 300 秒写入 profile再执行daemon --profile cursor start最后最多轮询 30 秒等待/health就绪。在 macOS 上会自动附加HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1强制本地 embedding/reranker 走 CPU。3. 已有本地服务器如果你已经自行运行了hindsight-embed保持hindsightApiUrl为空并设置apiPort与你的服务器端口一致即可插件会自动探测到本地健康端口daemon.py 会先对http://127.0.0.1:port/health做健康检查。若以上都不满足插件最终会回退到默认云端地址https://api.hindsight.vectorize.ioconfig.py中的DEFAULT_HINDSIGHT_API_URL遵循跨集成一致的默认连云端约定。配置详解所有设置存放在~/.hindsight/cursor.json中每个设置都可通过环境变量覆盖。插件内置了合理的默认值见 settings.json你只需按需覆盖。加载顺序后加载者优先实现在 lib/config.py内置默认值硬编码在插件中即lib/config.py的DEFAULTS插件自带settings.json位于CURSOR_PLUGIN_ROOT/settings.json用户配置~/.hindsight/cursor.json推荐在这里写覆盖项环境变量优先级最高。连接与守护进程配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL空外部 Hindsight API 服务器地址。为空时插件按连接模式解析逻辑选择本地守护进程或云端默认。hindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 的认证 token仅在设置了hindsightApiUrl时需要。apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程的端口。useLocalDaemonHINDSIGHT_USE_LOCAL_DAEMONfalse是否允许插件自动拉起本地守护进程需配合 LLM API Key。daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT300守护进程空闲自动退出秒数。embedVersionHINDSIGHT_EMBED_VERSIONlatest通过uvx安装的hindsight-embed版本。embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed源码目录开发用会改用uv run --directory启动。LLM Provider仅本地守护进程模式以下设置配置本地守护进程用于事实抽取的 LLM。连接外部 API 时会被忽略。配置项环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDER自动检测LLM 提供商openai、anthropic、gemini、groq、ollama。通过检查对应 API Key 环境变量自动检测lib/llm.py。llmModelHINDSIGHT_LLM_MODEL提供商默认覆盖所选提供商的默认模型。llmApiKeyEnv—提供商标准若 API Key 所在环境变量名非标准可在此指定。Memory Bankbank是隔离的记忆存储如同一个独立的大脑。配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为false时使用的 bank ID。bankMissionHINDSIGHT_BANK_MISSION通用助手提示词对 Agent 身份与用途的描述。插件默认值为面向 Cursor 编码助手的使命见 settings.json。retainMission—null为该 bank 设置的自定义 retain mission仅首次使用时写入。dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时基于上下文字段推导唯一 bank ID见dynamicBankGranularity。dynamicBankGranularity—[agent, project]用于组合动态 bank ID 的字段agent、project、session、channel、user。从 lib/bank.py 看各字段依次取自agentName、工作区目录名、conversation_id、环境变量HINDSIGHT_CHANNEL_ID、HINDSIGHT_USER_ID用::连接并做 URL 编码。bankIdPrefix—添加到所有 bank ID 前的前缀用于命名空间隔离。agentNameHINDSIGHT_AGENT_NAMEcursor动态 bank ID 推导中agent字段使用的名称。Session Recall会话召回会话召回在每个会话开始时执行一次查询 Hindsight 中的相关项目记忆并以不可见的additionalContext注入 Agent 上下文同时写入会话规则文件作为回退通道。配置项环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue会话召回的总开关。recallBudgetHINDSIGHT_RECALL_BUDGETmid搜索充分度low、mid、high。recallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024召回记忆块的最大 token 数。recallTypes—[world, experience]检索的记忆类型。recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800查询字符串最大字符数。recallPromptPreamble—见settings.json附加在召回记忆前的提示文本指导 Agent 如何取舍记忆默认提示优先采用最近的记忆仅使用对继续对话直接有用的部分。useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue将召回记忆写入workspace/.cursor/rules/hindsight-session.mdc以便 Cursor 规则引擎注入用于绕开原生additionalContext通道的缺陷。appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue写入规则文件回退时幂等地将该路径追加到工作区.gitignore非 git 工作区为 no-op。Auto-Retain自动保留自动保留在 Agent 完成任务后执行提取对话记录并发送给 Hindsight。配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动保留的总开关。retainModeHINDSIGHT_RETAIN_MODEfull-session保留策略full-session或chunked。retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10每 N 轮保留一次1表示每轮都保留。retainOverlapTurns—2分块模式下从前一块额外包含的轮数以保证连续性。retainContextHINDSIGHT_RETAIN_CONTEXTcursor保留记忆的来源标签Hindsight 据此按来源聚类记忆。retainToolCalls—false是否在保留的记录中纳入工具调用消息。retainTags—[]附加到保留文档的标签支持{session_id}等模板变量源码中还会展开{bank_id}、{timestamp}。retainMetadata—{}附加到保留文档的额外元数据同样支持模板变量。Debug调试配置项环境变量默认值说明debugHINDSIGHT_DEBUGfalse启用 verbose 日志输出到 stderr行首以[Hindsight]前缀标记。验证 Hook 是否生效插件在每次Hook 调用时都会写入状态文件——即使没有召回任何记忆或保留被跳过也会写入。检查这些文件即可确认 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在更新说明 Hook 正在触发再查看status判断发生了什么。故障排查插件未激活检查插件目录下是否存在.cursor-plugin/plugin.json。在~/.hindsight/cursor.json中启用debug: true并查看 stderr 输出。Agent 窗口中看到 Ran Recall in hindsight那是 MCP 而非插件。插件式召回是静默的——通过additionalContext注入上下文不产生可见的工具调用。若看到显式的 Hindsight 工具调用说明.cursor/mcp.json中配置了 MCP。两者可以共存、协同工作。召回不到记忆确认 Hindsight 服务器可达curl http://localhost:9077/health。记忆至少需要经历一次完整的 retain 周期才会被召回。守护进程不启动确认已设置 LLM API KeyllmProvider自动检测依赖对应环境变量。查看守护进程日志~/.hindsight/profiles/cursor.log。会话启动高延迟sessionStart召回 Hook 有 15 秒超时。可改用recallBudget: low或调低recallMaxTokens。源码导读本集成的完整实现位于仓库 hindsight-integrations/cursor 目录各模块职责如下模块/文件职责hindsight_cursor/cli.pyinit/uninstall命令拷贝插件、合并 hooks、生成配置与 MCP 配置hooks/hooks.json三个 Hook 的声明随插件包分发scripts/session_start.pysessionStart召回流程scripts/retain.pystop/sessionEnd保留流程转录解析、轮次门控、最终冲刷scripts/lib/config.py配置默认值与环境变量覆盖表scripts/lib/daemon.pyhindsight-embed守护进程生命周期与连接模式解析scripts/lib/bank.pybank ID 推导与 mission 管理scripts/lib/client.py基于 stdliburllib的 Hindsight REST API 客户端settings.json插件默认配置rules/hindsight-memory.mdc常驻规则skills/hindsight-recall/SKILL.md按需召回技能tests/覆盖配置加载、bank 推导、内容格式化与 Hook 行为的自动化测试插件脚本仅依赖 Python 标准库HTTP 客户端用urllib、状态持久化用fcntl文件锁因此运行时零第三方依赖。其变更历史可参阅 Cursor 集成 Changelog。若想了解 Hindsight 记忆 API 的服务端实现bank、recall、retain、reflect 等可继续阅读仓库中 hindsight-api 与 hindsight-embed 的源码。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考