Quick Start

This page shows the smallest useful GUMem integration with the Node SDK: create a Session, write conversation messages, query Memory, and put the recalled context into the next Agent turn.

If you use Python, read Python SDK. If you need direct HTTP calls, first confirm that the API version and endpoints are stable in your deployment.

Before you start

Prepare:

• Node.js 18 or later.
• A server-side GUMEM_API_KEY created in the GUMem Console.
• A stable business user_id for the user.
• A trusted server-side runtime, such as an API route, worker, Express service, or Agent backend.

Use the GUMem API Key only from server-side code. Do not expose it in browsers, mobile apps, client-side scripts, or public repositories.

Install

npm install @steamory-agent-kit/gumem

For local testing, set the API key as an environment variable:

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

1. Create a client

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

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

2. Create a Session

Create a Session for one user conversation and store the returned session.id. Later message writes and Memory queries use this Session.

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

console.log(session.id);

user_id should come from your business system. It determines which user owns long-term Memory across Sessions.

3. Write conversation messages

Write information that may be useful in later tasks. This example stores a user's team scheduling city preferences.

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

Do not write every temporary intermediate state to GUMem. Good Memory candidates include long-lived preferences, explicit plans, stable constraints, and facts that affect future tasks.

4. Query Memory

Before the next Agent response, query Memory with the current user question.

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

console.log(memory.data);

GUMem returns context that can be used in the next Agent response. Common fields include:

Field	Description
short_term_context	Recent context from the current Session.
mid_term_context	Query-relevant mid-term information.
long_term_user_context	Long-term user Memory reused across Sessions.
long_term_session_context	Long-term context formed inside the current Session.
formatted_context	Formatted context text, usually ready for the Agent prompt.

5. Put it into Agent context

In a real Agent, recall Memory first, call the model, then write the turn back to 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;
}

If the write-back fails, most Agent products should not block the main response the user is waiting for. Log the error and retry in the background.

Checkpoint

After completing this page, you should have:

• Installed the SDK and authenticated with GUMEM_API_KEY.
• Created a Session for one business user and stored session.id.
• Written conversation messages that can affect later tasks.
• Queried relevant Memory and added it to an Agent prompt.

Next step

• Read Overview to understand GUMem's boundaries and smallest integration path.
• Read What to remember to decide what should be written to GUMem.
• Read Node SDK for full SDK methods, error handling, and troubleshooting.