Long-term Memory Service mem0 - PolarDB - Alibaba Cloud Documentation Center

PolarDB-X Mem0 is a managed long-term memory service for AI agents, built on PolarDB-X. It is 100% compatible with the open-source Mem0 framework and the Mem0 cloud service SDK. The service efficiently extracts, stores, and retrieves memories across multiple interactions, enabling you to build intelligent and personalized AI applications.

Advantages

Dual-channel memory with unified management: In a single PolarDB-X instance, the service provides both the Mem0 semantic memory API and direct MySQL connectivity for structured memory storage. This allows you to manage both semantic memory (such as user preferences and habits) and structured memory (such as user profiles, session logs, and tool call records) without purchasing a separate database.
Full compatibility for seamless migration: Existing agent applications that use the community version or the cloud SDK can connect directly without any code changes.
Distributed high performance: Built on the native vector capabilities of PolarDB-X and a four-layer concurrency architecture (multi-process, async event loop, thread pool bridge, and instance pool), this service delivers 10 to 50 times the throughput of the open-source server on comparable hardware.
Fully managed service with cost optimization: As a fully managed service, it provides a web-based management interface that eliminates hardware costs and the overhead of managing system deployment, operations, and failure handling. Memory refinement technology significantly reduces token consumption of large models, further lowering resource costs.
Elastic horizontal scaling: Based on the distributed architecture of PolarDB-X, this service supports the storage and retrieval of massive amounts of memory data. With automatic scale-out through horizontal sharding, it can easily handle memory scales ranging from millions to tens of millions of entries.

Use cases

Intelligent customer service systems: Understands context across multiple sessions to avoid repetitive questions, provide consistent solutions, and improve service efficiency and satisfaction.
Personalized education: Builds student competency profiles to dynamically adjust teaching content and provide personalized learning paths for adaptive instruction.
Healthcare management: Continuously records patient history, treatment plans, and physiological indicators to create complete health profiles for continuous and individualized medical services.
Emotional companionship and mental health: Deeply understands user emotions, personality, and life events to identify stressors and provide empathetic, ongoing support.
Intelligent recommendation systems: Provides more accurate and dynamic content recommendations based on long-term user interests and immediate feedback.
Multi-agent collaboration: Provides shared or isolated memory spaces for multiple agents (differentiated by agent_id) to support knowledge accumulation and transfer in team collaboration scenarios.

Availability

Enterprise Edition: Requires version 2.6.0_5.4.21-20260610_xcluster8.4.21-20260605 or later.
Standard Edition: Requires version 2.5.0_standard_xcluster8.4.21-20260605 or later.

Note

For information about the instance version naming rules, see Release notes.
For information about how to view the version of an instance, see View and update the engine version of a PolarDB for Xscale instance.

Quick start

Step 1: Create a Mem0 instance

Log on to the PolarDB-X console.
In the left-side navigation pane, click AI Capability > Memory Engine.
Click Activate Memory Engine for Free.
In the confirmation dialog box, click OK.

Note

Creating the application takes 3 to 5 minutes. After the instance is created, the page displays its details.

Step 2: Get connection address and credentials

Obtain the Mem0 connection address
On the Mem0 instance details page, click the Basic Information tab. In the Endpoint section, view the VPC address (private address) and public address.
Note
- A public address must be applied for separately. On the Basic Information tab, in the Endpoint section, click Apply for Public Endpoint.
- The VPC address (private address) provides lower latency and higher security.
Obtain the API key
Click the Configuration and Management tab to find the API key in the parameter list. The value is hidden by default. Click the eye icon to show the key, and then click Copy.

Step 3: Configure a whitelist

On the Mem0 instance details page, click the Whitelist tab.
Click Add IP Address Whitelist Group, or click Configure for an existing group.
In the dialog box that appears, enter a group name and the allowed IP addresses, and then click OK.

Note

If your ECS instance and Mem0 instance are in the same VPC, enter the private IP address of the ECS instance or its VPC CIDR block.
If your ECS instance and Mem0 instance are not in the same VPC, enter the public IP address of the ECS instance.
To access the Mem0 instance from a local server or computer, add its public IP address to the whitelist.

Step 4: Usage examples

Add memories

Add a conversation to Mem0. The service automatically extracts semantic memory from the content.

curl -X POST http://<your-endpoint>:3306/v1/memories/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "messages": [
            {
              "role": "user",
              "content": "My name is John Doe, I work in New York, and my favorite food is pizza."
            },
            {
              "role": "assistant",
              "content": "Okay, I have noted your information and preferences."
            }
        ],
        "user_id": "user_001",
        "run_id": "session_001",
        "metadata": {
            "source": "chat"
        }
    }'

Example response:

{
    "results": [
        {
            "id": "70db3ad0-xxxx-xxxx-xxxx-66b3d24656ed",
            "memory": "Name is John Doe",
            "event": "ADD"
        },
        {
            "id": "769e6f22-xxxx-xxxx-xxxx-bfad6ade692c",
            "memory": "Works in New York",
            "event": "ADD"
        },
        {
            "id": "30966d63-xxxx-xxxx-xxxx-d68d1048bc31",
            "memory": "Favorite food is pizza",
            "event": "ADD"
        }
    ]
}

Note

The current instance has a known limitation: When the messages content is in Chinese and also includes the agent_id field, LLM extraction returns an empty {"results":[]} (an HTTP 200 status is returned, but no data is written to memory). We recommend that you do not pass the agent_id in Chinese-language scenarios. If you need multi-agent isolation, you can achieve it after the write operation by using the metadata field or a separate user_id. Messages in English are not affected by this limitation.

Search memories

Perform a semantic search based on a query to return the most relevant memories.

curl -X POST http://<your-endpoint>:3306/v2/memories/search/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "query": "What do I like to eat?",
        "user_id": "user_001",
        "top_k": 5
    }'

Example response:

{
    "results": [
        {
            "id": "30966d63-xxxx-xxxx-xxxx-d68d1048bc31",
            "memory": "Favorite food is pizza",
            "hash": "ec3a1bec939942045e2c90ac2acd93e7",
            "metadata": {"source": "chat"},
            "score": 0.5295314589229717,
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        },
        {
            "id": "769e6f22-xxxx-xxxx-xxxx-bfad6ade692c",
            "memory": "Works in New York",
            "hash": "1b3f2e1f5d70920d8a1cac47cf365a31",
            "metadata": {"source": "chat"},
            "score": 0.2815325178698094,
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        }
    ]
}

Get all memories

Retrieve all memory entries for a specific user or agent.

curl -X POST http://<your-endpoint>:3306/v2/memories/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "user_id": "user_001"
    }'

Example response:

{
    "results": [
        {
            "id": "70db3ad0-xxxx-xxxx-xxxx-66b3d24656ed",
            "memory": "Name is John Doe",
            "hash": "7d0a10343e179826a9cbb01e5d4f6e71",
            "metadata": {"source": "chat"},
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        },
        {
            "id": "769e6f22-xxxx-xxxx-xxxx-bfad6ade692c",
            "memory": "Works in New York",
            "hash": "1b3f2e1f5d70920d8a1cac47cf365a31",
            "metadata": {"source": "chat"},
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        },
        {
            "id": "30966d63-xxxx-xxxx-xxxx-d68d1048bc31",
            "memory": "Favorite food is pizza",
            "hash": "ec3a1bec939942045e2c90ac2acd93e7",
            "metadata": {"source": "chat"},
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        }
    ]
}

Release a Mem0 instance

Log on to the PolarDB-X console.
In the left-side navigation pane, click AI Capability > Memory Engine.
Click Disable Memory Engine.
In the confirmation dialog box, click OK.

Warning

Disabling the memory engine permanently deletes all stored memory data and renders its features unavailable. This action is irreversible.

API reference

PolarDB-X Mem0 is a managed service based on the open-source framework mem0 and is compatible with two sets of API paths: the Mem0 cloud service SDK and the open-source server. You can view the up-to-date API documentation by accessing http://<your-endpoint>:3306/docs.

Request header

All API requests must include the following authentication information in the HTTP request header:

Authorization: Token <your-api-key>
Content-Type: application/json

API endpoints

Function	Cloud SDK path	Open source path	Method	Description
Health check	`/v1/ping/`	`/`	GET	Verify SDK initialization
Add memories	`/v1/memories/`	`/memories`	POST	Extract memories from a conversation
Get all memories	`/v2/memories/`	`/memories` (GET)	POST/GET	Retrieve a list of memories by criteria
Search memories	`/v2/memories/search/`	`/memories/search`	POST	Perform a semantic similarity search
Get a single memory	`/v1/memories/{id}/`	`/memories/{id}`	GET	Retrieve memory details by ID
Update memory	`/v1/memories/{id}/`	`/memories/{id}`	PUT	Modify memory content
Delete a single memory	`/v1/memories/{id}/`	`/memories/{id}`	DELETE	Delete a memory by ID
Delete all memories	`/v1/memories/`	`/memories`	DELETE	Delete memories in bulk based on criteria
Memory history	`/v1/memories/{id}/history/`	`/memories/{id}/history`	GET	Retrieve the change history of a memory
Batch update	`/v1/batch/`	—	PUT	Update multiple memories in a single batch
Batch delete	`/v1/batch/`	—	DELETE	Delete multiple memories in a single batch
Get entities	`/v1/entities/`	`/entities`	GET	Retrieve a list of all entities
Delete entity	`/v2/entities/{type}/{id}/`	—	DELETE	Delete all memories associated with an entity
Reset	`/v1/memories/reset/`	`/reset`	POST	Reset all memories
Create export	`/v1/exports/`	—	POST	Create a memory export task
Get export	`/v1/exports/get/`	—	POST	Retrieve export results
Summary	`/v1/summary/`	—	POST	Get a memory summary
Feedback	`/v1/feedback/`	—	POST	Submit memory feedback

Add memories

Stores new memories. The service automatically analyzes the content of messages to generate semantic memory.

Request URL: POST /v1/memories/

Request parameters:

Parameter	Type	Required	Description
messages	Array	Yes	A list of dialogue messages, where each message contains a `role` field (user/assistant/system) and a `content` field.
user_id	String	Yes	The unique identifier for the user.
agent_id	String	No	The unique identifier for the agent, used to isolate memories for different applications under the same user.
run_id	String	No	The unique identifier for a single execution or session.
metadata	Object	No	Additional metadata to store with the memory.
filters	Object	No	Filter conditions.
prompt	String	No	A custom extraction policy prompt to override the default system template.

Example request:

curl -X POST http://<your-endpoint>:3306/v1/memories/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "messages": [
            {"role": "user", "content": "My name is John Doe, I work in New York, and my favorite food is pizza."},
            {"role": "assistant", "content": "Okay, I have noted your information and preferences."}
        ],
        "user_id": "user_001",
        "run_id": "session_001",
        "metadata": {"source": "chat"}
    }'

Search memories

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

Request URL: POST /v2/memories/search/

Request parameters:

Parameter	Type	Required	Description
query	String	Yes	The query text for the search.
user_id	String	No	Limits the search to a specific user.
agent_id	String	No	Limits the search to a specific agent.
run_id	String	No	Limits the search to a specific session.
filters	Object	No	Filter conditions based on metadata.
top_k	Integer	No	The maximum number of results to return. Default: 5.

Example request:

curl -X POST http://<your-endpoint>:3306/v2/memories/search/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "query": "What do I like to eat?",
        "user_id": "user_001",
        "top_k": 5
    }'

Get all memories

Retrieves all memories within a specified scope.

Request URL: POST /v2/memories/

Request parameters:

Parameter	Type	Required	Description
user_id	String	No	The unique identifier for the user.
agent_id	String	No	Limits retrieval to a specific agent's memories.
run_id	String	No	Limits retrieval to a specific session's memories.
filters	Object	No	Filter conditions based on metadata.

Query parameters (Optional): page and page_size are used for pagination.

Example request:

curl -X POST http://<your-endpoint>:3306/v2/memories/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "user_id": "user_001"
    }'

Update memory

Updates the content of a specific memory.

Request URL: PUT /v1/memories/{memory_id}/
Request parameters:
Parameter
Type
Required
Description
data
String
Yes
The updated memory content.
text
String
Yes
Updated memory content (SDK-compatible alias, mutually exclusive with data).

Example request:

curl -X PUT http://<your-endpoint>:3306/v1/memories/<memory_id>/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{"data": "Updated memory content"}'

Example response:

{"message": "Memory updated successfully!"}

Delete memories

Deletes memories within a specified scope.

Delete a single memory: DELETE /v1/memories/{memory_id}/

Delete all by condition: DELETE /v1/memories/

Parameter	Type	Required	Description
user_id	String	Yes	The unique identifier for the user. It can be provided as a query parameter or in the request body.
agent_id	String	No	If provided, only memories for this agent are deleted.
run_id	String	No	If provided, only memories for this session are deleted.

Example requests:

# Delete a single memory
curl -X DELETE http://<your-endpoint>:3306/v1/memories/<memory_id>/ \
  -H "Authorization: Token <your-api-key>"

# Delete all memories by criteria
curl -X DELETE 'http://<your-endpoint>:3306/v1/memories/?user_id=user_001' \
  -H "Authorization: Token <your-api-key>"

Example responses:

// Delete a single memory
{"message": "Memory deleted successfully!"}

// Delete all memories by criteria
{"message": "Memories deleted successfully!"}

Batch operations

Use these endpoints to update or delete multiple memories in a single request.

Batch update: PUT /v1/batch/

# Update multiple memories in a batch. Specify each with a memory_id and data.
curl -X PUT http://<your-endpoint>:3306/v1/batch/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "memories": [
            {"memory_id": "<id_1>", "data": "Updated content 1"},
            {"memory_id": "<id_2>", "data": "Updated content 2"}
        ]
    }'

Batch delete: DELETE /v1/batch/

# Delete multiple memories in a batch. Specify each with a memory_id.
curl -X DELETE http://<your-endpoint>:3306/v1/batch/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "memories": [
            {"memory_id": "<id_1>"},
            {"memory_id": "<id_2>"}
        ]
    }'

Entity management

Manages registered entities in the system, such as users, agents, and sessions.

Get entity list: GET /v1/entities/
Delete all memories for an entity: DELETE /v2/entities/{entity_type}/{entity_id}/, where entity_type supports: user, agent, app, run.

Example requests:

# Get a list of all entities
curl -X GET http://<your-endpoint>:3306/v1/entities/ \
  -H "Authorization: Token <your-api-key>"

# Delete all memories for a specific entity (example: delete all memories for user_001)
curl -X DELETE http://<your-endpoint>:3306/v2/entities/user/user_001/ \
  -H "Authorization: Token <your-api-key>"

Example response for listing entities:

{
    "results": {
        "users": ["user_001"],
        "agents": [],
        "apps": [],
        "runs": []
    }
}

Memory history

Retrieves the change history for a specific memory.

Request URL: GET /v1/memories/{memory_id}/history/

Example request:

curl -X GET http://<your-endpoint>:3306/v1/memories/<memory_id>/history/ \
  -H "Authorization: Token <your-api-key>"

Example response:

[
    {
        "id": "0421a406-xxxx-xxxx-xxxx-7a0e886ead99",
        "memory_id": "d6b4fac6-xxxx-xxxx-xxxx-3289a763b6dc",
        "old_memory": null,
        "new_memory": "Favorite food is pizza",
        "event": "ADD",
        "created_at": "2026-06-24T00:27:19.772241-07:00",
        "updated_at": null,
        "is_deleted": false,
        "actor_id": null,
        "role": null
    },
    {
        "id": "085674b6-xxxx-xxxx-xxxx-5392c72dc5b8",
        "memory_id": "d6b4fac6-xxxx-xxxx-xxxx-3289a763b6dc",
        "old_memory": "Favorite food is pizza",
        "new_memory": "Favorite foods are pizza and tacos",
        "event": "UPDATE",
        "created_at": "2026-06-24T00:27:19.772241-07:00",
        "updated_at": "2026-06-24T00:27:47.207790-07:00",
        "is_deleted": false,
        "actor_id": null,
        "role": null
    }
]