Add Memory

Synchronously saves conversations or custom content as memories and returns the extraction result in the response. Add Memory Async is recommended. Use this synchronous API for latency-sensitive scenarios in efficient mode; requests in intelligent mode may time out.

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

Method and endpoint

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

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`
`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 used for secondary memory isolation
`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 and requires both `profile_schema` and `messages`
`meta_data`	object	No	Custom metadata

Response

Field	Type	Description
`request_id`	string	Request ID
`memory_nodes`	array	Memories changed by the request
`memory_nodes[].memory_node_id`	string	Memory node ID
`memory_nodes[].content`	string	Memory content
`memory_nodes[].event`	string	Memory event: `ADD`, `UPDATE`, or `DELETE`. Returned when present
`memory_nodes[].old_content`	string	Previous content. Returned only when `event` is `UPDATE`

Request example

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

Response example

{
  "request_id": "048983ff-ed50-96e0-b0a6-482cce26cbe3",
  "memory_nodes": [
    {
      "memory_node_id": "42dfc089dfa7409889966960a95c3b7e",
      "content": "The user needs a reminder to order takeout at 11 AM every day",
      "event": "ADD"
    }
  ]
}

After writing a memory, use Search Memory to retrieve it.

​Method and endpoint

​Request parameters

​Response

​Request example

​Response example

Method and endpoint

Request parameters

Response

Request example

Response example