Long-term memory API

Key features

• Memory nodes: Automatically extracts key content from conversations and stores it as structured memory nodes. You can also add content directly. The feature supports retrieval and dynamic updates based on historical conversations.

• User profiles: Extract structured user attributes, such as age, occupation, and interests, from conversations based on custom profile templates.

Memory nodes are suitable for most long-term memory scenarios. To extract a fixed set of attributes, use this feature in combination with user profiles.

Generated memory nodes and user profiles do not currently have an expiration date.

Scope

The long-term memory feature provides an open API that you can integrate into any application. It also supports sharing a single memory library across multiple applications.

Improvements over the legacy long-term memory API

• Greater speed and efficiency: Lower latency and improved recall for memory retrieval.

• Automatic extraction: Automatically extracts and deduplicates key information from conversations, eliminating the need for manual input.

• Optimized retrieval algorithms: A new semantic search feature that significantly improves retrieval accuracy and response speed.

• User profile capabilities: Provides a comprehensive feature set for user profile extraction and management.

Usage

Before you start, set the DASHSCOPE_API_KEY environment variable. For instructions on how to obtain and configure it, see Obtain API key.

# Add a memory
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": "OK, I have recorded it."},
      {"role": "user", "content": "Remind me to organize the meeting minutes at 10 AM tomorrow."}
    ],
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "project_id": "your_project_id",
    "profile_schema": "your_profile_schema_id",
    "meta_data": {
      "location_name": "Beijing"
    }
  }'
# memory_library_id: Optional. The ID of the memory library, which can be found on the memory library card. If not specified, the default memory library is used.
# project_id: Optional. The ID of the memory node rule, which can be found under memory rules on the memory library details page.
# profile_schema: Optional. The ID of the user profile rule, which can be found under memory rules on the memory library details page.
# meta_data: Optional. Custom metadata used to categorize and manage memories.

# Add a memory with custom content
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_content": "The user is going to Shanghai for the WAIC this weekend.",
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "meta_data": {
      "custom_key": "custom_value"
    }
  }'

# Search for memories
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",
    "memory_library_id": "your_memory_library_id",
    "messages": [
      {"role": "user", "content": "What do I need to do?"}
    ],
    "top_k": 5
  }'

# Add a memory
curl -X POST 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 drink water at 9 AM every day."},
      {"role": "assistant", "content": "OK, I have recorded it."}
    ]
  }'

# List memories
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# Update a memory
curl --location --request PATCH 'https://dashscope.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": "Also remind me to take my medicine at 10 AM."
  }'

# View the updated memory
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",
    "memory_library_id": "your_memory_library_id",
    "messages": [
      {"role": "user", "content": "What do I need to do?"}
    ],
    "top_k": 5
  }'

# Delete a memory
curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# Create a profile schema
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Basic user profile",
    "description": "User information including age and interests",
    "attributes": [
      {"name": "Age", "description": "User's age"},
      {"name": "Hobbies", "description": "User's interests and hobbies"},
      {"name": "Occupation", "description": "User's occupation"}
    ]
  }'

# Add a conversation containing profile information (use the profile_schema_id returned above)
curl -X POST 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": "I am 28 years old and a software engineer. I like to play soccer on weekends."},
      {"role": "assistant", "content": "Nice to meet you!"}
    ],
    "profile_schema": "YOUR_SCHEMA_ID"
  }'

# Get the user profile (wait ~3 seconds for extraction to complete)
curl -X GET "https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{YOUR_SCHEMA_ID}/user_profile?user_id=user_001" \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json"

Environment variables

API reference

For a complete API reference, including request parameters, responses, and code samples, see Long-term Memory (New) API Reference. This document also includes error codes and recommended solutions.

Related documentation

To use and manage the long-term memory and user profile features described in this document in the Model Studio console, see Memory Library.

FAQ

API throttling