Skip to main content

Long-term Memory API

The long-term memory API enables writing, searching, updating, and deletion of memories, as well as profile schema management and user profile retrieval, served through the workspace-dedicated domain.

Common Request Information

ParameterDescription
Base URLhttps://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/. Replace {workspaceId} in the request URL with your actual workspace ID, and use an API key that belongs to the same workspace.
AuthenticationAdd Authorization: Bearer $DASHSCOPE_API_KEY to the request header. See the API Key management page for obtaining a key
Content-Typeapplication/json
Before using the long-term memory API, you must enable the memory service in the console. Without activation, AddMemory and SearchMemory return a ServiceNotOpened error.

API Overview

Factual Memory

APIMethodPathDescription
AddMemoryPOST/addAdd memories with automatic key information extraction
ListMemoryGET/memory_nodesList memories with pagination
SearchMemoryPOST/memory_nodes/searchSearch historical memories based on semantics
UpdateMemoryPATCH/memory_nodes/{memory_node_id}Update memory content
DeleteMemoryDELETE/memory_nodes/{memory_node_id}Delete a memory node

User Profiles

APIMethodPathDescription
CreateProfileSchemaPOST/profile_schemasCreate a profile schema
GetUserProfileGET/profile_schemas/{schema_id}/user_profileGet the user profile for the specified schema

Error Codes

CodeHTTPDescription
ServiceNotOpened400Memory service not activated
MemoryNodeNotFound404Memory node does not exist
InvalidApiKey401Invalid API key
Throttling.RateQuota429Rate limit exceeded

API Authentication

export DASHSCOPE_API_KEY='your-api-key'

AddMemory

Add memories to the memory store, either from conversation messages (with automatic extraction) or as custom content.

Request

curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"messages": [
{"role": "user", "content": "Remind me to drink water at 9 AM"},
{"role": "assistant", "content": "OK, noted."}
],
"user_id": "user_001",
"meta_data": {"location_name": "Beijing"}
}'
ParameterTypeRequiredDescription
messagesarrayYes (when using conversation)The conversation messages.
custom_contentstringYes (when using custom)Custom memory content.
user_idstringYesThe user identifier for the memory space.
memory_library_idstringNoThe memory store ID. Defaults to the default store.
profile_schemastringNoThe user profile schema ID.
meta_dataobjectNoCustom metadata for categorizing memories.

Response

{"request_id": "xxx", "code": "Success", "message": ""}

ListMemory

List memory nodes for a user with pagination. 
curl --location --request GET 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

SearchMemory

Search memories based on semantic similarity. 
curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"user_id": "user_001",
"messages": [{"role": "user", "content": "What do I need to do?"}],
"top_k": 5
}'

UpdateMemory

Update the content of a memory node. 
curl --location --request PATCH 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"user_id": "user_001",
"custom_content": "Updated memory content."
}'

DeleteMemory

Delete a memory node. 
curl --location --request DELETE 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

CreateProfileSchema

Create a user profile schema. 
curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/profile_schemas \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "User Profile",
"attributes": [
{"name": "Age", "description": "User age"},
{"name": "Occupation", "description": "User occupation"}
]
}'

GetUserProfile

Get the user profile for the specified schema. 
curl -X GET "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/profile_schemas/{schema_id}/user_profile?user_id=user_001" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"