Quick Start

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

前置条件

开始前，请准备：

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

安装

Node SDKPython SDK

bash

npm install @steamory-agent-kit/gumem
export GUMEM_API_KEY="<your-gumem-api-key>"

bash

pip install steamory-agent-kit-gumem
export GUMEM_API_KEY="<your-gumem-api-key>"

1. 初始化访问方式

Node SDKPython SDKcURL

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

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

python

import os

from gumem import GUMemClient

gumem = GUMemClient(api_key=os.environ["GUMEM_API_KEY"])

bash

export GUMEM_API_KEY="<your-gumem-api-key>"
export GUMEM_BASE_URL="http://localhost:8000"

2. 创建 Session

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

Node SDKPython SDKcURL

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

console.log(session.id);

python

session = gumem.sessions.create({
    "user_id": "user_123",
})

print(session.id)

bash

curl -sS -X POST "$GUMEM_BASE_URL/api/sessions" \
  -H "Authorization: Api-Key $GUMEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123"
  }'

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

3. 写入对话消息

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

Node SDKPython SDKcURL

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.",
  },
]);

python

session.add_messages([
    {
        "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."
        ),
    },
])

bash

export GUMEM_SESSION_ID="session_xxx"

curl -sS -X POST "$GUMEM_BASE_URL/api/sessions/$GUMEM_SESSION_ID/messages" \
  -H "Authorization: Api-Key $GUMEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "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。

Node SDKPython SDKcURL

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

console.log(memory.data);

python

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

print(memory.get("data"))

bash

curl -sS -G "$GUMEM_BASE_URL/api/sessions/$GUMEM_SESSION_ID/context" \
  -H "Authorization: Api-Key $GUMEM_API_KEY" \
  --data-urlencode "query=which city should be used for Europe team scheduling" \
  --data-urlencode "details=false"

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

字段	类型	说明
`history`	`list[Message]`	当前 Session 中返回的 Message 列表。没有可返回消息时为空列表。
`facts`	`str`	与 query 相关的 Facts 文本。没有命中 Facts 时为空字符串。
`summary`	`str`	当前 Session 或用户上下文中可用于本次召回的 Summary。没有可用 Summary 时为空字符串。
`formatted_context`	`str`	已格式化的上下文文本，通常可直接放入 Agent prompt。没有可格式化上下文时为空字符串。

5. 放入 Agent 上下文

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

Node SDKPython SDKcURL

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;
}

python

def assistant_turn(session_id: str, user_content: str) -> str:
    session = gumem.sessions.from_id(session_id)

    memory = session.get_memory({
        "query": user_content,
    })
    memory_data = memory.get("data") or {}

    system_prompt = f"""
You are a team scheduling assistant.
Use the recalled memory when it is relevant.

Recalled memory:
{memory_data.get("formatted_context") or memory_data}
"""

    assistant_reply = call_your_llm(system_prompt, user_content)

    try:
        session.add_messages([
            {"role": "user", "content": user_content},
            {"role": "assistant", "content": assistant_reply},
        ])
    except Exception as error:
        print("GUMem memory write failed", error)

    return assistant_reply

bash

USER_CONTENT="Which city should I use for Europe team scheduling?"

curl -sS -G "$GUMEM_BASE_URL/api/sessions/$GUMEM_SESSION_ID/context" \
  -H "Authorization: Api-Key $GUMEM_API_KEY" \
  --data-urlencode "query=$USER_CONTENT" \
  --data-urlencode "details=false"

# 把返回结果中的 data.formatted_context 放入你的模型 prompt。
# 模型返回后，再把本轮 user / assistant 消息写回 GUMem。
curl -sS -X POST "$GUMEM_BASE_URL/api/sessions/$GUMEM_SESSION_ID/messages" \
  -H "Authorization: Api-Key $GUMEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Which city should I use for Europe team scheduling?"
      },
      {
        "role": "assistant",
        "content": "Use Berlin for Europe team scheduling."
      }
    ]
  }'

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

检查结果

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

已使用 Node SDK、Python SDK 或 cURL 建立服务端访问方式。
已为一个业务用户创建 Session，并保存 session.id 或 data.session_id。
已写入会影响后续任务的对话消息。
下一轮查询可以返回相关 Memory，并将其放入 Agent prompt。

下一步

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

Quick Start ​

前置条件 ​

安装 ​

1. 初始化访问方式 ​

2. 创建 Session ​

3. 写入对话消息 ​

4. 查询 Memory ​

5. 放入 Agent 上下文 ​

检查结果 ​

下一步 ​

Quick Start

前置条件

安装

1. 初始化访问方式

2. 创建 Session

3. 写入对话消息

4. 查询 Memory

5. 放入 Agent 上下文

检查结果

下一步