GetMemoryTask

Updated at:
Copy as MD

Queries the status, input, execute results, and error message of a memory extraction node. A successful node may not generate new memories. If a fault occurs, check the error field for the cause.

Operation description

Uses the taskId returned by AddMemories during asynchronous writes to query the progress and results of a memory extraction task.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

agentcore:GetMemoryTask

get

*MemoryStore

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/memorystore/{#memoryStoreName}

None None

Request syntax

GET /workspaces/{workspaceId}/memorystores/{memoryStoreName}/memory-tasks/{taskId} HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example

workspaceId

string

Yes

The AgentCore workspace ID.

ws-2f5f9c5a8d0e4c3b

memoryStoreName

string

Yes

The MemoryStore name.

customer-memory

taskId

string

Yes

The task ID returned by AddMemories.

task-2f5f9c5a8d0e4c3b

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element

Type

Description

Example

object

requestId

string

The request ID.

01A00000-0000-0000-0000-000000000001

message

string

The response message.

success

httpStatusCode

integer

The HTTP status code.

200

code

string

The business status code.

SUCCESS

success

boolean

Indicates whether the request is successful.

data

object

The task details.

taskId

string

The task ID.

task-2f5f9c5a8d0e4c3b

triggerType

string

The task trigger type. Valid values:

  • AUTO: Automatically triggered by session events.

  • MANUAL: Triggered when writing to memory.

Valid values:

  • AUTO
  • MANUAL

AUTO

status

string

The extraction task status.

Valid values:

  • FAILED :

    Failed.

  • RUNNING :

    Running.

  • SUCCEEDED :

    Succeeded.

  • PENDING :

    Pending.

  • UNKNOWN :

    Unknown.

SUCCEEDED

strategyConfig

object

The extraction strategy used for this task.

type

string

The memory extraction strategy type. Valid values:

  • auto: automatic extraction that currently generates semantic memories

  • semantic: semantic memory

  • skill: skill

  • user_profile: user preference

  • session_summary: session summary

Valid values:

  • auto
  • semantic
  • skill
  • user_profile
  • session_summary

auto

instruction

string

The custom extraction instructions used to restrict the content to be retained. If a conflict occurs with the memory base extraction instructions, this rule prevails. The auto type does not support non-empty instructions.

Retain only long-term preferences explicitly expressed by the user

inputMessageCount

integer

The number of messages, events, or text entries input for this task.

8

inputTokenCount

integer

The number of tokens in the input content for this task.

120

memories

array<object>

Returned only when the task succeeds. An empty array is allowed.

object

memoryId

string

The long-term memory ID.

mem-2f5f9c5a8d0e4c3b

changes

array<object>

The list of memory changes generated by the task, excluding memories that are not modified.

object

operation

string

The memory change type. Valid values:

  • ADD: Adds a memory.

  • UPDATE: Updates a memory.

  • DELETE: Deletes a memory.

Valid values:

  • ADD
  • UPDATE
  • DELETE

ADD

memoryId

string

The unique identifier of the memory.

mem-2f5f9c5a8d0e4c3b

error

object

The task error returned only when the status is FAILED or UNKNOWN. This does not indicate that the current query failed.

code

string

The task error code.

UnknownError

message

string

The task error message.

Memory extraction failed.

createdAt

string

The creation time in RFC 3339 format with time zone.

2026-09-23T10:00:00Z

startedAt

string

The task start time in RFC 3339 format with time zone. This field is not returned if the task has not started.

2026-09-23T10:00:00Z

finishedAt

string

The task completion time in RFC 3339 format with time zone. This field is not returned if the task has not finished.

2026-09-23T10:00:01Z

input

object

The input content processed by this task.

type

string

The input content format. Valid values:

  • text: text

  • messages: message list

  • events: event list

events

text

string

The raw text to be extracted for this task.

The user likes hiking

messages

array<object>

The list of messages to be processed.

object

role

string

The message role. For example, user indicates the user, and assistant indicates the assistant.

user

content

string

The body content of the memory.

The user likes hiking

referenceTime

string

The reference time of this message in RFC 3339 format with time zone. If omitted, the request-level referenceTime is used. If both are omitted, the current request time is used.

2023-05-08T13:56:00+08:00

events

array<object>

The list of session events to be processed.

array<object>

eventId

string

The unique identifier of the event.

evt-2f5f9c5a8d0e4c3b

timestamp

integer

The actual occurrence time of the event in Unix milliseconds, provided by the caller.

1758614400000

type

string

The event type. Valid values:

  • message: message

  • compaction: summary

  • fork: session branch

Valid values:

  • message
  • compaction
  • fork

message

data

object

The event content. Select fields based on the event type. For message events, use role, content, and an optional callId. For compaction events, use eventIds and summary. For fork events, use parentScope and parentEventId. Do not mix fields from different event types.

role

string

The message role. Valid values: system, developer, user, assistant, and tool. The tool role also requires a callId.

user

content

array<object>

The list of message content blocks. This field is required and can be an empty array.

object

type

string

The type of the message content block. Valid values: text, reasoning, tool_call, json, and opaque.

text

text

string

The text of the text or reasoning content block. This field is required and can be an empty string.

The user likes hiking

callId

string

The tool invocation ID. This field is required for tool_call content blocks and is used to associate subsequent tool messages.

call-001

name

string

The tool name. This field is required for the tool_call type.

get_weather

arguments

any

The tool invocation parameters. This field is required for tool_call content blocks and supports JSON values.

{"city":"Hangzhou"}

value

any

The data carried by the content block. This field is required for json and opaque content blocks and supports JSON values.

{"preference":"hiking"}

format

string

The data format identifier for the opaque content block. A non-empty string is required.

application/json

callId

string

The tool invocation ID. It is used to associate a tool invocation with its response message.

call-001

eventIds

array

The list of visible event IDs referenced by the summary. This field cannot be empty.

string

The event ID.

evt-2f5f9c5a8d0e4c3b

summary

string

The summary content for the referenced events. This field cannot be empty.

The user plans a weekend hiking trip

parentScope

object

The full association scope of the parent session. Each dimension must be consistent with those specified when the parent session was created.

userId

string

The business user ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes.

user-001

teamId

string

The business team ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes.

team-001

agentId

string

The agent ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes.

agent-001

sessionId

string

The session ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes.

session-001

parentEventId

string

The event ID that serves as the cutoff position for historical references in the parent session.

evt-2f5f9c5a8d0e4c3b

referenceTime

string

The reference time for interpreting relative times in the content, in RFC 3339 format with a time zone. If not provided, the time of the current request is used.

2023-05-08T13:56:00+08:00

metadata

object

The string key-value tags set by the caller. A maximum of 16 tags are supported. A key can contain up to 64 Unicode characters, and a value can contain up to 1024 Unicode characters. Empty strings are allowed. Nested objects or arrays are not supported.

{"topic":"hiking"}

string

The metadata tag value set by the caller.

hiking

Examples

Success response

JSON format

{
  "requestId": "01A00000-0000-0000-0000-000000000001",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": false,
  "data": {
    "taskId": "task-2f5f9c5a8d0e4c3b",
    "triggerType": "AUTO",
    "status": "SUCCEEDED",
    "strategyConfig": {
      "type": "auto",
      "instruction": "仅保留用户明确表达的长期偏好。"
    },
    "inputMessageCount": 8,
    "inputTokenCount": 120,
    "memories": [
      {
        "memoryId": "mem-2f5f9c5a8d0e4c3b"
      }
    ],
    "changes": [
      {
        "operation": "ADD",
        "memoryId": "mem-2f5f9c5a8d0e4c3b"
      }
    ],
    "error": {
      "code": "UnknownError",
      "message": "Memory extraction failed."
    },
    "createdAt": "2026-09-23T10:00:00Z",
    "startedAt": "2026-09-23T10:00:00Z",
    "finishedAt": "2026-09-23T10:00:01Z",
    "input": {
      "type": "events",
      "text": "用户喜欢徒步旅行。",
      "messages": [
        {
          "role": "user",
          "content": "用户喜欢徒步旅行。",
          "referenceTime": "2023-05-08T13:56:00+08:00"
        }
      ],
      "events": [
        {
          "eventId": "evt-2f5f9c5a8d0e4c3b",
          "timestamp": 1758614400000,
          "type": "message",
          "data": {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "用户喜欢徒步旅行。",
                "callId": "call-001",
                "name": "get_weather",
                "arguments": "{\"city\":\"杭州\"}",
                "value": "{\"preference\":\"徒步旅行\"}",
                "format": "application/json"
              }
            ],
            "callId": "call-001",
            "eventIds": [
              "evt-2f5f9c5a8d0e4c3b"
            ],
            "summary": "用户计划周末徒步旅行。",
            "parentScope": {
              "userId": "user-001",
              "teamId": "team-001",
              "agentId": "agent-001",
              "sessionId": "session-001"
            },
            "parentEventId": "evt-2f5f9c5a8d0e4c3b"
          }
        }
      ],
      "referenceTime": "2023-05-08T13:56:00+08:00",
      "metadata": {
        "key": "hiking"
      }
    }
  }
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified request parameter is invalid.
400 UnsupportedOperation The memory store does not support this operation.
500 UnknownError The request processing has failed due to some unknown error.
403 Forbidden You are not authorized to perform this operation.
404 Resource.NotFound The specified memory store does not exist.
429 Throttling Request was denied due to request throttling.
409 Operation.Conflict The memory store is not in a state that permits this operation.
409 Resource.OperationConflict The memory task cannot be queried in its current state.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.