agentmemory recap 技能实战:用 memory_sessions 与 memory_recall 打造按日分组的会话工作回顾

agentmemory recap 技能实战:用 memory_sessions 与 memory_recall 打造按日分组的会话工作回顾 agentmemory recap 技能实战用 memory_sessions 与 memory_recall 打造按日分组的会话工作回顾【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 的recap技能定义见 plugin/skills/recap/SKILL.md为 AI 编码 Agent 提供了一条标准化的最近工作回顾路径当用户询问 recap、what have we been doing、today、this week 或希望获得近期工作的汇总时Agent 通过memory_sessions拉取最近会话、按本地日期分组再借memory_recall为每个会话提取高重要性观察最终生成紧凑且可核对的回顾。读完本文你将掌握 recap 的完整调用流程、时间窗口解析规则、输出格式约定与反模式规避并能结合仓库源码理解memory_sessions/memory_recall在 MCP 层与 REST API 层的真实实现与边界行为。recap 是什么技能的定位与触发场景recap是一个用户可直接调用user-invocable的 agentmemory 技能其 frontmatter 中的描述明确了职责边界对当前项目最近的 N 个 Agent 会话做摘要按本地日历日期分组每个会话附带高亮观察highlight observations。触发词覆盖了最常见的回顾诉求recap、what have we been doing、today、this week以及任何最近工作汇总的意图。参数提示为[last N | today | this week]即三种典型的窗口形态。技能入口行会向 LLM 传递用户原始参数The user wants a recap. Time window args: $ARGUMENTS后续所有窗口解析都基于$ARGUMENTS展开。快速上手两次 MCP 调用 一段输出技能文档给出的最小可运行路径只有两步见 SKILL.md先拉取会话列表memory_sessions { limit: 30 }对每个存活的会话surviving session用该会话的顶层概念做召回memory_recall { query: top concepts, limit: 3 }期望输出是一个按日期分组的紧凑文本块2026-06-07 7f3a9c2 · Auth refresh rework · 14 obs · completed - [8] Rotate refresh tokens on every use 3 sessions across 2 days, 41 observations.其中[8]表示该观察的 importance 分值为 8亮点阈值见下文亮点筛选行尾14 obs为该会话的 observationCountcompleted为会话状态。最后一行是对全部存活会话的汇总统计。时间窗口解析$ARGUMENTS 的四种形态SKILL.md 明确规定了参数解析规则Agent 必须按以下映射执行参数形态窗口含义today当前本地日期当天this week最近 7 天last n或裸数字如recap 3最近 N 个会话空参数默认取最近 10 个会话注意这里的this week被技能定义为最近 7 天这一滚动窗口而非自然周的周一起点这是实现上刻意简化的约定。today则对应运行 Agent 机器的本地日期local calendar date。完整工作流五步标准流程SKILL.md 给出了标准工作流共五步解析$ARGUMENTS按上表把用户输入映射为时间窗口调用memory_sessions并过滤只保留cwd与当前工作目录匹配的会话项目隔离应用窗口并按startedAt降序排序按本地日历日期分组日期格式YYYY-MM-DD逐会话呈现每个会话列出 id前 8 个字符、标题或首个 prompt、观察数observationCount、状态再从memory_recall中缩进 2~3 条亮点importance 7收尾汇总以N sessions across M days, K observations.结束。值得强调第 2 步中的项目过滤memory_sessions返回的是全量近期会话recap 必须用会话的cwd字段与当前工作目录比对剔除其他项目的会话——这与仓库中项目作用域project scope的隔离设计一致相关测试见 remember-project-scope.test.ts。亮点筛选与输出约定为什么必须来自 memory_recall技能强调高亮观察必须来自memory_recall的返回值而不是对会话的转述或 LLM 凭记忆的概括Highlights come frommemory_recall, not paraphrase。原因在于memory_recall是检索真实落盘的观察记录其返回结果带有 importance 分值可被下游核对。从源码看importance 是观察observation的一个核心字段贯穿多个功能模块高重要性观察的筛选阈值在仓库中多处出现importance 7例如 profile.ts 在构建画像时过滤importance 7的观察其他模块使用不同阈值满足不同诉求如 consolidate.ts 与 context.ts 取importance 5file-index.ts 取 4quality.ts 中评估器还会校验观察的 importance 是否落在 1~10 的合法区间。因此 recap 中importance 7的约定并非凭空设定而是与 profile 等模块共用同一高价值观察语义。反模式空窗口是真实答案SKILL.md 用一组对比点明最容易犯的错误WRONG窗口内没有会话却基于对话记忆编造这周做了一周充满成效的 auth 工作RIGHT如实输出No sessions in the last 7 days for this project.这是技能设计的一个核心原则——只总结工具真正返回的会话与观察Only summarize sessions and observations the tools returned。空窗口是有效答案a real answer绝不是触发虚构活动的信号。这在依赖 Agent 自主调用的场景下尤其重要能防止回顾性幻觉污染后续决策。输出前自检清单技能内置了四步自查SKILL.md可作为 Agent 输出前的最小校验窗口是否按参数正确解析today/this week/last N/ 默认 10会话是否已过滤到当前项目的 cwd亮点是否确实来自memory_recall而非转述汇总行的N sessions across M days, K observations.是否与实际展示的数字一致计数必须可核对。相关技能对照同一份会话数据的不同视角SKILL.md 明确指出handoff、session-history、recall与 recap 共享同一份会话数据只是视角不同技能视角依赖的会话数据recap按日期分组的近期工作汇总memory_sessionsmemory_recallhandoff交接上下文memory_sessionsmemory_recallsession-history完整会话历史memory_sessionsrecall语义召回过去观察memory_recall/memory_smart_search它们各自的技能定义位于 plugin/skills/handoff/SKILL.md、plugin/skills/session-history/SKILL.md、plugin/skills/recall/SKILL.md需要区分回顾汇总与精确检索两种诉求时可以参考。故障排查MCP 工具不可用时的降级路径若memory_sessions或memory_recall在宿主环境中不可用技能指向共享的 plugin/skills/_shared/TROUBLESHOOTING.md按顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主——插件的.mcp.json只在启动时读取新装或重新启用的插件不会在会话中途注册工具查看/mcp确认agentmemoryserver 显示为 live 连接。若 MCP 工具始终不可用但 daemon 在运行可降级为直接调用 REST API设置AGENTMEMORY_URL为 daemon 基地址默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才附加Authorization: Bearer $AGENTMEMORY_SECRET头——默认的 localhost daemon 是开放的多余的头反而会被拒绝。recap 对应的 REST 调用为GET /agentmemory/sessions POST /agentmemory/smart-search即先GET会话列表再用POST /agentmemory/smart-search替代memory_recall做亮点检索。TROUBLESHOOTING 文档还提醒daemon 同样只在启动时读取.mcp.json任何端口或鉴权变更都需要重启后两个传输通道才能感知。实战示例三种典型输入EXAMPLES.md 提供了三个可直接对照的完整样例本文完整保留并补充解析。示例 1Recap this week窗口为最近 7 天。调用memory_sessions { limit: 30 }过滤到 cwd 与 7 天窗口后返回两个会话{ sessions: [ { id: 7f3a9c21, cwd: /Users/dev/app, title: Auth refresh rework, startedAt: 2026-06-07T09:00:00Z, observationCount: 14, status: completed, concepts: [jwt-refresh-rotation, auth-flow] }, { id: b21d004e, cwd: /Users/dev/app, title: Rate limiter audit, startedAt: 2026-06-05T14:00:00Z, observationCount: 9, status: completed, concepts: [rate-limiter, per-ip-bug] } ] }注意concepts字段它正是第 2 步每会话执行memory_recall时 query 的素材来源。逐会话拉取亮点memory_recall { query: jwt-refresh-rotation auth-flow, limit: 3 }最终呈现亮点带 importance 分值2026-06-077f3a9c2Auth refresh rework, 14 obs, completed[8] Rotate refresh tokens on every use2026-06-05b21d004eRate limiter audit, 9 obs, completed[7] limit.ts counts per-IP, not per-user2 sessions across 2 days, 23 observations.这里两个会话的亮点分别为 importance 8 与 7均满足 7的阈值23 observations即 14 9汇总行与实际计数严格一致。示例 2Bare number用户输入recap 3时视为last 3调用memory_sessions { limit: 3 }按日期分组输出格式与示例 1 完全相同。这也是裸数字等于最近 N 个会话规则的落地样例。示例 3空窗口用户输入Recap today.若memory_sessions返回的会话中没有任何一个满足startedAt在今天且cwd匹配则正确输出不是虚构而是No sessions today for this project. The most recent was yesterday,7f3a9c2Auth refresh rework. Want a recap of that instead?这个示例同时展示了两个要点一是空窗口如实声明二是可以基于已有数据给出可选的下一步建议指向最近的会话保持答案的实用性。底层实现从 MCP 工具到会话存储recap 依赖的两个工具在源码中有明确定义理解它们有助于预测边界行为。memory_sessions 与 memory_recall 的工具契约在 src/mcp/tools-registry.ts 中memory_recall描述为检索过去的会话观察用于查找之前的决策或某个文件如何被修改入参query必填、limit默认 10、formatfull / compact / narrative、token_budget可选的 token 预算用于裁剪返回结果memory_sessions描述为列出最近会话及其状态与观察计数入参为空对象properties: {}memory_smart_search混合语义 关键词检索支持expandIds渐进展开默认 limit 10。memory_recall与memory_smart_search在工具注册表中是并列的两个工具但从 REST 映射看二者都落到智能搜索通道见下文。MCP 代理层参数校验与默认值src/mcp/standalone.ts 揭示了关键默认值与代理行为memory_sessions的limit通过parseLimit(args[limit], 20)解析默认值为 20技能示例中显式传 30 正是为了覆盖更多会话memory_recall的代理调用是POST /agentmemory/smart-search即召回本质上走的是混合检索通道memory_sessions的代理调用是GET /agentmemory/sessions?limitn。而在独立standalone模式下memory_sessions会退化为直接读取 KV 中的mem:sessions键并截取前 N 条standalone.ts。REST 层/agentmemory/sessions 的真实语义src/triggers/api.ts 实现了GET /agentmemory/sessions值得注意的实现细节支持agentId查询参数过滤*表示通配不过滤缺省时若启用了 agent 隔离isAgentScopeIsolated()则默认按当前getAgentId()过滤——这印证了会话数据具有 agent 作用域维度获取摘要时采用分批扇出每批 10 个并发kv.get、批间串行避免数百个会话同时触发引擎调用打满调用池每个会话对象会附带对应的summary若有但会话基础字段id / cwd / title / startedAt / observationCount / status / concepts不依赖摘要存在因此即使摘要缺失recap 的前三步过滤、排序、分组依然可用。会话与观察的数据来源会话记录由观察写入流程维护。在 src/functions/observe.ts 中可以看到每次观察写入都会递增会话的observationCount若会话尚不存在例如某些插件跳过POST /session/start直接上报观察会基于观察载荷隐式创建会话记录id、project、cwd 等否则memory_sessions永远列不出这些会话每会话观察数有上限默认MAX_OBS_PER_SESSION 500src/config.ts达到上限后写入被拒绝——这解释了为什么 recap 输出中的 observationCount 总是有界的。检索通道smart-search 的 limit 语义src/functions/smart-search.ts 展示了memory_recall/memory_smart_search底层的混合检索实现limit会被钳制在 1~100 之间Math.max(1, Math.min(data.limit ?? 20, 100))默认 20检索会超额拉取over-fetchlimit * 3上限 300再截断到请求的 limit为后续的重排与渐进展开预留余量支持lessons召回通道recallLessonslessonLimit Math.min(limit, 10)。这些细节意味着 recap 中memory_recall { limit: 3 }的实际行为是检索器先取更多候选再精筛出 3 条最相关的观察返回与技能只取 2~3 条亮点的输出约定天然匹配。小结recap 技能把回顾最近工作这个高频诉求收敛为一套可复现、可核对的协议参数决定窗口memory_sessions提供事实memory_recall提供亮点cwd 过滤保证项目隔离importance 7 保证亮点质量空窗口如实回答杜绝幻觉。配合 MCP 层默认值limit 20、REST 降级路径GET /agentmemory/sessionsPOST /agentmemory/smart-search以及源码中的分批扇出、隐式建会话等实现细节任何 Agent 都能在 agentmemory 之上稳定地产出3 sessions across 2 days, 41 observations式的可信回顾。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考