SearchMemories 检索记忆 - 表格存储

使用 SearchMemories 接口根据查询文本检索结构化记忆和服务生成的记忆文件。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
Scope 规则：appId 必填且不能为 *；其他字段省略时补 __default__，只有显式传入 * 才通配。包含 file 输出的记忆库暂不支持通配 Scope 搜索，请使用精确 Scope，必要时搭配 filter 进一步确认范围。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	目标记忆库名称。
`query`	string	是	查询文本，默认最多 8192 个 Unicode 字符。
`scope`	object	是	基础查询范围。`appId` 必填且不能为 ``；其他字段省略时补 `__default__`，只有显式传入 `` 才通配。
`filter`	object	否	Scope Filter，与 `scope` 按 AND 组合；最终仅搜索匹配的 conversation Scope。结构见通用对象。
`contextScope`	object	否	当前会话的完整精确 Scope，用作软排序信号；必须同时位于 `scope` 范围内并满足 `filter`。
`topK`	int	否	每类结果最多返回数量，默认 10，上限 50。
`enableRerank`	boolean	否	是否对结构化记忆启用 Rerank，默认 `true`。
`includeEvidence`	boolean	否	是否附带结构化记忆对应的短期消息证据，默认 `false`。
`minSimilarity`	float	否	兼容字段，范围 `0~1`，过滤 `score`。新请求建议使用 `thresholds`；两者不能混用。
`thresholds`	object	否	显式结果门槛。内部两个门槛同时设置时采用 AND。
`thresholds.minSimilarity`	float	否	范围 `0~1`，过滤 `similarity`。
`thresholds.minScore`	float	否	范围 `0~1`，过滤 `score`。
`metadata`	object	否	结构化记忆的 Metadata 完整精确匹配条件。最多 16 个键，键最长 64 个 Unicode 字符，值最长 1024 个 Unicode 字符；键和值均为字符串，多个键值对按 AND 组合。

scope 和 filter 解析出的范围最多包含 1000 个唯一 conversation Scope，超过时返回 400 INVALID_PARAMETER。Scope 查询能力暂时不可用时返回 503 SERVICE_UNAVAILABLE。包含 file 输出的记忆库暂不支持通配 Scope 搜索；请使用精确 Scope，必要时搭配 filter 进一步确认范围。

metadata 对完整字符串执行精确匹配，*、?、逗号和等号等字符按普通字符处理，适合检索 UUID、追踪 ID 等长值。超过键数量或键值长度限制时返回 400 INVALID_PARAMETER。通用定义见Metadata。

topK 分别作用于 results 和 fileResults。相关性过滤、去重或可见数据不足时，实际结果数可能少于 topK；应用不应依赖固定数量的返回项。

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

curl -X POST https://<endpoint>/SearchMemories \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "filter": {"op": "eq", "field": "text", "value": "*sess*"},
  "contextScope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "query": "用户喜欢什么饮品",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "thresholds": {
    "minSimilarity": 0.3,
    "minScore": 0.2
  },
  "metadata": {
    "source": "chat"
  }
}'

响应

字段	说明
`results`	结构化记忆结果列表；没有 `structured` 输出时为 `[]`。
`results[].unit`	长期记忆单元，字段定义见下表。
`results[].score`	规范相关性分数（`0~1`），由 `thresholds.minScore` 过滤；兼容字段 `minSimilarity` 也过滤该字段。
`results[].similarity`	查询与记忆的归一化余弦相似度（`0~1`），由 `thresholds.minSimilarity` 过滤。
`results[].rankingScore`	使用 `contextScope` 软排序时可能返回的最终排序分数。
`results[].rankingSignals`	与 `rankingScore` 同时返回的排序解释。
`results[].source`	命中来源，例如 `vector`、`vector+text`。
`fileResults`	记忆文件结果列表；没有 `file` 输出时为 `[]`。
`evidence`	`includeEvidence=true` 时返回的短期消息证据；无可用证据时为 `[]`。
`scope`	查询使用的 Scope。
`memoryStoreName`	记忆库名称。

results 和 fileResults 在所有记忆库中都会返回，因此客户端可以使用同一种响应结构。双输出记忆库最多分别返回 topK 条结构化结果和 topK 条文件结果。

fileResults 的元素字段如下。

字段	说明
`type`	固定为 `memoryfile`。
`itemId`	记忆文件 ID。
`path`	记忆文件路径。
`summary`	文件摘要，也是参与检索的文本。
`versionId`	命中文件版本的 ID。
`versionSeq`	命中文件版本的序号。
`score`	规范相关性分数（`0~1`）。当前文件搜索中与 `similarity` 相同。
`similarity`	文件摘要与查询的归一化余弦相似度（`0~1`）。

双输出记忆库的响应示例：

默认情况下，results 按 score 从高到低排序。仅当响应中包含 rankingScore 时，结果改按 rankingScore 从高到低排序；session 软排序不会改写 score。

results[].unit 内部字段如下。ListMemories、GetMemory 返回的记忆单元字段与此一致。embedding 向量不会在响应中返回。

字段	说明
`id`	长期记忆单元 ID。
`conversation_key`	关联的会话键。
`scope`	记忆所属 Scope，对象包含 `appId`、`tenantId`、`agentId`、`runId` 四个字段。
`memcell_id`	记忆片段 ID。
`unit_type`	记忆单元类型，例如 `atomic_fact`、`entity_fact`、`temporal_anchor`。
`title`	记忆名称，最多 64 个字符；旧数据或字段为空时客户端可回退展示 `text`。
`text`	记忆文本。
`search_text`	用于检索的文本。
`keywords`	关键词列表，最多 8 个，每个最多 32 个字符。
`source_turn_ids`	来源消息 ID 列表。
`type_label`	类型标签。
`date_bucket`	日期分桶。
`metadata`	元数据对象（写入时提供的键值对）。
`metadata_json`	元数据，JSON 字符串。
`metadata_flat`	元数据扁平化字符串，用于过滤。
`deleted`	是否已删除。
`created_at`	创建时间。
`effective_at`	事实、事件或计划所描述的生效时间；可能早于或晚于记忆写入时间。
`updated_at`	记忆单元最近一次服务端更新的时间。
`time_source`	时间来源，例如 `explicit_event`、`source_message`、`legacy_created_at`、`manual`。
`time_precision`	`effective_at` 的原始精度：`second`、`day`、`month`、`year` 或 `unknown`。
`salience`	显著性分数。
`version`	版本号。
`speaker`	记忆涉及的说话人（字段非空时返回）。
`topic`	主题标签（字段非空时返回）。
`entities`	相关实体列表（字段非空时返回）。
`time_anchor`	时间锚点信息（字段非空时返回）。
`source_turn_refs`	来源消息引用列表，元素含 `messageId` 与 `timestampMs`（字段非空时返回）。
`superseded_by` / `supersedes_id`	记忆被合并/更新时的替代链信息（字段非空时返回）。
`dream_id` / `dream_action_id` / `dream_reason` / `dream_source_message_ids` / `dream_source_memory_ids`	由记忆整理（Dream）产生或改写的记忆携带的溯源字段（字段非空时返回）。

提供 contextScope 时，服务可以在语义相关性接近的候选中优先当前会话的记忆。该字段只影响排序，不扩大 scope 和 filter 指定的数据范围，也不能绕过 thresholds 或兼容阈值。

{
    "memoryStoreName": "agent_memory",
    "results": [
        {
            "unit": {
                "id": "1b88d0d65a5b6c0d9142e9b7c7347048",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我写脚本只用 Python。",
                "search_text": "用户编程语言偏好\n我写脚本只用 Python。\nkeywords: Python, 脚本, 编程语言, 偏好\nPython 脚本语言 技术偏好\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "Python",
                    "脚本",
                    "编程语言",
                    "偏好"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "4ec0592b5550159a3f77b9dc62bca64e",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "写脚本只用 Python"
                },
                "metadata_json": "{\"content_hash\":\"4ec0592b5550159a3f77b9dc62bca64e\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"写脚本只用 Python\"}",
                "metadata_flat": "content_hash=4ec0592b5550159a3f77b9dc62bca64e,session_date=5:52 AM on 25 August, 2026,source_quote=写脚本只用 Python",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户编程语言偏好",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.3358759430317645,
            "similarity": 0.2652787210590392,
            "source": "vector"
        },
        {
            "unit": {
                "id": "546b00a31ddd5e76e309e2da5cb0030e",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我常驻杭州。",
                "search_text": "用户常驻地\n我常驻杭州。\nkeywords: 杭州, 常驻, 地理位置\n杭州 常驻地 地理位置\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "杭州",
                    "常驻",
                    "地理位置"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "9f9821b441975f392313a2d7aec6ed6e",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "常驻杭州"
                },
                "metadata_json": "{\"content_hash\":\"9f9821b441975f392313a2d7aec6ed6e\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"常驻杭州\"}",
                "metadata_flat": "content_hash=9f9821b441975f392313a2d7aec6ed6e,session_date=5:52 AM on 25 August, 2026,source_quote=常驻杭州",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户常驻地",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.32277120656532554,
            "similarity": 0.25208147048454044,
            "source": "vector"
        },
        {
            "unit": {
                "id": "4f6ddad33fad6f52d475c69708b44dd1",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我的内部工号是 FALCON-9931。",
                "search_text": "用户内部工号\n我的内部工号是 FALCON-9931。\nkeywords: 工号, FALCON-9931, 内部标识\nFALCON-9931 工号 身份标识\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "工号",
                    "FALCON-9931",
                    "内部标识"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "d0b62aedd9294009f14ed6ab951ebfed",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "我的内部工号是 FALCON-9931"
                },
                "metadata_json": "{\"content_hash\":\"d0b62aedd9294009f14ed6ab951ebfed\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"我的内部工号是 FALCON-9931\"}",
                "metadata_flat": "content_hash=d0b62aedd9294009f14ed6ab951ebfed,session_date=5:52 AM on 25 August, 2026,source_quote=我的内部工号是 FALCON-9931",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户内部工号",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.2805238412257555,
            "similarity": 0.23675615504707195,
            "source": "vector"
        }
    ],
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "*",
        "runId": "*"
    }
}