Agent Memories

The agent_memory object

A piece of information an agent has saved for recall in future runs.

idstring

Memory ID.

objectstringenumValues:agent_memory

Resource type identifier.

categorystring

The kind of information this memory holds, used to group related memories.

  • preference: how someone likes things done, such as a customer who always wants express shipping.
  • fact: a durable detail worth remembering about the account or one of its records, such as a customer's typical order size.
  • instruction: standing guidance for agents to follow, such as always confirming freight before issuing an order.
contentstring

The information itself, written as plain text for an agent to read.

metadataobjectnullable

Arbitrary metadata as JSON.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

entityentitynullable

The platform record this memory is about (e.g. a specific customer or product).

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

importancenumber

Relative importance from 0 to 1, used to prioritize which memories the agent recalls.

An agent takes in only a limited number of memories per run, and the highest-importance ones are recalled first.

expires_atstring (date-time)nullable

When this memory stops being used.

Past this time the memory is no longer recalled by agents and is omitted from list results, but it is not deleted and can still be retrieved by ID. A memory with no expiration is used indefinitely.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Used by

POSTCreate Agent MemoryAgent MemoriesPATCHUpdate Agent MemoryAgent MemoriesGETList Agent MemoriesAgent MemoriesGETRetrieve Agent MemoryAgent MemoriesDELETEDelete Agent MemoryAgent Memories