# 搜索记忆 - SearchCoreSpaceMemories #### 功能介绍 该接口用于基于向量相似度搜索指定 Space 中的长期记忆，在需要通过语义检索找到与查询内容最相关的记忆、为 Agent 提供上下文记忆参考时使用。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-agentarts/Permission.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | agentarts:memorySpace:searchCoreSpaceMemories | List | memorySpace \* | g:ResourceTag/\ | - | - | | agentarts:memorySpace:searchCoreSpaceMemories | List | - | - agentarts:MemoryActorId - agentarts:MemorySessionId | - | - | #### URI POST /v1/core/spaces/{space_id}/memories/search 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | space_id | 是 | String | **参数解释：** Space ID是记忆空间的唯一标识，可通过"创建Space"获取。 **约束限制：** 不涉及。 **取值范围：** UUID格式。示例：123e4567-e89b-12d3-a456-426614174001。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 否 | String | **参数解释：** 查询文本（可选，不传时仅按过滤条件检索）。 **约束限制：** 不涉及。 **取值范围：** 长度1-2000字符。 **默认取值：** 不涉及。 | | strategy_type | 否 | String | **参数解释：** 按策略类型过滤，决定记忆的存储和使用方式。 **约束限制：** 不涉及。 **取值范围：** - semantic: 语义记忆，用于存储语义化的信息 - summary: 摘要记忆，用于对话总结 - user_preference: 用户偏好，用于存储用户偏好设置 - episodic: 事件记忆，用于存储特定事件 - procedural: 程序化记忆, 用于存储可复用的多步骤操作流程 **默认取值：** 不涉及。 | | strategy_id | 否 | String | **参数解释：** 按策略实例 ID 过滤，仅返回指定策略实例关联的记录，可通过"ListCoreSpaceMemories"接口获取。 **约束限制：** 不涉及。 **取值范围：** 长度36-36字符。 **默认取值：** 不涉及。 | | actor_id | 否 | String | **参数解释：** 按 Actor ID 过滤，仅返回指定 Actor 关联的记录。Actor ID 用于标识对话参与者。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | assistant_id | 否 | String | **参数解释：** 按 Assistant ID 过滤，仅返回指定 Assistant 关联的记录。Assistant ID 用于标识 AI 助手。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | session_id | 否 | String | **参数解释：** 按 Session ID 过滤，支持逗号分隔多值（如 session_id=uuid1,uuid2），最多 100 个。 **约束限制：** 不涉及。 **取值范围：** 长度1-6500字符。 **默认取值：** 不涉及。 | | memory_type | 否 | String | **参数解释：** 按记忆类型过滤，决定检索的记忆类别。 **约束限制：** 不涉及。 **取值范围：** - memory: 一般记忆，用于存储一般的记忆信息 - episode: 事件记忆，用于存储特定事件 - reflection: 反思记忆，用于存储反思和总结 **默认取值：** 不涉及。 | | start_time | 否 | Long | **参数解释：** 按创建时间过滤的起始时间（毫秒时间戳，包含），用于指定检索的时间范围起点。 **约束限制：** 不涉及。 **取值范围：** 0-253402300799999。 **默认取值：** 不涉及。 | | end_time | 否 | Long | **参数解释：** 按创建时间过滤的结束时间（毫秒时间戳，包含），用于指定检索的时间范围终点。 **约束限制：** 不涉及。 **取值范围：** 0-253402300799999。 **默认取值：** 不涉及。 | | top_k | 否 | Integer | **参数解释：** 返回相似度最高的前 K 个结果，用于控制检索返回数量。 **约束限制：** 不涉及。 **取值范围：** 1-200。 **默认取值：** 10。 | | min_score | 否 | Float | **参数解释：** 最小向量相似度分数阈值（基于 OpenSearch 向量检索分数过滤，Rerank 前生效）。不传时使用服务端配置默认值。 **约束限制：** 不涉及。 **取值范围：** 0.0-1.0。 **默认取值：** 不涉及。 | | only_actived | 否 | Boolean | **参数解释：** 搜索记忆是否只召回active状态的记忆，默认是关闭。 **约束限制：** 不涉及。 **取值范围：** - true: 只会召回 active 状态的记忆 - false: 会召回所有状态的记忆 **默认取值：** false。 | | rerank | 否 | Boolean | **参数解释：** 搜索记忆是否开启重排序，开启会增加API时延。默认开启。 **约束限制：** 不涉及。 **取值范围：** - true: 开启 - false: 关闭 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表3响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | results | Array of [results] objects | **参数解释：** 检索结果（按 Rerank 分数降序）。 **取值范围：** 0-100个。 | | query | String | **参数解释：** 原始查询，搜索时使用的检索文本。 **取值范围：** 长度0-2000字符。 | | total | Integer | **参数解释：** 符合条件的搜索结果总数（单位：条），用于计算总页数。 **取值范围：** 0-2147483647。 | 表4results | 参数 | 参数类型 | 描述 | |:---|:---|:---| | record | [MemoryRecord] object | **参数解释：** 搜索记忆记录结果。 **取值范围：** 0-100个。 | | score | Float | **参数解释：** 相似度分数，表示检索结果与查询的相关程度。 **取值范围：** 0.0-1.0。 | 表5MemoryRecord | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 记忆记录 ID，唯一标识一条记忆记录，可通过"创建记忆"接口获取。 **取值范围：** 长度36-36字符。 | | space_id | String | **参数解释：** 所属 Space ID，标识该记录所属的记忆空间，可通过"创建Space"接口获取。 **取值范围：** 长度36-36字符。 | | strategy_id | String | **参数解释：** 来源策略 ID，标识该记忆记录由哪个策略生成，可通过"查询策略详情"接口获取。 **取值范围：** 长度36-36字符。 | | strategy_type | String | **参数解释：** 策略类型，决定记忆的存储和使用方式。 **取值范围：** - semantic: 语义记忆，用于存储语义化的信息 - summary: 摘要记忆，用于对话总结 - user_preference: 用户偏好，用于存储用户偏好设置 - episodic: 事件记忆，用于存储特定事件 - event: 事件记忆，与episodic相同，用于存储特定事件 - custom: 自定义记忆，用于用户自定义的记忆类型 | | actor_id | String | **参数解释：** 归属 Actor ID，标识该记忆记录所属的 Actor，实现 Actor 级记忆隔离。 **取值范围：** 长度1-64字符。 | | assistant_id | String | **参数解释：** 归属 Assistant ID，标识该记录所属的 AI 助手。 **取值范围：** 长度1-64字符。 | | session_id | String | **参数解释：** 来源会话 ID，标识该记忆记录关联的会话，可通过"创建Session"接口获取，实现 Session 级记忆隔离。 **取值范围：** 长度1-64字符。 | | content | String | **参数解释：** 记忆内容，存储具体的记忆信息文本，如用户偏好、重要事实等。 **取值范围：** 长度1-16000字符。 | | memory_type | String | **参数解释：** 记忆类型，标识该记忆的分类。 **取值范围：** - memory: 一般记忆，用于存储一般的记忆信息 - episode: 事件记忆，用于存储特定事件 - reflection: 反思记忆，用于存储反思和总结 | | isolation_level | String | **参数解释：** 记忆隔离级别，决定记忆的共享范围。 **取值范围：** - actor: Actor 隔离，记忆只能在 Actor 内部共享 - session: Session 隔离，记忆只能在 Session 内部共享 | | created_at | String | **参数解释：** 记录的创建时间，由系统自动生成。 **取值范围：** 格式为 ISO 8601（YYYY-MM-DDTHH:mm:ssZ）。 | | updated_at | String | **参数解释：** 记录的最近更新时间，由系统自动更新。 **取值范围：** 格式为 ISO 8601（YYYY-MM-DDTHH:mm:ssZ）。 | | meta | Object | **参数解释：** 用户自定义元数据。 **取值范围：** 长度0-4096字符。 | **状态码：401** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：403** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表8Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：404** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表10Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：429** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表12Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：500** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | #### 请求示例 ``` /v1/core/spaces/123e4567-e89b-12d3-a456-426614174000/memories/search { "query" : "User's programming language preference", "strategy_type" : "user_preference", "strategy_id" : "123e4567-e89b-12d3-a456-426614174002", "actor_id" : "user-12345", "assistant_id" : "assistant-abc", "session_id" : "789e0123-e89b-12d3-a456-426614174000", "memory_type" : "memory", "start_time" : 1705312980000, "end_time" : 1705399380000, "top_k" : 10, "min_score" : 0.8 } ``` #### 响应示例 **状态码：200** 无 **状态码：401** ``` { "error_code" : "AgentArts.01020002", "error_msg" : "Authentication failed" } ``` **状态码：403** ``` { "error_code" : "AgentArts.01020003", "error_msg" : "Insufficient permissions" } ``` **状态码：404** ``` { "error_code" : "AgentArts.01020005", "error_msg" : "Record not found" } ``` **状态码：429** ``` { "error_code" : "AgentArts.01020008", "error_msg" : "Too many requests" } ``` **状态码：500** ``` { "error_code" : "AgentArts.01020004", "error_msg" : "Internal service error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 搜索成功 | | 401 | 认证失败 | | 403 | 权限不足 | | 404 | Space 不存在 | | 429 | 请求过于频繁 | | 500 | 服务不可用 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。