长记忆服务mem0

步骤一：创建 Mem0 实例

1. 登录 PolarDB-X 控制台。

2. 在左侧导航栏，单击AI能力 > 记忆引擎。

3. 单击免费开通记忆引擎。

4. 在弹出的确认对话框中，单击确定。

步骤二：获取连接地址与访问凭证

• 获取 Mem0 连接地址

  在 Mem0 实例详情页，单击基本信息页签，在连接地址区域查看 VPC 地址（私网地址）和公网地址。

  说明

  • 公网地址需单独申请。在基本信息页签的连接地址区域，单击申请外网地址进行申请。

  • 建议优先使用 VPC 地址（私网地址）以获得更低延迟和更高安全性。

• 获取 API Key

  单击配置与管理页签，在参数列表中查看API Key。参数值默认隐藏，单击眼睛图标可查看完整内容，单击复制可复制参数值。

步骤三：配置白名单

1. 在 Mem0 实例详情页，单击白名单页签。

2. 单击新增IP白名单分组，或单击已有分组的配置按钮。

3. 在弹出的对话框中，输入分组名称和允许访问的 IP 地址，单击确定。

步骤四：操作示例

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": "我叫张三，在杭州工作，最爱吃川菜里的水煮鱼。"
            },
            {
              "role": "assistant",
              "content": "好的，已经记下您的信息和口味偏好。"
            }
        ],
        "user_id": "user_001",
        "run_id": "session_001",
        "metadata": {
            "source": "chat"
        }
    }'

{
    "results": [
        {
            "id": "70db3ad0-xxxx-xxxx-xxxx-66b3d24656ed",
            "memory": "名字是张三",
            "event": "ADD"
        },
        {
            "id": "769e6f22-xxxx-xxxx-xxxx-bfad6ade692c",
            "memory": "在杭州工作",
            "event": "ADD"
        },
        {
            "id": "30966d63-xxxx-xxxx-xxxx-d68d1048bc31",
            "memory": "最爱吃川菜里的水煮鱼",
            "event": "ADD"
        }
    ]
}

curl -X POST http://<your-endpoint>:3306/v2/memories/search/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your-api-key>" \
  -d '{
        "query": "我喜欢吃什么",
        "user_id": "user_001",
        "top_k": 5
    }'

{
    "results": [
        {
            "id": "30966d63-xxxx-xxxx-xxxx-d68d1048bc31",
            "memory": "最爱吃川菜里的水煮鱼",
            "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": "在杭州工作",
            "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"
        }
    ]
}

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"
    }'

{
    "results": [
        {
            "id": "70db3ad0-xxxx-xxxx-xxxx-66b3d24656ed",
            "memory": "名字是张三",
            "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": "在杭州工作",
            "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": "最爱吃川菜里的水煮鱼",
            "hash": "ec3a1bec939942045e2c90ac2acd93e7",
            "metadata": {"source": "chat"},
            "created_at": "2026-06-24T16:00:00.000000+08:00",
            "updated_at": null,
            "user_id": "user_001"
        }
    ]
}

请求头

所有 API 请求都需要在 HTTP Header 中包含认证信息：

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

API 端点总览

创建记忆

存储新的记忆。服务会自动对 messages 内容进行分析，生成语义记忆。

• 请求地址：POST /v1/memories/

• 请求参数：

  参数	类型	必选	说明
  messages	Array	是	对话消息列表，每条消息包含 role（user/assistant/system）和 content 字段。
  user_id	String	是	用户的唯一标识符。
  agent_id	String	否	智能体的唯一标识符，用于在同一用户下隔离不同应用的记忆。
  run_id	String	否	单次执行或会话的唯一标识符。
  metadata	Object	否	附加的元数据，会与记忆一同存储。
  filters	Object	否	过滤条件。
  prompt	String	否	自定义提取策略 Prompt，覆盖系统默认模板。

• 请求示例：

  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": "我叫张三，在杭州工作，最爱吃川菜里的水煮鱼。"},
              {"role": "assistant", "content": "好的，已经记下您的信息和口味偏好。"}
          ],
          "user_id": "user_001",
          "run_id": "session_001",
          "metadata": {"source": "chat"}
      }'

搜索记忆

根据查询字符串，搜索最相关的记忆。

• 请求地址：POST /v2/memories/search/

• 请求参数：

  参数	类型	必选	说明
  query	String	是	用于搜索的查询文本。
  user_id	String	否	限定在指定用户下搜索。
  agent_id	String	否	限定在指定智能体下搜索。
  run_id	String	否	限定在指定会话下搜索。
  filters	Object	否	基于元数据的过滤条件。
  top_k	Integer	否	返回结果数量上限，默认 5。

• 请求示例：

  curl -X POST http://<your-endpoint>:3306/v2/memories/search/ \
    -H "Content-Type: application/json" \
    -H "Authorization: Token <your-api-key>" \
    -d '{
          "query": "我喜欢吃什么",
          "user_id": "user_001",
          "top_k": 5
      }'

获取全部记忆

获取指定范围内的所有记忆。

• 请求地址：POST /v2/memories/

• 请求参数：

  参数	类型	必选	说明
  user_id	String	否	用户的唯一标识符。
  agent_id	String	否	限定获取指定智能体的记忆。
  run_id	String	否	限定获取指定会话的记忆。
  filters	Object	否	基于元数据的过滤条件。

  查询参数（可选）：page、page_size 用于分页。

• 请求示例：

  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"
      }'

更新记忆

更新指定记忆的内容。

• 请求地址：PUT /v1/memories/{memory_id}/

• 请求参数：

  参数	类型	必选	说明
  data	String	是	更新后的记忆内容。
  text	String	是	更新后的记忆内容（SDK 兼容别名，与 data 二选一）。

• 请求示例：

  curl -X PUT http://<your-endpoint>:3306/v1/memories/<memory_id>/ \
    -H "Content-Type: application/json" \
    -H "Authorization: Token <your-api-key>" \
    -d '{"data": "更新后的记忆内容"}'

  返回示例：

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

删除记忆

删除指定范围内的记忆。

• 删除单条：DELETE /v1/memories/{memory_id}/

• 按条件删除全部：DELETE /v1/memories/

  参数	类型	必选	说明
  user_id	String	是	用户的唯一标识符（query 参数或 JSON body）。
  agent_id	String	否	如果提供，则仅删除该智能体的记忆。
  run_id	String	否	如果提供，则仅删除该会话的记忆。

• 请求示例：

  # 删除单条
  curl -X DELETE http://<your-endpoint>:3306/v1/memories/<memory_id>/ \
    -H "Authorization: Token <your-api-key>"
  
  # 按条件删除全部
  curl -X DELETE 'http://<your-endpoint>:3306/v1/memories/?user_id=user_001' \
    -H "Authorization: Token <your-api-key>"

  返回示例：

  // 删除单条
  {"message": "Memory deleted successfully!"}
  
  // 按条件批量删除
  {"message": "Memories deleted successfully!"}

批量操作

对多条记忆进行批量更新或删除。

• 批量更新：PUT /v1/batch/

  # 批量更新多条记忆（每条用 memory_id + 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": "更新内容1"},
              {"memory_id": "<id_2>", "data": "更新内容2"}
          ]
      }'

• 批量删除：DELETE /v1/batch/

  # 批量删除多条记忆（每条只需 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>"}
          ]
      }'

实体管理

管理系统中注册的用户、智能体、会话等实体。

• 获取实体列表：GET /v1/entities/

• 删除实体下所有记忆：DELETE /v2/entities/{entity_type}/{entity_id}/，其中entity_type 支持：user、agent、app、run。

• 请求示例：

  # 获取所有实体列表
  curl -X GET http://<your-endpoint>:3306/v1/entities/ \
    -H "Authorization: Token <your-api-key>"
  
  # 删除指定实体下所有记忆（示例：删除用户 user_001 的全部记忆）
  curl -X DELETE http://<your-endpoint>:3306/v2/entities/user/user_001/ \
    -H "Authorization: Token <your-api-key>"

  获取实体列表返回示例：

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

记忆历史

获取指定记忆的变更历史记录。

• 请求地址：GET /v1/memories/{memory_id}/history/

• 请求示例：

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

  返回示例：

  [
      {
          "id": "0421a406-xxxx-xxxx-xxxx-7a0e886ead99",
          "memory_id": "d6b4fac6-xxxx-xxxx-xxxx-3289a763b6dc",
          "old_memory": null,
          "new_memory": "最爱吃川菜里的水煮鱼",
          "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": "最爱吃川菜里的水煮鱼",
          "new_memory": "最爱吃川菜里的水煮鱼和麻婆豆腐",
          "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
      }
  ]