用途
memory-handoff 提供一种跨 CLI 的会话交接契约：每个项目一个纯文本 Markdown 文件，会话开始时读取，会话结束时重写，让任意智能体 CLI（如 Claude Code、Cursor、Gemini CLI、OpenCode、Codex、aider）接手工作时能延续上下文，而不是冷启动。它没有守护进程、没有数据库、没有锁定机制，文件即记忆，格式即接口。
适用时机
- 在存在交接文件的项目上开始会话时（默认路径 ~/.agent/handoffs/<project-slug>.md）。
- 用户要求“hand off”“save context”或“pick up where we left off”时。
- 会话较长、丢掉上下文损失较大时（做出的决策超出你能可靠回忆的范围）。
主要能力与使用方式
- 定位文件：默认目录为 ~/.agent/handoffs，$AGENT_HANDOFF_DIR 可覆盖。示例：对 ~/dev/src/crawlkit，slug 为 "crawlkit"，命令为： printf '%s\n' "${AGENT_HANDOFF_DIR:-$HOME/.agent/handoffs}/crawlkit.md"
- 会话开始时读取：读取整个文件，把 Next step 视为默认的第一步动作，把 Open threads 视为议程；并口头说明你接手的上下文，便于人类在过期信息误导你之前纠正。
- 会话结束时重写：整体重写各章节而非追加；过期的交接文件比没有更糟。五个固定章节为：
-
handoff: <project-slug>
-
Status：一段话说明项目是什么、进展到哪一步；陌生人只读这一段就能行动。
-
Open threads：要点列表，最新在前；每项写明恢复所需的 branch、file 或 command。
-
Decisions：带日期、一行一条，只记录不可逆的选择。
-
Next step：最有用的第一个动作，附确切命令。
-
Updated：最后写入的 ISO 时间戳及由哪个智能体写入。
-
- 不可逆操作前检查 Decisions：在做任何难以撤销的事情之前，查看 Decisions 中是否有带日期的条目与即将进行的操作相矛盾。
适用场景
适合需要在多个智能体 CLI 之间轮换工作、希望跨会话保留项目决策与下一步指针的开发者；适合以点文件工具同步的个人环境。
限制
- 只在交接目录内写入；从不删除文件，也不触碰 ~/.agent/handoffs（或 $AGENT_HANDOFF_DIR）之外的内容。
- 文件是主目录下的纯文本，常被点文件工具同步：绝不要把机密、令牌或凭据写入文件。
- 效果取决于最后一次写入：会话后未更新的交接文件即为过期，读取时必须明确说明其已过期。
- 没有 WSL 时不支持 Windows 原生路径（slug 来自目录名，挂载路径不同）。
- 不要把会话记录倾倒进文件：交接内容是决策与指针，不是历史。