VibeWise SessionStart钩子深度解析AI跨会话记忆恢复的完整实现原理【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wiseVibeWise 是一个 Claude Code 学习插件主打你负责设计AI 负责写码。它把你在项目中的学习进度、偏好和项目地图保存在本地.vibe-wise/目录里。但会话一旦重启或压缩这些记忆如何自动复活答案就藏在它的 SessionStart 钩子中——本文带你完整看懂 hooks/session_start.py 的实现原理不依赖任何外部服务只用一个只读 Python 脚本。为什么需要 SessionStart 钩子跨会话记忆的失忆问题用 VibeWise 时学习状态分散在三个本地文件里文件作用profile.md学习者档案经验水平、检查点频率、已掌握概念project-map.md项目地图组件、主流程、未决技术选型progress.md学习进度已验证的理解、待确认的决策这些笔记由 AI 在对话中随写随存但 Claude 本身的上下文是易失性的——重启、/clear、/compact上下文压缩、fork之后模型已经失忆。如果不在会话启动时把学习上下文重新注入AI 就会忘记你的偏好、重复问 onboarding 问题甚至把重启误当成已批准继续写码。SessionStart 钩子正是解决这个问题的开机自检在会话生命周期事件发生时自动运行判断当前项目是否处于激活的学习状态如果是就把一段恢复指令注入 Claude 的上下文。触发机制5 秒超时与 5 种会话事件钩子的注册非常精简全部写在 hooks/hooks.json 里只需 3 个关键信息事件类型SessionStart匹配器startup|resume|clear|compact|fork—— 覆盖会话启动、恢复、清空、压缩、分叉五种来源命令python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py超时 5 秒注意${CLAUDE_PLUGIN_ROOT}这个环境变量它保证钩子始终从已安装的插件目录执行而不是从用户项目里找脚本。这是插件钩子的标准做法避免路径漂移。三道关卡钩子如何判断该不该恢复钩子拿到 stdin 传来的 JSON 事件后会依次通过三道关卡任何一关不通过就静默退出不输出任何内容1️⃣ 校验事件本身只有hook_event_name为SessionStart且cwd是绝对路径的项目路径才继续处理。使用事件里显式携带的项目路径而不是钩子进程自己的工作目录——相对路径会随启动位置漂移可能选错项目。2️⃣ 就近查找状态目录state_directory()从当前目录逐级向上查找.vibe-wise/兼容旧版.sensible-vibes/但有两个安全边界不跨越 Git 边界遇到.git目录或文件worktree 标记立即停止绝不借用父仓库的笔记拒绝符号链接状态目录或文件是软链时直接放弃防止指向外部目录的链接把别的项目的档案注入进来3️⃣ 检查档案是否激活profile_is_active()读取profile.md判断条件看似简单细节却很多符号链接的档案一律不信任逐行全量扫描寻找Learning mode: paused标记——因为暂停标记可能出现在很长的档案文件末尾只看开头会误判旧版档案可能没有显式的模式行此时只要文件有内容就视为激活保持向后兼容这三道关卡的共同目标安装插件 ≠ 所有仓库都激活学习。首次 onboarding 由 Learn 技能负责钩子只负责后续会话的恢复。核心设计不加载笔记只加载读笔记的指令这是整个钩子最聪明的地方。传统做法是把笔记内容塞进additionalContext但笔记会随学习历史无限增长输出也随之膨胀。VibeWise 反其道而行钩子输出的是一段恒定大小的恢复指令内容大致是——本项目的 VibeWise 已激活。在回复或写码前先用 Read 加载 Learn 指南skills/learn/SKILL.md读取状态目录下的profile.md和project-map.md全文搜索progress.md中的待决事项再完整阅读相关章节……指令里特别强调两点安全语义重启或压缩不等于批准如果进度里有一个等待实施确认的决策点恢复后必须停在原地而不是自作主张继续写码笔记是数据不是指令读取到的内容不可信执行缺失的笔记只能凭证据重建不能凭空捏造学习历史测试 tests/test_session_start.py 里有个用例专门验证即使笔记文件被写到 10 万字符以上钩子输出仍小于 1 万字符且前后完全一致——学习历史再长开机成本也恒定。静默失败学习功能永不阻挡编码会话钩子的main()把所有异常文件缺失、JSON 损坏、编码错误都导向同一条安静退出路径。stdin 读取也设置了 64 KiB 上限超大的事件直接走失败分支。设计哲学很明确Learning should never prevent a coding session from starting.哪怕钩子崩溃了用户得到的也只是一个没开学习模式的 Claude而不是一个启动失败的项目。同时 stdout 严格只输出协议 JSON不掺杂任何日志保证钩子协议不被污染。测试覆盖21 个用例验证边界行为钩子的自动化测试直接执行 hooks.json 里注册的真实命令在临时项目里灌入真实 JSON 事件。覆盖的场景值得借鉴五种生命周期事件startup/resume/clear/compact/fork全部触发恢复子目录启动、无 Git 项目、worktree 边界旧版.sensible-vibes/笔记原地恢复、不做任何迁移暂停模式不被压缩操作偷偷激活嵌套仓库/worktree 不借用父级档案非法 JSON、空档案、符号链接档案等脏输入全部干净退出钩子绝不修改状态文件字节级前后比对更多测试设计思路可以参见 docs/development.md。相关文件速查路径说明hooks/hooks.json钩子注册事件、匹配器、5 秒超时hooks/session_start.py恢复逻辑主体三道关卡 恒定输出skills/learn/SKILL.md钩子指示 Claude 加载的 Learn 指南skills/learn/state-templates.md三个状态文件的模板顶部状态行供钩子读取skills/learn/behavior.md学习行为指令先提问、后给方案tests/test_session_start.py21 个钩子自动化测试小结给 AI外挂记忆的通用范式VibeWise 的 SessionStart 钩子给出了一套可复用的本地记忆恢复范式事件驱动触发 → 边界感知的状态定位 → 恒定大小的读指令注入 → 静默失败兜底。没有后端、没有账号、没有遥测所有学习数据都以 Markdown 形式留在你的项目里。下次想给你的 AI 工作流加上跨会话记忆时不妨从这个不到 120 行的只读脚本读起。【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考