Add Memory

Do not treat Summary as data you usually write by hand. Prefer writing Message input with provenance, time, and business context, then let GUMem process it.

Before You Start

• You have a Project and a server-side API Key.
• You have created a Session bound to the correct user identity.
• You have decided what can be stored long term and what should stay in the current request or business system.
• If the input comes from image or video, an upstream system has converted it into text, transcript, summary, or metadata.

Write Session Message

One request can write one or more Message entries. Each Message needs at least role and content.

JavaScript

await session.addMessages([
  {
    role: "user",
    content: "Please remember that I will travel to Shanghai next Wednesday.",
    metadata: {
      source: "chat"
    },
    timestamp: "2026-04-24T10:30:00Z"
  }
]);

Python

# Draft interface
session.add_messages([
    {
        "role": "user",
        "content": "Please remember that I will travel to Shanghai next Wednesday.",
        "metadata": {
            "source": "chat"
        },
        "timestamp": "2026-04-24T10:30:00Z",
    }
])

cURL

curl -X POST "http://localhost:8000/api/sessions/session_xxx/messages" \
  -H "Authorization: Api-Key your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please remember that I will travel to Shanghai next Wednesday.",
        "metadata": {
          "source": "chat"
        },
        "timestamp": "2026-04-24T10:30:00Z"
      }
    ]
  }'

Fields

Field	Required	Description
messages[].role	Yes	Message role, such as user, assistant, or system.
messages[].content	Yes	Raw text content. GUMem extracts Facts from this field.
messages[].metadata	No	Business metadata, such as source, page, attachment reference, or business object ID.
messages[].timestamp	No	Message event time. ISO 8601 is recommended.
messages[].id	No	Caller-provided Message ID. The server can generate one if omitted.
sync	No	Whether to wait synchronously for later Memory processing to finish. The default returns asynchronously, which is better for online conversation writes; set it to true when you need to verify processing results immediately.

When a Session is already bound to a user, do not override memory ownership inside the write request. Ownership should be controlled by Session, Project, and server-side identity.

What Happens After Write

After Message input is accepted, GUMem processes it by configuration:

1. Save raw Message input.
2. Extract Facts with source Message, time range, entities, and labels.
3. If long-term writes are enabled, generate Summary from Facts.
4. Assign Summary to Topic and update Topic summary text.
5. Write Facts, Summary, and Topic to retrieval indexes.

If long-term write is disabled, GUMem stops at Facts and does not generate Summary or Topic.

What To Write

• Explicit long-lived preferences, constraints, identity details, or goals.
• Information that can affect future recommendations, tool calls, risk decisions, or response style.
• Auditable behavior results, such as searches, filters, saves, skips, or tool outputs.
• Text descriptions, transcripts, summaries, or metadata derived from image or video input.

What Not To Write

• Temporary state useful only for the current request.
• Unsupported model inference.
• Strongly consistent business state, such as order status, permission, billing, or inventory.
• Sensitive information without a governance policy.

Checkpoint

After writing Message input, use Query Memory to verify whether related information appears in context. Newly written Message input may first appear in recent context; long-term Summary and Topic require processing to finish.

Next Step

Read Query Memory to recall Memory that has been written.