User Case

This scenario is a good fit for GUMem because the user should not have to repeat "use Berlin for Europe and Toronto for the Americas" in every scheduling task. Those preferences affect later work and should be recalled.

Scenario

The user is using a team scheduling assistant. Your backend has already stored the current session.id, and previous turns have written the user's scheduling preferences.

Current user input:

Can you schedule the Europe team check-in for next week?

The Agent should query GUMem first. If Memory contains a preference such as "Europe team uses Berlin", the Agent can use it naturally in the reply and later tool calls.

Recommended order

1. The user input reaches your backend.
2. Query GUMem Memory with the current session.id.
3. Put the recalled result into model context.
4. Call the model to generate a reply.
5. Write the user message and assistant reply back to GUMem asynchronously.

Recall first, generate next, write back last. This prevents the current reply from contaminating the current recall result.

Example

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

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

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

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

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

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

  const assistantReply = await callYourLLM(systemPrompt, params.userContent);

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

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

Checkpoint

After this flow is connected, you should see:

• When the user asks about Europe team scheduling, the Agent can recall city preferences related to the Europe team.
• GUMem write failures do not block the current user response.
• New user messages and assistant replies enter the later Memory processing pipeline.
• If recall returns no result, the Agent asks for missing information instead of pretending to know the preference.

Failure handling

Case	Recommended handling
Query Memory fails	Log the error and fall back to a normal Agent response without historical Memory.
GUMem write-back fails	Do not block the main response; log the error and retry in the background.
Recall returns empty results	Ask the user for the missing information.
Recalled Memory conflicts with current input	Treat the user's current explicit statement as authoritative and write the correction back to GUMem.

Next step

• Read Quick Start to complete the smallest GUMem integration.
• Read What to remember to decide which preferences and behavior signals belong in GUMem.
• Read Query Memory to tune recall scope and returned fields.