Use PolarDB Mem0 memory endpoints whitelist API reference - PolarDB

Scope of application

The procedures in this topic apply to both the Standard Edition and Enterprise Edition of PolarDB Agent Memory. The Enterprise Edition stores vector data in the associated PolarDB for MySQL cluster. The client connection method and API invocation are the same as those of the Standard Edition. If you have not created a PolarDB Agent Memory, see Create PolarDB Agent Memory.

Obtain the endpoint and access credentials

Obtain the endpoint: On the PolarDB Agent Memory list page, click the target Application ID/Name to go to the details page. On the Basic Information tab, view the Public network address or Private network address.
Note
- The Public network address must be requested separately. Click the Application button to apply.
- The Public network address provides only the IP address and port, not a domain name. If needed, you can bind a domain name yourself.
Obtain configuration information: On the details page, view the related configuration information on the Configure tab, such as the API key (secret.access.apikey).

Configure the whitelist

On the PolarDB Agent Memory list page, click the target Application ID/Name to go to the details page, switch to the Whitelist tab, and manage whitelist groups by using Add Whitelist, Select Security Groups, or by modifying existing whitelist groups.

Note

The application whitelist is independent of the cluster whitelist and must be configured separately.
If an ECS instance needs to access the application, you can view the IP address of the ECS instance on the ECS Instance Details page and add it to the IP whitelist:
- If the ECS instance and the application are in the same VPC, enter the private IP address of the ECS instance or the CIDR block of the VPC.
- If the ECS instance and the application are not in the same VPC, enter the public IP address of the ECS instance, or add the security group to which the ECS instance belongs.
If a local server, a computer, or another cloud server needs to access the application, add its public IP address to the IP whitelist.

(Optional) Customize the extraction strategy (Prompt)

PolarDB Agent Memory uses built-in prompt templates (extraction strategies) to guide the large language model in extracting and summarizing memories from conversations. You can customize these prompts to adapt to different business scenarios.

Strategy types

Multiple strategy types are currently supported, including Conversation Summary, Memory Update, Question Answering, and Memory Summary. For more information about strategy types, see the console.
Only one strategy per type can be enabled at any given time.

Procedure

Manage strategies on the Extraction Policy tab of the PolarDB Agent Memory details page.
You can edit an existing strategy for fine-tuning, or add a new strategy through Add Policy, and then set it as the currently enabled strategy through Edit Policy.

Operation examples

Add memories

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": "Especially likes Sichuan cuisine"
            }
        }
    ]
}

Search memories

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": "Especially 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 memories

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": "Especially 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"
        }
    ]
}

Release a PolarDB Agent Memory

Log on to the PolarDB console, click PolarDB Agent Memory in the left-side navigation pane, find the target PolarDB Agent Memory, and click Release Application in the Actions column.

Warning

After release, the PolarDB Agent Memory and the memory data stored in it cannot be recovered. Proceed with caution.

Appendix: API reference

PolarDB Agent Memory provides a managed service based on the open source mem0 framework (V1.0.1). You can view the up-to-date API documentation by visiting http://<your-endpoint>:8080/docs.

Request headers

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

Request examples

Only some API references are listed here.

Create memories

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

Endpoint: POST /v1/memories

Request body:

messages array (Required)

The list of conversation messages, following the OpenAI format.

Properties

role String (Required)

The message sender role, such as user or assistant.

content String (Required)

The message content.

curl

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

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())

user_id String (Required)

The unique identifier of the user.

agent_id String (Optional)

The unique identifier of the agent, used to isolate memories of different applications under the same user.

run_id String (Optional)

The unique identifier of a single execution or session.

metadata Object (Optional)

Additional metadata stored together with the memory.

Search memories

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

Endpoint: POST /v2/memories/search

Request body:

query String (Required)

The query text used for the search, for example, a new question from the user.

curl

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

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))

agent_id String (Optional)

Limits the search to the specified agent.

filters String (Required)

Filter conditions based on metadata.

Properties

user_id String (Required)

The unique identifier of the user.

run_id String (Optional)

Limits the search to the specified session.

Get memories

Retrieves all raw memories within the specified scope.

Endpoint: POST /v2/memories

Request body:

filters String (Required)

Filter conditions based on metadata.

Properties

user_id String (Required)

The unique identifier of the user.

agent_id String (Optional)

Limits retrieval to the memories of the specified agent.

run_id String (Optional)

Limits the search to the specified session.

curl

  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

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 body:

user_id String (Required)

The unique identifier of the user.

curl

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

import requests
import json

# Limit the search scope
current_user_id = "user_002"
current_agent_id = "food-assistant"

# Prepare the API request URL and data
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))

agent_id String (Optional)

If provided, only memories of this agent are deleted.

run_id String (Optional)

If provided, only memories of this session are deleted.