Search Memory-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Returns the most relevant historical memories based on semantic search

Performs a similarity search based on conversation messages and returns relevant memory nodes.

Method and endpoint

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes/search

Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Parameter	Type	Required	Description
`messages`	array	Yes	Conversation messages used as the query
`messages[].role`	string	No	Message role
`messages[].content`	string / array	No	Message content as a text string or multimodal content array
`messages[].content[].type`	string	No	Content type: `text` or `image_url`. Images are parsed only for projects that support multimodal input
`messages[].content[].text`	string	Conditionally required	Text content. Required when `type` is `text`
`messages[].content[].image_url`	object	Conditionally required	Image information. Required when `type` is `image_url`
`messages[].content[].image_url.url`	string	Conditionally required	Image URL
`user_id`	string	Yes	Sub-user ID used to isolate memories
`memory_library_id`	string	No	Memory library ID
`project_id`	string	No	Project ID used for secondary isolation. Mutually exclusive with `project_ids`
`project_ids`	array[string]	No	Multiple project IDs. Mutually exclusive with `project_id`
`top_k`	integer	No	Maximum number of results. Default: `10`
`min_score`	number	No	Minimum score threshold. Results below this score are filtered out. Default: `0.3`. Effective only when `plan_version` is `pro`
`memory_types`	array[string]	No	Memory type filter. Valid values: `observation` and `skill`. Default: `["observation"]`
`plan_version`	string	No	Billing plan: `pro` or `lite`. Default: `pro`. The value is case-insensitive; other values cause an error

NoteThe pro plan supports filtering results by min_score. The lite plan does not use this parameter. See Billing.

Response

Field	Type	Description
`request_id`	string	Request ID
`plan_version`	string	Billing plan used for this search: `pro` or `lite`
`memory_nodes`	array	Memory nodes
`memory_nodes[].memory_node_id`	string	Memory node ID
`memory_nodes[].content`	string	Memory content
`memory_nodes[].timestamp`	integer	Time associated with the memory
`memory_nodes[].created_at`	integer	Creation time
`memory_nodes[].updated_at`	integer	Update time
`memory_nodes[].media_desc`	string	Multimodal content description
`memory_nodes[].meta_data`	object	Custom metadata
`memory_nodes[].memory_type`	string	Memory type
`memory_nodes[].status`	string	Memory status
`memory_nodes[].score`	number	Search score
`memory_nodes[].project_id`	string	Project ID. Returned when present
`memory_nodes[].multimodal_medias`	array	Multimodal resources. Returned when present

Request example

cURL

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/memory_nodes/search' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "user_001",
    "memory_library_id": "memory_library_001",
    "project_ids": ["project_001"],
    "messages": [
      {"role": "user", "content": "What do I have scheduled for 11 AM tomorrow?"}
    ],
    "top_k": 10,
    "min_score": 0.3,
    "memory_types": ["observation"],
    "plan_version": "pro"
  }'

Python

from agentscope_runtime.tools.modelstudio_memory import (
    SearchMemory, SearchMemoryInput, Message,
)
import asyncio

async def main():
    search_memory = SearchMemory()
    try:
        result = await search_memory.arun(SearchMemoryInput(
            user_id="user_001",
            messages=[Message(role="user", content="What do I need to do?")],
            top_k=10,
            min_score=0.6
        ))
        for node in result.memory_nodes:
            print(f"Memory: {node.content}")
    finally:
        await search_memory.close()

asyncio.run(main())

Response example

{
  "request_id": "416f3d78-2bba-9852-ac15-4b3bcee6c7e4",
  "plan_version": "pro",
  "memory_nodes": [
    {
      "memory_node_id": "cafff28fd3a44c04ac5a65d1ea0858b7",
      "content": "The user needs a reminder to order takeout at 11 AM tomorrow",
      "timestamp": 1783267200,
      "created_at": 1783254720,
      "updated_at": 1783254720,
      "media_desc": "",
      "meta_data": {"location_name": "Beijing"},
      "memory_type": "observation",
      "status": "valid",
      "score": 0.651,
      "project_id": "project_001",
      "multimodal_medias": []
    }
  ]
}

ImportantTo view a paginated memory list, use List Memory.