Hindsight Claude Code 记忆插件版本演进全解析从 0.2.0 到 0.7.5 的变更图谱与源码印证【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文以仓库内 skills/hindsight-docs/references/changelog/integrations/claude-code.mdClaude Code Changelog为骨架结合 hindsight-integrations/claude-code 目录下的插件源码、hook 配置与默认设置逐版本解读hindsight-memory插件从 0.2.0 到 0.7.5 的完整演进脉络。读完本文你将理解该插件如何利用 Claude Code 的 Hook 体系实现自动记忆recall/retain、如何通过 MCP Server 提供知识工具、动态 bank 隔离机制如何随版本逐步完善以及每个版本修复背后的源码级原因——这份版本图谱同样可以作为排查故障、评估升级影响的参考手册。一、先理解插件的整体架构版本演进的坐标系在逐版本解读变更之前有必要先建立插件的整体架构认知。hindsight-memory是 Hindsight 为 Claude Code 提供的长期记忆插件通过 Claude Code 的 Hook 事件机制与一个 MCP Server 组合工作。插件根目录 hindsight-integrations/claude-code/hooks/hooks.json 定义了全部 Hook 注册关系Hook 事件脚本超时异步职责SessionStartscripts/session_start.py5s否健康检查确认 Hindsight 可达UserPromptSubmitscripts/recall.py45s否自动召回——查询记忆并注入additionalContextStopscripts/retain.py15s是自动保留——抽取对话记录并 POST 到 HindsightSessionEndscripts/session_end.py10s否清理——若由插件自启 daemon 则停止除 Hook 外插件还包含scripts/mcp_server.pyMCP stdio 服务暴露agent_knowledge_*系列知识工具、skills/create-agent/hindsight-memory:create-agent子代理创建向导以及scripts/lib/下的一组标准库模块client.pyREST 客户端、config.py配置加载、bank.pybank 派生、daemon.pydaemon 生命周期、content.py内容处理、state.py状态持久化等。这个架构正是版本演进的主轴早期版本0.2.x ~ 0.4.x打磨 Hook 驱动的 recall/retain 核心链路中期版本0.6.x引入知识工具 MCP Server 与子代理能力后期版本0.7.x聚焦召回质量、跨平台健壮性与多 bank 隔离。完整的功能与配置说明可参考 Claude Code 集成主文档。二、版本演进全图谱0.2.0 → 0.7.5 逐版本解读0.2.0插件诞生——Hook 驱动的记忆捕获与回填0.2.0 是hindsight-memory的首个版本确立了插件的基本能力新增 Claude Code 集成插件在 Claude Code 中捕获并使用 Hindsight 记忆。整会话保留retain full sessions通过 document upsert 将完整会话写入 Hindsight并支持可配置的 tagging。会话开始自动启动 daemonClaude Code 会话启动时自动拉起 Hindsight 后台 daemon保证记忆服务就绪。改进安装与配置体验新增受支持的 setup 命令来可靠注册 Hook——这正是仓库中 scripts/setup_hooks.py 的作用它解决了早期 Hook 注册不稳定的问题。修复 Windows 兼容性从首个版本起就关注跨平台。模型不再硬编码集成不再依赖硬编码的默认模型模型选择完全可配置对应今天的llmModel/HINDSIGHT_LLM_MODEL配置项。0.3.0工具调用结构化保留0.3.0 的关键变更将工具调用tool calls以结构化 JSON 形式保留相比纯文本转录结构化 JSON 能更准确地反映Claude 做了什么操作读取文件、搜索、编辑代码等从而提升记忆提取与检索的精度。这一能力演化为今天的retainToolCalls配置项默认true决定保留的对话中是否包含函数调用与结果。0.3.1可观测性增强所有 HTTP 请求携带标识性 User-Agent插件发出的每个 HTTP 请求都附带可识别的 User-Agent便于服务端兼容性判断与日志观测。0.4.0多 bank 召回与 UTF-8 健壮性0.4.0 是一个功能密集的版本支持从多个附加 bank 召回记忆除了主 bankprimary bank外可从额外 bank 召回记忆以获得更广的上下文——这是recallAdditionalBanks配置的由来。retainTags支持{user_id}模板变量可按照用户维度组织记忆。今天retainTags支持四类模板占位符{session_id}、{bank_id}、{timestamp}、{user_id}其中{user_id}取自HINDSIGHT_USER_ID环境变量未设置时为空字符串。修复 transcript 解析当工具结果为列表样式内容时不再导致 recall/retain 失败。动态生成的 bank ID 保留原始 UTF-8避免非 ASCII 标识符导致选错 bank——在源码 scripts/lib/bank.py 中有对应注释说明bank_id is stored as-is server-side; HTTP path encoding is the client layers job即 bank ID 原样存储编码职责交给 HTTP 客户端层。防止记忆压缩compaction覆盖本应保留的记忆。retainEveryNTurns大于 1 时会话结束SessionEnd也确保最终记忆被保留这是分块保留机制的重要兜底。transcript 以 UTF-8 读取避免包含非 ASCII 字符的对话出现错误或乱码。0.6.0知识工具与子代理——插件能力的转折点0.6.0 是里程碑版本新增基于 Python MCP Server 的知识工具让 Claude 能够更直接地读写和使用 Hindsight 知识。MCP Server 暴露的agent_knowledge_*工具集包括agent_knowledge_list_pages列出知识页、agent_knowledge_get_page读取页面、agent_knowledge_create_page创建页面并附带 source query、agent_knowledge_update_page、agent_knowledge_delete_page、agent_knowledge_recall搜索记忆、agent_knowledge_ingest摄入文本、agent_knowledge_ingest_file摄入磁盘文件、agent_knowledge_get_current_bank获取当前 bank ID。这些工具不接受bank_id参数——bank 由服务端从与 Hook 相同的配置解析保证工具与 Hook 始终操作同一个 bank。引入子代理subagents与create-agentskill用户可通过/hindsight-memory:create-agent创建和管理带长期记忆的子代理。0.6.1子代理生成器理解 SDA 项目布局create-agentskill 支持并理解 SDA 项目布局在生成代理时可识别 SDA 风格的项目结构使生成的子代理配置更贴合项目实际。0.6.2依赖引导隔离化在插件数据目录下的隔离虚拟环境中引导 Python 依赖首次运行时会通过uv在${CLAUDE_PLUGIN_DATA}/venv下创建独立 venv 并安装所需依赖主要是mcp包不做全局 pip 安装、与系统环境隔离、且不受插件更新影响。这是零全局污染设计的延续——插件的 Hook 脚本本身是纯 Python 标准库实现。0.6.3显式目录映射与 Git Worktree 支持新增显式目录到 bank 的映射directoryBankMap允许将特定目录固定到指定 bank。更好地支持 Git worktrees避免在短生命周期分支上碎片化记忆。在 scripts/lib/bank.py 中_resolve_project_name()通过git rev-parse --path-formatabsolute --git-common-dir解析 worktree 的主仓库路径对普通仓库/home/user/myprojectgit-common-dir为.../myproject/.git取 basename 得到myproject对 worktree/home/user/myproject-wt1同样解析到主仓库myproject。因此同一仓库的所有 worktree 共享一个 bank如claude-code::myproject这正是resolveWorktrees默认true的语义。将其设为false则每个 worktree 使用字面目录名、各自独立 bank。0.6.4召回参数命名与页面检索修复修复 recall 参数命名避免限制结果条数时limit 场景因参数名错误而失败。提升页面检索可靠性返回完整页面内容并妥善处理超大工具结果oversized tool results。知识页 list 工具只取元数据修正了agent_knowledge_list_pages之前返回内容过大/不正确的问题list 仅返回元数据ID、名称避免响应过大。0.6.5MCP 请求超时可配置为集成中的 MCP 请求增加可配置超时。这一能力与稍后统一的requestTimeoutSecondsHINDSIGHT_REQUEST_TIMEOUT_SECONDS配置相衔接——该配置可整体覆盖 recall默认 10s、retain默认 15s与知识工具调用10–15s的单次超时健康检查保持快速5s不受影响。适用于自托管 Hindsight 在并发下如并行召回合理耗时超过 10s 的场景避免客户端对服务端其实已成功的请求报出read operation timed out对应集成仓库 CHANGELOG.md 中记录的 #1575 修复。0.7.0召回默认行为优化与 Windows 引导修复默认召回类型改为 observationsrecallTypes默认值变为[observation]。world表示通用事实、experience表示个人经验、observation表示由多条原始记忆整合去重后的信念。默认取 observations 的好处是当大量原始记忆表达同一信息时同一答案不会反复出现。可在 hindsight-integrations/claude-code/settings.json 中看到该默认值。召回上下文中的 Current time 明确标注为 UTC避免时区混淆。Windows MCP 引导脚本幂等化重复运行 setup 脚本不再失败。0.7.1知识工具默认启用与空 server 存活知识工具默认启用enableKnowledgeTools默认true。即使知识工具被禁用MCP Server 也保持运行这是为了规避 Claude Code 的-32000重连错误——如果 server 退出Claude Code 会报告 reconnect 错误保持一个空 server存活即可避免。0.7.2跨平台 bank 解析加固修复目录到 bank 映射对 symlink 的处理提升 bank 解析可靠性。对应 scripts/lib/bank.py 中os.path.realpath()的使用——映射比较时先解析真实路径避免符号链接导致匹配失败。Windows 下目录映射大小写不敏感匹配源码注释解释了原因——PowerShell 与 git-bash 传给子进程的是大写盘符而 VS Code 扩展可能传小写大小写敏感比较会静默漏掉映射并回落到默认 bank。实现通过os.path.normcase()处理POSIX 上为 no-op保持大小写敏感。修复 Windows virtualenv 检测让 MCP runner 能在Scripts/布局下定位 Python 解释器。健康检查超时从 2s 提升到 10s减少不必要的 daemon 重启。0.7.3召回质量门槛——分数下限与标签过滤新增召回分数下限recall score floors记忆召回可强制执行最小相关性阈值对应recallMinScores配置例如{semantic: 0.65, reranker: 0.2}。为 Claude Code 记忆 Hook 新增召回标签过滤recallTags如[memory_type:rule]、recallTagsMatchany/all/any_strict/all_strict与复合过滤recallTagGroups。recallMinScores的语义可以在 scripts/recall.py 的filter_by_min_scores()中看到精确实现对每个 score 字段设置下限后结果中缺失或null的分数直接放行fail-open——因为仅靠 BM25 命中的结果没有 semantic 分数、passthrough reranker 会报告 null若强制拦截会误伤合法结果同时该实现会忽略非法数值配置并在 debug 日志中提示。0.7.4去重召回与隔离工作目录获取附加 bank 时避免重复召回主 bank 或重复 bank减少冗余结果。对应 scripts/recall.py 中的seen_banks集合——主 bank 先加入集合遍历recallAdditionalBanks时跳过已出现项防止双向交叉 bank 配置下重复召回同一 bank。MCP Server 在隔离的工作目录中运行避免从不同位置启动时出现路径相关问题。0.7.5会话增量保留保留会话增量session deltas修复增量更新在两次运行之间丢失的问题。这一修复直接支撑了retainMode: full-session的分块保留语义——首次发送完整 transcript 后后续只发送新消息组成的 chunk 文档compaction 开始时会开启全新 chunk。retainEveryNTurns默认 10retainOverlapTurns默认 2组成滑窗总窗口大小 两者之和保证 chunk 之间的连续性。三、版本变更背后的源码纵深三个关键实现3.1 召回分数下限filter_by_min_scores0.7.3召回结果在注入 Claude 上下文之前会经过分数下限过滤。实现位于 scripts/recall.py 的filter_by_min_scores()解析recallMinScores中的每个字段为 float非法值忽略并记 debug 日志对每条结果检查scores中各字段只有明确的数值且低于下限才丢弃缺失/null分数一律放行统计被丢弃的数量并记录 debug 日志。文档对其使用建议是当启用 cross-encoder reranker 时reranker下限是主要精度闸门但需注意 reranker 分数是 query-local 的、跨查询不可直接比较。3.2 bank 解析优先级derive_bank_id0.6.3 / 0.7.2bank ID 的解析顺序在 scripts/lib/bank.py 的derive_bank_id()中一目了然directoryBankMap最高优先级当前工作目录cwd匹配映射键时直接返回对应 bank静态/动态解析都不再执行映射匹配经过realpathnormcase规范化symlink 与 Windows 盘符大小写问题都因此修复静态模式dynamicBankId: false全部会话共享bankId默认claude_code单个 bank动态模式dynamicBankId: true按dynamicBankGranularity字段组合用::连接生成形如agent::project的 bank ID。合法字段为agent、project、session、channel、user后两者分别取HINDSIGHT_CHANNEL_ID、HINDSIGHT_USER_ID环境变量。未知字段会打印警告。bankIdPrefix在以上所有模式之上追加前缀适合做prod/staging之类的命名空间隔离。动态 bank 是 0.4.0 多 bank 能力的延伸例如 Claude Code Channels 场景下设置dynamicBankGranularity: [agent, channel, user]即可实现每通道、每用户记忆隔离。3.3 保底保留会话结束的最终 retain0.4.0retainEveryNTurns 1时如果会话在未到保留轮次时结束最后一次对话可能丢失。0.4.0 修复确保SessionEnd时总会触发最终保留。这与Stophook 的异步设计配合——hooks.json 中Stop事件标注了async: true保留操作不阻塞对话响应。四、与版本演进强相关的配置速查表以下配置项在版本演进中反复出现可在~/.hindsight/claude-code.json中覆盖优先级内置默认 插件settings.json 用户配置 环境变量配置项环境变量默认值引入/强化的版本说明recallMinScores—{}0.7.3召回分数下限缺失/null分数放行recallTags/recallTagsMatch/recallTagGroupsHINDSIGHT_RECALL_TAGS等[]/any/null0.7.3召回标签过滤recallTypes—[observation]0.7.0改默认召回的记忆类型recallAdditionalBanks/recallAdditionalBankFiltersHINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS{}0.4.0 / 0.7.4附加 bank 召回与按 bank 过滤已含去重retainEveryNTurns/retainOverlapTurns—10/20.4.0分块保留滑窗retainTags含{user_id}等模板—[{session_id}]0.4.0保留文档标签模板requestTimeoutSecondsHINDSIGHT_REQUEST_TIMEOUT_SECONDSnull0.6.5 起步 / 统一超时覆盖 recall 10s、retain 15s、知识工具 10–15senableKnowledgeToolsHINDSIGHT_ENABLE_KNOWLEDGE_TOOLStrue0.6.0 / 0.7.1知识工具开关关闭时 MCP server 仍存活resolveWorktrees/directoryBankMap—true/{}0.6.3 / 0.7.2worktree 归并与显式目录映射其余连接、daemon、LLM Provider、Debug 配置详见 Claude Code 集成主文档。五、升级与实践建议基于版本演进脉络可归纳出如下实践要点快速启用插件claude plugin marketplace add vectorize-io/hindsight→claude plugin install hindsight-memory然后配置 LLM ProviderOPENAI_API_KEY/ANTHROPIC_API_KEY自动检测或HINDSIGHT_LLM_PROVIDERclaude-code免 API key 复用 Claude Code 自身模型或通过{hindsightApiUrl: ...}连接外部 Hindsight 服务。多项目隔离优先用动态 bankdynamicBankId: true, dynamicBankGranularity: [agent, project]让每个子代理在每仓库拥有独立 bank需要每用户隔离时用[agent, channel, user]并设置HINDSIGHT_CHANNEL_ID/HINDSIGHT_USER_ID。召回质量调优先默认recallTypes: [observation]去重若出现低质量命中逐步引入recallMinScores下限先semantic再reranker若召回延迟高用recallBudget: low或降低recallMaxTokens默认 1024。注意召回 Hook 有 12 秒超时。自托管性能兜底并发召回下服务端响应慢于 10s 时设置requestTimeoutSeconds避免客户端误报read operation timed out。排障入口debug: true开启[Hindsight]前缀日志curl http://localhost:9077/health验证本地 daemondaemon 日志位于~/.hindsight/profiles/claude-code.log。首次启用知识工具后首启需要约 20–30 秒在${CLAUDE_PLUGIN_DATA}/venv引导 Python 依赖之后即时启动。插件现状提示Claude Code 集成主文档 skills/hindsight-docs/references/sdks/integrations/claude-code.md 声明该独立插件已被仓库中的 Coding Agents 插件 取代后者一套包覆盖 Claude Code、Codex、opencode、Cursor、Copilot 等多个 CLI 代理并改为每仓库共享 bank本插件仍可用但不再积极开发。迁移时服务端配置apiUrl/token会自动延续旧会话则通过本地 transcript 重新导入。从版本演进的视角看0.2.0 → 0.7.5 这条完整路径——从单一静态 bank、纯 Hook 记忆到多 bank 隔离、知识工具、子代理与召回质量门槛——恰好浓缩了插件从原型走向被替代者Coding Agents之前的全部设计积累其配置模型与排障经验在迁移后依然高度复用。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考