Memories

client.memories reads and writes the notes an agent keeps across sessions. Agents save memories themselves through the memory tools; use these methods to seed facts, show a user what the agent remembers about them, or remove something. To learn how memory reaches the agent, read Memory.

await client.memories.create({
  agentId,
  userId: "user_42",
  text: "Prefers concise release notes.",
});

const { data } = await client.memories.list({ agentId, userId: "user_42", search: "release" });

Every method takes the owning agentId and accepts an optional abortSignal.

How memories are kept

• Each memory belongs to one agent and, through userId, to one of your end users or to no one (""). Neither can change later.
• Text is up to 10 KiB of UTF-8.
• An agent holds up to 500 memories across all users. When it is full, a new memory replaces the one used least recently.
• update() counts as a use. Reading with list() or get() does not.

Available operations

Methods

create()

Adds a memory to an agent.

Signature: create(input: CreateMemoryBody & { agentId: string } & ResourceRequestOptions): Promise<MemoryResponse>

const { memory } = await client.memories.create({
  agentId,
  userId: "user_42",
  text: "Prefers concise release notes.",
});

Returns MemoryResponse. Errors: validation_failed, not_found.

list()

Lists an agent's memories, or searches their text.

Signature: list(input: { agentId: string } & MemoriesListOptions): Promise<MemoriesListResponse>

const page = await client.memories.list({ agentId, userId: "user_42", search: "release" });

Returns MemoriesListResponse. Errors: validation_failed, invalid_cursor, not_found.

get()

Reads one memory.

Signature: get(input: { agentId: string; memoryId: string } & ResourceRequestOptions): Promise<MemoryResponse>

const { memory } = await client.memories.get({ agentId, memoryId });

Returns MemoryResponse. Errors: validation_failed, not_found.

update()

Replaces a memory's text.

Signature: update(input: UpdateMemoryBody & { agentId: string; memoryId: string } & ResourceRequestOptions): Promise<MemoryResponse>

const { memory } = await client.memories.update({
  agentId,
  memoryId,
  text: "Prefers release notes under five lines.",
});

text is required and replaces the old text. The agent and userId stay the same. Returns MemoryResponse. Errors: validation_failed, not_found.

delete()

Deletes a memory for good.

Signature: delete(input: { agentId: string; memoryId: string } & ResourceRequestOptions): Promise<void>

await client.memories.delete({ agentId, memoryId });

Errors: validation_failed, not_found.

Response types

MemoryResponse

MemoryResponse is { memory: Memory }.

MemoriesListResponse

interface MemoriesListResponse {
  data: Memory[];
  nextCursor: string | null;
}

Next

• Memory
• Agents reference