尧图网站建设 
Hindsight × ZCode为 Z.ai GLM 桌面编码代理接入跨工具长期记忆的完整指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 的 ZCode 集成通过三个原生 process hookSessionStart/UserPromptSubmit/Stop为 Z.ai 的 GLM 桌面编码代理 ZCode 提供会话前自动召回、会话中自动留存的长期记忆能力无需 MCP 服务器、无需改动现有工作流。读完本文你将掌握hindsight-zcode的安装、卸载、两种连接模式Hindsight Cloud 与本地hindsight-embed守护进程、全部配置项与加载优先级以及底层 hook 脚本的实现原理与调试手段。本文主体基于仓库文档 skills/hindsight-docs/references/sdks/integrations/zcode.md并辅以 hindsight-integrations/zcode 集成包的源码、测试与打包配置进行纵深展开。一、快速开始两条安装路径1. 推荐Hindsight Cloud注册 Hindsight Cloud 获取 API Key 后只需两步# 安装 CLI一次性安装器 pip install hindsight-zcode # 安装 hooks默认连接 Hindsight Cloud hindsight-zcode install --api-url https://api.hindsight.vectorize.io --api-token your-api-key # 重启 ZCode —— 记忆即刻生效安装器会完成三件事详见 install.py将 hook 脚本复制到~/.zcode/hooks/hindsight/将 Hindsight 的 hooks 合并进~/.zcode/cli/config.json保留已有键与其他工具的 hooks并强制hooks.enabled: true因为 ZCode 的配置 hooks 默认关闭若~/.hindsight/zcode.json尚不存在则生成该个人配置文件用于存放hindsightApiToken。关键隔离点整个过程只读写 ZCode 自己的配置命名空间~/.zcode/cli/config.json绝不会触碰Claude Code 的~/.claude/settings.json。2. 自托管替代方案如果希望连接本地的hindsight-embed守护进程省略上述两个 flags 即可hindsight-zcode install此时hindsightApiUrl保持为空hook 会自动连接http://localhost:9077。3. 卸载hindsight-zcode uninstall卸载逻辑与安装对称run_uninstall删除~/.zcode/hooks/hindsight/目录并从~/.zcode/cli/config.json中剥离 Hindsight 的条目——剥离依据是脚本路径中的hooks/hindsight标记段因此不会误伤其他工具的 hook个人配置~/.hindsight/zcode.json则原样保留。4. 备选以 ZCode 插件方式安装无需 pipZCode 可以直接从 Hindsight 插件市场安装同一套 hook 脚本以纯 hooks 的 Claude Code 插件形式发布# 在 ZCode 中添加 Hindsight 市场然后安装插件 zcode plugins add-marketplace vectorize-io/hindsight zcode plugins install hindsight-zcode以插件方式安装时ZCode 会自动注册 hooks无需手动编辑配置文件。凭据通过环境变量HINDSIGHT_API_URL/HINDSIGHT_API_TOKEN或~/.hindsight/zcode.json提供{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: hsk_your_token }注意CLI 安装方式要求本机有 Python 3.11pyproject.toml 中requires-python 3.11而 hook 脚本本身是纯 Python 标准库实现运行阶段不依赖任何第三方包pip install仅用于交付一次性安装器。二、核心特性一览特性说明自动召回Auto-recall每次提问前查询 Hindsight将相关记忆以additionalContext注入提示词模型可见、不污染转录记录自动留存Auto-retain每次回复后将该轮对话写入 Hindsight供未来召回无需 MCP纯 Python hook 脚本直连 Hindsight REST API无需伴随 ZCode 运行任何额外服务跨工具记忆同一 memory bank 可被 Claude Code、Cursor 等 Hindsight 集成共享记忆随工具迁移动态 bank ID支持基于工作目录实现按项目隔离记忆零运行时依赖hook 脚本仅用 Python 标准库pip包只负责一次性安装三、架构原理三个 hook 事件驱动记忆闭环ZCode 内嵌了 Claude Code 代理运行时并从自身的配置命名空间~/.zcode/cli/config.jsonhooks.enabled: true读取标准 Claude Code hook schema。插件接入三个 hook 事件Hook事件职责session_start.pySessionStart预热——验证 Hindsight 是否可达不可达时在后台预启动本地守护进程源码recall.pyUserPromptSubmit自动召回——查询记忆以additionalContext注入上下文retain.pyStop自动留存——组装本轮对话POST 到 Hindsight三个 hook 的超时与命令配置定义在 hooks.json__SCRIPTS_DIR__在安装时被替换为绝对路径事件commandargstimeoutMsSessionStartpython3session_start.py5000UserPromptSubmitpython3recall.py12000Stoppython3retain.py15000UserPromptSubmit注入记忆块用户在发送框按下回车后、请求发往模型之前recall.py读取提示词向 Hindsight 查询最相关的记忆并输出一个上下文块由 ZCode 在把对话交给模型前注入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从 recall.py 源码可见该上下文块由三部分拼装recallPromptPreamble提示词前缀、format_current_time()生成的时间戳、以及format_memories()格式化后的记忆列表最终以 Claude CodeUserPromptSubmit输出协议hookSpecificOutput.additionalContext写回 stdout。值得注意的实现细节ZCode 的 Stop 转录文件是仅含助手消息的临时文件不携带用户提示词因此recall.py会先把用户提示词暂存到状态文件last_prompt_session_id.json供 retain 钩子配对使用同时兼容session_id/sessionId两种字段名。Stop留存完整对话轮次ZCode 没有提供SessionEnd钩子事件因此留存挂在Stop上——每一轮对话完成后立即存储。retain.py的助手文本解析顺序为_resolve_assistant_texthook_input[responseText]完整回复优先transcript_path解析 ZCode 的{message: {...}}行取最后一条助手消息hook_input[responsePreview]截断回退。随后将暂存的用户提示词与助手回复组装为[user, assistant]消息对为每一轮生成独立的document_idf{session_id}-{int(time.time() * 1000)}确保每轮都是独立记忆、互不覆盖源码。模板变量{session_id}、{conversation_id}、{bank_id}、{timestamp}会先替换进 tags 与 metadata再随retainContext: zcode一起 POST 到 Hindsight retain API。四、两种连接模式模式一外部 API推荐通过~/.hindsight/zcode.json连接运行中的 Hindsight 服务云端或自托管{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: hsk_your_token }模式二本地守护进程本地运行hindsight-embeduvx hindsight-embedsession_start.py钩子会在apiPort默认9077上探测它。注意插件不会自动拉起守护进程需要你单独启动。配置中让hindsightApiUrl保持为空插件即连接http://localhost:9077。若会话启动时探测不到服务session_start.py会调用prestart_daemon_background在后台预启动daemonIdleTimeout等守护进程参数见下文配置表。五、配置详解默认配置随安装写入~/.zcode/hooks/hindsight/settings.json内含安装时打上的版本号。个人覆盖配置请创建~/.hindsight/zcode.json更新不丢失大部分设置还支持环境变量覆盖。加载优先级后者覆盖前者内置默认值插件settings.json~/.zcode/hooks/hindsight/settings.json用户配置~/.hindsight/zcode.json环境变量该顺序与 config.py 中load_config()的实现完全一致且合并时跳过值为null的项环境变量经过类型转换布尔值识别true/1/yes整型强转失败则忽略。连接Connection配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URLHindsight API 服务地址。空 本地守护进程hindsightApiTokenHINDSIGHT_API_TOKENnullAPI 认证令牌。Hindsight Cloud 必填apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程端口daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT0守护进程空闲超时秒0 表示不自动退出embedVersionHINDSIGHT_EMBED_VERSIONlatest守护进程使用的 embed 版本embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地 embed 包路径离线场景llmProvider/llmModel/llmApiKeyEnvHINDSIGHT_LLM_PROVIDER/HINDSIGHT_LLM_MODEL/ —null守护进程模式的 LLM 配置记忆库Memory Bank配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDzcode读写所用记忆库。所有会话共享此库除非启用dynamicBankIdbankMissionHINDSIGHT_BANK_MISSION编码助手提示词描述代理用途创建/更新 bank 时发送dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时按dynamicBankGranularity字段派生唯一 bank ID适合按项目隔离dynamicBankGranularity—[agent, project]动态 bank ID 的派生字段agentNameHINDSIGHT_AGENT_NAMEzcode动态 bank ID 派生时使用的代理名此外 settings.json 还内置了retainMission留存时指导记忆引擎提取技术决策、代码模式、调试方案、用户偏好等忽略寒暄与瞬时操作细节与bankIdPrefixbank ID 前缀默认空。自动召回Auto-Recall配置项环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue自动召回总开关recallBudgetHINDSIGHT_RECALL_BUDGETmid检索深度low快/mid均衡/high彻底recallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024注入记忆块的 token 预算recallTimeoutHINDSIGHT_RECALL_TIMEOUT10召回 API 调用超时秒recallTypes—[world, experience]召回的记忆类型过滤recallContextTurnsHINDSIGHT_RECALL_CONTEXT_TURNS11 时从transcript_path组装多轮查询上下文recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800召回查询最大字符数超长截断recallRoles—[user, assistant]参与多轮查询的消息角色recallPromptPreamble—内置提示词注入记忆块前的引导语自动留存Auto-Retain配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动留存总开关retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS1每 N 轮留存一次。默认1即每轮Stop都存retainRoles—[user, assistant]参与留存的角色过滤retainContext—zcode留存时的上下文标识retainTags—[{session_id}]每轮记忆的标签支持模板变量retainMetadata—{}额外元数据支持模板变量环境变量覆盖的完整清单与类型转换规则见 config.py 的ENV_OVERRIDES例如export HINDSIGHT_API_URLhttps://api.hindsight.vectorize.io export HINDSIGHT_API_TOKENyour-api-key export HINDSIGHT_BANK_IDmy-project export HINDSIGHT_RECALL_TIMEOUT30 export HINDSIGHT_DEBUGtrue六、动态 Bank ID按项目隔离记忆默认所有会话共享bankIdzcode。开启动态派生后{ dynamicBankId: true, dynamicBankGranularity: [agent, project] }安装器会自动创建形如zcode::my-project的 bank项目名取自 hook 的cwd由 Claude Code 运行时注入、可选的ZCODE_PROJECT_DIR环境变量或workspace_roots首项参见 lib/bank.py 的derive_bank_id与测试 test_bank.py。每个项目因此拥有独立的记忆空间互不串扰。七、与 ZCode 内置记忆的关系ZCode 自带本地、按项目隔离的记忆~/.zcode/cli/memories/。Hindsight 与之是互补关系而非替代Hindsight 将记忆存储在云端或自托管且跨工具共享的 bank 中——同一个 bank 同时服务 Claude Code、Cursor 及其他 Hindsight 集成——因此你的上下文可以跟随你穿梭于不同代理与不同机器之间而不是局限于某一个 ZCode 项目本地。八、故障排查与本地开发常见问题记忆不出现开启调试模式debug: true或HINDSIGHT_DEBUGtrue确认HINDSIGHT_API_URL指向可达的服务器。调试日志输出到 stderr并写入~/.hindsight/zcode/state/*.log安装完成后终端会提示tail -F ~/.hindsight/zcode/state/*.log。Hooks 不触发检查~/.zcode/cli/config.json是否为合法 JSON、hooks.enabled是否为true、hooks.events下是否存在 Hindsight 条目。ZCode 需要重启会话才能加载新 hooks。注意输出上限ZCode 以maxOutputBytes安装器默认写入 32768截断 hook 的 stdout超出的输出会被丢弃。设计保证优雅降级三个 hook 均以永远退出码 0为原则recall.py / retain.py任何召回/留存失败只写 stderr 并正常退出绝不阻塞代理。仅在调试模式下才会以退出码 2 暴露错误。UserPromptSubmit输出还受additionalContext协议约束多轮查询、字符截断、UTF-8 清洗recall.py都为此服务。本地开发与测试仓库中的集成包自带完整测试套件tests/ 下共 7 个测试文件test_cli、test_install、test_client、test_bank、test_content、test_hooks、test_plugincd hindsight-integrations/zcode uv sync uv run pytest tests/ -v测试通过 mock HTTP 客户端、stdin/stdout 管道和基于文件的状态来运行无需真实 Hindsight 服务器。安装器的合并/剥离逻辑幂等性、保留外来 hooks在 test_install.py 中均有覆盖集成包遵循 MIT 许可见 LICENSE。总结hindsight-zcode以一种零侵入的方式解决了编码代理的长期记忆问题既不需要 MCP 服务器也不需要改造 ZCode 工作流仅靠 ZCode 原生 hook 体系中的三个事件SessionStart/UserPromptSubmit/Stop就完成了召回 → 注入 → 留存的完整记忆闭环。配合动态 bank ID 实现项目级隔离、通过共享 bank 实现跨工具记忆跟随再辅以四层配置覆盖与优雅降级设计它是一条上手门槛低、扩展余地大的 Agent 记忆落地方案。需要深入了解实现细节时可直接阅读 hindsight-integrations/zcode 下的源码与测试。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight × ZCode：为 Z.ai GLM 桌面编码代理接入跨工具长期记忆的完整指南
Hindsight × ZCode为 Z.ai GLM 桌面编码代理接入跨工具长期记忆的完整指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 的 ZCode 集成通过三个原生 process hookSessionStart/UserPromptSubmit/Stop为 Z.ai 的 GLM 桌面编码代理 ZCode 提供会话前自动召回、会话中自动留存的长期记忆能力无需 MCP 服务器、无需改动现有工作流。读完本文你将掌握hindsight-zcode的安装、卸载、两种连接模式Hindsight Cloud 与本地hindsight-embed守护进程、全部配置项与加载优先级以及底层 hook 脚本的实现原理与调试手段。本文主体基于仓库文档 skills/hindsight-docs/references/sdks/integrations/zcode.md并辅以 hindsight-integrations/zcode 集成包的源码、测试与打包配置进行纵深展开。一、快速开始两条安装路径1. 推荐Hindsight Cloud注册 Hindsight Cloud 获取 API Key 后只需两步# 安装 CLI一次性安装器 pip install hindsight-zcode # 安装 hooks默认连接 Hindsight Cloud hindsight-zcode install --api-url https://api.hindsight.vectorize.io --api-token your-api-key # 重启 ZCode —— 记忆即刻生效安装器会完成三件事详见 install.py将 hook 脚本复制到~/.zcode/hooks/hindsight/将 Hindsight 的 hooks 合并进~/.zcode/cli/config.json保留已有键与其他工具的 hooks并强制hooks.enabled: true因为 ZCode 的配置 hooks 默认关闭若~/.hindsight/zcode.json尚不存在则生成该个人配置文件用于存放hindsightApiToken。关键隔离点整个过程只读写 ZCode 自己的配置命名空间~/.zcode/cli/config.json绝不会触碰Claude Code 的~/.claude/settings.json。2. 自托管替代方案如果希望连接本地的hindsight-embed守护进程省略上述两个 flags 即可hindsight-zcode install此时hindsightApiUrl保持为空hook 会自动连接http://localhost:9077。3. 卸载hindsight-zcode uninstall卸载逻辑与安装对称run_uninstall删除~/.zcode/hooks/hindsight/目录并从~/.zcode/cli/config.json中剥离 Hindsight 的条目——剥离依据是脚本路径中的hooks/hindsight标记段因此不会误伤其他工具的 hook个人配置~/.hindsight/zcode.json则原样保留。4. 备选以 ZCode 插件方式安装无需 pipZCode 可以直接从 Hindsight 插件市场安装同一套 hook 脚本以纯 hooks 的 Claude Code 插件形式发布# 在 ZCode 中添加 Hindsight 市场然后安装插件 zcode plugins add-marketplace vectorize-io/hindsight zcode plugins install hindsight-zcode以插件方式安装时ZCode 会自动注册 hooks无需手动编辑配置文件。凭据通过环境变量HINDSIGHT_API_URL/HINDSIGHT_API_TOKEN或~/.hindsight/zcode.json提供{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: hsk_your_token }注意CLI 安装方式要求本机有 Python 3.11pyproject.toml 中requires-python 3.11而 hook 脚本本身是纯 Python 标准库实现运行阶段不依赖任何第三方包pip install仅用于交付一次性安装器。二、核心特性一览特性说明自动召回Auto-recall每次提问前查询 Hindsight将相关记忆以additionalContext注入提示词模型可见、不污染转录记录自动留存Auto-retain每次回复后将该轮对话写入 Hindsight供未来召回无需 MCP纯 Python hook 脚本直连 Hindsight REST API无需伴随 ZCode 运行任何额外服务跨工具记忆同一 memory bank 可被 Claude Code、Cursor 等 Hindsight 集成共享记忆随工具迁移动态 bank ID支持基于工作目录实现按项目隔离记忆零运行时依赖hook 脚本仅用 Python 标准库pip包只负责一次性安装三、架构原理三个 hook 事件驱动记忆闭环ZCode 内嵌了 Claude Code 代理运行时并从自身的配置命名空间~/.zcode/cli/config.jsonhooks.enabled: true读取标准 Claude Code hook schema。插件接入三个 hook 事件Hook事件职责session_start.pySessionStart预热——验证 Hindsight 是否可达不可达时在后台预启动本地守护进程源码recall.pyUserPromptSubmit自动召回——查询记忆以additionalContext注入上下文retain.pyStop自动留存——组装本轮对话POST 到 Hindsight三个 hook 的超时与命令配置定义在 hooks.json__SCRIPTS_DIR__在安装时被替换为绝对路径事件commandargstimeoutMsSessionStartpython3session_start.py5000UserPromptSubmitpython3recall.py12000Stoppython3retain.py15000UserPromptSubmit注入记忆块用户在发送框按下回车后、请求发往模型之前recall.py读取提示词向 Hindsight 查询最相关的记忆并输出一个上下文块由 ZCode 在把对话交给模型前注入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从 recall.py 源码可见该上下文块由三部分拼装recallPromptPreamble提示词前缀、format_current_time()生成的时间戳、以及format_memories()格式化后的记忆列表最终以 Claude CodeUserPromptSubmit输出协议hookSpecificOutput.additionalContext写回 stdout。值得注意的实现细节ZCode 的 Stop 转录文件是仅含助手消息的临时文件不携带用户提示词因此recall.py会先把用户提示词暂存到状态文件last_prompt_session_id.json供 retain 钩子配对使用同时兼容session_id/sessionId两种字段名。Stop留存完整对话轮次ZCode 没有提供SessionEnd钩子事件因此留存挂在Stop上——每一轮对话完成后立即存储。retain.py的助手文本解析顺序为_resolve_assistant_texthook_input[responseText]完整回复优先transcript_path解析 ZCode 的{message: {...}}行取最后一条助手消息hook_input[responsePreview]截断回退。随后将暂存的用户提示词与助手回复组装为[user, assistant]消息对为每一轮生成独立的document_idf{session_id}-{int(time.time() * 1000)}确保每轮都是独立记忆、互不覆盖源码。模板变量{session_id}、{conversation_id}、{bank_id}、{timestamp}会先替换进 tags 与 metadata再随retainContext: zcode一起 POST 到 Hindsight retain API。四、两种连接模式模式一外部 API推荐通过~/.hindsight/zcode.json连接运行中的 Hindsight 服务云端或自托管{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: hsk_your_token }模式二本地守护进程本地运行hindsight-embeduvx hindsight-embedsession_start.py钩子会在apiPort默认9077上探测它。注意插件不会自动拉起守护进程需要你单独启动。配置中让hindsightApiUrl保持为空插件即连接http://localhost:9077。若会话启动时探测不到服务session_start.py会调用prestart_daemon_background在后台预启动daemonIdleTimeout等守护进程参数见下文配置表。五、配置详解默认配置随安装写入~/.zcode/hooks/hindsight/settings.json内含安装时打上的版本号。个人覆盖配置请创建~/.hindsight/zcode.json更新不丢失大部分设置还支持环境变量覆盖。加载优先级后者覆盖前者内置默认值插件settings.json~/.zcode/hooks/hindsight/settings.json用户配置~/.hindsight/zcode.json环境变量该顺序与 config.py 中load_config()的实现完全一致且合并时跳过值为null的项环境变量经过类型转换布尔值识别true/1/yes整型强转失败则忽略。连接Connection配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URLHindsight API 服务地址。空 本地守护进程hindsightApiTokenHINDSIGHT_API_TOKENnullAPI 认证令牌。Hindsight Cloud 必填apiPortHINDSIGHT_API_PORT9077本地hindsight-embed守护进程端口daemonIdleTimeoutHINDSIGHT_DAEMON_IDLE_TIMEOUT0守护进程空闲超时秒0 表示不自动退出embedVersionHINDSIGHT_EMBED_VERSIONlatest守护进程使用的 embed 版本embedPackagePathHINDSIGHT_EMBED_PACKAGE_PATHnull本地 embed 包路径离线场景llmProvider/llmModel/llmApiKeyEnvHINDSIGHT_LLM_PROVIDER/HINDSIGHT_LLM_MODEL/ —null守护进程模式的 LLM 配置记忆库Memory Bank配置项环境变量默认值说明bankIdHINDSIGHT_BANK_IDzcode读写所用记忆库。所有会话共享此库除非启用dynamicBankIdbankMissionHINDSIGHT_BANK_MISSION编码助手提示词描述代理用途创建/更新 bank 时发送dynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse为true时按dynamicBankGranularity字段派生唯一 bank ID适合按项目隔离dynamicBankGranularity—[agent, project]动态 bank ID 的派生字段agentNameHINDSIGHT_AGENT_NAMEzcode动态 bank ID 派生时使用的代理名此外 settings.json 还内置了retainMission留存时指导记忆引擎提取技术决策、代码模式、调试方案、用户偏好等忽略寒暄与瞬时操作细节与bankIdPrefixbank ID 前缀默认空。自动召回Auto-Recall配置项环境变量默认值说明autoRecallHINDSIGHT_AUTO_RECALLtrue自动召回总开关recallBudgetHINDSIGHT_RECALL_BUDGETmid检索深度low快/mid均衡/high彻底recallMaxTokensHINDSIGHT_RECALL_MAX_TOKENS1024注入记忆块的 token 预算recallTimeoutHINDSIGHT_RECALL_TIMEOUT10召回 API 调用超时秒recallTypes—[world, experience]召回的记忆类型过滤recallContextTurnsHINDSIGHT_RECALL_CONTEXT_TURNS11 时从transcript_path组装多轮查询上下文recallMaxQueryCharsHINDSIGHT_RECALL_MAX_QUERY_CHARS800召回查询最大字符数超长截断recallRoles—[user, assistant]参与多轮查询的消息角色recallPromptPreamble—内置提示词注入记忆块前的引导语自动留存Auto-Retain配置项环境变量默认值说明autoRetainHINDSIGHT_AUTO_RETAINtrue自动留存总开关retainEveryNTurnsHINDSIGHT_RETAIN_EVERY_N_TURNS1每 N 轮留存一次。默认1即每轮Stop都存retainRoles—[user, assistant]参与留存的角色过滤retainContext—zcode留存时的上下文标识retainTags—[{session_id}]每轮记忆的标签支持模板变量retainMetadata—{}额外元数据支持模板变量环境变量覆盖的完整清单与类型转换规则见 config.py 的ENV_OVERRIDES例如export HINDSIGHT_API_URLhttps://api.hindsight.vectorize.io export HINDSIGHT_API_TOKENyour-api-key export HINDSIGHT_BANK_IDmy-project export HINDSIGHT_RECALL_TIMEOUT30 export HINDSIGHT_DEBUGtrue六、动态 Bank ID按项目隔离记忆默认所有会话共享bankIdzcode。开启动态派生后{ dynamicBankId: true, dynamicBankGranularity: [agent, project] }安装器会自动创建形如zcode::my-project的 bank项目名取自 hook 的cwd由 Claude Code 运行时注入、可选的ZCODE_PROJECT_DIR环境变量或workspace_roots首项参见 lib/bank.py 的derive_bank_id与测试 test_bank.py。每个项目因此拥有独立的记忆空间互不串扰。七、与 ZCode 内置记忆的关系ZCode 自带本地、按项目隔离的记忆~/.zcode/cli/memories/。Hindsight 与之是互补关系而非替代Hindsight 将记忆存储在云端或自托管且跨工具共享的 bank 中——同一个 bank 同时服务 Claude Code、Cursor 及其他 Hindsight 集成——因此你的上下文可以跟随你穿梭于不同代理与不同机器之间而不是局限于某一个 ZCode 项目本地。八、故障排查与本地开发常见问题记忆不出现开启调试模式debug: true或HINDSIGHT_DEBUGtrue确认HINDSIGHT_API_URL指向可达的服务器。调试日志输出到 stderr并写入~/.hindsight/zcode/state/*.log安装完成后终端会提示tail -F ~/.hindsight/zcode/state/*.log。Hooks 不触发检查~/.zcode/cli/config.json是否为合法 JSON、hooks.enabled是否为true、hooks.events下是否存在 Hindsight 条目。ZCode 需要重启会话才能加载新 hooks。注意输出上限ZCode 以maxOutputBytes安装器默认写入 32768截断 hook 的 stdout超出的输出会被丢弃。设计保证优雅降级三个 hook 均以永远退出码 0为原则recall.py / retain.py任何召回/留存失败只写 stderr 并正常退出绝不阻塞代理。仅在调试模式下才会以退出码 2 暴露错误。UserPromptSubmit输出还受additionalContext协议约束多轮查询、字符截断、UTF-8 清洗recall.py都为此服务。本地开发与测试仓库中的集成包自带完整测试套件tests/ 下共 7 个测试文件test_cli、test_install、test_client、test_bank、test_content、test_hooks、test_plugincd hindsight-integrations/zcode uv sync uv run pytest tests/ -v测试通过 mock HTTP 客户端、stdin/stdout 管道和基于文件的状态来运行无需真实 Hindsight 服务器。安装器的合并/剥离逻辑幂等性、保留外来 hooks在 test_install.py 中均有覆盖集成包遵循 MIT 许可见 LICENSE。总结hindsight-zcode以一种零侵入的方式解决了编码代理的长期记忆问题既不需要 MCP 服务器也不需要改造 ZCode 工作流仅靠 ZCode 原生 hook 体系中的三个事件SessionStart/UserPromptSubmit/Stop就完成了召回 → 注入 → 留存的完整记忆闭环。配合动态 bank ID 实现项目级隔离、通过共享 bank 实现跨工具记忆跟随再辅以四层配置覆盖与优雅降级设计它是一条上手门槛低、扩展余地大的 Agent 记忆落地方案。需要深入了解实现细节时可直接阅读 hindsight-integrations/zcode 下的源码与测试。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考