GUMem Node SDK

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

Before you start

You need:

• Node.js 18 or later.
• A valid GUMem API Key.
• A server-side runtime, such as a Node.js API route, worker backend, Express service, or queue job.

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

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

Install

npm install @steamory-agent-kit/gumem

The SDK ships ESM, CommonJS, and TypeScript declarations. Node.js 18+ can use the built-in fetch implementation.

Quickstart

The following example covers the shortest integration path: initialize the client, create a Session, write a few conversation messages, and retrieve relevant Memory.

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

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

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

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

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

console.log(memory.data);

Checkpoint

After this code runs, you should have a Session object and a Memory result in memory.data. Use session.id as the stable identifier for adding future messages and retrieving future Memory.

Use GUMem in an assistant turn

In a real agent or assistant system, use this flow:

1. Receive the user input in your Node.js backend.
2. Retrieve relevant Memory for the current session.id.
3. Add that Memory to your model context.
4. After the model replies, write the user message and assistant reply back to GUMem.

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

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

type ModelInput = {
  userContent: string;
  recalledMemory: unknown;
};

async function generateAssistantReply(input: ModelInput): Promise<string> {
  // Replace this function with your OpenAI, Anthropic, Gemini, or local model call.
  return `I will use the recalled memory for: ${input.userContent}`;
}

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

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

  const assistantReply = await generateAssistantReply({
    userContent: params.userContent,
    recalledMemory: memory.data,
  });

  await session.addMessages([
    { role: "user", content: params.userContent },
    { role: "assistant", content: assistantReply },
  ]);

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

Checkpoint

In production, store session.id when a new conversation is created. Later requests can restore the local Session handle with gumem.sessions.fromId(sessionId); this does not make a network request.

Client configuration

By default, only apiKey is required. You do not need to configure host when using the default GUMem service.

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

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

Pass additional options when you need a custom deployment or timeout behavior:

const gumem = new GUMemClient({
  apiKey: process.env.GUMEM_API_KEY!,
  host: "gumem.asix.inc",
  timeoutMs: 30_000,
});

Option	Type	Default	Description
apiKey	string	Required	GUMem API Key. The SDK sends Authorization: Api-Key <apiKey>. Values that already start with Api-Key are not prefixed again.
host	string	gumem.asix.inc	GUMem service host. Plain host values are normalized to HTTPS, explicit http:// and https:// URLs are preserved, and a trailing / is removed.
timeoutMs	number	30000	Default request timeout in milliseconds. Set to 0 to disable the SDK timeout.
fetch	FetchLike	globalThis.fetch	Fetch-compatible implementation for tests, proxies, custom runtimes, or observability wrappers.

Health check

gumem.health(options?) checks the GUMem service health endpoint. Use it in startup checks, deployment verification, or monitoring probes.

const health = await gumem.health();

console.log(health);

Parameters:

Name	Type	Required	Description
options	RequestOptions	No	Per-request options. Use it to override timeout, abort signal, and headers.

Sessions

A Session is the GUMem object that holds one user conversation and its Memory retrieval context. Prefer the methods on the Session handle. Use lower-level resource methods only when passing raw Session IDs is more convenient for your application.

Create a Session

gumem.sessions.create(input, options?) creates a Session and returns a Session object. user_id is required by the current GUMem API.

const session = await gumem.sessions.create({
  user_id: "user_123",
  title: "Support chat",
  metadata: {
    source: "web-chat",
    locale: "en-US",
  },
});

console.log(session.id);
console.log(session.rawResponse);

Parameters:

Name	Type	Required	Description
input	SessionCreateRequest	Yes	Request body for creating a Session.
input.user_id	string	Yes	User ID from your application. GUMem uses it to associate the Session with user Memory.
input.title	string | null	No	Session title, useful for storing a conversation topic or source label.
input.metadata	Record<string, unknown> | null	No	Custom metadata such as channel, locale, product area, or business trace information.
options	RequestOptions	No	Per-request options.

session.rawResponse keeps the original response envelope returned by GUMem when the Session was created. If GUMem returns a successful response without data.session_id, the SDK throws a regular Error with the message GUMem API did not return data.session_id.

Restore a Session handle

gumem.sessions.fromId(sessionId) creates a local Session handle from an existing Session ID without making a network request.

const session = gumem.sessions.fromId("session_123");

await session.addMessage({
  role: "user",
  content: "Continue with the city preference from earlier.",
});

Parameters:

Name	Type	Required	Description
sessionId	string	Yes	Existing Session ID that was created by GUMem and stored in your application.

Add messages

session.addMessage(message, options?) writes one message.

await session.addMessage({
  role: "user",
  content: "For Europe planning, keep Berlin as the default city.",
  metadata: {
    channel: "chat",
  },
});

Parameters:

Name	Type	Required	Description
message	Message	Yes	One message to write to the current Session.
message.role	string	Yes	Message role, such as user, assistant, system, or a custom role from your application.
message.content	string	Yes	Message text. GUMem uses it to build and retrieve Memory.
message.id	string | null	No	Message ID from your application. Use it to connect GUMem writes with your message table, logs, or traces.
message.metadata	Record<string, unknown>	No	Message-level metadata such as channel, model name, locale, or business tags.
message.timestamp	string | Date | null	No	Time when the message happened. Date values are serialized to ISO strings.
message.created_at	string | Date | null	No	Time when the message was created. Use it when this differs from the event timestamp.
message.status	pending | chunked | processed | failed	No	Message processing status.
options	RequestOptions	No	Per-request options.

session.addMessages(input, options?) writes multiple messages. input can be either a message array or an object with a messages field.

await session.addMessages([
  {
    role: "user",
    content: "Use Toronto for Americas planning.",
  },
  {
    role: "assistant",
    content: "Understood. I will use Toronto for Americas planning.",
  },
]);

await session.addMessages({
  messages: [
    {
      role: "user",
      content: "Keep those defaults for future scheduling tasks.",
      timestamp: new Date(),
    },
  ],
});

Parameters:

Name	Type	Required	Description
input	Message[] | AddMessagesRequest	Yes	Message collection to write. Array input is wrapped by the SDK as { messages }.
input.user_id	string | null	No	Optional user ID. Usually the Session is already bound to user_id when created, so this does not need to be repeated.
input.messages	Message[]	Yes	Messages to write to the current Session. When using array shorthand, the SDK creates this field.
options	RequestOptions	No	Per-request options.

Message Date values are serialized to ISO strings. undefined fields are removed from request bodies.

Lower-level Session methods

If you only want to pass the Session ID, call the resource methods directly.

await gumem.sessions.addMessages("session_123", [
  {
    role: "user",
    content: "Draft the next Europe team agenda.",
  },
]);

const memory = await gumem.sessions.getMemory("session_123", {
  query: "which city should be used for Europe planning",
});

gumem.sessions.addMessages(sessionId, input, options?) parameters:

Name	Type	Required	Description
sessionId	string	Yes	Session ID to write messages to. The SDK safely encodes this value in the URL.
input	Message[] | AddMessagesRequest	Yes	Message collection to write.
options	RequestOptions	No	Per-request options.

gumem.sessions.getMemory(sessionId, params?, options?) parameters:

Name	Type	Required	Description
sessionId	string	Yes	Session ID to retrieve Memory from. The SDK safely encodes this value in the URL.
params	GetSessionMemoryParams	No	Memory retrieval parameters. Omit it to request default Memory for the current Session.
options	RequestOptions	No	Per-request options.

Memory recall and recall_config

session.getMemory(params?, options?) retrieves Memory for the current Session. Use query to focus retrieval and details to request richer response data.

const memory = await session.getMemory({
  query: "which city should be used for Europe or Americas planning",
  details: true,
});

Parameters:

Name	Type	Required	Description
params	GetSessionMemoryParams	No	Memory retrieval parameters. Omit it to use GUMem's default retrieval strategy for the current Session.
params.query	string	No	Query text for retrieval. Prefer the current user intent instead of the full prompt.
params.details	boolean	No	Requests richer Memory response data. Exact fields depend on the GUMem API response.
params.recall_config	RecallConfig | null	No	Recall configuration. When present, the SDK uses the POST context request; null sends an explicit empty configuration.
options	RequestOptions	No	Per-request options.

By default, the SDK uses the GET context request. When recall_config is present, the SDK uses the POST context request and sends the recall settings in the JSON body.

const memory = await session.getMemory({
  query: "which city should be used for the user's scheduling request",
  details: true,
  recall_config: {
    MessageRecentLimit: 20,
    MetadataFilters: {
      ping: "pong",
    },
  },
});

Common recall_config fields:

Field names follow the current SDK/API. Descriptions use GUMem's public terms.

Field	Type	Purpose
MessageRecentLimit	number	Controls how many recent Message items can be recalled.
MetadataFilters	object	A simple metadata key-value dictionary for exact recall filtering. Keys must be non-empty strings, and values must be strings, numbers, or booleans.

User Actions

User Actions record important product behavior, such as page views, button clicks, tool calls, or task state changes. They are useful for writing behavior Message input so an Agent can understand behavioral context.

await gumem.userActions.create({
  user_id: "user_123",
  timestamp: new Date(),
  content: "User opened the Europe team scheduling page",
  session_id: "session_123",
  event_type: "page_view",
  page: "team_scheduling",
  anchors: {
    region: "Europe",
    city: "Berlin",
  },
  metadata: {
    source: "assistant-api",
  },
});

gumem.userActions.create(input, options?) parameters:

Name	Type	Required	Description
input	ActionLogInput	Yes	Request body for a user Action event.
input.user_id	string	Yes	User ID from your application that triggered this Action.
input.timestamp	string | Date	Yes	Time when the Action happened. Date values are serialized to ISO strings.
input.content	string	Yes	Natural-language description of the Action. Prefer a clear statement of what the user did.
input.session_id	string | null	No	Related Session ID. Use it to connect behavior with conversation context.
input.device_id	string | null	No	Device ID, useful for multi-device behavior analysis.
input.app	string | null	No	Application or product area name.
input.platform	string | null	No	Platform such as web, ios, android, or server.
input.event_type	string | null	No	Event type such as page_view, click, or tool_call.
input.page	string | null	No	Page, route, or feature entry point.
input.anchors	Record<string, string> | null	No	Searchable anchors such as region, city, or document_id.
input.metadata	Record<string, unknown> | null	No	Custom metadata.
input.entities	string[] | null	No	Entity names or IDs related to the Action.
options	RequestOptions	No	Per-request options.

timestamp can be an ISO string or a Date. If you pass a Date, the SDK serializes it automatically.

Runtime behavior

Request options

Every SDK method accepts request options as its final argument. Use them to override timeout, abort signal, or headers for one request.

const controller = new AbortController();

const memory = await session.getMemory(
  {
    query: "which scheduling city should be used",
  },
  {
    timeoutMs: 5_000,
    signal: controller.signal,
    headers: {
      "X-Request-Id": "request_123",
    },
  },
);

Option	Type	Description
timeoutMs	number	Overrides the timeout for one request.
signal	AbortSignal	External abort signal.
headers	HeadersInit	Additional request headers.

Response envelope

Except for gumem.sessions.create(), which returns a Session object, resource methods return the GUMem response envelope.

type GUMemEnvelope<T = unknown> = {
  data?: T;
  success?: boolean;
  message?: string;
  error?: unknown;
  [key: string]: unknown;
};

For example:

• session.getMemory() returns Promise<GUMemEnvelope<SessionMemory>>.
• session.addMessages() returns the GUMem response envelope.
• gumem.userActions.create() returns Promise<GUMemEnvelope<CreateActionResponse>>.

Serialization

Before sending a JSON body, the SDK applies lightweight serialization:

• Date values become ISO strings.
• undefined fields are removed from objects and arrays.
• null is preserved, which is useful when you need to send an explicit empty value.

Error handling

The SDK exposes three primary error types:

import {
  GUMemApiError,
  GUMemConnectionError,
  GUMemTimeoutError,
} from "@steamory-agent-kit/gumem";

try {
  await session.getMemory({
    query: "which scheduling city should be used",
  });
} catch (error) {
  if (error instanceof GUMemApiError) {
    console.error(error.status, error.detail, error.body);
  } else if (error instanceof GUMemTimeoutError) {
    console.error(`Request timed out after ${error.timeoutMs}ms`);
  } else if (error instanceof GUMemConnectionError) {
    console.error("Network or fetch failure", error.cause);
  } else {
    throw error;
  }
}

Error	When it is thrown
GUMemApiError	GUMem returns a non-2xx response. Includes status, statusText, headers, body, and detail.
GUMemConnectionError	The underlying fetch request fails before a response is received.
GUMemTimeoutError	A request is aborted by the SDK timeout or an external AbortSignal. Extends GUMemConnectionError.

TypeScript reference

Common types are exported from the package root:

import type {
  ActionLogInput,
  AddMessagesRequest,
  CreateActionResponse,
  GUMemClientOptions,
  GUMemEnvelope,
  Message,
  RecallConfig,
  RequestOptions,
  SessionMemory,
  SessionCreateRequest,
} from "@steamory-agent-kit/gumem";

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

Core type reference:

type QueryRouter =
  | "single_hop_direct"
  | "single_hop_parallel"
  | "multi_hop_chain";

interface SessionCreateRequest {
  user_id: string;
  title?: string | null;
  metadata?: Record<string, unknown> | null;
}

interface Message {
  role: string;
  content: string;
  id?: string | null;
  metadata?: Record<string, unknown>;
  timestamp?: string | Date | null;
  created_at?: string | Date | null;
  status?: "pending" | "chunked" | "processed" | "failed";
}

Troubleshooting

apiKey must not be empty

apiKey is an empty string or contains only whitespace. Confirm that GUMEM_API_KEY is available in the server-side runtime and that runtime-only code is not being executed unexpectedly during a build step.

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

401 or 403

Check that the API Key is correct, has permission to access the target GUMem service, and that requests are going to the expected host. The SDK adds the Api-Key prefix automatically, so you do not need to concatenate it yourself.

Request timeout

The default timeout is 30 seconds. You can adjust it at the client level or per request.

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

Empty Memory result

First confirm that messages were written to the same Session. Then use a query that describes the user's intent. Add recall_config only when you need more control over retrieval behavior.

Next step

Continue with GUMem Overview to understand GUMem's role as the Memory infrastructure layer in EAK, or read Integration Patterns to choose a production integration pattern.