Quick Start

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

Before you start

Prepare:

• Node.js 18 or later, or Python 3.9 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.

cURL examples

The cURL examples show the current HTTP integration shape. Before using them in production, confirm that your deployment has stabilized the corresponding endpoints, authentication scheme, and base URL.

Install

Node SDK

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

Python SDK

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

cURL

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

1. Initialize access

Node SDK

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

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

Python SDK

import os

from gumem import GUMemClient

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

cURL

test -n "$GUMEM_API_KEY"
test -n "$GUMEM_BASE_URL"

2. Create a Session

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

Node SDK

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

console.log(session.id);

Python SDK

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

print(session.id)

cURL

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",
    "title": "Team scheduling session"
  }'

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.

Node SDK

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 SDK

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

cURL

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."
      }
    ]
  }'

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.

Node SDK

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

console.log(memory.data);

Python SDK

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

print(memory.get("data"))

cURL

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 returns context that can be used in the next Agent response. Common fields include:

Field	Type	Description
project_id	str	Project ID for the current Memory query.
user_id	str	Business user ID bound to the current Session.
session_id	str	Session ID for the current query.
history	list[Message]	Message list returned from the current Session. Empty list when no messages are returned.
facts	str	Facts text related to the query. Empty string when no Facts are matched.
summary	str	Summary from the current Session or user context that can be used for this recall. Empty string when no Summary is available.
formatted_context	str	Formatted context text, usually ready for the Agent prompt. Empty string when no context can be formatted.

5. Put it into Agent Context

In a real Agent, recall Memory first, call the model, then write the turn back to GUMem.

Node SDK

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 SDK

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

cURL

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"

# Put data.formatted_context from the response into your model prompt.
# After the model returns, write this user / assistant turn back to 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."
      }
    ]
  }'

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:

• Initialized server-side access with the Node SDK, Python SDK, or cURL.
• Created a Session for one business user and stored session.id or data.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 or Python SDK for full SDK methods, error handling, and troubleshooting.