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 install+hindsight-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_KEY=your-key docker run --rm -it --pull always -p 8888:8888 \ -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \ -e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \ -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latest

3. 完全退出并重新打开 Cursor

插件在启动时加载，仅仅重新加载窗口是不够的。若 Cursor 正处于打开状态，安装后必须完全退出再重新打开。

init命令做了什么

从源码看，cli.py 中的cmd_init依次执行以下步骤：

1. 拷贝插件文件到.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；若捆绑包缺失任一文件，安装会直接报错退出，避免出现"静默无效安装"。
2. 写入/合并项目.cursor/hooks.json，让 Cursor 注册三个 Hook（sessionStart/stop/sessionEnd）。注意：Cursor 只从.cursor/hooks.json（工作区级）或~/.cursor/hooks.json（用户级）加载 Hook，.cursor-plugin/目录下的文件本身不会被 IDE 加载。你已有的其他 Hook 会被保留，重复执行init只替换 Hindsight 自己的条目——这是通过_HOOK_MARKER = ".cursor-plugin/hindsight-memory"标记来识别的（cli.py）。
3. 创建~/.hindsight/cursor.json，写入连接配置（若该文件已存在则跳过）。
4. 写入.cursor/mcp.json，配置 Hindsight MCP 端点用于按需工具。
5. --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 事件一览

插件注册了三个 Hook（hooks.json）：

sessionStart：会话召回

sessionStart在每个新 Cursor 会话开始、Agent 处理第一条提示词时触发一次。其完整流程（session_start.py）为：

1. 从 stdin 读取 Hook 输入（workspace_roots、conversation_id等）；
2. 解析 API 地址（外部 API → 已有本地服务器 → 本地守护进程 → 云端默认）；
3. 推导 bank ID（静态或基于项目上下文动态推导）；
4. 首次使用时设置 bank mission；
5. 基于工作区上下文（项目名、工作区根目录、bank mission）构造一条宽泛的项目级查询，并截断到recallMaxQueryChars（默认 800 字符）；
6. 调用 Hindsight 的 recall API（超时 10 秒，见 client.py 中POST /v1/default/banks/{bank_id}/memories/recall）；
7. 将召回的记忆格式化为<hindsight_memories>上下文块，输出additionalContext；
8. 将本次召回状态写入状态文件。

stop+sessionEnd：自动保留与最终冲刷

retain.py同时注册在stop和sessionEnd两个事件上，这是刻意设计（retain.py 与 cli.py 中的注释都解释了这个原因）：

• stop在每次 Agent 循环结束时触发，是周期性自动保留的理想粒度，但每次触发都受轮次窗口约束。在默认retainEveryNTurns = 10下，一个只有 7 轮对话的会话会触发 7 次stop，7 次都被轮次门控拒绝，最终整段会话永远不会被存储。
• sessionEnd在会话结束时只触发一次，作为最终冲刷：它绕过轮次窗口，无论会话结束在窗口的哪个位置，尾部内容都会被保留。

两个事件在会话末尾存在重叠。插件以会话为单位记录"已保留的消息条数"水印（retained.json），若自上次保留以来没有新消息则直接 no-op，因此重叠不会导致重复存储（retain.py）。

此外，retain.py 的read_transcript支持三种在实际环境中见过的转录格式：扁平格式（{role, content}）、类型嵌套（{type, message}）以及 Cursor 3.x 的role 嵌套格式（顶层role+message.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 以async=true异步 POST 到/v1/default/banks/{bank_id}/memories。文档 ID 采用{session_id}-{毫秒时间戳}形式，保证同一会话内多次保留会累积成不同文档，而非互相覆盖（源码注释中说明，旧设计使用document_id=session_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.mdc（frontmatter 中带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.mdc，rules/hindsight-memory.mdc）：alwaysApply: true的常驻规则，指导 Agent 使用<hindsight_memories>块中的会话记忆、了解自动保留行为、并在需要时调用 MCP 工具；同时要求"记忆与当前上下文冲突时优先当前上下文并注明差异"、"不向用户暴露原始记忆元数据"。
• 技能（hindsight-recall，skills/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_KEY="sk-your-key" # 或 export ANTHROPIC_API_KEY="your-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_CPU=1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU=1强制本地 embedding/reranker 走 CPU。

3. 已有本地服务器

如果你已经自行运行了hindsight-embed，保持hindsightApiUrl为空并设置apiPort与你的服务器端口一致即可，插件会自动探测到本地健康端口（daemon.py 会先对http://127.0.0.1:<port>/health做健康检查）。

若以上都不满足，插件最终会回退到默认云端地址https://api.hindsight.vectorize.io（config.py中的DEFAULT_HINDSIGHT_API_URL），遵循跨集成一致的"默认连云端"约定。

配置详解

所有设置存放在~/.hindsight/cursor.json中，每个设置都可通过环境变量覆盖。插件内置了合理的默认值（见 settings.json），你只需按需覆盖。

加载顺序（后加载者优先，实现在 lib/config.py）：

1. 内置默认值（硬编码在插件中，即lib/config.py的DEFAULTS）；
2. 插件自带settings.json（位于CURSOR_PLUGIN_ROOT/settings.json）；
3. 用户配置~/.hindsight/cursor.json（推荐在这里写覆盖项）；
4. 环境变量（优先级最高）。

连接与守护进程

LLM Provider（仅本地守护进程模式）

以下设置配置本地守护进程用于事实抽取的 LLM。连接外部 API 时会被忽略。

Memory Bank

bank是隔离的记忆存储，如同一个独立的"大脑"。

Session Recall（会话召回）

会话召回在每个会话开始时执行一次，查询 Hindsight 中的相关项目记忆，并以不可见的additionalContext注入 Agent 上下文（同时写入会话规则文件作为回退通道）。

Auto-Retain（自动保留）

自动保留在 Agent 完成任务后执行，提取对话记录并发送给 Hindsight。

Debug（调试）

验证 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—— 使用了哪个 bank（success与empty时存在）；
• mode—— 恒为plugin；
• hook—— 召回为sessionStart；
• result_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 Key（llmProvider自动检测依赖对应环境变量）。查看守护进程日志~/.hindsight/profiles/cursor.log。

会话启动高延迟：sessionStart召回 Hook 有 15 秒超时。可改用recallBudget: "low"或调低recallMaxTokens。

源码导读

本集成的完整实现位于仓库 hindsight-integrations/cursor 目录，各模块职责如下：

插件脚本仅依赖 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