User Case

这个场景适合 GUMem，因为用户不应该每次都重复说明“欧洲团队用 Berlin，美洲团队用 Toronto”。这些偏好会影响后续排期任务，应该被召回。

场景

用户正在使用一个 team scheduling assistant。你的服务端已经保存了当前对话的 session.id，并且此前已经写入过用户的排期偏好。

本轮用户输入：

Can you schedule the Europe team check-in for next week?

Agent 应该先查询 GUMem。如果 Memory 中已经有 “Europe team uses Berlin” 这类偏好，就在回复和后续工具调用中自然使用它。

推荐顺序

1. 用户输入到达服务端。
2. 使用当前 session.id 查询 GUMem Memory。
3. 把召回结果放入模型上下文。
4. 调用模型生成回复。
5. 将本轮用户消息和 assistant 回复异步写回 GUMem。

先召回再生成，最后写回。这样本轮回复不会污染本轮召回结果。

示例

import { GUMemClient } from "@steamory-agent-kit/gumem";

const gumem = new GUMemClient({
  apiKey: process.env.GUMEM_API_KEY!,
});

async function schedulingAssistantTurn(params: {
  sessionId: string;
  userContent: string;
}) {
  const session = gumem.sessions.fromId(params.sessionId);

  const memory = await session.getMemory({
    query: params.userContent,
    details: true,
  });

  const systemPrompt = `
You are a team scheduling assistant.
Use recalled memory only when it is relevant to the current scheduling task.

Recalled memory:
${memory.data?.formatted_context ?? JSON.stringify(memory.data ?? {}, null, 2)}
`;

  const assistantReply = await callYourLLM(systemPrompt, params.userContent);

  void session.addMessages([
    { role: "user", content: params.userContent },
    { role: "assistant", content: assistantReply },
  ]).catch((error) => {
    console.error("GUMem memory write failed", error);
  });

  return {
    reply: assistantReply,
    recalledMemory: memory.data,
  };
}

检查结果

这个流程接通后，你应该能观察到：

• 用户问欧洲团队排期时，Agent 可以召回与 Europe team 相关的城市偏好。
• GUMem 写入失败不会阻塞当前用户响应。
• 新一轮用户消息和 assistant 回复会进入后续 Memory 处理链路。
• 当召回结果为空时，Agent 仍能正常询问必要信息，而不是假装知道用户偏好。

失败处理

情况	推荐处理
Query Memory 失败	记录错误，降级为无历史 Memory 的普通 Agent 回复。
写回 GUMem 失败	不阻塞主响应，记录错误并在后台重试。
召回结果为空	让 Agent 向用户询问缺失信息。
召回结果和当前输入冲突	以用户当前明确表达为准，并把更正写回 GUMem。

下一步

• 阅读 Quick Start 完成最小 GUMem 接入。
• 阅读 What to remember 判断哪些偏好和行为应该写入 GUMem。
• 阅读 Query Memory 调整召回范围和返回内容。