AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

Agentic Memory智能体记忆服务

更新时间：
复制为 MD 格式
产品详情
我的收藏

为Agentic AI智能体与智能搜索服务提供长期/短期/上下文记忆存储与检索服务，支持个性化记忆memory，Agent智能体记忆，搜索记忆和技能Skill管理服务等多种搜索数据的存储、查询、更新和遗忘操作，采用BM25和向量检索结合的融合检索与多路召回技术，确保高效准确召回的智能记忆检索服务。

服务名称

服务ID

服务描述

API调用QPS限制（含主账号与RAM子账号）

Agentic Memory智能体记忆服务

agentic-memory

提供Memory和Skill两类数据的存储与管理：Memory存储用户个人爱好、兴趣、偏好等信息；Skill存储可复用的执行逻辑和技能。

10

如需扩充QPS，请通过工单联系技术支持协助。

前提条件

  • 获取身份鉴权信息

    通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见认证和鉴权。

  • 获取服务调用地址

    支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

公共请求说明

公共URI

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}

参数说明：

  • host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。

  • workspace_name：工作空间名称，例如default。

  • service_id：服务ID，固定值为agentic-memory。

Header参数

API-KEY认证

参数

类型

必填

描述

示例值

Content-Type

String

是

请求类型：application/json

application/json

Authorization

String

是

API-Key

Bearer OS-d1**2a

公共返回参数

以下参数在所有接口的返回结果中均包含。

参数

类型

描述

示例值

request_id

String

系统对一次API调用赋予的唯一标识。

9907b179-7bcc-2c43-21db-d3c9d777bbfe

latency

Int

请求耗时，单位ms。

161

status

String

请求状态。

OK

健康检查

检查Memory服务的健康状态。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/health

返回参数

参数

类型

描述

示例值

result.status

String

服务健康状态。取值：healthy（健康）、unhealthy（不健康）。

healthy

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/health' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "287d9462-3c9a-2706-780e-b49aa3702e01",
  "latency": 6,
  "status": "OK",
  "result": {
    "status": "healthy"
  }
}

存储Memory

从消息内容中智能提取用户偏好信息并存储为Memory。存储过程为异步处理，接口返回任务ID，需通过查询任务状态接口获取处理结果。

存储时系统会自动搜索已有记忆并进行去重处理，自动判断新增或更新。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/memories

Body参数

参数

类型

必填

描述

示例值

messages

String/Object/Array

是

消息内容，支持三种格式：String（简单文本）、Object（单条消息）、Array（多轮对话）。

仅传多轮对话时能提取Skill。

参数支持以下三种格式：

  • String 格式：

    "我喜欢喝咖啡"

  • Object 格式：

    {
 "role": "user",
 "content": "我喜欢喝咖啡"
 }

  • Array 格式（消息列表）：

     [
  {
    "role": "user",
    "content": "我喜欢喝咖啡，帮我推荐"
  },
  {
    "role": "assistant",
    "content": "为您推荐以下几款咖啡..."
  }
]

user_id

String

是

用户ID。

user_123

agent_id

String

否

Agent ID。传入此字段时，提取的是assistant属性而非user属性。

agent_001

run_id

String

否

Run ID。

run_001

enhancements

Object

否

增强功能配置。默认不开启，传参即代表启用。

enhancements.skill

Object

否

Skill提取配置。

enhancements.skill.enable

Boolean

否

是否同时提取Skill。默认false。

仅传多轮对话时能提取Skill。

true

返回参数

参数

类型

描述

示例值

result.memory

Object

Memory处理结果。

result.memory.task_id

String

Memory异步任务ID，可通过查询任务状态接口查询处理进度。

mt-52b939a7-5a20-47e6-97e4-3cbb87bd9227

result.skill.task_id

String

Skill任务ID。

st-1b0bfe52-d44d-4fdb-94ae-8513fa77ab55

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/memories' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {"role": "user", "content": "我喜欢喝咖啡，帮我推荐"},
    {"role": "assistant", "content": "为您推荐以下几款咖啡..."}
  ],
  "user_id": "user_123",
  "enhancements": {
    "skill": {
      "enable": true
    }
  }
}'

响应示例

{
  "request_id": "9907b179-7bcc-2c43-21db-d3c9d777bbfe",
  "latency": 161,
  "status": "OK",
  "result": {
    "memory": {
      "task_id": "mt-52b939a7-5a20-47e6-97e4-3cbb87bd9227"
    },
    "skill": {
      "task_id": "st-1b0bfe52-d44d-4fdb-94ae-8513fa77ab55"
    }
  }
}

查询任务状态

查询存储Memory或Skill的异步任务处理状态。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/tasks/{task_id}

Path参数

参数

类型

必填

描述

示例值

task_id

String

是

存储Memory或上传Skill时返回的异步任务ID。

mt-52b939a7-5a20-47e6-97e4-3cbb87bd9227

返回参数

参数

类型

描述

示例值

result.task_id

String

任务ID。

mt-d16cbff2-d971-4d90-be55-91957d15a034

result.status

String

任务状态。取值：

running（处理中）、completed（处理完成）、pending（待处理）、failed（处理失败）。

completed

result.memory_ids

Array

生成的Memory ID列表。与skill_ids最多一个不为空。

["m-60aa2de5-c43e-4b3d-9efd-f058bc3994be"]

result.skill_ids

Array

生成的Skill ID列表。与memory_ids最多一个不为空。

["s-60aa2de5-c43e-4b3d-9efd-f058bc3994be"]

result.error_message

String

错误信息。status为failed时返回。

null

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/tasks/mt-52b939a7-5a20-47e6-97e4-3cbb87bd9227' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "f638818812e3cc629302738263f00984",
  "latency": 5,
  "status": "OK",
  "result": {
    "task_id": "mt-d16cbff2-d971-4d90-be55-91957d15a034",
    "status": "completed",
    "memory_ids": [
      "m-60aa2de5-c43e-4b3d-9efd-f058bc3994be"
    ]
  }
}

搜索Memory/Skill

根据查询条件搜索Memory和Skill，采用BM25和向量多路召回技术。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/search

Body参数

参数

类型

必填

描述

示例值

query

String

是

搜索关键词。

咖啡

user_id

String

是

用户ID。

user_123

agent_id

String

否

Agent ID。

agent_001

run_id

String

否

Run ID。

run_001

size

Int

否

返回结果数量限制。默认10。

10

enhancements

Object

否

增强功能配置。

enhancements.skill

Object

否

Skill搜索配置。

enhancements.skill.enable

Boolean

否

是否同时返回Skill搜索结果。默认false。

true

返回参数

参数

类型

描述

示例值

result.memory

Object

Memory搜索结果。

result.memory.results

Array

Memory结果列表。每个元素包含memory_id、memory、user_id等字段。

result.memory.total

Int

Memory结果总数（mem+skill）。

1

result.skill

Object

Skill搜索结果。

result.skill.results

Array

Skill结果列表。每个元素包含skill_id,name,description,version,user_id等字段。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/search' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "query": "咖啡",
  "user_id": "user_123",
  "enhancements": {
    "skill": {
      "enable": true
    }
  }
}'

响应示例

{
  "request_id": "63c88d63-0bb7-90a6-7edd-281453d4ae37",
  "latency": 1123,
  "status": "OK",
  "result": {
    "memory": {
      "results": [
        {
          "memory_id": "m-60aa2de5-c43e-4b3d-9efd-f058bc3994be",
          "memory": "喜欢喝咖啡",
          "user_id": "user_123"
        }
      ],
      "total": 1
    },
    "skill": {

      "results": [
        {
          "skill_id": "s-817cae3c-337e-434a-97a8-38b4c443683b",
          "name": "统一多端登录失败提示文案",
          "description": "将用户登录失败提示文案统一调整为“登录信息有误，请重试”，并在 Android、iOS、Web 三端保持一致。",
          "version": "0.1.0",
          "user_id": "1"
        }
      ]

    }
  }
}

获取Memory

根据Memory ID获取单条Memory详情。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Path参数

参数

类型

必填

描述

示例值

memory_id

String

是

Memory ID，前缀为m-。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

返回参数

参数

类型

描述

示例值

result.memory_id

String

记忆ID。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

result.memory

String

记忆内容。

喜欢喝咖啡

result.user_id

String

用户ID。

user_123

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/m-60aa2de5-c43e-4b3d-9efd-f058bc3994be' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "f762571f-caf2-40d4-14b3-e8a9dd3c7c65",
  "latency": 347,
  "status": "OK",
  "result": {
    "memory_id": "m-60aa2de5-c43e-4b3d-9efd-f058bc3994be",
    "memory": "喜欢喝咖啡",
    "user_id": "user_123"
  }
}

获取Skill

根据Skill ID获取单条Skill详情。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Path参数

参数

类型

必填

描述

示例值

skill_id

String

是

Skill ID，前缀为s-。

s-817cae3c-337e-434a-97a8-38b4c443683b

返回参数

参数

类型

描述

示例值

result.skill_id

String

Skill ID。

s-817cae3c-337e-434a-97a8-38b4c443683b

result.name

String

Skill名称。

统一多端登录失败提示文案

result.version

String

Skill版本。

0.1.0

result.files

Object

Skill对应的内部文件，格式为"文件路径":"文件内容"。

{"SKILL.md": "---\nid: \"s-817cae3c-337e-434a-97a8-38b4c443683b\"\nname: \"统一多端登录失败提示文案\"\ndescription: \"将用户..."}

result.user_id

String

用户ID。

user_123

result.agent_id

String

Agent ID。

agent_001

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/s-817cae3c-337e-434a-97a8-38b4c443683b' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "ea95f21f-3f76-5efe-caf2-f3ee7692e0de",
  "latency": 85,
  "status": "OK",
  "result": {
    "skill_id": "s-817cae3c-337e-434a-97a8-38b4c443683b",
    "name": "统一多端登录失败提示文案",
    "version": "0.1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-817cae3c-337e-434a-97a8-38b4c443683b\"\nname: \"统一多端登录失败提示文案\"\ndescription: \"将用户..."
    },
    "user_id": "user_123",
    "agent_id": ""
  }
}

更新Memory

根据Memory ID更新已有记忆内容。

请求方式

PUT

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Path参数

参数

类型

必填

描述

示例值

memory_id

String

是

记忆ID。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

Body参数

参数

类型

必填

描述

示例值

memory

String

是

更新后的记忆内容。

喜欢喝美式咖啡

返回参数

参数

类型

描述

示例值

result.memory_id

String

记忆ID。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

result.memory

String

更新后的记忆内容。

喜欢喝美式咖啡

result.message

String

操作结果消息。

Memory updated successfully!

Curl请求示例

curl --location --request PUT 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/memories/m-60aa2de5-c43e-4b3d-9efd-f058bc3994be' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "memory": "喜欢喝美式咖啡"
}'

响应示例

{
  "request_id": "b7aa651b-ade5-e03d-a344-6e5cbfafe9a4",
  "latency": 1011,
  "status": "OK",
  "result": {
    "memory_id": "m-60aa2de5-c43e-4b3d-9efd-f058bc3994be",
    "memory": "喜欢喝美式咖啡",
    "message": "Memory updated successfully!"
  }
}

上传Skill

通过ZIP包方式批量上传Skill到服务。上传过程为异步处理，接口返回任务ID。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills

Body参数

参数

类型

必填

描述

示例值

zip_base64

String

是

ZIP文件的Base64编码内容。

<base64>

user_id

String

是

用户ID。

user_123

agent_id

String

否

Agent ID。

agent_001

返回参数

参数

类型

描述

示例值

result.imported_count

Int

导入成功的Skill数量。

1

result.data

Array

导入的Skill列表。

Curl请求示例

curl -X POST --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "zip_base64": "<base64编码的ZIP文件内容>",
  "user_id": "user_123"
}'

响应示例

{
  "request_id": "4f0f6a7f-d09a-44dd-b2af-995bd41b8acd",
  "latency": 650,
  "status": "OK",
  "result": {
    "imported_count": 1,
    "data": [
      {
        "id": "s-dc33e933-d19d-4e0d-9c8c-e0c3493c4f66",
        "name": "polymarket",
        "description": "Query Polymarket prediction markets - xxx",
        "version": "0.1.0",
        "owner": "3",
        "tags": [],
        "triggers": [],
        "resource_paths": [
          "_meta.json",
          "scripts/polymarket.py"
        ],
        "updated_at": "2026-04-17T07:40:38+00:00"
      }
    ]
  }
}

更新Skill

更新指定Skill的信息，可单独更新一个或多个字段。

请求方式

PUT

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Path参数

参数

类型

必填

描述

示例值

skill_id

String

是

Skill ID。

s-xxxx-xxxx-xxxx

Body参数

参数

类型

必填

描述

示例值

agent_id

String

否

agent id

files

Object

否

skill内容字段，参考获取到的skill字段result.files

name

String

否

skill名字

user_id

String

是

user id

version

String

否

版本

Curl请求示例

curl -X PUT --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-xxxx-xxxx-xxxx' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "version": "1.0",
  "user_id": "001"
}'

响应示例

{
  "request_id": "224c2313-7b70-47f7-8748-8f583d7b9ae1",
  "latency": 284,
  "status": "OK",
  "result": {
    "name": "统一多端登录失败提示文案",
    "version": "1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-817cae3c-337e-434a-97a8-38b4c443683b\"\nname: \"统一多端登录失败提示文案\"\ndescription: xxx"
    }
  }
}

删除Memory

根据Memory ID删除一条Memory。

请求方式

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Path参数

参数

类型

必填

描述

示例值

memory_id

String

是

Memory ID，前缀为m-。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

返回参数

参数

类型

描述

示例值

result.memory_id

String

被删除的Memory ID。

m-60aa2de5-c43e-4b3d-9efd-f058bc3994be

result.status

String

删除状态。

success

result.message

String

操作结果消息。

Memory m-60aa2de5-c43e-4b3d-9efd-f058bc3994be deleted

Curl请求示例

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/m-60aa2de5-c43e-4b3d-9efd-f058bc3994be' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "d17dcf71-57f6-9923-56d3-74dfc9d4d92",
  "latency": 356,
  "status": "OK",
  "result": {
    "memory_id": "m-60aa2de5-c43e-4b3d-9efd-f058bc3994be",
    "status": "success",
    "message": "Memory m-60aa2de5-c43e-4b3d-9efd-f058bc3994be deleted"
  }
}

删除Skill

根据Skill ID删除一条Skill。

请求方式

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Path参数

参数

类型

必填

描述

示例值

skill_id

String

是

Skill ID，前缀为s-。

s-60aa2de5-c43e-4b3d-9efd-f058bc3994be

返回参数

参数

类型

描述

示例值

result.skill_id

String

被删除的Skill ID。

s-60aa2de5-c43e-4b3d-9efd-f058bc3994be

result.status

String

删除状态。

success

result.message

String

操作结果消息。

Skill s-60aa2de5-c43e-4b3d-9efd-f058bc3994be deleted

Curl请求示例

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/s-60aa2de5-c43e-4b3d-9efd-f058bc3994be' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "ddc7a762-7531-4686-90ef-6b8ad42e5a16",
  "latency": 93,
  "status": "OK",
  "result": {
    "skill_id": "s-60aa2de5-c43e-4b3d-9efd-f058bc3994be",
    "status": "success",
    "message": "Skill s-60aa2de5-c43e-4b3d-9efd-f058bc3994be deleted"
  }
}

状态码说明

HTTP状态码

错误码

描述

200

-

请求成功。异步任务的实际处理状态需从result.status中判断。

400

InvalidParameter

请求参数不合法。

401

Unauthorized

未授权访问。

404

NotFound

资源不存在（Memory/Skill/Task等）。

429

RateLimitExceeded

请求频率超过限制。

500

InternalServerError

服务器内部错误。

异常响应示例

{
  "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
  "latency": 0,
  "code": "InvalidParameter",
  "http_code": 400,
  "message": "user_id is required"
}
上一篇：API参考下一篇：文档内容解析