Hindsight + Cline 集成实战：用生命周期 Hook 为 Cline 注入跨会话长期记忆

Hindsight + Cline 集成实战：用生命周期 Hook 为 Cline 注入跨会话长期记忆

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

导读

本指南讲解如何通过hindsight-cline安装器，把 Hindsight 的长期记忆能力接入 Cline 编辑器的生命周期 Hook（Lifecycle Hooks）：任务开始前自动召回（Recall）相关记忆注入上下文，任务结束时自动留存（Retain）本次会话摘要，从而让 Cline 在跨会话场景下不再每次从零发现项目上下文。整个过程完全不依赖 MCP，记忆读写是确定性的自动行为，不依赖模型主动调用工具。读完本文你将掌握完整的安装、配置、验证与排障流程，并能基于源码理解四个 Hook 的底层工作方式。

快速答案

1. pip install hindsight-cline。
2. 在项目目录运行hindsight-cline install --api-url … --api-token …。
3. 在 Cline 中启用 Hook：Settings → Features → Hooks。
4. 召回的记忆会以<hindsight_memories>上下文块注入；默认写入名为cline的 bank。
5. 用一个后续任务能否想起先前任务存下的决策来验证配置是否生效。

前置条件

开始之前，请确认满足以下条件：

• VS Code 中已安装并正常使用 Cline（官方文档中关于 lifecycle hooks 的说明见 Cline 文档）；
• 有一个可达的 Hindsight 后端，可以是 Hindsight Cloud（推荐，注册即用）或自托管服务器；
• macOS 或 Linux（Cline 的 Hook 不在 Windows 上运行），且系统具备 Python 3 环境。

自托管备选方案（来自 hindsight-integrations/cline/README.md）：

pip install hindsight-all export HINDSIGHT_API_LLM_API_KEY=your-openai-key hindsight-api # 启动后监听 http://localhost:8888

关于自托管后端的安装与配置，可参阅仓库中的 hindsight-all/README.md 与 hindsight-api/README.md。

Step 1：安装 hindsight-cline CLI

pip install hindsight-cline

安装后即可获得hindsight-cline命令，它负责帮你安装和管理 Cline 的 Hook 脚本。从 pyproject.toml 可以看到，hindsight-cline是包的 console script 入口，指向hindsight_cline.cli:main；包本身依赖为空（dependencies = []），因为四个 Hook 脚本运行时只依赖 Python 标准库，这保证了 Hook 在任何 Python 3 环境中都能零依赖运行。

Step 2：运行安装器对接 Hindsight

在项目目录下，用你的 Hindsight 地址和 API Key 运行安装器。

对接 Hindsight Cloud：

hindsight-cline install \ --api-url https://api.hindsight.vectorize.io --api-token YOUR_KEY

安装器的完整命令行形态（见 cli.py）：

参数	说明
install	安装四个生命周期 Hook 到 Cline
install --api-url URL	Hindsight API 基地址，默认取环境变量HINDSIGHT_API_URL；Cloud 默认值为https://api.hindsight.vectorize.io
install --api-token TOKEN	Hindsight API Token（Cloud 必填），默认取环境变量HINDSIGHT_API_TOKEN
install --project-dir DIR	安装目标项目目录，默认当前目录
install --global	全局安装到~/Documents/Cline/Rules/Hooks/，对所有项目生效
uninstall	卸载 Hook（若曾全局安装需加--global）

安装器做两件事（见 install.py）：

1. 部署 Hook 文件：把四个 Hook 脚本（TaskStart、UserPromptSubmit、TaskComplete、TaskCancel）连同它们的lib/共享库和settings.json复制到目标目录：
   • 项目安装：.clinerules/hooks/（建议提交到版本库与团队共享）；
   • 全局安装：~/Documents/Cline/Rules/Hooks/。
   • 脚本会被chmod 0o755，因为Cline 只运行可执行的 Hook 文件。
2. 写入连接配置：把--api-url/--api-token持久化到~/.hindsight/cline.json（注意：是用户级配置文件，不会随 Hook 一起复制进项目目录）。

自托管时如何对接

不需要 Hindsight Cloud 也可以：安装hindsight-all并运行hindsight-api后，把安装器指向本机地址即可：

hindsight-cline install --api-url http://localhost:8888

从 install.py 的DEFAULT_API_URL可以看到 Cloud 默认地址是https://api.hindsight.vectorize.io；自托管时显式传入自己的地址即可覆盖。

Step 3：在 Cline 中启用 Hooks

最后一步也是最容易遗漏的一步：在 Cline 中打开Settings → Features → Hooks并开启 Hook 开关。在启用之前，脚本虽然已经安装，但 Cline 不会执行它们。安装器完成时也会在终端提示你完成这一步。

四个 Hook 如何读写记忆

Cline 暴露了生命周期 Hook——在关键节点运行的小脚本。本集成工作在四个 Hook 上：

Cline Hook	Hindsight 的行为
TaskStart	为当前新任务召回上下文并注入模型上下文；同时把任务描述写入该任务的本地转录（transcript），作为后续 retain 的种子。
UserPromptSubmit	为你的消息召回记忆并注入；同时把本条 prompt 追加到任务转录，供任务结束时 retain。
TaskComplete	把累计的任务转录与最终摘要 retain 到 Hindsight。
TaskCancel	把被取消任务的部分转录retain 到 Hindsight。

记忆的注入形态：<hindsight_memories>上下文块

召回得到的记忆会被格式化为一个<hindsight_memories>上下文块注入模型上下文。从 hooks_impl.py 的实现看，该块的组成是：

<hindsight_memories> {recallPromptPreamble 预设引导语} Current time - {UTC 当前时间} - 记忆条目文本 [记忆类型] (提及时间) - … </hindsight_memories>

默认的recallPromptPreamble（见 config.py）是：

"Relevant memories from past conversations (prioritize recent when conflicting). Only use memories that are directly useful to continue this task; ignore the rest:"

即提示模型"优先采用最近的记忆、只使用与当前任务直接相关的部分"。

转录（Transcript）如何被累积

Cline 不会把对话转录交给 Hook，因此集成必须自己累积：UserPromptSubmit和TaskStart把每一条用户消息/任务描述追加到按 taskId 隔离的本地转录文件（位于~/.hindsight/cline/state/下），任务结束时由TaskComplete/TaskCancel读回并 retain。相关实现细节：

• 转录以transcript_{task_id}.json形式存储在~/.hindsight/cline/state/（见 state.py），文件名做了防路径穿越清洗，写入采用"临时文件 +os.replace"的原子写方式；
• 单个任务的转录最多保留 500 条消息（超出丢弃最旧的），避免超长任务撑爆状态文件（见 content.py）；
• retain 成功后转录即被清除（clear_transcript），避免重复留存；
• 在写入转录与 retain 之前，会先调用strip_memory_tags把内容中的<hindsight_memories>/<relevant_memories>块剥掉，防止注入过的记忆被再次存回，形成留存回环（feedback loop）。

记忆落在哪个 bank

默认情况下，所有记忆都写入同一个 bank：cline（bankId默认值）。如果你希望按项目或会话隔离，需要显式开启dynamicBankId，详见下文配置章节。

底层实现：Hook 与 Hindsight API 的交互

Hook 的 stdin/stdout JSON 契约

Cline 以子进程方式运行每个 Hook：向 stdin 写入一个 JSON 对象，从 stdout 读取形如{"cancel": bool, "contextModification": str, "errorMessage": str}的 JSON（见 cline_io.py）。其中contextModification正是 Hook 向模型上下文注入文本的通道——<hindsight_memories>块就是通过它进入上下文的。

每个 Hook 脚本只是薄薄的一层入口（例如 TaskStart）：把lib/加入sys.path后调用lib.hooks_impl中对应的main_*函数。

关键设计：任何失败都降级为 no-op

hooks_impl.py 中每个main_*入口都有明确的注释：它们永不抛异常——任何记忆相关的异常都被捕获并降级为无操作（cancel: false、空contextModification），保证记忆服务抖动永远不会阻塞 Cline 的正常工作。这也是"确定性记忆"理念的一部分：记忆读写是旁路，而不是卡点。

三个核心 REST 调用

client.py 使用 Python 标准库（urllib）实现了一个零第三方依赖的 HTTP 客户端，核心调用包括：

用途	端点	说明
健康检查	GET /health	用于探测本地 Hindsight 是否可达
召回	POST /v1/default/banks/{bankId}/memories/recall	请求体含query、max_tokens、budget、types，返回results列表
留存	POST /v1/default/banks/{bankId}/memories	携带async: true，服务端后台异步处理，document_id默认取taskId
设置银行使命	PATCH /v1/default/banks/{bankId}/config	设置reflect_mission与retain_mission

值得注意的实现细节：

• 请求携带Authorization: Bearer {token}（Cloud 场景）与自定义User-Agent: hindsight-cline/{version}——后者是为了避免 stdlib 默认的Python-urllib/X.YUA 被 Cloudflare 等反代按机器人过滤策略拦截（Cloudflare 1010 错误）；
• retain 请求带context: "cline"字段，帮助 Hindsight 按来源聚类记忆；
• API 地址解析策略（cline_io.py 的resolve_api_url）：优先使用配置的hindsightApiUrl；若为空，则探测本地http://localhost:{apiPort}（默认端口9077）是否可达，可达则自动使用本地服务。集成不会自动拉起 daemon——没有可达服务时 Hook 安静地降级为 no-op。

Bank Mission 的自动初始化

首次向某个 bank 写入前，集成会自动为该 bank 设置"使命"（bank.py）：bank_mission默认描述为"Cline AI 编码助手，聚焦技术决策、代码变更、调试会话、架构选择与项目上下文"；retain_mission默认要求提取"技术决策、代码模式、调试方案、用户偏好、项目上下文与架构选择，忽略日常寒暄与瞬时操作细节"。这些使命通过PATCH /config下发给 Hindsight，指导后续的反思（reflect）与留存（retain）行为。已设置过的 bank 记录在~/.hindsight/cline/state/bank_missions.json中，避免重复调用。

动态 bank：按项目/会话隔离

关闭dynamicBankId时，bank ID 固定为bankId（默认cline）。开启后，bank ID 由dynamicBankGranularity指定的维度拼接而成（默认["agent", "project"]），每个维度可取的值包括：

维度	取值来源
agent	配置的agentName（默认cline）
project	第一个工作区根目录的 basename
session	Hook 输入中的taskId
user	环境变量HINDSIGHT_USER_ID（未设置则为anonymous）

例如agent::project会生成形如cline::myrepo的 bank ID，实现"每个项目一个记忆库"。

配置详解

配置的默认值位于安装后的settings.json中；个人覆盖项放在~/.hindsight/cline.json（跨重装保持稳定）；每个配置项也都可以通过HINDSIGHT_*环境变量覆盖。下表汇总了常用配置项及其默认值（依据 settings.json、config.py 与 README.md）：

配置项	默认值	说明
hindsightApiUrl	空	Hindsight 服务地址；为空时自动探测apiPort上的本地服务
hindsightApiToken	null	Hindsight Cloud 的 API Key
bankId	cline	本集成使用的记忆 bank
bankMission	Cline 编码助手描述	银行使命，指导记忆反思方向
retainMission	提取技术决策等描述	指导留存时提取哪些信息、忽略哪些信息
autoRecall	true	任务/消息前自动注入召回记忆
autoRetain	true	任务结束时自动留存任务转录
recallBudget	mid	召回深度：low/mid/high
recallMaxTokens	1024	召回结果的最大 token 预算
recallTimeout	10	召回请求超时（秒）
recallTypes	["world", "experience"]	要召回的记忆类型
recallContextTurns	1	组合多轮召回查询时包含的上下文轮数（默认仅用最新 prompt）
recallMaxQueryChars	800	召回查询最大字符数，超限先丢弃最旧上下文
recallPromptPreamble	见上	<hindsight_memories>块内的引导语
retainContext	cline	留存内容的来源上下文标签
retainTags	["{task_id}"]	留存标签，支持{task_id}、{project}、{status}、{timestamp}模板变量
retainMetadata	{}	额外的元数据键值对，同样支持模板变量
retainTimeout	15	留存请求超时（秒）
apiPort	9077	本地 Hindsight 探测端口
bankIdPrefix	空	bank ID 前缀（如prefix-cline）
dynamicBankId	false	每个项目/会话使用独立 bank
dynamicBankGranularity	["agent", "project"]	动态 bank 的维度组合
agentName	cline	agent 维度取值
debug	false	是否向 stderr 输出调试日志

配置的加载顺序

从 config.py 的load_config()可以看到，配置按以下顺序合并（后者覆盖前者）：

1. 内置默认值（dataclass 默认值）；
2. 插件自带的settings.json（通过向上逐级查找定位，兼容仓库源码布局与安装后布局）；
3. 用户配置~/.hindsight/cline.json（跨重装稳定）；
4. HINDSIGHT_*环境变量覆盖（优先级最高）。

环境变量采用与配置项一一对应的命名，例如HINDSIGHT_BANK_ID、HINDSIGHT_AUTO_RECALL=false、HINDSIGHT_RECALL_BUDGET=high、HINDSIGHT_DYNAMIC_BANK_ID=true等；布尔值按true/1/yes解析。

两个高频配置示例

每个项目独立的记忆库：

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

只召回、不自动留存：

{ "autoRetain": false }

验证记忆是否生效

推荐的验证流程：

1. 用 URL 和 Key 运行hindsight-cline install，并在 Cline 中启用 Hook；
2. 开启一个任务，让 Cline 记录一个决策或约定（例如"本项目用 pnpm 管理依赖"）；
3. 完成该任务，让转录被 retain；
4. 在同一项目里开启一个新任务；
5. 询问先前记录的那个决策。

如果召回的<hindsight_memories>块里出现了先前的决策，说明集成已生效。你也可以通过 API 或 Hindsight 控制台检查clinebank，确认确实出现了一条记忆。

不启动 Cline 也能冒烟测试 Hook

集成自带无 Cline 的冒烟测试方式（来自 README.md）：直接把 Cline 的 Hook 负载 JSON 通过管道喂给 Hook 脚本，观察 stdout 返回：

echo '{"hookName":"UserPromptSubmit","prompt":"how do we authenticate?","taskId":"t1","workspaceRoots":["/tmp/x"]}' \ | .clinerules/hooks/UserPromptSubmit # → {"cancel": false, "contextModification": "<hindsight_memories>…", "errorMessage": ""}

这正好验证了上文提到的 stdin/stdout JSON 契约：contextModification非空即说明召回成功、注入块已生成。

测试用例如何印证行为

tests/test_hooks.py 用一组测试固化了核心行为，可以直接对照理解实现：

• 召回注入：UserPromptSubmit返回的注入块包含<hindsight_memories>与召回的记忆文本；
• 转录累积：UserPromptSubmit会把 prompt 以{"role": "user", "content": ...}追加到transcript_{taskId}.json；
• 短消息跳过：prompt 不足 5 个字符（RECALL_MIN_CHARS = 5）时不召回；
• 留存：TaskComplete会把累积转录 + 最终摘要（task字段）一起 retain，document_id取taskId，metadata.status为completed；成功后又清空转录；
• 优雅降级：服务端全部请求失败时，Hook 不抛异常，输出空contextModification且cancel: false。

常见错误与排查

忘记在 Cline 中启用 Hooks

安装脚本不等于启用。必须到Settings → Features → Hooks打开开关，否则 Hook 永远不会被运行。

在 Windows 上运行

Cline 的 Hook 只在 macOS 和 Linux 上运行，且依赖 Python 3。Windows 上 Hook 不会执行。

过早测试 retain

转录是在任务完成或取消时才被 retain 的。如果在任务结束前就去检查 bank，会话可能还没被存进去。请先完成任务，再验证记忆。

误以为默认就有按项目隔离的 bank

默认所有记忆都落在同一个clinebank。想要按项目或会话隔离，必须显式设置dynamicBankId: true（可配合dynamicBankGranularity选择隔离维度）。

FAQ

必须要用 Hindsight Cloud 吗？

不是。自托管的 Hindsight 服务器同样可用——安装hindsight-all、运行hindsight-api，然后用--api-url http://localhost:8888指向它即可。

这用到了 MCP 吗？

没有。集成完全运行在 Cline 的生命周期 Hook 之上，因此记忆行为是确定性的，不依赖模型决定是否调用某个工具。

记忆的作用域是怎样的？

默认全部落在同一个clinebank。设置dynamicBankId: true后，每个项目或会话使用独立的 bank。

支持哪些平台？

仅 macOS 和 Linux。Cline 的 Hook 不支持 Windows，且需要 Python 3。

更进一步

• 使用 Hindsight Cloud 作为托管后端可跳过自托管步骤；
• 集成完整说明与配置表见 hindsight-integrations/cline/README.md；
• 自托管部署可参考 hindsight-all/README.md 与 hindsight-api/README.md；
• 想从源码层面理解 Hook 的 I/O 契约、API 调用与状态管理，可依次阅读 cline_io.py、client.py 与 hooks_impl.py；
• 想验证集成行为的边界情况，可运行 tests/test_hooks.py 中的测试（在集成目录下执行uv run pytest tests/ -v）。

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