agentmemory session-history 技能实战用 memory_sessions 构建可信的跨会话时间线【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读本指南聚焦 agentmemory 开源仓库中session-history这一用户可主动调用的技能skill讲解 AI 编码 Agent 如何通过 MCP 工具memory_sessions把近期会话整理成一份干净、可信的时间线回答上次我们做了什么会话历史这类问题。读完本文你将掌握该技能的标准调用方式、输出编排规则、反模式规避方法并理解其背后memory_sessions工具在 src/mcp/tools-registry.ts 与 src/mcp/server.ts 中的真实实现原理以及 MCP 工具不可用时的 REST 回退方案。技能定位把上次做了什么变成可验证的答案session-history是 agentmemory 仓库中 plugin/skills/session-history/SKILL.md 定义的技能其 frontmatter 明确了适用场景name: session-history description: Show what happened in recent past sessions on this project as a clean timeline. Use when the user asks what did we do last time, session history, past sessions, or wants an overview of previous work. user-invocable: true从描述可以看出它的两个关键特性只做展示show它不搜索、不总结、不推断只把工具返回的近期会话按时间倒序陈列出来形成一条时间线。用户可主动调用user-invocable用户可以直接要求 Agent 执行该技能也可以由 Agent 在收到what did we do last time等请求时自行触发。在整套技能体系中session-history与 recap按日期分组汇总、handoff直接跳到最近一次会话继续工作、recall跨会话按主题搜索共享同一份会话数据只是观察视角不同前者是按时间倒序的原始时间线后者分别是分组汇总断点续传主题检索。快速上手一次调用产出时间线技能的核心调用非常简单只需一次 MCP 工具调用memory_sessions { limit: 20 }预期的输出格式如下会话 id 取前 8 位、项目名、开始时间、状态、观测数关键高亮为类型 标题7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs - decision: Rotate refresh tokens on every use b21d004 · app · 2026-06-05 14:00 · completed · 9 obs - code: limit.ts counts per-IP关于limit参数从 src/mcp/standalone.ts 的实现可以看到默认值逻辑memory_sessions的参数校验调用parseLimit(args[limit], 20)即未传limit时默认取 20 条对应地处理分支会先kvInstance.list(mem:sessions)列出全部会话再slice(0, limit)截断见 src/mcp/standalone.ts。因此limit: 20恰好覆盖有意义的近期窗口是官方推荐的默认取值。设计原则空历史是真实答案而非编造线索session-history技能在 Why 一节明确了一条铁律Only show sessions and observations the tool returned. An empty history is a real answer, never a cue to invent past work.即只展示工具返回的会话与观测空历史本身就是真实答案绝不能把它当作编造过往工作的提示。这条原则与 recap 中的同类约束An empty window is a real answer, not a prompt to invent activity一脉相承是整个记忆类技能的可信度基石——Agent 会话数据必须来自工具的真实返回任何凭对话记忆脑补出来的历史都会污染记忆系统的可信度。工作流五步产出规范时间线session-history的工作流分为五个明确步骤SKILL.md 原文如下调用memory_sessions并传入limit: 20获取一个有意义的窗口。按时间倒序呈现会话 id前 8 位、项目、开始时间、状态。对有观测的会话展示关键高亮类型 标题。标注每个会话的观测总数。当会话存在摘要summary时呈现其标题与关键决策。每一步都有明确的产出要求其中会话 id 取前 8 位与工具返回数据的实际形态一致EXAMPLES 中的示例响应里会话 id 形如7f3a9c21展示时截断为7f3a9c2。状态字段则对应 src/types.ts 中Session接口定义的联合类型active | completed | abandoned。反模式展示与编造的分界线技能用一组正反对照明确了输出纪律错误做法WRONG工具只返回两个会话你却描述连续几周稳定推进还补上自己从对话里记住的会话——这是典型的编造。正确做法RIGHT只展示工具返回的这两个会话每个都带真实的 id、状态和观测数。为什么必须如此严格因为session-history的消费方是用户本人或后续的 Agent 会话任何混入的虚构条目都会让记忆失去可信度进而误导后续决策。这与 handoff 中绝不为空会话编造观测Never invent observations for an empty session的约束完全一致。输出自检清单每次执行完该技能应逐项核对展示的每个会话都来自工具响应。顺序为时间倒序reverse-chronological。每个会话的观测数与响应一致。没有会话或高亮是被编造或合并的。这份清单既是 Agent 的自我校验工具也可以作为评测脚本断言确保每次输出都可复现、可审计。实战示例三种典型场景技能配套的 EXAMPLES.md 给出了三个完整示例覆盖了最典型的分支情况。示例 1标准时间线用户Show me the session history.调用memory_sessions { limit: 20 }工具响应关键字段id、project、startedAt、status、observationCount、summary、highlights{ sessions: [ { id: 7f3a9c21, project: app, startedAt: 2026-06-07T09:00:00Z, status: completed, observationCount: 14, summary: Reworked refresh rotation, highlights: [ { type: decision, title: Rotate refresh tokens on every use } ] }, { id: b21d004e, project: app, startedAt: 2026-06-05T14:00:00Z, status: completed, observationCount: 9, highlights: [ { type: code, title: limit.ts counts per-IP } ] } ] }Agent 呈现给用户的时间线7f3a9c2app, 2026-06-07 09:00, completed, 14 obsdecision: Rotate refresh tokens on every use (summary: Reworked refresh rotation)b21d004app, 2026-06-05 14:00, completed, 9 obscode: limit.ts counts per-IP注意高亮行携带了类型decision/code与标题并在第一条后附加了摘要标题正好对应工作流第 3、5 步。示例 2无观测的会话如果返回的会话observationCount: 0仍然要列出它但如实说明c98f110app, 2026-06-04 11:00, abandoned, 0 obs (no recorded work)这里abandoned状态说明该会话以中断方式结束。从源码看会话状态转换由多种途径触发例如 src/functions/replay.ts 在回放结束时将active会话标记为completedsrc/functions/diagnostics.ts 会以abandoned-session:id命名检测到的问题项——这些都可以佐证abandoned是系统真实产生的合法状态Agent 应如实展示而非隐去。示例 3空历史用户What did we do last time?工具响应{ sessions: [] }Agent 的诚实回答No recorded sessions yet for this project. Once you work with memory capture on, they will show here. Userememberto save a note now.这个示例与空历史是真实答案的原则直接呼应不编造、不猜测同时给出后续行动指引开启记忆捕获、或用remember先保存一条笔记。背后的工具memory_sessions 的实现与字段session-history的全部数据来自 MCP 工具memory_sessions。它在 src/mcp/tools-registry.ts 中注册{ name: memory_sessions, description: List recent sessions with their status and observation counts., inputSchema: { type: object, properties: {} }, }几点值得注意的实现细节无必填参数inputSchema.properties为空对象limit属于可选参数由 standalone 代理层解析默认 20。属于精简核心工具集在 plugin/skills/agentmemory-mcp-tools/REFERENCE.md 自动生成的工具清单中memory_sessions标记为 core核心集合工具即--tools core模式下也可用而非仅存在于--tools all的完整集合中。服务端处理在 src/mcp/server.ts 中memory_sessions分支直接执行kv.list(KV.sessions)并原样返回全部会话记录由上层决定是否截断。会话记录的数据结构定义在 src/types.tsexport interface Session { id: string; project: string; cwd: string; startedAt: string; endedAt?: string; status: active | completed | abandoned; observationCount: number; model?: string; tags?: string[]; firstPrompt?: string; summary?: string; commitShas?: string[]; agentId?: string; }其中project与cwd用于区分不同项目session-history默认展示当前项目的时间线firstPrompt可用于显示会话标题summary即工作流第 5 步提到的会话摘要。会话记录是如何诞生的从 src/functions/observe.ts 的实现看当插件如 OpenCode跳过POST /session/start直接上报观测时系统会依据观测载荷隐式创建会话记录status: active、observationCount: 1并从用户提示中提取最多 200 字符作为firstPrompt。这意味着有时间线的前提是记忆捕获机制在正常工作这也解释了空历史示例中Once you work with memory capture on的提示——会话是随观测活动逐步积累出来的。与相邻技能的分工session-history的 See also 一节给出了三条互补路径它们在数据源上相同、在呈现方式上互补技能数据源视角典型触发语session-historymemory_sessions按时间倒序的原始时间线what did we do last timerecapmemory_sessionsmemory_recall按日期分组的汇总 高亮观测recap、this weekhandoffmemory_sessionsmemory_recall直接恢复最近一次会话where were we、resumerecallmemory_recall跨会话按主题检索recall、do you remember例如需要今天/本周都干了什么时应该用recap它支持today、this week、last n等时间窗口参数并按本地日期 YYYY-MM-DD 分组、以memory_recall补充每条会话的高亮观测需要接着上次继续干时应该用handoff它会优先呈现上次遗留的未回答问题并给出一个具体的 next step。而session-history的定位始终是最朴素的近期会话时间线。故障排查工具不可用与 REST 回退如果memory_sessions不可用例如 stdio MCP shim 未启动技能的 Troubleshooting 一节指向共享的 plugin/skills/_shared/TROUBLESHOOTING.md其中给出了两阶段恢复方案。第一阶段恢复 MCP 工具按顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled。重启宿主——插件的.mcp.json只在启动时读取新安装或重新启用的插件不会在会话中途注册工具。检查/mcp确认agentmemory服务器显示为活跃连接。第二阶段REST 回退。当 MCP 工具持续不可用但守护进程daemon在运行时可直接调用 REST API将AGENTMEMORY_URL设为守护进程基础地址默认http://localhost:3111。仅当设置了AGENTMEMORY_SECRET时才附加Authorization: Bearer $AGENTMEMORY_SECRET请求头——默认的本机守护进程是开放的多余的请求头反而会被拒绝。session-history对应的 REST 端点为GET /agentmemory/sessions同一张端点映射表中recap与handoff还需追加POST /agentmemory/smart-search获取高亮。注意守护进程同样只在启动时读取.mcp.json因此任何端口或认证变更都需要重启才能被两个传输通道感知。小结session-history技能的价值不在于花哨而在于克制与可信一次memory_sessions { limit: 20 }调用严格按时间倒序、如实展示每个会话的 id、状态与观测数空历史就如实回答暂无记录。配合 EXAMPLES.md 的三个典型示例、SKILL.md 的五步工作流与自检清单任何 Agent 都能稳定地产出可复现、可审计的会话时间线而工具注册、会话数据结构与隐式创建逻辑等源码细节则为理解这条时间线的数据来源提供了完整的实现依据。若想进一步探索可以通读同一目录下 recap、handoff 技能以及 src/types.ts 中的完整数据模型。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考