Skip to main content

Overview

Service address, protocol, request format, and response structure

Through the Memory API, you can programmatically write memories, search memories, and manage profile templates. All endpoints are served via the workspace-dedicated domain.

Service address

https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/
{workspaceId} is your workspace ID, in the format llm-xxxxxxxxxxxx. View it on the console's Workspace Management page. See Obtain APP ID and Workspace ID. The workspace-dedicated domain accepts only API keys that belong to the same workspace. All endpoints use the same base URL with the /memory/ path prefix. When you use the Python SDK (agentscope-runtime), set the MEMORY_SERVICE_ENDPOINT environment variable to the base URL (without a trailing /): 
export MEMORY_SERVICE_ENDPOINT="https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory"

Protocol

  • All endpoints use HTTPS only
  • Request and response bodies are JSON in UTF-8
  • Write and search use POST; list uses GET; update uses PATCH; delete uses DELETE

Common headers

HeaderRequiredDescription
AuthorizationYesBearer $DASHSCOPE_API_KEY, see Authentication
Content-TypeYesapplication/json

Response format

All endpoints return a unified JSON structure. Success: 
{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "memory_nodes": [
    {
      "memory_node_id": "node_xxx",
      "content": "User needs hydration reminder at 9 AM daily"
    }
  ]
}
Error: 
{
  "code": "InvalidParameter",
  "message": "user_id is required",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Provide request_id to help locate the relevant logs quickly. See Error codes.

Pagination

List endpoints support pagination:
ParameterDescription
page_sizePage size
page_numPage number, starting from 1
Memory begins commercial billing on August 20, 2026. Add and Search calls distinguish Pro and Lite plan versions. See Billing.
View AddMemory to start.