Add durable Memory

Use Memory for durable Agent-owned text that must remain available across Sessions. A Memory is a database record, not a Sandbox file or a Tenant-wide store, and can be partitioned to one end-user through Attribution.

Outcome

You will enable automatic recall, create an end-user Memory, and verify its storage and use in a second Session with the same userId.

Before you begin

You need an Agent ID, a backend SDK client, a stable opaque userId, and two new Sessions. Review Memory, Tenancy and end-user Attribution, and Tools.

Choose a recall mode

Automatic injection (memoryInjectionEnabled) places visible Memory text into every Turn's context. The memory Tool group instead lets the model save, get, search, update, and delete Memories explicitly. They are independent Agent fields and can be enabled separately or together; this guide uses automatic injection and creates the record through the SDK.

Enable Memory

Agent updates are merge updates. Set only memoryInjectionEnabled to preserve unrelated configuration; enabling the memory Tool group would require reading and merging the complete tools array.

Save a Memory

memories.create() nests the record under one Agent. userId: "" creates Agent-general Memory; a non-empty value creates an end-user partition visible only alongside general Memory for Turns with the same userId.

Recall it in another Session

import assert from "node:assert/strict";
const userId = "app-user-42";
await client.agents.update(agentId, { memoryInjectionEnabled: true });
const first = await client.chat({
  agentId,
  userId,
  message: { id: crypto.randomUUID(), role: "user", parts: [
    { type: "text", text: "I prefer concise status updates." },
  ] },
});
for await (const _chunk of first.toUIMessageStream()) { /* settle Session one */ }
const firstSessionId = await first.sessionId;
const saved = await client.memories.create(agentId, {
  userId,
  text: "Prefers concise status updates.",
});
const second = await client.chat({
  agentId,
  userId,
  message: { id: crypto.randomUUID(), role: "user", parts: [
    { type: "text", text: "How should you format my status updates?" },
  ] },
});
let reply = "";
for await (const chunk of second.toUIMessageStream()) {
  if (chunk.type === "text-delta") reply += chunk.delta;
}
assert.notEqual(await second.sessionId, firstSessionId);
assert.equal(saved.memory.userId, userId);
assert.match(reply, /concise/i);

Omitting sessionId on both calls creates distinct Sessions. The second Turn resolves Agent-general Memory plus the app-user-42 partition before the model runs.

Search explicitly

Use the search list option for PostgreSQL full-text search. It is lexical search, not semantic or vector search.

const matches = await client.memories.list(agentId, {
  userId,
  search: "concise status",
  limit: 10,
});

console.log(matches.data.map(({ id, text }) => ({ id, text })));

Verify persistence

Verify both layers: saved.memory or a later memories.list() call proves the record exists, while the second Session's answer demonstrates automatic recall in the same Attribution scope. A stored record alone does not prove it was injected into a Turn.

Production notes

One Agent-wide pool spans all end-user partitions. It holds at most 500 Memories; creating one at capacity evicts the least recently accessed record. Each text value is limited to 10 KiB.
Automatic injection includes newest visible Memories up to a 4,000-word context cap. General Memory is visible to every scope; end-user Memory is visible only to the matching non-empty userId.
Delete stale or sensitive Memory explicitly. Deleting the Agent cascades to its Memories, and there is no time-based retention in the current release.
Treat Memory as application data: choose opaque userId values, avoid unnecessary sensitive content, and apply your own privacy and deletion policy.

See Memory, Tenancy and end-user Attribution, Tools, and Limits and reliability.

SDK and REST reference

The example uses agents.update(), chat(), memories.create(), and memories.list(). Deletion uses memories.delete().

The matching operations are update Agent, create a Session Turn, create Memory, list and search Memories, and delete Memory.

On this page