Skip to main content

Long-term memory API

AI forgets key information in long conversations and has no memory across sessions, causing context loss and an inconsistent experience. The long-term memory API automatically extracts and stores factual memories and user profiles from historical conversations in a structured way. In subsequent conversations or new sessions, these memories can be retrieved and injected into prompts, enabling the AI to achieve truly continuous understanding.

Memory (long-term memory) provides a complete set of open APIs covering the writing, searching, updating, and deletion of factual memories, as well as profile schema management and user profile retrieval. All endpoints are served through the DashScope gateway at https://dashscope.aliyuncs.com/api/v2/apps/memory/, using API Key authentication. See Authentication.

API overview

Factual memory:
APIMethodPathDescription
AddMemoryPOST/addAdd memories with automatic key information extraction
AddMemoryAsyncPOST/add-asyncSubmit a memory extraction task asynchronously
GetEventGET/events/{event_id}Get asynchronous task event details
ListMemoryGET/memory_nodesList memories with pagination
SearchMemoryPOST/memory_nodes/searchSearch historical memories based on semantics
GetMemoryNodeGET/memory_nodes/{memory_node_id}Get a memory node
GetSkillExportGET/skill/export/{memory_node_id}Export a skill memory node
UpdateMemoryPATCH/memory_nodes/{memory_node_id}Update memory content
DeleteMemoryDELETE/memory_nodes/{memory_node_id}Delete memories
User profile:
APIMethodPathDescription
CreateProfileSchemaPOST/profile_schemasCreate a profile schema
ListProfileSchemasGET/profile_schemasList profile schemas
GetProfileSchemaGET/profile_schemas/{profile_schema_id}Get profile schema details
UpdateProfileSchemaPATCH/profile_schemas/{profile_schema_id}Update a profile schema
GetUserProfileGET/profile_schemas/{profile_schema_id}/user_profileGet a user profile

Minimal call examples

Write a memory (AddMemory): 
curl -X POST https://dashscope.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 every day."},
      {"role": "assistant", "content": "Sure, I'll remember that."}
    ],
    "user_id": "user_001"
  }'
Search memories (SearchMemory): 
curl -X POST https://dashscope.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?"}
    ]
  }'

Usage limits

All APIs combined must not exceed 3,000 QPM (per Alibaba Cloud account). The factual memory add API is limited to 120 QPM, and the search API to 300 QPM. For more information, see Rate limits.
For per-API request parameters, responses, and Python examples, see the Long-term memory API reference. For an end-to-end walkthrough, see Quickstart. For features and console operations, see Memory.
Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support