Skip to main content

Memory Entry

View as Markdown

A workspace-scoped entry in a memory store.

ManagedMemoryEntry object​

A workspace-scoped entry in a memory store.

namestringBetaOutput onlyIDImmutable

Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}.

actor_idstringBetaImmutable

Customer-provided identifier for the actor whose memory this entry represents.

session_idstringBetaImmutable

Optional identifier for the session associated with this memory entry. When omitted, the entry applies across the actor's sessions.

pathstringBetaImmutable

Absolute, case-sensitive path identifying the entry within its actor and optional session. Paths must begin with / and must not contain empty, . or .. segments.

contentstringBeta

Optional free-form memory content.

descriptionstringBeta

Human-readable description of the memory entry.

source_typestringBetaImmutable

Which writer created this entry. Caller sets this on Create; immutable after creation.

Values:

  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_AGENT
  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_DREAMER
create_timestringBetaOutput only

Time when the entry was created.

update_timestringBetaOutput only

Time when the entry was last updated.

Get a memory entry by resource name Beta​

GET /api/2.0/agents/{name=memory-stores/*/entries/*}

Retrieves a memory entry by resource name. view controls whether the response includes memory content. Returns NOT_FOUND when the entry does not exist in the caller's workspace.

API scopes: agent-kit

Parameters​

namestringRequiredpath

Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}.

Response​

Returns the ManagedMemoryEntry object.

List memory entries Beta​

GET /api/2.0/agents/{parent=memory-stores/*}/entries

Lists memory entries for one actor. An exact path filters entries across sessions, ignoring session metadata. Otherwise, session_id and path_prefix restrict the actor partition. view controls whether each returned entry includes memory content.

API scopes: agent-kit

Parameters​

parentstringRequiredpath

Memory store whose entries are listed, in the form memory-stores/{managed_memory_store_id}.

page_sizeint32query

Maximum number of entries to return. The service may return fewer entries than requested. Defaults to 10; must be between 1 and 100.

page_tokenstringquery

Opaque pagination token from a previous ListManagedMemoryEntries response.

actor_idstringRequiredquery

Customer-provided identifier for the actor whose entries are listed.

path_prefixstringquery

Optional path prefix used to restrict entries within the actor partition.

session_idstringquery

Optional session identifier. When set, only entries with this exact session_id are returned. Omitted-session (cross-session) entries are not included. Ignored when path is set.

Response​

Returns a list of ManagedMemoryEntry objects.

Create a memory entry Beta​

POST /api/2.0/agents/{parent=memory-stores/*}/entries

Creates a memory entry using exclusive-create semantics. Callers may choose the entry ID; the service generates one when it is omitted. Returns ALREADY_EXISTS when an entry with the same actor, session, and path already exists. Omitted session_id is its own uniqueness key: two omitted-session entries with the same actor and path conflict, but an omitted-session entry does not conflict with a session-scoped entry at the same actor and path.

API scopes: agent-kit

Parameters​

parentstringRequiredpath

Memory store that will contain the entry, in the form memory-stores/{managed_memory_store_id}.

managed_memory_entry_idstringquery

Optional caller-selected memory entry ID. The service generates an ID when omitted.

Request body​

The memory entry to create.

actor_idstringRequiredImmutable

Customer-provided identifier for the actor whose memory this entry represents.

session_idstringImmutable

Optional identifier for the session associated with this memory entry. When omitted, the entry applies across the actor's sessions.

pathstringRequiredImmutable

Absolute, case-sensitive path identifying the entry within its actor and optional session. Paths must begin with / and must not contain empty, . or .. segments.

contentstring

Optional free-form memory content.

descriptionstring

Human-readable description of the memory entry.

source_typestringImmutable

Which writer created this entry. Caller sets this on Create; immutable after creation.

Values:

  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_AGENT
  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_DREAMER

Response​

Returns the ManagedMemoryEntry object.

Update a memory entry Beta​

PATCH /api/2.0/agents/{name=memory-stores/*/entries/*}

Updates selected mutable fields on a memory entry. Identity fields are immutable.

API scopes: agent-kit

Parameters​

namestringRequiredIDImmutablepath

Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}.

update_maskstringRequiredquery

Fields to update. Only content and description may be updated.

Request body​

The memory entry to update.

actor_idstringRequiredImmutable

Customer-provided identifier for the actor whose memory this entry represents.

session_idstringImmutable

Optional identifier for the session associated with this memory entry. When omitted, the entry applies across the actor's sessions.

pathstringRequiredImmutable

Absolute, case-sensitive path identifying the entry within its actor and optional session. Paths must begin with / and must not contain empty, . or .. segments.

contentstring

Optional free-form memory content.

descriptionstring

Human-readable description of the memory entry.

source_typestringImmutable

Which writer created this entry. Caller sets this on Create; immutable after creation.

Values:

  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_AGENT
  • MANAGED_MEMORY_ENTRY_SOURCE_TYPE_DREAMER

Response​

Returns the ManagedMemoryEntry object.

Delete a memory entry by resource name Beta​

DELETE /api/2.0/agents/{name=memory-stores/*/entries/*}

Deletes a memory entry by resource name. Returns NOT_FOUND when the entry does not exist in the caller's workspace.

API scopes: agent-kit

Parameters​

namestringRequiredpath

Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}.

Search memory entries Beta​

POST /api/2.0/agents/{parent=memory-stores/*}/entries:search

Searches memory entries by text query for one actor. Returns matching entries and scores ranked by relevance; view controls whether each returned entry includes content.

API scopes: agent-kit

Parameters​

parentstringRequiredpath

Memory store whose entries are searched, in the form memory-stores/{managed_memory_store_id}.

Request body​

actor_idstringRequired

Customer-provided identifier for the actor whose entries are searched.

querystringRequired

Free-form search query.

limitint32Deprecated

Deprecated alias for page_size. When both fields are set, their values must match.

page_sizeint32

Maximum number of relevance-ranked entries to return. Defaults to 10 and must be between 1 and 100.

page_tokenstring

Reserved for pagination compatibility. The server currently ignores this field because Search returns a ranked top-N result set.

session_idstring

Optional session identifier. When set, only entries with this exact session_id are searched. Omitted-session (cross-session) entries are not included.

path_prefixstring

Optional absolute, case-sensitive path prefix used to restrict searched entries within the actor partition. The prefix must begin with / and must not contain empty, . or .. segments.

Response​

Returns a list of ManagedMemoryEntry objects.