SearchMemories Search Memories - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

An AgentStorage instance has been created and its status is normal, and you have obtained the instance endpoint and instance name.
An API Key has been created.
Scope rules: appId is required and cannot be *; other fields default to __default__ when omitted, and only match all values when * is explicitly passed. Memory stores that include file output do not yet support wildcard Scope search; use exact Scopes and, when necessary, combine with filter to further narrow the range.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the target memory store.
`query`	string	Yes	The query text, up to 8192 Unicode characters by default.
`scope`	object	Yes	The base query scope. `appId` is required and cannot be ``; other fields default to `__default__` when omitted, and only match all values when `` is explicitly passed.
`filter`	object	No	A Scope Filter combined with `scope` using AND logic; the final search covers only matching conversation Scopes. For the structure, see [Common objects](../common-objects.md#scope-filter).
`contextScope`	object	No	The exact full Scope of the current conversation, used as a soft ranking signal; it must fall within the `scope` range and satisfy the `filter`.
`topK`	int	No	The maximum number of results returned per category, default 10, upper limit 50.
`enableRerank`	boolean	No	Whether to enable Rerank for structured memories, default `true`.
`includeEvidence`	boolean	No	Whether to include the corresponding short-term message evidence for structured memories, default `false`.
`minSimilarity`	float	No	Compatibility field, range `0~1`, filters `score`. New requests should use `thresholds`; the two cannot be used together.
`thresholds`	object	No	Explicit result thresholds. When both internal thresholds are set, AND logic applies.
`thresholds.minSimilarity`	float	No	Range `0~1`, filters `similarity`.
`thresholds.minScore`	float	No	Range `0~1`, filters `score`.
`metadata`	object	No	Exact match conditions for the Metadata of structured memories. At most 16 keys, each key up to 64 Unicode characters and each value up to 1024 Unicode characters; both keys and values are strings, and multiple key-value pairs are combined with AND logic.

scope and filter can resolve to at most 1000 unique conversation Scopes; when exceeded, 400 INVALID_PARAMETER is returned. When Scope query is temporarily unavailable, 503 SERVICE_UNAVAILABLE is returned. Memory stores that include file output do not yet support wildcard Scope search; use exact Scopes and, when necessary, combine with filter to further narrow the range.

metadata performs exact matching on the full string; characters such as *, ?, commas, and equals signs are treated as ordinary characters, making it suitable for retrieving long values such as UUIDs and trace IDs. When the key count or key-value length limits are exceeded, 400 INVALID_PARAMETER is returned. For the general definition, see [Metadata](../common-objects.md#metadata).

topK applies separately to results and fileResults. Due to relevance filtering, deduplication, or insufficient visible data, the actual number of results may be less than topK; applications should not rely on a fixed number of returned items.

Request example

When using API Key authentication, pass the instance name and API Key through the x-ots-instancename and x-ots-apikey request headers.

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

Response

Field	Description
`results`	The list of structured memory results; `[]` when there is no `structured` output.
`results[].unit`	The long-term memory unit; see the table below for field definitions.
`results[].score`	The normalized relevance score (`0~1`), filtered by `thresholds.minScore`; the compatibility field `minSimilarity` also filters this field.
`results[].similarity`	The normalized cosine similarity between the query and the memory (`0~1`), filtered by `thresholds.minSimilarity`.
`results[].rankingScore`	The final ranking score that may be returned when `contextScope` soft ranking is used.
`results[].rankingSignals`	The ranking explanation returned alongside `rankingScore`.
`results[].source`	The hit source, for example `vector`, `vector+text`.
`fileResults`	The list of memory file results; `[]` when there is no `file` output.
`evidence`	The short-term message evidence returned when `includeEvidence=true`; `[]` when no evidence is available.
`scope`	The Scope used for the query.
`memoryStoreName`	The memory store name.

results and fileResults are returned for all memory stores, so clients can use the same response structure. Dual-output memory stores return at most topK structured results and topK file results, respectively.

fileResults elements have the following fields.

Field	Description
`type`	Fixed as `memoryfile`.
`itemId`	The memory file ID.
`path`	The memory file path.
`summary`	The file summary, which is also the text that participates in retrieval.
`versionId`	The ID of the matched file version.
`versionSeq`	The sequence number of the matched file version.
`score`	The normalized relevance score (`0~1`). In the current file search, this is the same as `similarity`.
`similarity`	The normalized cosine similarity between the file summary and the query (`0~1`).

Response example for a dual-output memory store:

By default, results are sorted by score in descending order. Only when the response includes rankingScore are the results re-sorted by rankingScore in descending order; session soft ranking does not overwrite score.

results[].unit has the following internal fields. The memory unit fields returned by ListMemories and GetMemory are consistent with these. embedding vectors are not returned in the response.

Field	Description
`id`	The long-term memory unit ID.
`conversation_key`	The associated conversation key.
`scope`	The Scope to which the memory belongs; the object contains four fields: `appId`, `tenantId`, `agentId`, and `runId`.
`memcell_id`	The memory fragment ID.
`unit_type`	The memory unit type, for example `atomic_fact`, `entity_fact`, `temporal_anchor`.
`title`	The memory name, up to 64 characters; for legacy data or when the field is empty, clients can fall back to displaying `text`.
`text`	The memory text.
`search_text`	The text used for retrieval.
`keywords`	The keyword list, up to 8 keywords, each up to 32 characters.
`source_turn_ids`	The list of source message IDs.
`type_label`	The type label.
`date_bucket`	The date bucket.
`metadata`	The metadata object (key-value pairs provided at write time).
`metadata_json`	The metadata as a JSON string.
`metadata_flat`	The flattened metadata string, used for filtering.
`deleted`	Whether it has been deleted.
`created_at`	The creation time.
`effective_at`	The effective time of the fact, event, or plan described; it may be earlier or later than the memory write time.
`updated_at`	The time of the most recent server-side update to the memory unit.
`time_source`	The time source, for example `explicit_event`, `source_message`, `legacy_created_at`, `manual`.
`time_precision`	The original precision of `effective_at`: `second`, `day`, `month`, `year`, or `unknown`.
`salience`	The salience score.
`version`	The version number.
`speaker`	The speaker involved in the memory (returned when the field is non-empty).
`topic`	The topic label (returned when the field is non-empty).
`entities`	The list of related entities (returned when the field is non-empty).
`time_anchor`	Time anchor information (returned when the field is non-empty).
`source_turn_refs`	The list of source message references; each element contains `messageId` and `timestampMs` (returned when the field is non-empty).
`superseded_by` / `supersedes_id`	The replacement chain information when the memory is merged or updated (returned when the field is non-empty).
`dream_id` / `dream_action_id` / `dream_reason` / `dream_source_message_ids` / `dream_source_memory_ids`	Provenance fields carried by memories produced or rewritten by memory consolidation (Dream) (returned when the field is non-empty).

When contextScope is provided, the service can prioritize memories from the current conversation among candidates with similar semantic relevance. This field only affects ranking and does not expand the data range specified by scope and filter, nor can it bypass thresholds or compatibility 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": "*"
    }
}