Hindsight for Cursor 插件实战为 Cursor 会话接入跨会话长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文基于 hindsight-integrations/cursor/README.md 与插件源码编写讲解 Hindsight 记忆插件如何在 Cursor 中实现会话开始自动回忆 会话结束自动留存 会话中按需检索三种记忆能力并完整给出安装命令、init的内部行为、全部配置参数、Bank ID 派生规则与 Cursor 3.xadditionalContext注入缺陷的绕开方案。读完你可以直接在项目里安装并调优该插件理解其 Hook 机制与状态持久化细节。插件定位与核心能力Hindsight for Cursor 是基于 Hindsight 的仿生长期记忆插件它在每次 Cursor 会话开始时查询相关项目记忆并注入上下文同时把对话转录留存到 Hindsight 供未来回忆。插件包名为hindsight-cursor见 pyproject.toml版本 0.2.0MIT 协议一个值得注意的设计约束是零运行时依赖——所有 Hook 脚本仅使用 Python 标准库urllib、json、fcntl等pyproject.toml 中dependencies []。插件提供五类能力会话召回Session recall每次会话开始时查询 Hindsight 中与项目相关的记忆通过additionalContext与 rules 文件两条通道注入自动留存Auto-retain每轮任务结束后提取对话转录并留存按需 MCP 工具会话中通过 Hindsight MCP 服务器调用recall/retain/reflect三个显式工具按需召回技能hindsight-recall技能用于显式记忆查找见 skills/hindsight-recall/SKILL.mdDaemon 管理可本地自动启停hindsight-embed或连接外部 Hindsight 服务器动态 Bank ID支持按 agent、project、session 维度隔离记忆。快速开始两种后端接入方式方式 AHindsight Cloud最快路径无需本地服务器。注册 Hindsight Cloud 并在Settings API Keys创建 API key 后cd /path/to/your-project pip install hindsight-cursor hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN如果 Cursor 已经打开安装后必须完全退出并重新打开。插件在启动时加载。方式 B本地 Hindsight 服务器Dockerexport 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:latest容器通过-v $HOME/.hindsight-docker:/home/hindsight/.pg0将内置数据库目录挂到宿主机保证记忆跨容器重建持久化。然后cd /path/to/your-project pip install hindsight-cursor hindsight-cursor init --api-url http://localhost:8888如果不想永久安装包可以用uvx hindsight-cursor init一步完成。init到底做了什么init的实现在 hindsight_cursor/cli.py。结合源码其行为比文档描述更细复制插件文件到project/.cursor-plugin/hindsight-memory/。文件清单由_PLUGIN_FILES硬编码8 个lib/模块 session_start.pyretain.pysettings.json skill 等复制前做完整性校验——若内置文件缺失会直接报错退出因为session_start.py会导入全部lib/模块缺一个文件就会让每次 Hook 调用变成静默的 ImportError代码注释明确提到这是过去一次静默安装失败事故后加的保护。写入/合并项目级.cursor/hooks.json注册sessionStart/stop/sessionEnd三个 Hook。这是关键点只把文件放进.cursor-plugin/目录是不会被 Cursor IDE 加载的Cursor 只读 workspace 或 user 级的hooks.json。合并逻辑以.cursor-plugin/hindsight-memory作为标记识别 Hindsight 自己的条目——重跑init只会替换 Hindsight 条目已有其他 Hook 的条目原样保留。每个 Hook 的timeout为 15 秒。另外 Windows 上没有python3命令代码会根据sys.platform自动选择python/python3解释器名见_hook_interpreter()。创建~/.hindsight/cursor.json若不存在写入bankId及传入的--api-url/--api-token。写入.cursor/mcp.json接入 Hindsight 的单 Bank MCP 端点{api_url}/mcp/{bank_id}/并带Authorization: Bearer头——用单 Bank 端点后recall/retain/reflect工具无需再传bank_id参数。此步可用--no-mcp跳过。--force覆盖已有安装uninstall会移除插件目录、Hindsight 的 Hook 条目、MCP 服务器条目、生成的 session rules 文件及其.gitignore行。安装完成后完全退出并重开 Cursor插件即自动生效。架构Hook 自动化通道 MCP 按需通道插件用两个互补机制实现记忆1. Plugin Hooks自动Hook事件用途session_start.pysessionStart会话召回——查询记忆、写入workspace/.cursor/rules/hindsight-session.mdc使 agent 在系统上下文中获得记忆同时输出additionalContextJSON前向兼容retain.pystop自动留存——提取转录、POST 到 Hindsightretain.pysessionEnd最终冲刷final flush——留存 turn 窗口还没来得及存的部分注册配置即 hooks/hooks.json${CURSOR_PLUGIN_ROOT}为插件安装根init生成的项目级 Hook 则使用 workspace 相对路径。sessionStart在 agent 处理每个新 chat 的第一条 prompt 时触发。session_start.py 的流程读取 stdin 的 Hook 输入workspace_roots、conversation_id→ 解析 API URL外部/本地/自动起 daemon→ 派生 Bank ID → 首次使用时设置 bank mission → 用工作区上下文项目名 bankMission构造宽泛的项目级查询超过recallMaxQueryChars默认 800 字符会截断→ 调用 Hindsight recall API → 格式化记忆并输出。任何错误都优雅降级退出码恒为 0。stop在 agent 完成一轮任务时触发读取对话转录并留存。sessionEnd作为 final flush 是刻意设计。源码 retain.py 的模块 docstring 给出了具体场景在默认retainEveryNTurns 10下一段 7 轮的对话会触发 7 次stop但每一次都被 turn 窗口拒绝turn_count % 10 ! 0整个会话永远不会被存储。sessionEnd绕过 turn 窗口保证会话尾部一定被留存。两个事件在会话末尾重叠时插件按会话记录已留存的消息数watermark存于retained.json没有新消息的运行直接 no-op因此重叠不会重复存储。会话记忆如何真正到达 AgentCursor 3.x 缺陷绕行Cursor 的sessionStartHook 原生注入通道是additionalContextJSON 字段——Hook 把记忆文本输出到 stdoutCursor 应将其放进 agent 的系统提示词。但 README 指出该通道在 Cursor 3.x 中已失效Cursor 官方在论坛确认且在 3.6.31 上仍为 open 状态。若additionalContext是唯一投递路径召回的记忆到不了模型agent 会表现得像没装插件。插件的绕行方案是同时把召回记忆写入workspace/.cursor/rules/hindsight-session.mdc其 frontmatter 带alwaysApply: true实现见 lib/rules_file.py。workspace rules 文件会被 Cursor 的 rules 引擎可靠注入因此 agent 在每次新 chat 的第一条 prompt 就能看到记忆。实际效果每个新 agent 的首条 prompt 都带记忆。Cursor 会等sessionStartHook 返回后才放行 prompt——延迟仅为召回本身通常 1srules 文件在每次sessionStart开始时先删除再重写rotate_session_rules上一会话的陈旧记忆不会残留——即使本次召回为空工作区也不会有过期 rules 文件rules 文件会被自动追加进.gitignore仅 git 工作区幂等非 git 工作区为 no-op手动删除也安全会被重新生成additionalContext仍照常输出到 stdout作为前向兼容。一旦 Cursor 修复原生通道同一插件无需改代码继续工作。可通过useRulesFileFallback: false完全禁用 rules 文件写入——此时插件完全依赖additionalContext意味着在 Cursor 修复上游缺陷前不会有记忆投递。README 直言这仅适合宁可看到 bug 发作、也不让插件动你的工作区的场景。2. MCP 服务器按需init同时配置了 Cursor 的原生 MCP 支持.cursor/mcp.json直连 Hindsight 的 MCP 端点为 agent 提供显式工具recall— 按查询检索特定记忆retain— 把特定内容存入记忆reflect— 针对问题对累积记忆做推理。agent 可以在会话中途使用这些工具获取超出会话开始注入范围之外的记忆。hindsight-recall 技能 还规定了工作流守则先检查当前上下文的hindsight_memories是否已覆盖需求不足时再用 MCPrecall深挖记忆与当前上下文冲突时以当前上下文为准并指出差异。库模块模块职责lib/client.pyHindsight REST API 客户端标准库urlliblib/config.py配置加载器settings.json 环境变量覆盖lib/daemon.pyhindsight-embeddaemon 生命周期start/stop/healthlib/bank.pyBank ID 派生 mission 管理lib/content.py内容处理转录解析、记忆格式化、标签剥离lib/state.py基于文件的持久化带fcntl锁lib/rules_file.py写.cursor/rules/hindsight-session.mdcsessionStart additionalContext 绕行lib/llm.pydaemon 模式下的 LLM 提供方自动探测客户端细节值得说明HindsightClient会校验 API URL 必须是 http/https 且含 hostnamerecall 请求打到POST /v1/default/banks/{bank_id}/memories/recall携带query、max_tokens、budget、types参数见 lib/client.py。每次 Hook 运行都会把诊断状态写入本地 state如last_recall.json/last_retain.json含状态、原因、Bank ID、结果数配合debug: true的 stderr 日志可以定位为什么没召回/没留存。三种连接模式1. 外部 API生产环境推荐连接运行中的 Hindsight 服务器云或自托管{ hindsightApiUrl: https://your-hindsight-server.com, hindsightApiToken: your-token }2. 本地 Daemon自动管理插件通过uvx自动启停hindsight-embed需要一个 LLM 提供方 API key{ hindsightApiUrl: , apiPort: 9077 }从 lib/daemon.py 的get_api_url()可以看出解析优先级先检查配置的 URL 是否健康请求/health→ 检查配置端口上是否已有本地服务器在跑 → 允许 daemon 启动时会话开始/留存路径允许自动拉起 embed。3. 已有本地服务器若你已有hindsight-embed在运行把hindsightApiUrl留空并将apiPort设为该服务器端口即可。配置系统四层加载顺序所有配置集中在~/.hindsight/cursor.json每个配置项都可用环境变量覆盖插件自带合理默认值。加载顺序后者覆盖前者实现在 lib/config.py 的load_config()内置默认值硬编码在DEFAULTS字典中插件自带的settings.jsonCURSOR_PLUGIN_ROOT/settings.json用户配置~/.hindsight/cursor.json环境变量插件自带的 settings.json 预置了两段对编码场景高度定制的 mission 文案bankMission声明你是 Cursor 编码助手关注技术讨论、架构决策、代码模式、用户偏好与项目上下文retainMission则指示提取技术决策、架构选择、用户偏好、项目上下文与工具/库关系忽略寒暄和临时运维细节。retainTags默认值[{session_id}]会为每条留存文档打上会话 ID 标签支持{session_id}/{bank_id}/{timestamp}模板变量。连接与 Daemon设置环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URL外部 Hindsight API 服务器 URLhindsightApiTokenHINDSIGHT_API_TOKENnull外部 API 的认证 tokenapiPortHINDSIGHT_API_PORT9077本地hindsight-embeddaemon 端口embedVersionHINDSIGHT_EMBED_VERSIONlatest安装的hindsight-embed版本embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地hindsight-embed包路径开发覆盖记忆 Bank设置环境变量默认值说明bankIdHINDSIGHT_BANK_IDcursordynamicBankId为 false 时使用的 Bank IDdynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse从上下文字段派生 Bank IDdynamicBankGranularity—[agent, project]派生动态 Bank ID 的字段agent, project, sessionbankIdPrefix—加在所有 Bank ID 前的前缀agentNameHINDSIGHT_AGENT_NAMEcursor动态 Bank ID 的 agent 名bankMissionHINDSIGHT_BANK_MISSION设置在 Bank 上的 mission仅首次使用时retainMission—nullBank 的自定义 retain mission动态 Bank ID 的派生逻辑lib/bank.py 的derive_bank_id()开启dynamicBankId后按dynamicBankGranularity列表从上下文中取字段——agent取agentName、project取 cwd 的目录名、session取会话 ID另支持channel/user来自环境变量HINDSIGHT_CHANNEL_ID/HINDSIGHT_USER_ID各段做 URL 编码后用::连接无效字段名会输出告警到 stderr。bankMission通过本地bank_missions.json状态记录已设置过的 Bank保证只写入一次。会话召回设置环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue启用/禁用会话开始召回recallBudgetHINDSIGHT_RECALL_BUDGETmid搜索深度low, mid, highrecallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024召回记忆块的最大 token 数recallTypes—[world, experience]要召回的记忆类型recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800召回查询的最大字符数recallPromptPreamble—(见 settings.json)拼在召回记忆前的文本useRulesFileFallbackHINDSIGHT_USE_RULES_FILE_FALLBACKtrue将召回记忆写入workspace/.cursor/rules/hindsight-session.mdc由 Cursor rules 引擎注入。用于绕行原生additionalContext通道的缺陷appendToGitignoreHINDSIGHT_APPEND_TO_GITIGNOREtrue写 rules 文件回退时幂等追加其路径到工作区.gitignore非 git 工作区为 no-op自动留存设置环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue启用/禁用自动留存retainModeHINDSIGHT_RETAIN_MODEfull-session留存策略full-session或chunkedretainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS10每 N 轮留存一次1 每轮retainOverlapTurns—2块间重叠轮数仅 chunked 模式retainToolCalls—false留存的转录是否包含工具调用消息retainContextHINDSIGHT_RETAIN_CONTEXTcursor留存记忆的来源标签retainTags—[]应用于留存文档的标签支持{session_id}模板retainMetadata—{}留存文档上的额外元数据留存路径的两个工程细节源自 retain.py转录解析兼容三种 JSONL 形态flat{role, content}、type-nested{type, message: {...}}、以及 Cursor 3.x 的 role-nested{role, message: {content: [...blocks...]}}。旧版两分支解析器对 Cursor 3.6.31 写的转录会静默丢弃全部行、导致每次 stop Hook 都以empty_transcript退出现已在read_transcript()中修复且tool_use/tool_result块会被内联为紧凑标记。document_id 设计{session_id}-{毫秒时间戳}保证同一会话的多次留存累积为不同文档而非 upsert 覆盖同一文档旧设计document_idsession_id在 full-session 模式下会让多轮会话重新留存时静默丢掉早期轮次。LLMDaemon 模式设置环境变量默认值说明llmProviderHINDSIGHT_LLM_PROVIDERnulldaemon 模式的 LLM 提供方覆盖llmModelHINDSIGHT_LLM_MODELnulldaemon 模式的 LLM 模型覆盖llmApiKeyEnv—null包含 LLM API key 的环境变量名调试设置环境变量默认值说明debugHINDSIGHT_DEBUGfalse启用向 stderr 的详细日志卸载与测试卸载hindsight-cursor uninstall它会移除插件目录、从.cursor/hooks.json剥离 Hindsight 条目保留其他 Hook、删除 MCP 服务器条目、删除生成的 session rules 文件及.gitignore行——最后两项的清理尤其重要因为该 rules 文件是alwaysApply: true若卸载后残留会把上一个死会话的记忆继续注入每个 agent 轮次。测试pip install pytest python -m pytest tests/ -v测试覆盖 tests/ 下的 Bank 派生、配置加载、内容处理、daemon 生命周期、rules 文件、Hook 行为与 e2e 场景可用于在修改插件行为后回归验证。小结Hindsight for Cursor 把一个记忆系统完整嵌进了 Cursor 的生命周期sessionStart召回注入、stop周期留存、sessionEnd兜底冲刷、MCP 工具与 skill 提供会话中按需操作。其最值得借鉴的工程设计有三点一是Hook 注册必须落到项目级hooks.json这一对 IDE 插件机制的硬约束处理二是针对 Cursor 3.xadditionalContext失效的双通道投递rules 文件 前向兼容 stdout三是 watermark 防重、document_id 防覆盖、完整 payload 校验防静默失败这类对静默数据丢失的防御。配置面则通过四层覆盖内置默认 → 插件 settings.json →~/.hindsight/cursor.json→ 环境变量保持了云托管、自托管、本地 daemon 三种部署形态的平滑切换。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考