企业官网建设流程全解析

Hindsight Cursor CLI 集成：从 v0.1.0 到 v0.3.0 的演进历程与完整接入实战

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

本篇技术指南以 Hindsight 仓库中hindsight-cursor-cli集成的官方 Changelog（skills/hindsight-docs/references/changelog/integrations/cursor-cli.md）为主线，系统讲解 Cursor CLI 如何通过 Hook 机制获得 Hindsight 长期记忆：包括 v0.1.0 的初始架构、v0.2.0 的 pip 安装器重构、v0.3.0 对 Cursor 3.x 对话解析的修复，并结合集成源码、默认配置与测试用例，给出可直接落地复制的安装、配置、排障全流程方案。

集成概览：四个 Hook 撑起的长期记忆

hindsight-cursor-cli是 Hindsight 为 Cursor CLI 提供的长期记忆集成。它不侵入 Cursor 的交互流程，而是借助 Cursor CLI v0.45+ 的 Hook 机制，用四个纯 Python（仅标准库）脚本自动完成记忆的召回（Recall）与保留（Retain），让 Agent 在跨会话、跨项目时仍然记得你的技术栈、偏好与历史决策。

官方集成文档对四个 Hook 的职责定义如下（见 skills/hindsight-docs/references/sdks/integrations/cursor-cli.md 与 hindsight-integrations/cursor-cli/README.md）：

四个事件的命令注册在 hooks.json 中，分别配置了超时：sessionStart5 秒、beforeSubmitPrompt45 秒、stop30 秒、sessionEnd30 秒。

需要特别说明的是：Cursor CLI 集成目前已被 Coding Agents 插件取代（官方文档 cursor-cli.md 顶部有明确标注），后者用一个包覆盖 Claude Code、Codex、Cursor、Copilot 等多种 CLI Agent，并共享按仓库隔离的记忆银行。不过原集成包仍然可用、可安装，本文即围绕它展开。

版本演进：三个里程碑解读

这是本文的核心脉络。hindsight-cursor-cli的 Changelog 记录了三个版本的演进，每个版本都对应一个明确的功能里程碑。

v0.1.0：集成从 0 到 1

v0.1.0 是集成的首次发布（贡献者 @Korayem），核心内容：

Added a Cursor CLI integration for Hindsight, including install/uninstall scripts, session hooks, and commands to retain and recall memories during Cursor sessions.

这一版确立了整个集成的基本架构，一直沿用至今：

• install/uninstall 脚本：负责把 Hook 脚本部署到 Cursor CLI 的 Hook 目录，并在卸载时清理；
• session hooks：即上文的四个 Cursor CLI Hook 事件，实现"会话开始预热、提交前召回、回合结束保留、会话结束兜底"的完整记忆闭环；
• retain/recall 命令：为 Hook 脚本提供调用 Hindsight API 的能力。

v0.2.0：从脚本到 pip 包

v0.2.0（贡献者 @benfrank241）完成了集成的工程化改造：

Cursor CLI integration is now available as a pip-installable package (hindsight-cursor-cli) with a Python-based installer/CLI for setup and hook installation.

这一版的意义在于：用户不再需要手动复制脚本，只需pip install hindsight-cursor-cli即可获得一个带 CLI 入口的安装器。从 pyproject.toml 可以看到控制台脚本的注册方式：

[project.scripts] hindsight-cursor-cli = "hindsight_cursor_cli.cli:main"

Hook 载荷（scripts/、settings.json、hooks.json）以包数据形式随 wheel 发布，安装器通过importlib.resources读取，无论是从 wheel 安装还是从源码运行都能正确解析（见 install.py 的模块 docstring）。

v0.3.0：针对 Cursor 3.x 的解析修复

v0.3.0（贡献者 @bjornmp）是目前的最新版本（pyproject.toml 中version = "0.3.0"），它是一次关键的 Bug 修复：

Fixed Cursor 3.x transcripts so role-nested agent conversations are parsed correctly for recall/retention.

其含义是：Cursor 3.x 生成的会话 transcript 中，Agent 对话以角色嵌套（role-nested）结构组织。旧版解析器无法正确处理这种嵌套结构，会导致召回（recall）与保留（retain）拿到的消息不完整。v0.3.0 修复了 transcript 解析逻辑，保证嵌套的 agent 对话能被正确提取——这正是 retain.py 中read_transcript与prepare_retention_transcript所负责的环节。

快速接入：安装、验证与卸载

前置条件

集成官方要求（见 README.md）：

• Cursor CLIv0.45+，且支持 Hook 机制；
• Python 3.9+（Hook 脚本仅用标准库，无需 pip 依赖）；打包本身要求requires-python = ">=3.11"；
• Hindsight 服务：可以是 Hindsight Cloud，也可以是本地hindsight-embeddaemon。

安装

pip install hindsight-cursor-cli

然后运行一次安装器。两种连接模式对应两种命令：

# 模式一：Hindsight Cloud hindsight-cursor-cli install --api-url https://api.hindsight.vectorize.io --api-token your-api-key # 模式二：本地 daemon（hindsight-embed），省略参数即可 hindsight-cursor-cli install

安装器会依次完成三件事（逻辑见 install.py 的run_install）：

1. 将 Hook 脚本复制到~/.cursor/hooks/cursor-cli/；
2. 把绝对路径写入~/.cursor/hooks.json（与既有条目合并，不覆盖其他 Hook）；
3. 若~/.hindsight/cursor-cli.json不存在则播种一个用户配置（后续可在此填入 API Token）。

合并逻辑值得展开：merge_hooks是幂等的，它会先剔除已有注册中路径包含hooks/cursor-cli标记的旧条目，再追加新条目，避免重复注册（见 install.py）。

安装完成后必须重启 Cursor CLI才能加载 Hook。若记忆没有生效，检查~/.cursor/hooks.json是否存在、shell 的$PATH中是否有python3。

卸载

hindsight-cursor-cli uninstall

卸载会删除 Hook 脚本目录，并从~/.cursor/hooks.json中剥离 Hindsight 的条目，但保留~/.hindsight/cursor-cli.json个人配置（见 install.py）。

验证安装

安装完成后，可以查看安装器生成的注册文件确认四个事件都已注册：

cat ~/.cursor/hooks.json

预期的四个事件及其超时配置与 hooks.json 中的模板一致。

工作原理：记忆如何被召回与保留

召回（Recall）：提交 Prompt 前的"记忆注入"

recall.py挂在beforeSubmitPrompt事件上，在用户按下发送、但请求尚未到达后端时执行。核心流程（见 recall.py）：

1. 从 stdin 读取 Hook 输入（prompt、conversation_id、transcript_path等）；
2. 解析配置并解析 API URL；
3. 推导银行 ID 并确保银行使命（bank mission）已设置；
4. 若recallContextTurns > 1，从 transcript 中组合多轮查询；否则直接用当前 prompt；
5. 截断到recallMaxQueryChars；
6. 调用 Hindsight recall API；
7. 将记忆格式化为additional_context输出。

输出遵循 Cursor 的beforeSubmitPrompt响应协议：

{ "continue": true, "additional_context": "<hindsight_memories>...</hindsight_memories>" }

一个关键设计是优雅降级：所有错误路径都返回退出码 0（仅 debug 模式返回 2），因为"记忆 Hook 阻塞用户提问"是危险默认值。记忆以如下结构注入（官方文档示例）：

<hindsight_memories> Relevant memories from past conversations... Current time - 2026-03-27 09:14 - Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26) - Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26) </hindsight_memories>

保留（Retain）：回合结束与会话结束的"双重保险"

retain.py挂在stop事件上。Cursor 文档将其描述为 fire-and-forget（Agent 循环不会等待响应），因此保留请求以async=true方式提交，服务端后台处理，失败也只记录到 stderr 并退出 0。

流程要点（见 retain.py）：

• 文档 ID 即会话 ID：以conversation_id作为 document ID，同一会话重跑是"更新"而非"重复存储"；chunked 模式下追加时间戳生成独立文档；
• 回合节流：retainEveryNTurns控制保留频率，除非force=True（sessionEnd 强制保留）；
• 反馈循环防护：保留前会剥离先前注入的记忆标签（<hindsight_memories>块），防止记忆自我污染；
• 标签模板变量：retainTags支持{session_id}、{conversation_id}、{bank_id}、{timestamp}四个模板变量替换；
• 元数据：每次保留附带retained_at、message_count、session_id，并可通过retainMetadata追加自定义字段。

session_end.py在会话终止时调用run_retain(hook_input, force=True)，即使短会话尚未达到retainEveryNTurns也会被完整保留。

配置详解：参数、默认值与加载顺序

默认配置随包发布在~/.cursor/hooks/cursor-cli/settings.json（完整清单见 settings.json）。个人覆盖配置建议放在~/.hindsight/cursor-cli.json，它在更新时不会被覆盖。

配置加载顺序（后者覆盖前者，见 cursor-cli.md）：

1. 内置默认值；
2. 插件的settings.json；
3. 用户配置~/.hindsight/cursor-cli.json；
4. 环境变量。

核心配置项

个人配置示例：

{ "hindsightApiUrl": "https://api.hindsight.vectorize.io", "hindsightApiToken": "your-api-key", "bankId": "my-cursor-memory" }

settings.json中还有一组默认值值得注意：recallTypes为["world", "experience"]，recallContextTurns为1，recallMaxQueryChars为800，retainContext为"cursor-cli"（用于标识写入来源），apiPort为9077（本地 daemon 端口），retainTags默认["{conversation_id}"]。

环境变量覆盖

所有设置都可通过环境变量覆盖（优先级最高）：

export HINDSIGHT_API_URL=https://api.hindsight.vectorize.io export HINDSIGHT_API_TOKEN=your-api-key export HINDSIGHT_BANK_ID=my-project export HINDSIGHT_RECALL_TIMEOUT=30 export HINDSIGHT_DEBUG=true

其他常见变量还包括HINDSIGHT_AUTO_RECALL、HINDSIGHT_AUTO_RETAIN、HINDSIGHT_RECALL_BUDGET、HINDSIGHT_RECALL_MAX_TOKENS、HINDSIGHT_DYNAMIC_BANK_ID、HINDSIGHT_AGENT_NAME等（对应关系见 cursor-cli.md 的配置表格）。

连接模式：Cloud 与本地 Daemon

外部 API 模式（推荐）

在~/.hindsight/cursor-cli.json中配置 API 地址与 Token：

{ "hindsightApiUrl": "https://api.hindsight.vectorize.io", "hindsightApiToken": "hsk_your_token" }

本地 Daemon 模式

本地运行hindsight-embed：

uvx hindsight-embed

session_start.py会检测本地 daemon 的apiPort（默认9077）。注意：插件不会自动启动daemon，需要单独启动；配置中留空hindsightApiUrl即可自动连接http://localhost:9077。

session_start.py还有一个贴心设计：如果 Hindsight 不可达，它会调用prestart_daemon_background在后台预热 daemon，确保第一次召回或保留时服务已就绪（见 session_start.py）。

按项目隔离记忆：动态银行 ID

默认所有会话共享bankId指定的银行。如需按项目隔离，启用动态银行 ID：

{ "dynamicBankId": true, "dynamicBankGranularity": ["agent", "project"] }

这会自动创建形如cursor-cli::my-project的银行，项目路径取自CURSOR_PROJECT_DIR（Cursor 的环境变量）或 Hook 输入中的workspace_roots首项。这样在~/projects/api与~/projects/frontend分别运行 Cursor 时，记忆互不干扰。

如需在同一仓库的所有 worktree 间共享记忆，把project换成gitProject：

{ "dynamicBankId": true, "dynamicBankGranularity": ["agent", "gitProject"] }

动态银行 ID 的推导逻辑位于 bank.py（derive_bank_id），保留与召回两条路径都会调用。

故障排查

集成官方文档（README.md）提供了三个高频问题的排查思路：

• 会话启动时没有 "Hindsight is active" 提示：在~/.hindsight/cursor-cli.json中加入"debug": true（或HINDSIGHT_DEBUG=true）并检查 stderr 输出；
• 记忆没有出现：开启 debug 模式，确认HINDSIGHT_API_URL指向可达的服务；同时注意必须先完成至少一次保留才能召回——新会话首次提问时，记忆库里还没有任何内容；
• Hook 不触发：检查~/.cursor/hooks.json是否为合法 JSON 且包含四个 Hook 条目；Cursor CLI 需要重启会话才能加载新 Hook。若测试阶段希望尽快看到保留效果，可将retainEveryNTurns临时设为1（默认 10 意味着stopHook 每 10 回合才保留一次，但sessionEnd仍会兜底保留）。

从源码继续深入

如果你想深入理解实现细节或二次开发，以下文件值得优先阅读：

• 安装与卸载逻辑：install.py
• CLI 入口（hindsight-cursor-cli命令）：cli.py
• 四个 Hook 脚本：session_start.py、recall.py、retain.py、session_end.py
• 共享库（银行推导、HTTP 客户端、配置、内容处理、daemon、状态）：hooks/scripts/lib/
• 测试套件：tests/

测试是理解行为的捷径。集成测试覆盖了银行推导、CLI、HTTP 客户端、内容格式化、Hook 与安装逻辑（如test_install.py、test_hooks.py、test_content.py）。测试通过 mock HTTP 客户端、stdin/stdout 管道与基于文件的状态来完成，无需真实 Hindsight 服务：

cd hindsight-integrations/cursor-cli uv sync uv run pytest tests/ -v

其中test_content.py对 transcript 解析（含角色嵌套、工具调用标记）的用例，正是 v0.3.0 修复 Cursor 3.x 对话结构问题的回归保障所在。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight