Add Memory Async

Submits a memory extraction task asynchronously. The API immediately returns an event ID. Use Get Event to query the result. This API supports extraction for multiple projects, skills, and user profiles.

Before calling, ensure you have obtained an API Key. See Authentication.

Method and endpoint

POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add-async

Request parameters

Parameter	Type	Required	Description
`messages`	array	One of two	Conversation messages. Provide at least one of `messages` and `custom_content`
`messages[].role`	string	No	Message role. Valid values: `user`, `assistant`, and `tool`
`messages[].content`	string / array	No	Message content. Pass a text string or a multimodal array containing text and images
`messages[].content[].type`	string	No	Content type: `text` or `image_url`. Images are parsed only for projects that support multimodal input
`messages[].content[].text`	string	Conditionally required	Text content. Required when `type` is `text`
`messages[].content[].image_url`	object	Conditionally required	Image information. Required when `type` is `image_url`
`messages[].content[].image_url.url`	string	Conditionally required	Image URL
`messages[].tool_calls`	array	No	Tool calls initiated by an `assistant` message in OpenAI format. Tool messages are accepted only for skill extraction and are filtered out for other extraction types
`messages[].tool_calls[].id`	string	No	Tool call ID
`messages[].tool_calls[].type`	string	No	Tool call type. The value is `function`
`messages[].tool_calls[].function`	object	Conditionally required	Function call information. Required when `tool_calls` is present
`messages[].tool_calls[].function.name`	string	Conditionally required	Function name. Required for each tool call
`messages[].tool_calls[].function.arguments`	string	No	Function arguments as a JSON string, not an object
`messages[].tool_call_id`	string	Conditionally required	Corresponding tool call ID for a message whose `role` is `tool`. Tool messages are accepted only for skill extraction
`custom_content`	string	One of two	Custom content. When provided, it is saved directly and extraction is no longer based on `messages`. It cannot be used with `project_ids`
`user_id`	string	Yes	Sub-user ID used to isolate memories
`memory_library_id`	string	No	Memory library ID. The default library is used if omitted
`project_id`	string	No	Custom project ID. Mutually exclusive with `project_ids`
`project_ids`	array[string]	No	Up to five custom project IDs. Mutually exclusive with `project_id` and cannot be used with `custom_content`
`profile_schema`	string	No	User profile schema ID. Provide it to extract a user profile
`extract_mode`	string	No	Extraction mode. `profile_only` extracts only the profile
`skill_name`	string	Conditionally required	If the project is a skill and `custom_content` is provided, `skill_name`, `skill_description`, and `skill_tags` are all required
`skill_description`	string	Conditionally required	Skill description. Required under the same conditions as `skill_name`
`skill_tags`	array[string]	Conditionally required	Skill tags. Required under the same conditions as `skill_name`
`meta_data`	object	No	Custom metadata

Response

Field	Type	Description
`request_id`	string	Request ID
`event_id`	string	Execution event ID
`events`	array	Execution tasks
`events[].created_at`	integer	Creation time
`events[].event_id`	string	Event ID
`events[].event_type`	string	Event type, such as `ADD_ASYNC`
`events[].memory_library_id`	string	Memory library ID for the task
`events[].resource_id`	string	Source ID, such as a project ID or profile schema ID
`events[].resource_type`	string	Source type: `observation`, `skill`, `user_profile`, `custom_observation`, or `custom_skill`
`events[].status`	string	Task status: `PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, or `UNRECORDED`
`events[].updated_at`	integer	Time when the status was last updated
`events[].user_id`	string	Sub-user ID for the task
`events[].result`	array	Execution result. Empty in the initial response

Request example

cURL

curl --location 'https://dashscope.aliyuncs.com/api/v2/apps/memory/add-async' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "memory_library_id": "memory_library_001",
    "project_ids": ["project_001"],
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "Remind me to order takeout at 11 AM every day and to dress warmly tomorrow."},
      {"role": "assistant", "content": "Sure."}
    ],
    "meta_data": {"location_name": "Beijing"}
  }'

Response example

{
  "request_id": "048983ff-ed50-96e0-b0a6-482cce26cbe3",
  "event_id": "9d30e77a2f8e42378bf533406fdc09d9",
  "events": [
    {
      "created_at": 1784638015,
      "event_id": "9d30e77a2f8e42378bf533406fdc09d9",
      "event_type": "ADD_ASYNC",
      "memory_library_id": "memory_library_001",
      "resource_id": "project_001",
      "resource_type": "observation",
      "status": "PENDING",
      "updated_at": 1784638015,
      "user_id": "user_001",
      "result": []
    }
  ]
}

A status of PENDING or RUNNING means the task is still running. Use Get Event to query the result.

​Method and endpoint

​Request parameters

​Response

​Request example

​Response example

Method and endpoint

Request parameters

Response

Request example

Response example