Skip to main content

Managed Memory Entry

View as Markdown

A workspace-scoped entry in a managed memory store.

ManagedMemoryEntry object​

A workspace-scoped entry in a managed 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 managed memory entry by resource name Beta​

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

Retrieves a managed 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 managed memory entries Beta​

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

Lists managed 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

Managed 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 managed memory entry Beta​

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

Creates a managed 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

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

managed_memory_entry_idstringquery

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

Request body​

The managed 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 managed memory entry Beta​

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

Updates selected mutable fields on a managed 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 managed 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 managed memory entry by resource name Beta​

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

Deletes a managed 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 managed memory entries Beta​

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

Searches managed 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

Managed 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.