Long-term memory API

Usage notes

To use the long-term memory feature, you must enable it on the application configuration page.
After you enable long-term memory, a general memory configuration is used by default. This configuration stores user information, such as personal details, interests, and recent behaviors. This information is automatically recalled in subsequent conversations without requiring additional steps. Memories are stored by user ID.
To customize memory policies for your business scenarios, you can use the APIs described in this document. API configurations take effect immediately and overwrite the default system memory policies.
To query and modify memory results, you can use the APIs described in this document.

Endpoint: sfmmultimodalapp.cn-beijing.aliyuncs.com Region: cn-beijing

Integration examples

Java

Step 1: Import the SDK

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>sfmmultimodalapp20250909</artifactId>
    <version>1.1.2</version>
</dependency>

Step 2: Code example

        Config config = new Config();
        config.setAccessKeyId("*");
        config.setAccessKeySecret("*");

        config.setEndpoint("********");
        config.setRegionId("********");
        Client client = new Client(config);

        QueryMemoryConfigRequest request = new QueryMemoryConfigRequest();
        request.setWorkspaceId("llm-*"); // The workspace ID in Model Studio
        request.setAppId("*");  // The app ID of the multi-modal interaction suite in Model Studio
        request.setUserDefinedId("*");

        QueryMemoryConfigResponse queryProfileResponse = client.queryMemoryConfig(request);
        System.out.println(JsonUtils.toJson(queryProfileResponse.getBody()));

Python

Step 1: Install the SDK pip install -i http://yum.tbsite.net/aliyun-pypi/simple/ --extra-index-url http://yum.tbsite.net/pypi/simple/ --trusted-host=yum.tbsite.net alibabacloud-sfmmultimodalapp20250909==1.1.2 Step 2: Code example

import sys
from typing import List

from Tea.exceptions import UnretryableException, TeaException
from alibabacloud_sfmmultimodalapp20250909.client import Client as SfmMultiModalApp20250909Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_sfmmultimodalapp20250909 import models as sfm_multi_modal_app_20250909_models

class PopRequest:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> SfmMultiModalApp20250909Client:
        config = open_api_models.Config(
            access_key_id='*',
            access_key_secret='*'
        )

        config.endpoint = f'*******'
        return SfmMultiModalApp20250909Client(config)

    @staticmethod
    def main(
            args: List[str],
    ) -> None:
        client = PopRequest.create_client()
        memory_config_request = sfm_multi_modal_app_20250909_models.QueryMemoryConfigRequest(
            workspace_id='*',
            app_id='*',
            user_defined_id='*'
        )
        headers = {}
        try:
            # If you copy the code to run, print the API return value.
            res = client.query_memory_config(memory_config_request)
            print('body', res.body)
            if res.body.success:
                print('data', res.body.data)
        except UnretryableException as e:
            # Network error
            print(e)
        except TeaException as e:
            # Service error
            print(e)
        except Exception as e:
            # Other error
            print(e)

if __name__ == '__main__':
    PopRequest.main(sys.argv[1:])

Prerequisites

Log on to the Alibaba Cloud console and go to Resource Access Management (RAM). Grant the AliyunSFMMultiModalAppFullAcces permission to the RAM user that sends the requests. This permission is used to manage the Alibaba Cloud multi-modal interaction developer suite (sfmmultimodalapp).
The RAM user must also have permissions for the workspace ID in Model Studio.

API reference

Common response parameters

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.
success	Boolean	Yes	Indicates whether the request was successful.
code	String	Yes	The return code.
httpStatusCode	Integer	Yes	The HTTP status code.
message	String	No	The returned message.
data	Object	No	The returned data.

Memory policy configuration

User profile (profile)

A user profile is used to define specific memory mining policies for items such as personal information, interests, and behavioral preferences. The multi-modal interaction developer suite provides default user profile mining rules that cover most personal and work scenarios. To customize these rules, you can use the following APIs. You can configure user profiles at the user and application levels. After you complete the configuration using the API, the default user profile configuration is overwritten.

1. Create a profile schema (CreateProfile)

Request parameters:

Parameter		Type	Required	Description
userDefinedId		String	No	The user ID. This ID must be unique within the workspace.
workspaceId		varchar	Yes	The workspace ID.
appId		String	Yes	The application ID.
name		String	Yes	The profile name.
description		String	Yes	The profile description.
attributes		Array	Yes	The properties.
	[0].name	String	Yes	The name. Ensure the name is semantically unique to avoid affecting extraction performance. For example, do not use ["Full Name", "Name", "Given Name"] or ["Age", "Years Old"] at the same time.
	[0].description	String	No	The description.
	[0].immutable	Boolean	No	Indicates whether the property is immutable. Default value: False.
	[0].defaultValue	String	No	The initial value. This parameter is required if immutable is set to True.

Response parameters:

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.
schemaId	String	Yes	The user profile ID.
name	String	Yes	The profile name.
description	String	Yes	The profile description.

2. Update a profile schema (UpdateProfile)

Request parameters:

Parameter		Type	Required	Description
userDefinedId		String	No	The user ID. This ID must be unique within the workspace.
workspaceId		varchar	Yes	The Model Studio workspace ID.
appId		String	Yes	The multi-modal application ID.
name		String	No	The profile name.
description		String	No	The profile description.
attributesOperations		Array	Yes	The properties.
	[0].op	String	Yes	The operation. Valid values: "add", "update", and "delete".
	[0].attributeId	String	No	The attribute ID. This parameter is required when op is "update" or "delete".
	[0].name	String	No	The name. This parameter is required when op is "add". If you change the name, previous values may become abnormal.
	[0].description	String	No	The description.
	[0].defaultValue	String	No	The default value.

Response parameters:

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.
name	String	Yes	The profile name.
description	String	Yes	The profile description.

3. Delete a profile schema (DeleteProfile)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	No	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.

Response parameters:

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.

4. Query profile schema details (QueryProfile)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	No	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.

Response parameters:

Parameter		Type	Required	Description
name		String	Yes	The profile name.
description		String	Yes	The profile description.
attributes		Object	Yes	The properties.
	[0].attributeId	String	Yes	The attribute ID.
	[0].name	String	Yes	The name.
	[0].description	String	No	The description.
	[0].immutable	Boolean	No	Indicates whether the property is immutable. Default value: False.
	[0].defaultValue	String	No	The initial value. This parameter is required if immutable is set to True.

5. Query user profile data (QueryUserProfile)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	Yes	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.

Response parameters:

Parameter		Type	Required	Description
name		String	Yes	The profile name.
description		String	Yes	The profile description.
attributes		Object	Yes	The properties.
	[0].id	String	Yes	ID
	[0].name	String	Yes	The name.
	[0].value	String	No	The value.

Memory fragment configuration (memory config)

Memory fragments are used to mine scattered pieces of memory outside of the user profile, such as recent behaviors. You can configure specific memory policies using a prompt.

1. Update memory fragment configuration (PatchMemoryConfig)

This operation creates a configuration if one does not exist or modifies the configuration if one already exists. Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	No	The user ID.
workspaceId	String	Yes	The workspace ID.
appId	String	Yes	The application ID.
prompt	String	No	A custom instruction that affects memory extraction.
autoUpdate	Boolean	No	Specifies whether to merge and update memories. We recommend that you set this to true to prevent data bloat.
expirationTime	integer	No	The memory expiration time.
topK	integer	No	Maximum recall count
threshold	Double	No	The minimum threshold. A value of 0.03 is recommended.

Response parameters:

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.

2. Query memory fragment configuration (QueryMemoryConfig)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	No	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.

Response parameters:

Parameter	Type	Required	Description
requestId	String	Yes	The request ID.
prompt	String	No	A custom instruction that affects memory extraction. This corresponds to customInstructions for new memories.
autoUpdate	Boolean	No	Specifies whether to merge and update memories. We recommend that you set this to true to prevent data bloat.
expirationTime	integer	No	The memory expiration time.
topK	integer	No	The maximum number of memories to recall.
threshold	Double	No	The minimum threshold. A value of 0.03 is recommended.

Memory data management

Memory management (memory)

The memory management API is used to query and edit the memory mining results for a specific user.

1. Create memory content (CreateMemory)

Request parameters:

Parameter		Type	Required	Description
userDefinedId		String	Yes	The user ID.
workspaceId		String	Yes	The workspace ID.
appId		String	Yes	The application ID.
content		String	No	Custom content that is saved to the memory data. You must specify either content or messagesJson.
projectId		String	Yes	User profile: profile_project Memory fragment: observation_project
messagesJson		String	No	A list of messages in a JSON string. `messages[0].role` is a String. `messages[0].content` is a String or Array. Supports multi-modal content. For more information, see the request parameters for Omni.
prompt		String	No	A custom instruction that affects memory extraction. For example, "Focus only on the user's occupation. Do not pay attention to private information such as age or gender."
autoUpdate		Boolean	No	Specifies whether to merge and update memories. We recommend that you set this to true to prevent data bloat.
expirationTime		Integer	No	The expiration time. The range is [1-180]. A value of -1 means the memory never expires.
metaData		Object	No	Metadata. We recommend that you include the following fields.
	[0].dialog_id	String	No	The dialog ID, used to record which conversation the memory belongs to.
	[0].locationName	String	No	The geographic location (semantics).
	[0].workspaceId	String	No	The Model Studio workspace ID.
	[0].geoCoordinate	String	No	The coordinates. For the format, see Coordinate Transformation - AMAP API.
	[0].mediaDesc	Array	No	A description of the multi-modal information.

mediaDesc

Parameter	Type	Required	Description
url	String	No	The URL of the multi-modal file.
description	String	No	The corresponding text description.

Response parameters:

Parameter		Type	Required	Description
requestId		String	Yes	The request ID.
memoryNodes		Array		A list of changed memories.
	[0].memoryNodeId	String	Yes	Multimodal file URL
	[0].content	String	Yes	Text description
	[0].event	String	Yes	The memory event. Indicates whether the memory was added, updated, or deleted. "ADD", "UPDATE", "DELETE"
	[0].oldContent	String	No	The previous content. This is valid only when the event is "UPDATE".

2. Query a list of memories (QueryMemoryList)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	Yes	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.
projectId	String	No	User profile: profile_project Memory fragment: observation_project. This parameter is required for multi-modal applications but optional for voice applications.
pageSize	Integer	No	The number of entries per page. Default value: 10.
pageNum	Integer	No	The page number. Default value: 1.

Response parameters:

Parameter		Type	Required	Description
userDefinedId		String	Yes	The user ID.
workspaceId		varchar	Yes	The workspace ID.
appId		String	Yes	The application ID.
memoryNodes		Array	Yes	A list of memories.
	[0].memoryNodeId	String	Yes	The unique ID of the generated memory.
	[0].content	String	Yes	The content of the generated memory.
	[0].timestamp	String	Yes	The message timestamp.
	[0].createdAt	String	Yes	The creation time.
	[0].updatedAt	String	Yes	The update time.
	[0].projectId	String	Yes	The projectId specified during the add or update operation. This can be empty.
	[0].metaData	Obejct	No	The metadata.
total		Integer	Yes	The total number of entries.
pageSize		Integer	Yes	The number of entries per page.
pageNum		Integer	Yes	The page number.

3. Delete memory content (DeleteMemory)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	Yes	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.
memoryNodeId	String	Yes	The unique ID of the generated memory.

Response parameters:

Parameter		Type	Required	Description
requestId		String	Yes	The request ID.

4. Update memory content (UpdateMemory)

Request parameters:

Parameter	Type	Required	Description
userDefinedId	String	Yes	The user ID.
workspaceId	varchar	Yes	The workspace ID.
appId	String	Yes	The application ID.
memoryNodeId	String	Yes	The unique ID of the generated memory.
projectId	String	No	User profile: profile_project Memory fragment: observation_project
metaData		Object	No	Metadata. We recommend that you include the following.
	[0].dialog_id	String	No	The dialog ID, used to record which conversation the memory belongs to.
	[0].locationName	String	No	The geographic location (semantics).
	[0].workspaceId	String	No	The workspace ID.
	[0].geoCoordinate	String	No	The coordinates. For the format, see Coordinate Transformation - AMAP API.
	[0].mediaDesc	Array	No	A description of the multi-modal information.

mediaDesc

Parameter	Type	Required	Description
url	String	No	The URL of the multi-modal file.
description	String	No	The corresponding text description.

Appendix

Currently, user-based long-term memory can mine and recall the following types of content:

The following table shows the default user profile. If you define a user profile using the API, this content is overwritten.

Profile module	Profile	Example
Personal information	Name: Includes full name, nickname, English name, etc.	The user's name is Xiaobai, and their English name is Mike.
	Date of birth: Includes year, month, and day of birth, age, age group, zodiac sign, Chinese zodiac sign, etc.	The user's birthday is January 22, and they were born in the Year of the Ox.
	Gender	The user is a girl.
	Ethnicity	The user is of Korean ethnicity and can understand Korean but does not speak it well.
	Height, weight, blood type	The user is 160 cm tall and has type O blood.
	Occupation	The user used to work at a finance company and now runs their own restaurant.
	Educational background	The user graduated from the Computer Science department of Tsinghua University in 2016.
	Important dates: Anniversaries, etc.	May 1 is the user's wedding anniversary.
	Allergy history	The user is allergic to eggs and cannot eat any food containing eggs. The user is allergic to pollen and tries to avoid places with many plants in the spring.
	Region: Includes current city, home/work/school address, hometown, etc.	The user is from Jiangsu and works in Shanghai. The user's company is located in Lujiazui.
	Languages: Includes native language, second language, dialect, etc.	The user speaks English and Cantonese and is currently learning Japanese.
	Religious beliefs	The user has no religious beliefs but occasionally visits temples.
Interests and preferences	Dietary preferences: Includes taste, cuisine, food culture, food names, restaurant names, dietary restrictions, eating habits, etc.	The user likes spicy food and loves Sichuan hot pot. The user does not like cilantro. The user enjoys studying wine culture. The user is allergic to eggs.
	Travel preferences: Includes destination type, destination name, travel style, seasonal preference, accommodation type, etc.	The user prefers natural scenery. The user likes to go skiing in the winter. The user prefers to stay in guesthouses.
	Shopping preferences: Includes shopping method, preferred brands, price sensitivity, payment habits, etc.	The user likes to stock up on Taobao during the Double 11 shopping festival and enjoys researching various discount promotions. The user likes to buy clothes from brand XX.
	Reading preferences: Includes literary genre, book type, book title, author name, reading habits, etc.	The user likes French literature. The user likes to read books by Yu Hua. The user prefers to read physical books.
	Listening preferences: Includes type and name of music/podcasts/audiobooks, style and name of singers/streamers/creators, listening platform, listening time, listening duration, etc.	The user likes to listen to tech podcasts on the way to work in the morning. The user likes to listen to Jay Chou's songs. The user likes to use fragmented time to listen to spoken English lessons.
	Viewing preferences: Includes content area, type and name of movies/TV shows/variety shows/documentaries/plays, type and name of actors/directors/bloggers, etc.	The user has recently been watching short dramas. The user likes comedies, and their favorite actor is XXX. The user's favorite store-review blogger is XXX.
	Sports preferences: Includes type of sport, frequency, venue, etc.	The user has recently been jogging in the morning at least three times a week. The user enjoys cycling but is not good at basketball.
	Transportation preferences: Includes common modes of transportation, seat preference, etc.	The user prefers high-speed rail over airplanes for short-distance travel. The user prefers a window seat.
	Clothing preferences: Includes dress style, color scheme, fabric and pattern, clothing brands, etc.	The user prefers cotton clothes because they are more breathable and comfortable. The user prefers a casual style of dress, especially jeans.
	Other interests and preferences, specific to subcategories and names	The user enjoys photography and likes to take portraits. The user has recently become interested in flower arranging.
Lifestyle and status	Daily routine: Includes sleep habits, daily patterns, etc.	The user takes a 30-minute nap every day.
	Conversation style: Preferred conversation style	The user wants the assistant to speak in a lively tone.
	Thinking style: Emotional/rational, prefers direct answers or guided thinking through conversation, etc.	The user wants to be guided in their thinking rather than being given a direct answer.
	Skill level: Skill level in languages, sports, etc.	The user's spoken English is average and they hope to improve it quickly through practice.
Health status	Basic indicators: BMI, blood pressure, heart rate, etc.	The user's BMI is low, and the doctor recommends gaining some weight.
	Abnormal physical conditions: Illness, feeling unwell, etc.	The user has had a bit of a cold recently and has a sore throat.
	Psychological state: Anxiety, excitement, fatigue, etc.	The user has been in a bad mood recently because their beloved dog passed away.
	Personality traits: MBTI type, etc.	The user has an ESTJ personality type.
	Medical records: Surgery/hospitalization records, long-term medication list, post-operative recovery plan, etc.	The user just had an appendectomy and needs to take medication XX three times a day.
Life records	Shopping history: Recently purchased items	The user bought a lot of cleaning supplies two days ago.
	Browsing history: History of viewed and read media, articles, etc.	The user watched up to episode 30 of "Empresses in the Palace" today.
	Travel history: Recently visited cities and places	The user went to the Forbidden City and Tiananmen Square yesterday.
	Device passwords	The user's home Wi-Fi password is 29283238.
Personal plans	Short-term plans: Meeting schedules, shopping lists, hospital appointments, etc.	The user is going to the supermarket tomorrow to buy fruit and a cup. The user has a follow-up dental appointment next Monday.
Personal plans	Long-term plans: Career planning, fitness plans, weight loss goals, study plans, financial goals, and their progress.	The user plans to lose 5 kg this year.
Family-related	Basic information of family members/friends: Name, age, occupation, life preferences, etc.	The user's daughter is named Xiaohao, is 3 years old, and has recently enjoyed looking at picture books. The user's best friend is Lily. They have known each other for 5 years, and her birthday is October 15.
	Living situation of family members/friends: A child's nutritional supplement plan, favorite games and toys, school class, etc. An elderly person's health status, dietary habits, etc.	The user's mother has high blood pressure and takes medication for it every morning. The user's son is in the third grade and attends an art class every week.
	Pet-related: Breed, nickname, age, weight, dietary preferences, personality, health condition, etc.	The user has a dog named Wangcai who likes to eat chicken legs.

​Usage notes

​Integration examples

​Java

​Python

​API reference

​Memory policy configuration

​User profile (profile)

1. Create a profile schema (CreateProfile)

2. Update a profile schema (UpdateProfile)

3. Delete a profile schema (DeleteProfile)

4. Query profile schema details (QueryProfile)

5. Query user profile data (QueryUserProfile)

​Memory fragment configuration (memory config)

1. Update memory fragment configuration (PatchMemoryConfig)

2. Query memory fragment configuration (QueryMemoryConfig)

​Memory data management

​Memory management (memory)

1. Create memory content (CreateMemory)

2. Query a list of memories (QueryMemoryList)

3. Delete memory content (DeleteMemory)

4. Update memory content (UpdateMemory)

​Appendix

Usage notes

Integration examples

Java

Python

API reference

Memory policy configuration

User profile (profile)

Memory fragment configuration (memory config)

Memory data management

Memory management (memory)

Appendix