Quick Start

本页说明如何使用 Node SDK 完成 GUMem 的最小接入：创建 Session、写入对话消息、查询 Memory，并把召回结果放入下一轮 Agent 上下文。

如果你使用 Python，请阅读 Python SDK。如果你需要直接调用 HTTP API，请先确认接口版本和 endpoint 已经在你的部署中稳定。

前置条件

开始前，请准备：

Node.js 18 或更高版本。
在 GUMem Console 创建的服务端 GUMEM_API_KEY。
一个能稳定标识用户的业务 user_id。
一个可信服务端运行环境，例如 API route、worker、Express 服务或 Agent 后端。

GUMem API Key 只能放在服务端。不要把 API Key 暴露给浏览器、移动端应用、客户端脚本或公开仓库。

安装

bash

npm install @steamory-agent-kit/gumem

本地验证时，把 API Key 设置为环境变量：

bash

export GUMEM_API_KEY="<your-gumem-api-key>"

1. 创建 client

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

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

2. 创建 Session

为一次用户会话创建 Session，并保存返回的 session.id。后续写入消息和查询 Memory 都会围绕这个 Session 进行。

const session = await gumem.sessions.create({
  user_id: "user_123",
  title: "Team scheduling session",
});

console.log(session.id);

user_id 应该来自你的业务系统。它决定跨 Session 的长期 Memory 归属于哪个用户。

3. 写入对话消息

把后续任务可能复用的信息写入 GUMem。这里的例子写入用户对团队排期城市的偏好。

await session.addMessages([
  {
    role: "user",
    content:
      "For team scheduling, use Berlin when I mention Europe and Toronto when I mention the Americas.",
  },
  {
    role: "assistant",
    content:
      "Got it. I will use Berlin for Europe scheduling and Toronto for Americas scheduling.",
  },
]);

不要把所有临时中间状态都写入 GUMem。更适合写入的是长期偏好、明确计划、稳定约束和会影响后续任务的事实。

4. 查询 Memory

在下一轮 Agent 响应前，使用当前用户问题查询相关 Memory。

const memory = await session.getMemory({
  query: "which city should be used for Europe team scheduling",
});

console.log(memory.data);

GUMem 会返回可用于下一轮 Agent 响应的上下文。常见字段包括：

字段	说明
`short_term_context`	当前 Session 最近消息组成的短期上下文。
`mid_term_context`	与 query 相关的阶段性信息。
`long_term_user_context`	跨 Session 复用的用户长期 Memory。
`long_term_session_context`	当前 Session 内沉淀出的长期上下文。
`formatted_context`	已格式化的上下文文本，通常可直接放入 Agent prompt。

5. 放入 Agent 上下文

在真实 Agent 中，推荐顺序是先召回 Memory，再调用模型，最后把本轮消息写回 GUMem。

async function assistantTurn(sessionId: string, userContent: string) {
  const session = gumem.sessions.fromId(sessionId);

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

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

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

  const assistantReply = await callYourLLM(systemPrompt, userContent);

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

  return assistantReply;
}

如果写回 GUMem 失败，通常不应阻塞用户正在等待的主响应。记录错误并在后台重试更适合大多数 Agent 产品。

检查结果

完成本页操作后，你应能做到：

SDK 已安装，并使用 GUMEM_API_KEY 建立认证。
已为一个业务用户创建 Session，并保存 session.id。
已写入会影响后续任务的对话消息。
下一轮查询可以返回相关 Memory，并将其放入 Agent prompt。

下一步

阅读 Overview 理解 GUMem 的边界和最小链路。
阅读 What to remember 判断哪些信息应该写入 GUMem。
阅读 Node SDK 查看完整 SDK 方法、错误处理和 Troubleshooting。

Quick Start ​

前置条件 ​

安装 ​

1. 创建 client ​

2. 创建 Session ​

3. 写入对话消息 ​

4. 查询 Memory ​

5. 放入 Agent 上下文 ​

检查结果 ​

下一步 ​