Use memory management-PolarDB(PolarDB)-阿里云帮助中心

Scope of application

Before you start the configuration, confirm the following prerequisites and constraints:

A memory management application is created.
The whitelist of the application and the whitelist of the cluster are independent of each other and must be configured separately. After a whitelist is configured, only IP addresses or security groups in the whitelist can access the memory management service.
The network environment of the client (an ECS instance in the same VPC, an ECS instance in another VPC, an on-premises server, a personal computer, or another cloud server) determines the selection of the endpoint and the method for allowing access in the whitelist.
The engine type of the application determines the scope of available features, as shown in the following table.
Feature
mem0
memOS
Custom extraction policies
Supported
Not supported
View memory data in the console
Supported
Supported

Obtain the endpoint and access credentials

The endpoint determines from which network the client accesses the service, and the access credential is used for identity verification when the client connects. You can obtain both on the application details page.

Obtain the endpoint

There are two types of endpoints: private endpoints and public endpoints. Select one based on the network environment of the client:

Client environment	Endpoint to use
An ECS instance in the same VPC as the application	Private endpoint (recommended)
An ECS instance not in the same VPC as the application, an on-premises server, a personal computer, or another cloud server	Public endpoint

Log on to the PolarDB console. In the left-side navigation pane, clickPolarDB Mem0.
On the application list page, click the Application ID/Name of the target application to go to the application details page.
On the Basic Information tab, in the Connection Management area, view the Private network address.
If you need the Public network address, click Application to submit the application.

Note

A public endpoint provides only an IP address and a port, and does not provide a domain name. If you need a domain name, you can bind one by yourself.

Obtain the access credentials

On the application details page, click the Configure tab.
From the parameter list, find the secret.access.apikey parameter. The parameter value is the access credential.
Click the display icon on the right side of the parameter value to view the full content.

Configure a whitelist

Allow the corresponding IP addresses or security groups based on the network environment of the client, so that the client can access the memory management service.

On the application details page, click the Whitelist tab.
Select Add Whitelist, Select Security Groups, or edit an existing whitelist group.
Enter the IP addresses to allow or select a security group:
- If the ECS instance is in the same VPC as the application, enter the private IP address of the ECS instance or the CIDR block of the VPC where the ECS instance resides.
- If the ECS instance is not in the same VPC as the application, enter the public IP address of the ECS instance, or add the security group where the ECS instance resides.
- If an on-premises server, a computer, or another cloud server needs to access the application, add its public IP address to the IP whitelist.

Note

You can view the IP address of an ECS instance on the ECS Instance Details page.

Operation examples

Add memory

curl -X POST http://my-endpoint:8080/v1/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "messages": [
            {
              "role": "user",
              "content": "I love spicy food, especially Sichuan cuisine."
            },
            {
              "role": "assistant",
              "content": "Got it. I have noted down your taste preference."
            }
        ],
        "user_id": "user_002",
        "agent_id": "food-assistant",
        "run_id": "user_002_run_id",
        "enable_thinking": false
    }'

Expected response:

{
    "results": [
        {
            "id": "32155c0a-xxxx-xxxx-xxxx-804e119bb965",
            "event": "ADD",
            "data": {
                "memory": "Likes spicy food"
            }
        },
        {
            "id": "9188deee-xxxx-xxxx-xxxx-3073ef826b42",
            "event": "ADD",
            "data": {
                "memory": "Particularly likes Sichuan cuisine"
            }
        }
    ]
}

Search memory

curl -X POST http://my-endpoint:8080/v2/memories/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "query": "What food do I like",
        "agent_id": "food-assistant",
        "filters": {
            "user_id": "user_002",
            "run_id": "user_002_run_id"
        }
    }'

Expected response:

{
    "results": [
        {
            "id": "9188deee-xxxx-xxxx-xxxx-3073ef826b42",
            "memory": "Particularly likes Sichuan cuisine",
            "hash": "a826fbf3c3844024633e84d04875ee45",
            "metadata": {"additionalProp1": {}},
            "score": 0.681654033365126,
            "created_at": "2026-03-05T23:59:36.038217-08:00",
            "updated_at": null,
            "user_id": "user_002",
            "agent_id": "food-assistant",
            "run_id": "user_002_run_id"
        },
        {
            "id": "32155c0a-xxxx-xxxx-xxxx-804e119bb965",
            "memory": "Likes spicy food",
            "hash": "b2882aaf96654a9e16f45f363022010a",
            "metadata": {"additionalProp1": {}},
            "score": 0.582298149788604,
            "created_at": "2026-03-05T23:59:36.023417-08:00",
            "updated_at": null,
            "user_id": "user_002",
            "agent_id": "food-assistant",
            "run_id": "user_002_run_id"
        }
    ]
}

Get memory

curl -X POST http://my-endpoint:8080/v2/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "filters": {
            "user_id": "user_002",
            "run_id": "user_002_run_id",
            "agent_id": "food-assistant"
        }
    }'

Expected response:

{
    "results": [
        {
            "id": "39b06e97-xxxx-xxx-xxxx-4223818bc04e",
            "memory": "Likes spicy food",
            "hash": "b2882aaf96654a9e16f45f363022010a",
            "metadata": {"additionalProp1": {}},
            "created_at": "2026-03-06T00:12:45.109789-08:00",
            "updated_at": null,
            "user_id": "user_002",
            "agent_id": "food-assistant",
            "run_id": "user_002_run_id"
        },
        {
            "id": "482def46-xxxx-xxxx-xxxx-ff4886a1047c",
            "memory": "Particularly likes Sichuan cuisine",
            "hash": "a826fbf3c3844024633e84d04875ee45",
            "metadata": {"additionalProp1": {}},
            "created_at": "2026-03-06T00:12:45.121585-08:00",
            "updated_at": null,
            "user_id": "user_002",
            "agent_id": "food-assistant",
            "run_id": "user_002_run_id"
        }
    ]
}

Appendix: API reference

PolarDB Mem0 provides a managed service based on the open source mem0 framework (V1.0.1). You can view the real-time updated API documentation by visiting http://<your-endpoint>:8080/docs.

Request header

All API requests must include Authorization: Token <your-api-key> in the HTTP header for authentication.

Request examples

Only a few API references are listed here.

Create Memories

Stores new memories. The service automatically analyzes the messages content and generates session summaries and semantic memories.

Endpoint: POST /v1/memories

Request parameters:

Parameter	Required	Description
`messages` (array)	Yes	The list of conversation messages that follows the OpenAI format. Each item contains `role` (the message sender role, such as `user` or `assistant`) and `content` (message content).
`user_id` (String)	Yes	The unique identifier of the user.
`agent_id` (String)	No	The unique identifier of the agent, used to isolate memories of different applications under the same user.
`run_id` (String)	No	The unique identifier of a single execution or session.
`metadata` (Object)	No	Additional metadata stored together with the memory.

curl example:

curl -X POST http://my-endpoint:8080/v1/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "messages": [
            {"role": "user", "content": "I love spicy food, especially Sichuan cuisine."},
            {"role": "assistant", "content": "Got it. I have noted down your taste preference."}
        ],
        "user_id": "user_002",
        "agent_id": "food-assistant",
        "run_id": "user_002_run_id",
        "enable_thinking": false
    }'

Python example:

import requests
import json

payload = {
    "messages": [
        {"role": "user", "content": "I love spicy food, especially Sichuan cuisine."},
        {"role": "assistant", "content": "Got it. I have noted down your taste preference."}
    ],
    "user_id": "user-002",
    "agent_id": "food-assistant",
    "run_id": "user_002_run_id",
    "enable_thinking": false
}

response = requests.post(
    "http://<your-endpoint>:8080/v1/memories",
    headers={"Authorization": "Token <your-api-key>", "Content-Type": "application/json"},
    data=json.dumps(payload)
)

print(response.json())

Search Memories

Searches for the most relevant memories based on a query string.

Endpoint: POST /v2/memories/search

Request parameters:

Parameter	Required	Description
`query` (String)	Yes	The query text used for the search, for example, the new question of the user.
`agent_id` (String)	No	Limits the search to the specified agent.
`filters` (Object)	Yes	Filter conditions based on metadata. Required property: `user_id` (unique identifier of the user). Optional property: `run_id` (limits the search to the specified session).

curl example:

curl -X POST http://my-endpoint:8080/v2/memories/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "query": "What food do I like",
        "agent_id": "food-assistant",
        "filters": {
            "user_id": "user_002",
            "run_id": "user_002_run_id"
        }
    }'

Python example:

import requests
import json

payload = {
    "query": "What food do I like",
    "agent_id": "food-assistant",
    "filters": {
          "user_id": "user_002",
          "run_id": "user_002_run_id"
      }
}

response = requests.post(
    "http://<your-endpoint>:8080/v2/memories/search",
    headers={"Authorization": "Token <your-api-key>", "Content-Type": "application/json"},
    data=json.dumps(payload)
)

print(json.dumps(response.json(), indent=2, ensure_ascii=False))

Get Memories

Retrieves all raw memories within the specified scope.

Endpoint: POST /v2/memories

Request parameters:

Parameter	Required	Description
`filters` (Object)	Yes	Filter conditions based on metadata. Required property: `user_id` (unique identifier of the user). Optional properties: `agent_id` (limits retrieval to the specified agent) and `run_id` (limits the search to the specified session).

curl example:

curl -X POST http://my-endpoint:8080/v2/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "filters": {
            "user_id": "user_002",
            "run_id": "user_002_run_id",
            "agent_id": "food-assistant"
        }
    }'

Python example:

import requests
import json

payload = {
    "filters": {
          "user_id": "user_002",
          "run_id": "user_002_run_id",
          "agent_id": "food-assistant"
      }
}

response = requests.post(
    "http://<your-endpoint>:8080/v2/memories",
    headers={"Authorization": "Token <your-api-key>", "Content-Type": "application/json"},
    data=json.dumps(payload)
)

print(json.dumps(response.json(), indent=2, ensure_ascii=False))

Delete Memories

Deletes all memories within the specified scope.

Endpoint: DELETE /v1/memories

Request parameters:

Parameter	Required	Description
`user_id` (String)	Yes	The unique identifier of the user.
`agent_id` (String)	No	If provided, only memories of this agent are deleted.
`run_id` (String)	No	If provided, only memories of this session are deleted.

curl example:

curl -X DELETE 'http://<your-endpoint>:8080/v1/memories?user_id=user_002&agent_id=food-assistant' \
  -H 'accept: application/json' \
  -H 'Authorization: Token <your-api-key>'

Python example:

import requests
import json

current_user_id = "user_002"
current_agent_id = "food-assistant"

api_url = f"http://<your-endpoint>:8080/v1/memories?user_id={current_user_id}&agent_id={current_agent_id}"

response = requests.delete(
    api_url,
    headers={"Authorization": "Token <your-api-key>"},
)

print(json.dumps(response.json(), indent=2, ensure_ascii=False))

On-demand tuning and daily management

After the connection is established, you can adjust service parameters and customize memory extraction results as needed, and check the stored memory data in the console.

Parameter settings

On the Configure tab of the application details page, you can adjust the following parameters to optimize service performance and results.

Important

Modifying some parameters may cause the service to restart. We recommend that you perform such operations during off-peak hours.

Parameter	Description
`secret.access.apikey`	The access credential, used for identity verification when the client connects to the memory management service.
`memserver.POLAR_GRAPH_EMBEDDING_THRESHOLD`	The threshold for determining whether to create a graph node when extracting memories. When an extracted memory requires adding a relationship to an existing graph, the vector similarity of nodes is compared. If the similarity is greater than this threshold, an existing node is used; otherwise, a new graph node is created. Default value: `0.7`.
`memserver.POLAR_GRAPH_MAXCONN`	The maximum number of concurrent connections to the memory service.

Custom extraction policies

Note

Only the mem0 memory engine supports this configuration.

Memory management provides built-in prompt templates (extraction policies) that guide the large language model (LLM) in extracting and summarizing memories from conversations. You can customize these prompts to fit specific business scenarios.

Policy types

Only two policy types are supported: conversation summary and semantic memory.
Only one policy can be enabled at a time for each policy type (such as conversation summary).

Procedure

You can manage these policies on the Extraction Policy tab.
You can edit an existing policy for fine-tuning, or click Add Policy to add a policy, and then click the Edit Policy button to set it as the currently enabled policy.

View memory data in the console

Open the Memory Retrieval tab on the application details page to view and search stored memory data. Applications of both the mem0 and memOS engine types support this feature.

Feature	mem0	memOS
Custom extraction policies	Supported	Not supported
View memory data in the console	Supported	Supported