Hindsight Claude Code 插件变更指南：{user_id} 每用户记忆隔离与 requestTimeoutSeconds 超时覆盖

Hindsight Claude Code 插件变更指南{user_id} 每用户记忆隔离与 requestTimeoutSeconds 超时覆盖【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文以 hindsight-integrations/claude-code/CHANGELOG.md 为骨架解读 Hindsight 的 Claude Code 插件长期记忆集成两个版本的演进0.1.0 初始发布建立的自动召回 自动留存 会话生命周期钩子基线以及 Unreleased 阶段引入的{user_id}模板变量与requestTimeoutSeconds超时覆盖两项能力。读完后你将掌握如何在retainTags/retainMetadata中做机器无关的每用户记忆隔离、如何为自托管 Hindsight 调整 per-call HTTP 超时以避免read operation timed out以及空命名空间标签如user:被自动丢弃的新行为边界并能在仓库源码与测试中逐项验证这些变更。变更日志的基线0.1.0 初始发布理解 Unreleased 的两项新增需要先看 0.1.02025-03-23确立的插件形态。CHANGELOG 的 0.1.0 条目记录了完整的初始能力清单这也是当前仓库代码仍完整保留的架构基线初始发布面向 Hindsight 长期记忆的 Claude Code 插件自动召回通过UserPromptSubmit钩子在每次用户提交提示时触发把相关记忆以additionalContext注入自动留存通过异步Stop钩子在每轮响应结束后提取并存储会话转录会话生命周期钩子SessionStart做健康检查SessionEnd做 daemon 清理三种连接模式外部 API、自管理本地 daemonuvx hindsight-embed、已有本地服务器动态 bank ID粒度可配置为agent、project、session、channel、user渠道无关兼容 Claude Code ChannelsTelegram、Discord、Slack与交互式会话零 pip 依赖纯 Python 标准库urllib、fcntl、subprocess34 个配置项经settings.json配置并支持环境变量覆盖LLM 自动探测从OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、GROQ_API_KEY探测分块留存滑动窗口retainEveryNTurnsretainOverlapTurns记忆标签剥离防止 retain 反馈循环。这些钩子的接线在 hooks/hooks.json 中可以直接核对SessionStart5s 超时→scripts/session_start.pyUserPromptSubmit45s→scripts/recall.pyStop15sasync: true→scripts/retain.pySessionEnd10s→scripts/session_end.py。Unreleased 新增一{user_id}模板变量实现每用户记忆隔离CHANGELOG 的 Unreleased/Added 第一条写明retainTags和retainMetadata支持{user_id}模板变量从HINDSIGHT_USER_ID环境变量解析未设置时为空字符串从而无需在settings.json中硬编码用户 id即可实现机器无关的每用户记忆作用域。实现位置retain 钩子中的模板解析变量解析发生在 scripts/retain.py# Resolve template variables in tags and metadata. # Supported variables: {session_id}, {bank_id}, {timestamp}, {user_id} template_vars { session_id: session_id, bank_id: bank_id, timestamp: time.strftime(%Y-%m-%dT%H:%M:%SZ, time.gmtime()), user_id: os.environ.get(HINDSIGHT_USER_ID, ), }retainTags与retainMetadata中的每个值都经过同一套_resolve_template替换因此{user_id}与既有的{session_id}、{bank_id}、{timestamp}完全对等。配置侧的标准用法见 README.md 的 Template variables 小节{ retainTags: [user:{user_id}, session:{session_id}] }再把HINDSIGHT_USER_IDopaque-user-id写入 shell profile.zshrc、.bashrc等即可让所有该用户的会话记忆都打上user:id标签供后续按标签召回/过滤。与动态 bank 粒度的配合从源码结构看{user_id}与动态 bank ID 机制共享同一来源scripts/lib/bank.py 在dynamicBankGranularity包含user段时同样读取HINDSIGHT_USER_ID未设置时回落为anonymous。因此环境变量有两条落点一条是bank 维度隔离bank ID 拼接为...::user段一条是标签维度隔离user:{user_id}标签二者可独立或组合使用。配套测试test/tests/test_hooks.py 中有三个直接对应本条变更的用例test_retain_tag_resolves_user_id_when_env_set设置HINDSIGHT_USER_IDalice后[user:{user_id}, session:{session_id}]解析为[user:alice, session:sess-user-test]test_retain_tag_dropped_when_user_id_env_unset未设置环境变量时user:{user_id}解析为user:后被丢弃其余标签照常发送全标签被丢弃时item中不再出现tags字段retain.py将 tags 置为None而HindsightClient.retain仅在 tags 为真值时才写入请求体。Unreleased 新增二requestTimeoutSeconds覆盖 per-call HTTP 超时CHANGELOG 的第二条 Added 说明新增requestTimeoutSeconds配置环境变量HINDSIGHT_REQUEST_TIMEOUT_SECONDS用于覆盖 recall10s、retain15s与 knowledge MCP 工具所使用的 per-call HTTP 超时默认null保持现有行为。其动机是自托管 Hindsight 在争用如并行 recall时可能合法地耗时超过 10s此时客户端不应在服务端实际成功完成的情况下向用户暴露read operation timed out。该条同时注明健康检查不受影响、仍为 5s并修复了 issue #1575。配置解析settings.json 与环境变量在 scripts/lib/config.py 中requestTimeoutSeconds位于DEFAULTS连接配置分组默认None并在ENV_OVERRIDES中注册为HINDSIGHT_REQUEST_TIMEOUT_SECONDS: (requestTimeoutSeconds, int),配置加载遵循固定优先级见load_config文档字符串config.py内置默认值 → 插件自带settings.json→ 用户配置~/.hindsight/claude-code.json→ 环境变量覆盖。即settings.json里写requestTimeoutSeconds: 30或export HINDSIGHT_REQUEST_TIMEOUT_SECONDS30两者皆可。超时覆盖的生效路径客户端实现见 scripts/lib/client.pydef _resolve_timeout(self, timeout: int) - int: Return the override if configured, otherwise the callers timeout. return self.request_timeout_override if self.request_timeout_override is not None else timeout每个调用点保留自己的语义化默认超时——recall()默认timeout10client.py、retain()默认timeout15client.py——而request()统一先经_resolve_timeout替换。这与 CHANGELOG 中默认 null 保持现状一旦配置则 recall/retain/MCP 全部被覆盖的描述严格一致。三个构造HindsightClient的入口都传入了同一个覆盖值scripts/recall.pyrequest_timeout_overrideconfig.get(requestTimeoutSeconds)scripts/retain.py同上scripts/mcp_server.pyknowledge MCP 工具的客户端同样传入因此 CHANGELOG 所称knowledge MCP 工具也在覆盖范围内。至于健康检查仍为 5s从 hooks/hooks.json 看SessionStart钩子自身的执行超时即为 5s且session_start.py只做服务器可达性探测不启动 daemon与该边界相符。Unreleased 变更空命名空间标签自动丢弃CHANGELOG 的 Changed 条目规定解析后内容为空的命名空间标签例如HINDSIGHT_USER_ID未设置时的user:现在会从 retain 请求中丢弃此前这类标签会原样发送。不含:的标签不受影响。实现位于 scripts/retain.pyraw_tags config.get(retainTags, []) if raw_tags: tags [] for original in raw_tags: resolved _resolve_template(original) if : in resolved and resolved.split(:, 1)[1] : debug_log(config, fDropping tag {original} - {resolved} (empty content after :)) continue tags.append(resolved) if not tags: tags None else: tags None判定规则可以总结为仅当含冒号且冒号后为空时丢弃session:xxx、project无冒号等正常保留。丢弃过程在debug模式下会输出诊断日志debug_log在HINDSIGHT_DEBUGtrue时写入 stderr见 config.py。这条变更与{user_id}特性是配套的它保证了同一份settings.json模板在用户 id 已配置与未配置的机器上都能安全运行——已配置时得到user:alice标签未配置时静默降级为无该标签而不是向服务端写入一个语义为空的user:标签污染记忆检索。0.1.0 的其余默认配置仍为当前基线除上述变更外Unreleased 未改动插件的默认参数因此 settings.json 仍是理解行为基线的最佳参照autoRecall/autoRetain默认开启recallBudget: mid、recallMaxTokens: 1024、recallTypes: [observation]、recallContextTurns: 1retainMode: full-session、retainEveryNTurns: 10、retainOverlapTurns: 2retainTags默认[{session_id}]动态 bank 默认关闭dynamicBankId: false启用时dynamicBankGranularity为[agent, project]daemon 相关项apiPort: 9077、embedVersion: latest、daemonIdleTimeout: 0。环境变量覆盖清单见 config.py 的 ENV_OVERRIDES包含HINDSIGHT_API_URL、HINDSIGHT_BANK_ID、HINDSIGHT_RECALL_*、HINDSIGHT_DAEMON_IDLE_TIMEOUT等二十余项其中HINDSIGHT_REQUEST_TIMEOUT_SECONDS为本次 Unreleased 新增。适用前提与验证方式适用对象Hindsight 的 Claude Code 插件hindsight-integrations/claude-code连接自托管含uvx hindsight-embeddaemon 模式或外部 Hindsight API 的场景requestTimeoutSeconds适用前提仅当自托管服务端在争用下响应超过默认 10s/15s 时才需要设置对云端/低延迟部署保持默认null即可健康检查路径不受该配置影响{user_id}适用前提由宿主环境shell profile 或渠道机器人设置HINDSIGHT_USER_ID未设置时行为是安全降级标签丢弃不会报错本地验证可运行 hindsight-integrations/claude-code/tests/ 下的 pytest 用例如test_hooks.py、test_config.py、test_client.py观察模板解析、标签丢弃与超时覆盖行为配合HINDSIGHT_DEBUGtrue在 stderr 查看被丢弃标签等诊断信息。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考