agentmemory handoff 技能实战基于 memory_sessions 与 memory_recall 跨会话无缝恢复 Agent 工作现场【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读handoff是 agentmemory 仓库中一个面向 AI 编码 Agent 的持久记忆技能解决的是「会话中断后如何无缝续接工作」这一核心问题当用户说出 where were we、resume、handoff、pick up where I left off或开启一个没有任何新鲜上下文的新会话时Agent 能够依据 handoff 技能定义 自动定位最近一次会话、把未回答的问题放在最前面并给出明确的下一步动作。读完本文你将掌握 handoff 的完整五步工作流、目录边界匹配的正确姿势、空会话与兄弟仓库等边界情况的处理以及 MCP 工具不可用时的 REST 回退方案。handoff 是什么技能定位与触发时机handoff定义于 plugin/skills/handoff/SKILL.md是一个user-invocable: true的用户可调用技能其元数据如下namehandoffdescriptionResume the most recent agent session for the current working directory, leading with any unanswered question. Use when the user says where were we, resume, handoff, pick up where I left off, or starts a session with no fresh context.argument-hint[optional cwd override]它与你可能已经熟悉的recap汇总最近 N 个会话、session-history查看完整会话历史、recall检索历史上下文共享同一份会话数据只是视角不同recap是纵向滚动的回顾handoff是单点续接的恢复。技能内See also一节明确列出了这一关系recap、session-history、recallsame session data, broader views。从实现层面看该技能实际调用的两个 MCP 工具都注册在 src/mcp/tools-registry.ts 的CORE_TOOLS中memory_sessionstools-registry.tsList recent sessions with their status and observation counts输入 schema 为空对象{}即无条件列出最近会话。memory_recalltools-registry.tsSearch past session observations for relevant context参数包括query必填支持关键词、文件名、概念、limit默认 10、formatfull/compact/narrative。Quick Start两条命令完成一次恢复技能的快速开始部分给出了最精简的恢复流程memory_sessions { limit: 20 }选出cwd与当前项目匹配的最近一个会话然后memory_recall { query: session top concepts, limit: 10 }期望输出形如Resuming 7f3a9c2 Auth refresh rework. Open question: should logout revoke all device tokens or just the current one? Next step: decide revoke scope, then update auth/logout.ts.注意其中两个参数的默认语义与源码一致memory_recall的limit默认为 10、memory_sessions的limit传入 20 是为了给候选会话留出足够余量——因为后续还要按cwd过滤、按startedAt排序窗口太窄可能漏掉最近一次匹配项目的会话。为什么这样设计两条核心原则技能Why一节阐述了两个不可妥协的原则按目录边界匹配会话而不是按原始前缀匹配一个兄弟仓库sibling repo永远不会被误认成当前仓库。这是防串场cross-project confusion的关键设计。永远不要为空的会话编造观察记录如果会话里没有任何 observation就如实报告没有可交接的内容而不是基于对话记忆脑补一段productive week。这两条原则在实际工具与数据模型中都有据可查会话的cwd字段由观察层记录见 src/functions/observe.ts 中payload.cwd的校验与写入逻辑仅当payload.cwd是非空字符串时才随观察一并落库。会话status的类型定义为active | completed | abandonedsrc/types.ts这正是工作流第 2 步中优先选择completed而非abandoned的判断依据会话结束后由 src/triggers/events.ts 等触发路径将status置为completed。五步工作流详解技能核心工作流Workflow共五步每一步都有明确的判定标准第 1 步解析项目路径若$ARGUMENTS提供了 cwd 覆盖参数用path.resolve(process.cwd(), $ARGUMENTS)归一化为绝对路径否则直接使用当前工作目录 cwd。第 2 步调用memory_sessions并匹配会话在返回的会话列表中选出cwd与项目路径满足目录边界匹配的最近一个会话。匹配条件为三者之一session.cwd projectPath OR session.cwd.startsWith(projectPath sep) OR projectPath.startsWith(session.cwd sep)其中sep是平台路径分隔符POSIX 下为/。在候选结果中优先选择completed状态的会话abandoned次之。若没有任何匹配则回退到全局最近的一个会话。第 3 步未回答的问题最先呈现如果该会话结束时遗留了面向用户的未回答问题必须最先把它呈现出来。判定方法查看summary字段或近期conversation观察中narrative以?结尾的条目。这正是让用户能直接接上上次的决策点的关键动作。第 4 步摘要输出用memory_recall按会话顶层概念检索limit为 10概括出标题/摘要、关键文件、关键决策或错误。检索查询词应取自会话的concepts顶层概念而不是凭印象自造关键词。第 5 步给出唯一的下一步指针以一个具体的next step?收尾引导用户从断点继续而不是泛泛地问你想做什么。反模式为什么原始前缀匹配是错的技能明确给出了正反两个写法WRONG: session.cwd.startsWith(projectPath) // 当项目是 /repo-a 时会匹配到 /repo-a-staging恢复错仓库的会话 RIGHT: session.cwd projectPath || session.cwd.startsWith(projectPath sep) // 目录边界检查不可能跨越兄弟仓库为什么startsWith(projectPath)危险因为/repo-a是/repo-a-staging的字符串前缀而startsWith(projectPath sep)要求匹配位置后紧跟路径分隔符/repo-a-staging中-不是分隔符于是被正确拒绝。同理projectPath.startsWith(cwd sep)覆盖了当前项目是历史会话的子目录这类反向嵌套场景例如曾在上层目录工作、现在进入子项目。EXAMPLES.md 中的示例 2 完整演示了这一场景的判定与回退逻辑。检查清单输出前的四项自检每次执行 handoff 后对照以下清单确认没有遗漏cwd 覆盖参数已解析为绝对且归一化的路径会话匹配使用的是目录边界检查而非原始前缀未回答的问题若有已置于响应最前面空会话被如实报告并提供从当前状态重新开始的选项。实战示例三种典型场景plugin/skills/handoff/EXAMPLES.md 提供了三个可直接对照的工作示例。示例 1带未回答问题的恢复用户说 Where were we?项目 cwd 为/Users/dev/app调用memory_sessions { limit: 20 }返回{ sessions: [ { id: 7f3a9c21, cwd: /Users/dev/app, title: Auth refresh rework, status: completed, startedAt: 2026-06-07T09:00:00Z, summary: Reworked refresh rotation. Open: should logout revoke all device tokens?, concepts: [jwt-refresh-rotation, logout] } ] }随后拉取支撑上下文memory_recall { query: jwt-refresh-rotation logout, limit: 10 }最终呈现Resuming7f3a9c2Auth refresh rework.Open question:should logout revoke all device tokens or just the current one? Touchedauth/refresh.ts,auth/logout.ts. Refresh rotation is done.Next step:decide the revoke scope, then finishauth/logout.ts.注意示例中查询词jwt-refresh-rotation logout直接取自返回的concepts字段这正是工作流第 4 步按顶层概念检索的落地方式。示例 2兄弟仓库守卫项目 cwd 为/Users/dev/repo-a而会话记录里存在cwd: /Users/dev/repo-a-staging的会话。原始前缀匹配会错误命中repo-a-staging边界检查则因为/Users/dev/repo-a-staging既不等于/Users/dev/repo-a、也不以/Users/dev/repo-a/开头而将其拒绝。此时应挑选真正的repo-a会话若仍无匹配则回退到全局最近会话。示例 3空会话用户说 Resume.但匹配到的会话没有任何观察记录。正确响应是如实说明The most recent sessionc98f110for this project has no recorded observations. Nothing to hand off. Want to start fresh from the current state?这正是Why原则二Never invent observations for an empty session的体现——空窗口是一个真实答案而不是编造活动的借口。与其他技能的关系handoff 不是孤立存在的它隶属于plugin/skills/下整套可调用技能体系。与其共享会话数据、视角互补的技能包括recap 技能按日期分组汇总最近 N 个会话适合 recap、what have we been doing 等回顾诉求session-history 技能查看同一份会话数据的完整历史视图recall 技能按查询词检索过去的观察与决策。实际编排时可先handoff续接断点再用recap补看整体脉络用recall深挖某个决策的细节。故障排查MCP 工具不可用时的回退路径技能末尾将通用排障指引指向共享文档 plugin/skills/_shared/TROUBLESHOOTING.md技能内的../_shared/TROUBLESHOOTING.md链接即指该文件避免每个技能重复维护一份排障块。场景一memory_*MCP 工具不出现若某个memory_*工具未出现在工具列表中说明 stdio MCP shim 未启动。按顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主——插件的.mcp.json仅在启动时读取新安装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemoryserver 显示为活连接。场景二REST 回退当 MCP 工具始终不可用、但守护进程仍在运行时可直接调用 REST API设置AGENTMEMORY_URL为守护进程基地址默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才附加Authorization: Bearer $AGENTMEMORY_SECRET——默认的本地守护进程是开放的多余的 header 会被拒绝。与 handoff 相关的 REST 端点映射为GET /agentmemory/sessionsPOST /agentmemory/smart-search前者等价于memory_sessions后者等价于智能检索。注意守护进程同样只在启动时读取.mcp.json因此任何端口或认证变更都需要重启后两个传输通道才会生效。小结handoff是 agentmemory 持久记忆能力在会话续接场景的标准答案以目录边界匹配杜绝兄弟仓库串场以未答问题置顶 单一 next step确保恢复的高信噪比以空会话如实上报守住事实底线。配合memory_sessions/memory_recall两个 MCP 工具定义见 src/mcp/tools-registry.ts与 REST 回退机制plugin/skills/_shared/TROUBLESHOOTING.md无论宿主是 Claude Code、Codex 还是其他支持 MCP 的编码 Agent都能在几秒内把用户带回到上一次离开的精确断点。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agentmemory handoff 技能实战：基于 memory_sessions 与 memory_recall 跨会话无缝恢复 Agent 工作现场
agentmemory handoff 技能实战基于 memory_sessions 与 memory_recall 跨会话无缝恢复 Agent 工作现场【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读handoff是 agentmemory 仓库中一个面向 AI 编码 Agent 的持久记忆技能解决的是「会话中断后如何无缝续接工作」这一核心问题当用户说出 where were we、resume、handoff、pick up where I left off或开启一个没有任何新鲜上下文的新会话时Agent 能够依据 handoff 技能定义 自动定位最近一次会话、把未回答的问题放在最前面并给出明确的下一步动作。读完本文你将掌握 handoff 的完整五步工作流、目录边界匹配的正确姿势、空会话与兄弟仓库等边界情况的处理以及 MCP 工具不可用时的 REST 回退方案。handoff 是什么技能定位与触发时机handoff定义于 plugin/skills/handoff/SKILL.md是一个user-invocable: true的用户可调用技能其元数据如下namehandoffdescriptionResume the most recent agent session for the current working directory, leading with any unanswered question. Use when the user says where were we, resume, handoff, pick up where I left off, or starts a session with no fresh context.argument-hint[optional cwd override]它与你可能已经熟悉的recap汇总最近 N 个会话、session-history查看完整会话历史、recall检索历史上下文共享同一份会话数据只是视角不同recap是纵向滚动的回顾handoff是单点续接的恢复。技能内See also一节明确列出了这一关系recap、session-history、recallsame session data, broader views。从实现层面看该技能实际调用的两个 MCP 工具都注册在 src/mcp/tools-registry.ts 的CORE_TOOLS中memory_sessionstools-registry.tsList recent sessions with their status and observation counts输入 schema 为空对象{}即无条件列出最近会话。memory_recalltools-registry.tsSearch past session observations for relevant context参数包括query必填支持关键词、文件名、概念、limit默认 10、formatfull/compact/narrative。Quick Start两条命令完成一次恢复技能的快速开始部分给出了最精简的恢复流程memory_sessions { limit: 20 }选出cwd与当前项目匹配的最近一个会话然后memory_recall { query: session top concepts, limit: 10 }期望输出形如Resuming 7f3a9c2 Auth refresh rework. Open question: should logout revoke all device tokens or just the current one? Next step: decide revoke scope, then update auth/logout.ts.注意其中两个参数的默认语义与源码一致memory_recall的limit默认为 10、memory_sessions的limit传入 20 是为了给候选会话留出足够余量——因为后续还要按cwd过滤、按startedAt排序窗口太窄可能漏掉最近一次匹配项目的会话。为什么这样设计两条核心原则技能Why一节阐述了两个不可妥协的原则按目录边界匹配会话而不是按原始前缀匹配一个兄弟仓库sibling repo永远不会被误认成当前仓库。这是防串场cross-project confusion的关键设计。永远不要为空的会话编造观察记录如果会话里没有任何 observation就如实报告没有可交接的内容而不是基于对话记忆脑补一段productive week。这两条原则在实际工具与数据模型中都有据可查会话的cwd字段由观察层记录见 src/functions/observe.ts 中payload.cwd的校验与写入逻辑仅当payload.cwd是非空字符串时才随观察一并落库。会话status的类型定义为active | completed | abandonedsrc/types.ts这正是工作流第 2 步中优先选择completed而非abandoned的判断依据会话结束后由 src/triggers/events.ts 等触发路径将status置为completed。五步工作流详解技能核心工作流Workflow共五步每一步都有明确的判定标准第 1 步解析项目路径若$ARGUMENTS提供了 cwd 覆盖参数用path.resolve(process.cwd(), $ARGUMENTS)归一化为绝对路径否则直接使用当前工作目录 cwd。第 2 步调用memory_sessions并匹配会话在返回的会话列表中选出cwd与项目路径满足目录边界匹配的最近一个会话。匹配条件为三者之一session.cwd projectPath OR session.cwd.startsWith(projectPath sep) OR projectPath.startsWith(session.cwd sep)其中sep是平台路径分隔符POSIX 下为/。在候选结果中优先选择completed状态的会话abandoned次之。若没有任何匹配则回退到全局最近的一个会话。第 3 步未回答的问题最先呈现如果该会话结束时遗留了面向用户的未回答问题必须最先把它呈现出来。判定方法查看summary字段或近期conversation观察中narrative以?结尾的条目。这正是让用户能直接接上上次的决策点的关键动作。第 4 步摘要输出用memory_recall按会话顶层概念检索limit为 10概括出标题/摘要、关键文件、关键决策或错误。检索查询词应取自会话的concepts顶层概念而不是凭印象自造关键词。第 5 步给出唯一的下一步指针以一个具体的next step?收尾引导用户从断点继续而不是泛泛地问你想做什么。反模式为什么原始前缀匹配是错的技能明确给出了正反两个写法WRONG: session.cwd.startsWith(projectPath) // 当项目是 /repo-a 时会匹配到 /repo-a-staging恢复错仓库的会话 RIGHT: session.cwd projectPath || session.cwd.startsWith(projectPath sep) // 目录边界检查不可能跨越兄弟仓库为什么startsWith(projectPath)危险因为/repo-a是/repo-a-staging的字符串前缀而startsWith(projectPath sep)要求匹配位置后紧跟路径分隔符/repo-a-staging中-不是分隔符于是被正确拒绝。同理projectPath.startsWith(cwd sep)覆盖了当前项目是历史会话的子目录这类反向嵌套场景例如曾在上层目录工作、现在进入子项目。EXAMPLES.md 中的示例 2 完整演示了这一场景的判定与回退逻辑。检查清单输出前的四项自检每次执行 handoff 后对照以下清单确认没有遗漏cwd 覆盖参数已解析为绝对且归一化的路径会话匹配使用的是目录边界检查而非原始前缀未回答的问题若有已置于响应最前面空会话被如实报告并提供从当前状态重新开始的选项。实战示例三种典型场景plugin/skills/handoff/EXAMPLES.md 提供了三个可直接对照的工作示例。示例 1带未回答问题的恢复用户说 Where were we?项目 cwd 为/Users/dev/app调用memory_sessions { limit: 20 }返回{ sessions: [ { id: 7f3a9c21, cwd: /Users/dev/app, title: Auth refresh rework, status: completed, startedAt: 2026-06-07T09:00:00Z, summary: Reworked refresh rotation. Open: should logout revoke all device tokens?, concepts: [jwt-refresh-rotation, logout] } ] }随后拉取支撑上下文memory_recall { query: jwt-refresh-rotation logout, limit: 10 }最终呈现Resuming7f3a9c2Auth refresh rework.Open question:should logout revoke all device tokens or just the current one? Touchedauth/refresh.ts,auth/logout.ts. Refresh rotation is done.Next step:decide the revoke scope, then finishauth/logout.ts.注意示例中查询词jwt-refresh-rotation logout直接取自返回的concepts字段这正是工作流第 4 步按顶层概念检索的落地方式。示例 2兄弟仓库守卫项目 cwd 为/Users/dev/repo-a而会话记录里存在cwd: /Users/dev/repo-a-staging的会话。原始前缀匹配会错误命中repo-a-staging边界检查则因为/Users/dev/repo-a-staging既不等于/Users/dev/repo-a、也不以/Users/dev/repo-a/开头而将其拒绝。此时应挑选真正的repo-a会话若仍无匹配则回退到全局最近会话。示例 3空会话用户说 Resume.但匹配到的会话没有任何观察记录。正确响应是如实说明The most recent sessionc98f110for this project has no recorded observations. Nothing to hand off. Want to start fresh from the current state?这正是Why原则二Never invent observations for an empty session的体现——空窗口是一个真实答案而不是编造活动的借口。与其他技能的关系handoff 不是孤立存在的它隶属于plugin/skills/下整套可调用技能体系。与其共享会话数据、视角互补的技能包括recap 技能按日期分组汇总最近 N 个会话适合 recap、what have we been doing 等回顾诉求session-history 技能查看同一份会话数据的完整历史视图recall 技能按查询词检索过去的观察与决策。实际编排时可先handoff续接断点再用recap补看整体脉络用recall深挖某个决策的细节。故障排查MCP 工具不可用时的回退路径技能末尾将通用排障指引指向共享文档 plugin/skills/_shared/TROUBLESHOOTING.md技能内的../_shared/TROUBLESHOOTING.md链接即指该文件避免每个技能重复维护一份排障块。场景一memory_*MCP 工具不出现若某个memory_*工具未出现在工具列表中说明 stdio MCP shim 未启动。按顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主——插件的.mcp.json仅在启动时读取新安装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemoryserver 显示为活连接。场景二REST 回退当 MCP 工具始终不可用、但守护进程仍在运行时可直接调用 REST API设置AGENTMEMORY_URL为守护进程基地址默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才附加Authorization: Bearer $AGENTMEMORY_SECRET——默认的本地守护进程是开放的多余的 header 会被拒绝。与 handoff 相关的 REST 端点映射为GET /agentmemory/sessionsPOST /agentmemory/smart-search前者等价于memory_sessions后者等价于智能检索。注意守护进程同样只在启动时读取.mcp.json因此任何端口或认证变更都需要重启后两个传输通道才会生效。小结handoff是 agentmemory 持久记忆能力在会话续接场景的标准答案以目录边界匹配杜绝兄弟仓库串场以未答问题置顶 单一 next step确保恢复的高信噪比以空会话如实上报守住事实底线。配合memory_sessions/memory_recall两个 MCP 工具定义见 src/mcp/tools-registry.ts与 REST 回退机制plugin/skills/_shared/TROUBLESHOOTING.md无论宿主是 Claude Code、Codex 还是其他支持 MCP 的编码 Agent都能在几秒内把用户带回到上一次离开的精确断点。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考