Skip to main content

Add Memory Async

Asynchronously store conversations as memories and query execution status and results by event ID

POST
/add-async
cURL
curl --request POST \
  --url 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add-async' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "<string>",
  "messages": [
    {
      "role": "user",
      "content": null,
      "tool_calls": [
        {}
      ],
      "tool_call_id": "<string>"
    }
  ],
  "custom_content": "<string>",
  "profile_schema": "<string>",
  "memory_library_id": "<string>",
  "project_id": "<string>",
  "project_ids": [
    "<string>"
  ],
  "skill_name": "<string>",
  "skill_description": "<string>",
  "skill_tags": [
    "<string>"
  ],
  "meta_data": {}
}
'
{
  "request_id": "<string>",
  "event_id": "<string>",
  "events": [
    {
      "event_id": "<string>",
      "event_type": "<string>",
      "resource_type": "observation",
      "resource_id": "<string>",
      "memory_library_id": "<string>",
      "user_id": "<string>",
      "status": "PENDING",
      "created_at": 0,
      "updated_at": 0
    }
  ]
}
Asynchronously stores user conversations as memories. The API returns an event ID immediately while memory extraction runs in the background. Use GetEvent to query execution status and results. Compared with the synchronous AddMemory, the async API does not wait for extraction to finish within the request, making it suitable for long conversations with many turns.
Before calling, ensure you have obtained an API Key. See Authentication.

Request parameters

ParameterTypeRequiredDescription
user_idstringYesMemory entity ID, used to identify the owning object, max 64 characters
messagesarrayYes*Conversation message list, up to 50 entries. role supports user / assistant / tool; content supports a text string or a multimodal array in standard OpenAI format; assistant messages may carry tool_calls; messages with role set to tool must carry the corresponding tool_call_id
custom_contentstringYes*Custom content, max 512 characters. Mutually exclusive with messages, and can only be bound to one project_id
profile_schemastringNoProfile schema ID. If omitted, no user profile is extracted
memory_library_idstringNoMemory library ID. If not provided, the default library is used
project_idstringNoCustom project ID for secondary memory isolation. Mutually exclusive with project_ids
project_idsarray[string]NoMultiple custom project IDs. Mutually exclusive with project_id
skill_namestringNoName of the skill content
skill_descriptionstringNoDescription of the skill content
skill_tagsarray[string]NoTags of the skill content
meta_dataobjectNoUser-defined information
messages and custom_content are mutually exclusive. When custom_content is provided, messages is ignored.
When the project is a skill, if custom_content is provided, then skill_name, skill_description, and skill_tags are required; otherwise the API returns an error.

Response

FieldTypeDescription
request_idstringRequest ID
event_idstringID of the execution event
eventsarrayList of execution tasks. A single call may produce multiple tasks, for example one for factual memories and one for the user profile
events[].event_idstringEvent ID
events[].event_typestringEvent type, for example ADD_ASYNC
events[].resource_typestringTask source type: observation / skill / profile
events[].resource_idstringTask source ID, the corresponding project or profile ID
events[].memory_library_idstringMemory library ID of the task
events[].user_idstringMemory entity ID of the task
events[].statusstringTask status: PENDING / SUCCEEDED / FAILED / UNRECORDED
events[].created_atintegerTask creation timestamp
events[].updated_atintegerTimestamp of the last task status update

Code examples

Replace {workspaceId} with your actual workspace ID.
cURL
curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add-async \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {"role": "user", "content": "Remind me to order takeout at 11 AM every day, and remind me to dress warmly tomorrow."},
      {"role": "assistant", "content": "Sure, noted."},
      {"role": "assistant", "content": "", "tool_calls": [
        {"id": "call_1", "type": "function", "function": {"name": "update_memory", "arguments": "{\"text\":\"dress warmly tomorrow\"}"}}
      ]},
      {"role": "tool", "tool_call_id": "call_1", "content": "{\"ok\":true}"}
    ],
    "project_ids": ["project_001"],
    "user_id": "user_001"
  }'

# response
{
  "event_id": "9d30e77a...",
  "events": [
    {
      "event_id": "9d30e77a...",
      "event_type": "ADD_ASYNC",
      "resource_type": "observation",
      "resource_id": "project_001",
      "status": "PENDING",
      "created_at": 1784638015,
      "updated_at": 1784638015,
      "user_id": "user_001"
    }
  ],
  "request_id": "048983ff-ed50-..."
}
A status of PENDING means extraction is still running in the background. Use GetEvent to query the execution result.

Authorizations

​
string
header
required

Body

application/json
​
string
required

记忆实体 ID，最大 64 字符

​
object[]

对话消息列表，最多 50 条。与 custom_content 互斥

​
string

自定义内容，最大 512 字符。与 messages 互斥，只能绑定到一个 project_id

​
string

画像模板 ID。不传则不提取用户画像

​
string

记忆库 ID，不传则使用默认记忆库

​
string

自定义项目 ID，与 project_ids 互斥

​
string[]

多个自定义项目 ID，与 project_id 互斥

​
string

skill 内容名称。project 为 skill 且传入 custom_content 时必传

​
string

skill 内容描述。project 为 skill 且传入 custom_content 时必传

​
string[]

skill 内容标签。project 为 skill 且传入 custom_content 时必传

​
object

用户自定义信息

Response

200-application/json
​
string
​
string

执行任务事件 ID

​
object[]