2026/9/13 14:38:20
FEATURED · 精选文章 
Hindsight Cursor 集成指南为 Cursor 接入跨会话长期记忆Hook 自动回忆 MCP 按需记忆工具【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文是一份面向 Cursor 用户与 AI 编程代理开发者的实操指南完整讲解如何通过官方hindsight-cursor插件让 Cursor 在会话启动时自动回忆项目级长期记忆、在任务结束时自动沉淀对话内容并在会话中途通过 MCP 工具按需执行 recall / retain / reflect 记忆操作。读完本文你将掌握插件安装与卸载、三种连接模式、全部配置项及其环境变量覆盖方式、Hook 触发验证与常见故障排查方法并从源码层面理解会话回忆、自动保留与防重复存储的底层实现。背景与定位Cursor 是当前流行的 AI 代码编辑器之一其每次会话都从空白上下文开始上一轮讨论过的技术决策、用户偏好与项目约定除非显式写入文档否则不会自动出现在新会话中。Hindsight 提供类生物的长期记忆能力项目名为 Hindsight: Agent Memory That Learns而hindsight-cursor插件正是把这一能力嫁接到 Cursor 的载体。插件适配了 Cursor 的Hook 机制自动触发回忆与保留与MCP 机制会话中按需调用记忆工具二者互补由同一条命令hindsight-cursor init一次性完成安装。本仓库中该集成的完整实现位于 hindsight-integrations/cursor包含 CLIcli.py、Hook 脚本session_start.py、retain.py、运行库scripts/lib/与测试tests。工作原理两种互补的记忆机制插件使用两套机制协同工作| | 插件 Hooks自动 | MCP 工具按需 | |--|--------------------------|----------------------| |安装|pip install hindsight-cursor hindsight-cursor init| 由init自动配置 | |回忆Recall| 会话启动时通过additionalContext注入记忆 | Agent 在会话中调用recall工具 | |保留Retain| 任务结束时自动执行 | Agent 显式调用retain工具 | |反思Reflect| Hooks 不可用 | 作为工具提供 | |适用场景| 无需用户干预的沉浸式项目记忆 | 定向查找与显式记忆操作 |两种机制都由单条hindsight-cursor init命令完成配置如果只想用 Hooks、不需要 MCP可加--no-mcp跳过。从源码看init写入的 Hook 注册表实际包含三个事件。查看 cli.py 中的_project_hooks_block()sessionStart→ 执行scripts/session_start.py超时 15 秒stop→ 执行scripts/retain.py超时 15 秒sessionEnd→ 同样执行scripts/retain.py超时 15 秒。对应地仓库中随包分发的模板 hooks/hooks.json 也声明了这三个事件但它使用${CURSOR_PLUGIN_ROOT}变量仅适用于安装在~/.cursor/plugins下的场景而init会改写成工作区相对路径确保不依赖该环境变量也能运行。快速开始# 1. 安装插件 pip install hindsight-cursor cd /path/to/your-project # 2a. 连接 Hindsight Cloud最快——无需本地服务器 hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN # 2b. 或连接本地 Hindsight 服务器 hindsight-cursor init --api-url http://localhost:8888 # 3. 完全退出并重新打开 Cursor —— 插件在启动时加载⚠️重要如果向一个已经打开的 Cursor 工作区添加插件必须完全退出 Cursor 后重新打开。插件在启动时加载仅刷新窗口window reload不够。获取 Hindsight 服务端两种方式任选其一方式一Hindsight Cloud。注册获得 API Token 后在init时通过--api-url与--api-token传入。方式二本地 Docker 自托管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流程init依次完成拷贝插件文件到项目下的.cursor-plugin/hindsight-memory/文件清单定义在_PLUGIN_FILES共 16 个文件包含 Hook 脚本、settings.json、规则文件与技能文件。源码注释强调任何文件缺失都会中止安装并报错——因为session_start.py会 importlib/下所有模块缺一个文件就会让每次 Hook 调用变成静默 ImportError写入/合并项目的.cursor/hooks.json让 Cursor 注册 Hook。_setup_hooks()是幂等的已有用户的 Hook 会被保留重复执行init只替换 Hindsight 自己的条目通过_HOOK_MARKER .cursor-plugin/hindsight-memory识别归属。注意 Cursor 只从.cursor/hooks.json工作区或~/.cursor/hooks.json用户级加载 Hook——仅把文件丢进.cursor-plugin/是不够的创建~/.hindsight/cursor.json若文件尚不存在写入连接设置写入.cursor/mcp.json配置 Hindsight 的 MCP 端点。_setup_mcp()使用单 bank 端点{api_url}/mcp/{bank_id}/并将Authorization: Bearer token写入请求头使 recall / retain / reflect 工具自动限定在配置的 bank 内、无需每次传bank_id--force覆盖已有安装--no-mcp跳过 MCP 配置。卸载hindsight-cursor uninstall会全部还原——删除插件目录、从.cursor/hooks.json移除 Hindsight 条目、删除 MCP 服务器条目、删除生成的会话规则文件以及对应的.gitignore行。其中_remove_session_rules()的存在是有讲究的会话规则文件会在每次sessionStart时重新生成若卸载后残留其alwaysApply: true属性会让已死会话的记忆继续注入每一次 Agent 轮次。核心特性会话回忆Session recall——每个会话开始时向 Hindsight 查询项目相关记忆通过additionalContext注入上下文对聊天界面不可见对 Agent 可见自动保留Auto-retain——每个任务完成后提取会话内容并存储到 Hindsight 长期记忆按需 MCP 工具——recall、retain、reflect三个工具支持会话中途的显式记忆操作按需回忆技能Skill——hindsight-recall技能支持手动记忆查询守护进程管理——可自动启停本地hindsight-embed或连接外部 Hindsight 服务器动态 Bank ID——支持按 Agent、按项目、按会话隔离记忆零运行时依赖——插件脚本仅使用 Python 标准库。架构三个 Hook 事件如何协同插件构建在 Cursor 的 Hook 系统之上具体事件分工如下Hook事件用途session_start.pysessionStart会话回忆——查询记忆注入为additionalContextretain.pystop自动保留——提取会话文本POST 到 Hindsightretain.pysessionEnd最终冲刷——保留轮次窗口未能覆盖的尾部内容会话回忆sessionStartsessionStart事件在每个新 Cursor 会话开始时触发一次执行一次广谱的项目级回忆并把相关记忆注入为隐藏上下文。查看 session_start.py 的实现其完整流程是从 stdin 读取 Hook 输入workspace_roots、conversation_id等解析 API 地址外部 API / 已有本地服务 / 自动启动守护进程见下文连接模式派生 Bank ID静态或基于项目上下文动态派生见 bank.py首次使用时确保 Bank Mission 已设置ensure_bank_mission基于工作区上下文构造广谱查询——项目名来自workspace_roots的 basename叠加配置的bankMission并以recallMaxQueryChars默认 800截断调用 Hindsight 回忆 API超时 10 秒参数含max_tokens、budget、types将记忆格式化为hindsight_memories块输出additionalContext写入last_recall.json状态文件。值得注意的一个健壮性细节脚本总是以退出码 0 结束任何错误都优雅降级避免 Hook 失败反过来干扰 Cursor 的正常会话启动。自动保留与最终冲刷stop sessionEndretain.py同时注册在stop与sessionEnd两个事件上这是有明确原因的——只看 retain.py 的实现与注释stop在每次 Agent 循环结束时触发是周期性自动保留的合适粒度但每次触发都要过轮次闸门retainEveryNTurns。默认值为 10 时一段 7 轮的对话会触发 7 次stop、被闸门拦下 7 次最终永远不会被存储sessionEnd在对话结束时触发一次携带相同的transcript_path被当作最终冲刷final flush它绕过轮次窗口无论会话停在哪一轮尾部内容都会被保留。两者在会话末尾重叠插件为每个会话维护一个已保留消息数的水位线retained.json见 state.py当一次调用发现没有新增消息时直接跳过因此重叠不会导致重复存储。其他值得展开的实现细节转录读取兼容三种格式扁平式{role, content}、类型嵌套式{type, message: {...}}以及 Cursor 3.x 的角色嵌套式{role, message: {content: [blocks...]}}。注释明确指出 Cursor 3.6.31 实际写入~/.cursor/projects/workspace/agent-transcripts/conv/conv.jsonl的就是角色嵌套格式早期解析器因不认识该结构会在每个 stop 钩子上静默丢弃全部内容empty_transcript问题文档 ID 去重document_id {session_id}-{毫秒时间戳}保证同一会话内多次保留写入的是不同文档而非互相覆盖——旧设计在 full-session 模式下用session_id作文档 ID多轮会话重复保留时会静默丢弃早期轮次防反馈循环保留前会剥离hindsight_memories/relevant_memories块见 content.py避免把回忆注入的内容当作新记忆再次存储。一个上游竞态的绕行方案Cursor 的sessionStartHook 虽然接受additionalContextJSON 输出但在 Agent 的 composer 句柄就绪前会静默丢弃该内容——这是 Cursor 官方论坛确认的竞态问题在 Cursor 3.6.31 中仍存在。插件的绕行方案见 rules_file.py是把回忆到的记忆写入工作区.cursor/rules/hindsight-session.mdc该文件带alwaysApply: true前置元数据规则引擎会可靠地把内容注入 Agent 上下文。每次sessionStart开头会先轮换删除旧规则文件避免上一会话的过期记忆残留若工作区是 Git 仓库还会把该规则文件追加进.gitignore。同时 Hook 仍会输出additionalContext以兼容未来修复后的原生路径。Skill 与 Ruleinit还会安装两个配套资产技能Skillhindsight-recall/SKILL.md——按需记忆查询规则Rulerules/hindsight-memory.mdc——常驻规则指示 Agent 善用回忆到的记忆与 MCP 工具。三种连接模式插件通过 daemon.py 的get_api_url()按优先级解析 API 地址1. 外部 API生产环境推荐连接一个正在运行的 Hindsight 服务器云端或自托管。无需本地 LLM——事实提取由服务端完成。{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }对应源码中的 Mode 1显式配置的hindsightApiUrl优先级最高直接返回。2. 本地守护进程自动托管插件通过uvx自动启停hindsight-embed。本地事实提取需要 LLM 提供方的 API Keyexport OPENAI_API_KEYsk-your-key # 或 export ANTHROPIC_API_KEYyour-key模型由 Hindsight API 自动选择可用HINDSIGHT_LLM_MODEL覆盖。注意这是需要显式开启的模式useLocalDaemon: true对应源码 Mode 3。守护进程启动流程在 daemon.py 中分三步profile create创建cursor配置--merge --port port并注入 LLM 环境变量与 5 分钟空闲超时→daemon --profile cursor start启动 → 每 1 秒探测一次/health最多 30 秒等待就绪。macOS 上还会额外设置HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1强制 CPU 推理。3. 已有本地服务器如果hindsight-embed已在运行对应源码 Mode 2保持hindsightApiUrl为空、把apiPort设为服务器端口插件会通过健康检查自动探测并复用不重复启动守护进程。兜底逻辑当以上都不满足时对应源码 Mode 4插件回落到默认托管后端地址https://api.hindsight.vectorize.io定义于 config.py。这与全项目默认上云的跨集成约定一致全新安装、零配置也能直连托管后端自托管用户通过设置显式hindsightApiUrl或useLocalDaemon: true回到本地路径。LLM 提供方检测本地守护进程模式需要 LLM 做事实提取检测优先级见 llm.pyHINDSIGHT_API_LLM_PROVIDER等HINDSIGHT_API_LLM_*环境变量最高优先级插件配置llmProvider/llmModel/llmApiKeyEnv从标准环境变量自动检测OPENAI_API_KEY→ANTHROPIC_API_KEY→GEMINI_API_KEY→GROQ_API_KEYollama、openai-codex、claude-code、github-copilot无需 API Key但必须显式指定外部 API 模式——服务端处理 LLM本地无需配置。配置详解所有设置都保存在~/.hindsight/cursor.json每一项也都可以用环境变量覆盖。插件内置了合理的默认值见 settings.json 与 config.py 中的DEFAULTS字典通常你只需配置想要改变的部分。加载顺序后加载者胜出见load_config()实现内置默认值硬编码在插件中插件settings.json随插件分发位于CURSOR_PLUGIN_ROOT/settings.json用户配置~/.hindsight/cursor.json推荐在此覆盖环境变量。环境变量映射与类型转换定义在 config.py 的ENV_OVERRIDES布尔值接受true/1/yes数值做整数转换转换失败则静默忽略该覆盖。连接与守护进程配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL空外部 Hindsight API 服务器地址。为空时插件改用本地守护进程或按上文兜底逻辑回落托管后端。hindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 的认证令牌仅在设置了hindsightApiUrl时需要。apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程使用的端口。embedVersionHINDSIGHT_EMBED_VERSIONlatest通过uvx安装的hindsight-embed版本。embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed开发目录路径此时改用uv run --directory path hindsight-embed。useLocalDaemonHINDSIGHT_USE_LOCAL_DAEMONfalse是否让插件自动启动本地守护进程。默认 false空hindsightApiUrl会回落托管后端设为 true 则恢复自动起本地 daemon的经典行为。daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT300守护进程空闲超时秒映射为HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT。useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue是否启用.cursor/rules/hindsight-session.mdc规则文件绕行方案针对 Cursor 的additionalContext竞态。appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue是否把生成的会话规则文件追加进.gitignore。LLM 提供方仅本地守护进程模式这些设置配置本地守护进程用于事实提取的 LLM。连接外部 API 时被忽略服务端负责 LLM。配置项环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDER自动检测LLM 提供方openai、anthropic、gemini、groq、ollama。通过检测 API Key 环境变量自动判断。llmModelHINDSIGHT_LLM_MODEL提供方默认覆盖所选提供方的默认模型。llmApiKeyEnv—提供方标准存放 API Key 的环境变量名非标准场景。记忆 BankBank 是隔离的记忆存储——好比一个独立的大脑。配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为false时使用的 Bank ID。bankMissionHINDSIGHT_BANK_MISSION通用助手提示对 Agent 身份与用途的描述settings.json中自带一段针对 Cursor 编程助手的默认使命文本。retainMission—null保留阶段的提取指令如提取技术决策、架构选择、用户偏好……忽略日常寒暄。dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时根据上下文字段派生唯一 Bank ID见dynamicBankGranularity。dynamicBankGranularity—[agent, project]用于派生动态 Bank ID 的字段组合agent、project、session、channel、user。bankIdPrefix—前缀字符串加在一切 Bank ID 前做命名空间隔离。agentNameHINDSIGHT_AGENT_NAMEcursor动态 Bank ID 派生中agent字段使用的名称。动态 Bank ID 的派生实现见 bank.py各字段取值后经 URL 编码用::连接如cursor::myprojectproject取cwd的 basename、session取conversation_id、channel默认default、user默认anonymous后两者可分别通过HINDSIGHT_CHANNEL_ID、HINDSIGHT_USER_ID环境变量注入。会话回忆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查询字符串最大字符数。recallContextTurnsHINDSIGHT_RECALL_CONTEXT_TURNS1回忆时考虑的上下文轮数。recallPromptPreamble—见settings.json注入记忆块前的前缀提示词默认提示 Agent 优先采纳近期记忆、只使用对继续对话有用的记忆。自动保留Auto-Retain自动保留在 Agent 完成任务后运行提取会话文本并发送到 Hindsight。配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动保留总开关。retainModeHINDSIGHT_RETAIN_MODEfull-session保留策略full-session或chunked。retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10保留频率。1 每轮都保留。retainOverlapTurns—2分块模式下为保持连续性额外包含上一块的轮数。retainContextHINDSIGHT_RETAIN_CONTEXTcursor保留记忆的来源标签Hindsight 按来源聚类记忆例如claude-code与手动保留区分。retainToolCalls—false保留的转录中是否包含工具调用。为true时输出完整 JSON 结构化消息含 tool_use 输入与截断到 2000 字符的 tool_result为false时输出带[role: ...]...[role:end]标记的文本格式。retainTags—[{session_id}]附加标签支持{session_id}、{bank_id}、{timestamp}模板变量替换。retainMetadata—{}附加元数据同样支持模板变量插件还会自动写入retained_at、message_count、session_id。分块模式的细节值得注意见 retain.py周期触发时按用户消息边界向后切出retainEveryNTurns retainOverlapTurns轮的窗口而sessionEnd冲刷时没有轮次窗口可切直接保留水位线之后的新增消息保证块之间互不重叠。调试配置项环境变量默认值说明debugHINDSIGHT_DEBUGfalse向 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判断发生了什么。状态写入实现在 state.py而各状态字段由 session_start.py 与 retain.py 填充——例如保留被轮次闸门拦下时会记录status: skipped、reason: turn_window、turn与next_at。常见问题排查插件未激活检查插件目录下是否存在.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。记忆至少需要完成一次保留周期才会被检索到。守护进程启动失败确保设置了 LLM API Key。查看守护进程日志~/.hindsight/profiles/cursor.log。会话启动延迟高会话回忆 Hook 有 15 秒超时。可改用recallBudget: low或调低recallMaxTokens。深入阅读本集成的全部源码、默认配置与测试均位于仓库 hindsight-integrations/cursorCLI 与安装逻辑hindsight_cursor/cli.py——init/uninstall、Hook 注册表生成、MCP 配置合并Hook 脚本scripts/session_start.py、scripts/retain.py运行库config.py配置加载、daemon.py连接模式与守护进程、client.pyREST 客户端recall / retain / set_bank_mission 端点、bank.pyBank ID 派生、content.py转录格式化与记忆标签剥离、rules_file.py规则文件绕行方案、llm.pyLLM 检测默认配置settings.jsonHook 模板hooks/hooks.json配套资产rules/hindsight-memory.mdc、skills/hindsight-recall/SKILL.md测试用例tests——覆盖配置加载与覆盖test_config.py、CLI 安装/卸载test_cli.py、Bank ID 派生test_bank.py、转录内容处理test_content.py、守护进程生命周期test_daemon.py、Hook 注册test_hooks.py、规则文件test_rules_file.py及端到端流程test_e2e.py。如果你希望用同样的记忆能力打通其他编程工具可在 hindsight-integrations/README.md 中查看本仓库支持的全部分支例如 Claude Code、Codex、OpenHands、Continue、Cursor CLI 等对应的文档均收录在 hindsight-docs/docs-integrations。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hindsight Cursor 集成指南：为 Cursor 接入跨会话长期记忆（Hook 自动回忆 + MCP 按需记忆工具）
Hindsight Cursor 集成指南为 Cursor 接入跨会话长期记忆Hook 自动回忆 MCP 按需记忆工具【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文是一份面向 Cursor 用户与 AI 编程代理开发者的实操指南完整讲解如何通过官方hindsight-cursor插件让 Cursor 在会话启动时自动回忆项目级长期记忆、在任务结束时自动沉淀对话内容并在会话中途通过 MCP 工具按需执行 recall / retain / reflect 记忆操作。读完本文你将掌握插件安装与卸载、三种连接模式、全部配置项及其环境变量覆盖方式、Hook 触发验证与常见故障排查方法并从源码层面理解会话回忆、自动保留与防重复存储的底层实现。背景与定位Cursor 是当前流行的 AI 代码编辑器之一其每次会话都从空白上下文开始上一轮讨论过的技术决策、用户偏好与项目约定除非显式写入文档否则不会自动出现在新会话中。Hindsight 提供类生物的长期记忆能力项目名为 Hindsight: Agent Memory That Learns而hindsight-cursor插件正是把这一能力嫁接到 Cursor 的载体。插件适配了 Cursor 的Hook 机制自动触发回忆与保留与MCP 机制会话中按需调用记忆工具二者互补由同一条命令hindsight-cursor init一次性完成安装。本仓库中该集成的完整实现位于 hindsight-integrations/cursor包含 CLIcli.py、Hook 脚本session_start.py、retain.py、运行库scripts/lib/与测试tests。工作原理两种互补的记忆机制插件使用两套机制协同工作| | 插件 Hooks自动 | MCP 工具按需 | |--|--------------------------|----------------------| |安装|pip install hindsight-cursor hindsight-cursor init| 由init自动配置 | |回忆Recall| 会话启动时通过additionalContext注入记忆 | Agent 在会话中调用recall工具 | |保留Retain| 任务结束时自动执行 | Agent 显式调用retain工具 | |反思Reflect| Hooks 不可用 | 作为工具提供 | |适用场景| 无需用户干预的沉浸式项目记忆 | 定向查找与显式记忆操作 |两种机制都由单条hindsight-cursor init命令完成配置如果只想用 Hooks、不需要 MCP可加--no-mcp跳过。从源码看init写入的 Hook 注册表实际包含三个事件。查看 cli.py 中的_project_hooks_block()sessionStart→ 执行scripts/session_start.py超时 15 秒stop→ 执行scripts/retain.py超时 15 秒sessionEnd→ 同样执行scripts/retain.py超时 15 秒。对应地仓库中随包分发的模板 hooks/hooks.json 也声明了这三个事件但它使用${CURSOR_PLUGIN_ROOT}变量仅适用于安装在~/.cursor/plugins下的场景而init会改写成工作区相对路径确保不依赖该环境变量也能运行。快速开始# 1. 安装插件 pip install hindsight-cursor cd /path/to/your-project # 2a. 连接 Hindsight Cloud最快——无需本地服务器 hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN # 2b. 或连接本地 Hindsight 服务器 hindsight-cursor init --api-url http://localhost:8888 # 3. 完全退出并重新打开 Cursor —— 插件在启动时加载⚠️重要如果向一个已经打开的 Cursor 工作区添加插件必须完全退出 Cursor 后重新打开。插件在启动时加载仅刷新窗口window reload不够。获取 Hindsight 服务端两种方式任选其一方式一Hindsight Cloud。注册获得 API Token 后在init时通过--api-url与--api-token传入。方式二本地 Docker 自托管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流程init依次完成拷贝插件文件到项目下的.cursor-plugin/hindsight-memory/文件清单定义在_PLUGIN_FILES共 16 个文件包含 Hook 脚本、settings.json、规则文件与技能文件。源码注释强调任何文件缺失都会中止安装并报错——因为session_start.py会 importlib/下所有模块缺一个文件就会让每次 Hook 调用变成静默 ImportError写入/合并项目的.cursor/hooks.json让 Cursor 注册 Hook。_setup_hooks()是幂等的已有用户的 Hook 会被保留重复执行init只替换 Hindsight 自己的条目通过_HOOK_MARKER .cursor-plugin/hindsight-memory识别归属。注意 Cursor 只从.cursor/hooks.json工作区或~/.cursor/hooks.json用户级加载 Hook——仅把文件丢进.cursor-plugin/是不够的创建~/.hindsight/cursor.json若文件尚不存在写入连接设置写入.cursor/mcp.json配置 Hindsight 的 MCP 端点。_setup_mcp()使用单 bank 端点{api_url}/mcp/{bank_id}/并将Authorization: Bearer token写入请求头使 recall / retain / reflect 工具自动限定在配置的 bank 内、无需每次传bank_id--force覆盖已有安装--no-mcp跳过 MCP 配置。卸载hindsight-cursor uninstall会全部还原——删除插件目录、从.cursor/hooks.json移除 Hindsight 条目、删除 MCP 服务器条目、删除生成的会话规则文件以及对应的.gitignore行。其中_remove_session_rules()的存在是有讲究的会话规则文件会在每次sessionStart时重新生成若卸载后残留其alwaysApply: true属性会让已死会话的记忆继续注入每一次 Agent 轮次。核心特性会话回忆Session recall——每个会话开始时向 Hindsight 查询项目相关记忆通过additionalContext注入上下文对聊天界面不可见对 Agent 可见自动保留Auto-retain——每个任务完成后提取会话内容并存储到 Hindsight 长期记忆按需 MCP 工具——recall、retain、reflect三个工具支持会话中途的显式记忆操作按需回忆技能Skill——hindsight-recall技能支持手动记忆查询守护进程管理——可自动启停本地hindsight-embed或连接外部 Hindsight 服务器动态 Bank ID——支持按 Agent、按项目、按会话隔离记忆零运行时依赖——插件脚本仅使用 Python 标准库。架构三个 Hook 事件如何协同插件构建在 Cursor 的 Hook 系统之上具体事件分工如下Hook事件用途session_start.pysessionStart会话回忆——查询记忆注入为additionalContextretain.pystop自动保留——提取会话文本POST 到 Hindsightretain.pysessionEnd最终冲刷——保留轮次窗口未能覆盖的尾部内容会话回忆sessionStartsessionStart事件在每个新 Cursor 会话开始时触发一次执行一次广谱的项目级回忆并把相关记忆注入为隐藏上下文。查看 session_start.py 的实现其完整流程是从 stdin 读取 Hook 输入workspace_roots、conversation_id等解析 API 地址外部 API / 已有本地服务 / 自动启动守护进程见下文连接模式派生 Bank ID静态或基于项目上下文动态派生见 bank.py首次使用时确保 Bank Mission 已设置ensure_bank_mission基于工作区上下文构造广谱查询——项目名来自workspace_roots的 basename叠加配置的bankMission并以recallMaxQueryChars默认 800截断调用 Hindsight 回忆 API超时 10 秒参数含max_tokens、budget、types将记忆格式化为hindsight_memories块输出additionalContext写入last_recall.json状态文件。值得注意的一个健壮性细节脚本总是以退出码 0 结束任何错误都优雅降级避免 Hook 失败反过来干扰 Cursor 的正常会话启动。自动保留与最终冲刷stop sessionEndretain.py同时注册在stop与sessionEnd两个事件上这是有明确原因的——只看 retain.py 的实现与注释stop在每次 Agent 循环结束时触发是周期性自动保留的合适粒度但每次触发都要过轮次闸门retainEveryNTurns。默认值为 10 时一段 7 轮的对话会触发 7 次stop、被闸门拦下 7 次最终永远不会被存储sessionEnd在对话结束时触发一次携带相同的transcript_path被当作最终冲刷final flush它绕过轮次窗口无论会话停在哪一轮尾部内容都会被保留。两者在会话末尾重叠插件为每个会话维护一个已保留消息数的水位线retained.json见 state.py当一次调用发现没有新增消息时直接跳过因此重叠不会导致重复存储。其他值得展开的实现细节转录读取兼容三种格式扁平式{role, content}、类型嵌套式{type, message: {...}}以及 Cursor 3.x 的角色嵌套式{role, message: {content: [blocks...]}}。注释明确指出 Cursor 3.6.31 实际写入~/.cursor/projects/workspace/agent-transcripts/conv/conv.jsonl的就是角色嵌套格式早期解析器因不认识该结构会在每个 stop 钩子上静默丢弃全部内容empty_transcript问题文档 ID 去重document_id {session_id}-{毫秒时间戳}保证同一会话内多次保留写入的是不同文档而非互相覆盖——旧设计在 full-session 模式下用session_id作文档 ID多轮会话重复保留时会静默丢弃早期轮次防反馈循环保留前会剥离hindsight_memories/relevant_memories块见 content.py避免把回忆注入的内容当作新记忆再次存储。一个上游竞态的绕行方案Cursor 的sessionStartHook 虽然接受additionalContextJSON 输出但在 Agent 的 composer 句柄就绪前会静默丢弃该内容——这是 Cursor 官方论坛确认的竞态问题在 Cursor 3.6.31 中仍存在。插件的绕行方案见 rules_file.py是把回忆到的记忆写入工作区.cursor/rules/hindsight-session.mdc该文件带alwaysApply: true前置元数据规则引擎会可靠地把内容注入 Agent 上下文。每次sessionStart开头会先轮换删除旧规则文件避免上一会话的过期记忆残留若工作区是 Git 仓库还会把该规则文件追加进.gitignore。同时 Hook 仍会输出additionalContext以兼容未来修复后的原生路径。Skill 与 Ruleinit还会安装两个配套资产技能Skillhindsight-recall/SKILL.md——按需记忆查询规则Rulerules/hindsight-memory.mdc——常驻规则指示 Agent 善用回忆到的记忆与 MCP 工具。三种连接模式插件通过 daemon.py 的get_api_url()按优先级解析 API 地址1. 外部 API生产环境推荐连接一个正在运行的 Hindsight 服务器云端或自托管。无需本地 LLM——事实提取由服务端完成。{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }对应源码中的 Mode 1显式配置的hindsightApiUrl优先级最高直接返回。2. 本地守护进程自动托管插件通过uvx自动启停hindsight-embed。本地事实提取需要 LLM 提供方的 API Keyexport OPENAI_API_KEYsk-your-key # 或 export ANTHROPIC_API_KEYyour-key模型由 Hindsight API 自动选择可用HINDSIGHT_LLM_MODEL覆盖。注意这是需要显式开启的模式useLocalDaemon: true对应源码 Mode 3。守护进程启动流程在 daemon.py 中分三步profile create创建cursor配置--merge --port port并注入 LLM 环境变量与 5 分钟空闲超时→daemon --profile cursor start启动 → 每 1 秒探测一次/health最多 30 秒等待就绪。macOS 上还会额外设置HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1强制 CPU 推理。3. 已有本地服务器如果hindsight-embed已在运行对应源码 Mode 2保持hindsightApiUrl为空、把apiPort设为服务器端口插件会通过健康检查自动探测并复用不重复启动守护进程。兜底逻辑当以上都不满足时对应源码 Mode 4插件回落到默认托管后端地址https://api.hindsight.vectorize.io定义于 config.py。这与全项目默认上云的跨集成约定一致全新安装、零配置也能直连托管后端自托管用户通过设置显式hindsightApiUrl或useLocalDaemon: true回到本地路径。LLM 提供方检测本地守护进程模式需要 LLM 做事实提取检测优先级见 llm.pyHINDSIGHT_API_LLM_PROVIDER等HINDSIGHT_API_LLM_*环境变量最高优先级插件配置llmProvider/llmModel/llmApiKeyEnv从标准环境变量自动检测OPENAI_API_KEY→ANTHROPIC_API_KEY→GEMINI_API_KEY→GROQ_API_KEYollama、openai-codex、claude-code、github-copilot无需 API Key但必须显式指定外部 API 模式——服务端处理 LLM本地无需配置。配置详解所有设置都保存在~/.hindsight/cursor.json每一项也都可以用环境变量覆盖。插件内置了合理的默认值见 settings.json 与 config.py 中的DEFAULTS字典通常你只需配置想要改变的部分。加载顺序后加载者胜出见load_config()实现内置默认值硬编码在插件中插件settings.json随插件分发位于CURSOR_PLUGIN_ROOT/settings.json用户配置~/.hindsight/cursor.json推荐在此覆盖环境变量。环境变量映射与类型转换定义在 config.py 的ENV_OVERRIDES布尔值接受true/1/yes数值做整数转换转换失败则静默忽略该覆盖。连接与守护进程配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL空外部 Hindsight API 服务器地址。为空时插件改用本地守护进程或按上文兜底逻辑回落托管后端。hindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 的认证令牌仅在设置了hindsightApiUrl时需要。apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程使用的端口。embedVersionHINDSIGHT_EMBED_VERSIONlatest通过uvx安装的hindsight-embed版本。embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed开发目录路径此时改用uv run --directory path hindsight-embed。useLocalDaemonHINDSIGHT_USE_LOCAL_DAEMONfalse是否让插件自动启动本地守护进程。默认 false空hindsightApiUrl会回落托管后端设为 true 则恢复自动起本地 daemon的经典行为。daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT300守护进程空闲超时秒映射为HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT。useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue是否启用.cursor/rules/hindsight-session.mdc规则文件绕行方案针对 Cursor 的additionalContext竞态。appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue是否把生成的会话规则文件追加进.gitignore。LLM 提供方仅本地守护进程模式这些设置配置本地守护进程用于事实提取的 LLM。连接外部 API 时被忽略服务端负责 LLM。配置项环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDER自动检测LLM 提供方openai、anthropic、gemini、groq、ollama。通过检测 API Key 环境变量自动判断。llmModelHINDSIGHT_LLM_MODEL提供方默认覆盖所选提供方的默认模型。llmApiKeyEnv—提供方标准存放 API Key 的环境变量名非标准场景。记忆 BankBank 是隔离的记忆存储——好比一个独立的大脑。配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为false时使用的 Bank ID。bankMissionHINDSIGHT_BANK_MISSION通用助手提示对 Agent 身份与用途的描述settings.json中自带一段针对 Cursor 编程助手的默认使命文本。retainMission—null保留阶段的提取指令如提取技术决策、架构选择、用户偏好……忽略日常寒暄。dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时根据上下文字段派生唯一 Bank ID见dynamicBankGranularity。dynamicBankGranularity—[agent, project]用于派生动态 Bank ID 的字段组合agent、project、session、channel、user。bankIdPrefix—前缀字符串加在一切 Bank ID 前做命名空间隔离。agentNameHINDSIGHT_AGENT_NAMEcursor动态 Bank ID 派生中agent字段使用的名称。动态 Bank ID 的派生实现见 bank.py各字段取值后经 URL 编码用::连接如cursor::myprojectproject取cwd的 basename、session取conversation_id、channel默认default、user默认anonymous后两者可分别通过HINDSIGHT_CHANNEL_ID、HINDSIGHT_USER_ID环境变量注入。会话回忆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查询字符串最大字符数。recallContextTurnsHINDSIGHT_RECALL_CONTEXT_TURNS1回忆时考虑的上下文轮数。recallPromptPreamble—见settings.json注入记忆块前的前缀提示词默认提示 Agent 优先采纳近期记忆、只使用对继续对话有用的记忆。自动保留Auto-Retain自动保留在 Agent 完成任务后运行提取会话文本并发送到 Hindsight。配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动保留总开关。retainModeHINDSIGHT_RETAIN_MODEfull-session保留策略full-session或chunked。retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10保留频率。1 每轮都保留。retainOverlapTurns—2分块模式下为保持连续性额外包含上一块的轮数。retainContextHINDSIGHT_RETAIN_CONTEXTcursor保留记忆的来源标签Hindsight 按来源聚类记忆例如claude-code与手动保留区分。retainToolCalls—false保留的转录中是否包含工具调用。为true时输出完整 JSON 结构化消息含 tool_use 输入与截断到 2000 字符的 tool_result为false时输出带[role: ...]...[role:end]标记的文本格式。retainTags—[{session_id}]附加标签支持{session_id}、{bank_id}、{timestamp}模板变量替换。retainMetadata—{}附加元数据同样支持模板变量插件还会自动写入retained_at、message_count、session_id。分块模式的细节值得注意见 retain.py周期触发时按用户消息边界向后切出retainEveryNTurns retainOverlapTurns轮的窗口而sessionEnd冲刷时没有轮次窗口可切直接保留水位线之后的新增消息保证块之间互不重叠。调试配置项环境变量默认值说明debugHINDSIGHT_DEBUGfalse向 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判断发生了什么。状态写入实现在 state.py而各状态字段由 session_start.py 与 retain.py 填充——例如保留被轮次闸门拦下时会记录status: skipped、reason: turn_window、turn与next_at。常见问题排查插件未激活检查插件目录下是否存在.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。记忆至少需要完成一次保留周期才会被检索到。守护进程启动失败确保设置了 LLM API Key。查看守护进程日志~/.hindsight/profiles/cursor.log。会话启动延迟高会话回忆 Hook 有 15 秒超时。可改用recallBudget: low或调低recallMaxTokens。深入阅读本集成的全部源码、默认配置与测试均位于仓库 hindsight-integrations/cursorCLI 与安装逻辑hindsight_cursor/cli.py——init/uninstall、Hook 注册表生成、MCP 配置合并Hook 脚本scripts/session_start.py、scripts/retain.py运行库config.py配置加载、daemon.py连接模式与守护进程、client.pyREST 客户端recall / retain / set_bank_mission 端点、bank.pyBank ID 派生、content.py转录格式化与记忆标签剥离、rules_file.py规则文件绕行方案、llm.pyLLM 检测默认配置settings.jsonHook 模板hooks/hooks.json配套资产rules/hindsight-memory.mdc、skills/hindsight-recall/SKILL.md测试用例tests——覆盖配置加载与覆盖test_config.py、CLI 安装/卸载test_cli.py、Bank ID 派生test_bank.py、转录内容处理test_content.py、守护进程生命周期test_daemon.py、Hook 注册test_hooks.py、规则文件test_rules_file.py及端到端流程test_e2e.py。如果你希望用同样的记忆能力打通其他编程工具可在 hindsight-integrations/README.md 中查看本仓库支持的全部分支例如 Claude Code、Codex、OpenHands、Continue、Cursor CLI 等对应的文档均收录在 hindsight-docs/docs-integrations。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
