Add Memory-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Store conversations or custom content as memories synchronously, with automatic key information extraction

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.

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

Method and endpoint

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add

Replace {WorkspaceId} with your actual workspace ID.

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.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"}
  }'

Python

from agentscope_runtime.tools.modelstudio_memory import (
    AddMemory, AddMemoryInput, Message,
)
import asyncio

async def main():
    add_memory = AddMemory()
    try:
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            messages=[
                Message(role="user", content="Remind me to drink water at 9 AM every day"),
                Message(role="assistant", content="Sure, I've noted that"),
                Message(role="user", content="Remind me to organize the meeting notes at 10 AM tomorrow."),
            ]
        ))
        print("Memory added successfully")
    finally:
        await add_memory.close()

asyncio.run(main())

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"
    }
  ]
}

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