企业官网建设流程全解析

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 原文如下：

1. 调用memory_sessions并传入limit: 20，获取一个有意义的窗口。
2. 按时间倒序呈现：会话 id（前 8 位）、项目、开始时间、状态。
3. 对有观测的会话，展示关键高亮（类型 + 标题）。
4. 标注每个会话的观测总数。
5. 当会话存在摘要（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 obs
  • decision: Rotate refresh tokens on every use (summary: Reworked refresh rotation)
• b21d004app, 2026-06-05 14:00, completed, 9 obs
  • code: 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会话标记为completed；src/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.ts：

export 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" 一节给出了三条互补路径，它们在数据源上相同、在呈现方式上互补：

例如需要"今天/本周都干了什么"时应该用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 工具，按顺序排查：

1. 在宿主中运行/plugin list，确认agentmemory显示为 enabled。
2. 重启宿主——插件的.mcp.json只在启动时读取，新安装或重新启用的插件不会在会话中途注册工具。
3. 检查/mcp，确认agentmemory服务器显示为活跃连接。

第二阶段：REST 回退。当 MCP 工具持续不可用但守护进程（daemon）在运行时，可直接调用 REST API：

1. 将AGENTMEMORY_URL设为守护进程基础地址（默认http://localhost:3111）。
2. 仅当设置了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