Common objects - Tablestore - Alibaba Cloud Documentation Center

Scope

Scope indicates the ownership hierarchy of memory data and consists of four fields.

Field	Type	Description
`appId`	string	Application identifier.
`tenantId`	string	Tenant or user identifier.
`agentId`	string	Agent identifier.
`runId`	string	Session, run, or task identifier.

Different APIs have different rules for required Scope fields and wildcard * support.

Scenario	Scope rule
Write (`AddMemories`)	`appId` is required; omitted fields are filled with `__default__`; `*` is not allowed.
Search (`SearchMemories`)	`appId` is required and cannot be ``; omitted fields are filled with `__default__`, and only an explicit `` acts as a wildcard.
Query short-term messages (`ListMemoryStoreMessages`)	All four fields are required; `*` is not allowed.
Get, update, or delete a single long-term memory	`scope` is optional; when provided, all four fields are required and `*` is not allowed.
Exact file operations	All four fields are required; `*` is not allowed. Service-generated read-only files only support exact Scope.
List and range operations on application management files	`appId` and `tenantId` are required; `agentId` and `runId` support hierarchical use of `*`.
Batch delete file versions (DeleteItemVersions)	`appId` and `tenantId` must be specific values; a wildcard is required, and explicitly specifying `runId=""` is recommended; `agentId` can be a specific value or ``; exact Scope or cross-tenant deletion is not supported.
`ListMemoryStoreScopes`	`scope` is optional and supports hierarchical use of `*`; a structured `filter` can also be used.
Other list queries	Scope can be specified by hierarchy; omitted fields are treated as `__default__` and support hierarchical use of `*`.

Once a level uses *, subsequent levels must also use * or be omitted. For example, app-001/user-001/*/* is valid, while app-001/*/assistant/* is invalid.

{
  "appId": "app-001",
  "tenantId": "user-001",
  "agentId": "assistant",
  "runId": "session-001"
}

Agent Scope

Wiki uses a three-segment Agent Scope that contains only appId, tenantId, and agentId. All three fields are required, with a maximum length of 128 bytes each, and cannot contain / or use *. Wiki requests cannot include runId.

Each Agent Scope has only one Wiki in a memory store, and sessions with different runId values share that Wiki.

Scope Filter

SearchMemories, ListMemories, and ListMemoryStoreScopes support using filter to perform structured filtering on Scope. When both scope and filter are provided, they take effect together with an AND relationship. filter only matches Scope and does not match memory body text or Metadata.

`op`	Field	Description
`and`, `or`	`conditions`	`conditions` is one or more sub-conditions.
`not`	`condition`	`condition` is a single sub-condition. A `conditions` form containing only one element is also supported.
`eq`	`field`, `value`	Exact string match. The virtual field `text` also uses this operator.
`in`	`field`, `values`	Matches any value in a string array; `values` must not be empty.
`exists`	`field`	Matches Scope that contains this field.

Filterable fields include scopeType, scopeKey, appId, tenantId, agentId, runId, wikiId, and the virtual field text. conversation Scope uses agentId and runId, while Wiki Scope uses wikiId. Regular fields only support exact matching; prefix, wildcard, and range operators are not supported.

text performs short-segment matching against field values in Scope and only supports op: "eq". Its value can use * to match a character sequence of any length, and ? to match a single Unicode character, for example *abc*. The pattern cannot be empty and can be up to 32 Unicode characters long; the total number of characters other than * cannot exceed 4.

{
  "op": "and",
  "conditions": [
    { "op": "eq", "field": "appId", "value": "app-001" },
    { "op": "eq", "field": "text", "value": "*abc*" }
  ]
}

filter can be nested up to 8 levels and contain up to 64 leaf conditions. Paginated requests must keep scope and filter unchanged; the same nextToken cannot be used for other query conditions.

filter depends on the Scope query capability of the target memory store. Some existing memory stores do not support filter or the text virtual field. When INVALID_PARAMETER is returned, use exact or wildcard Scope instead; when SERVICE_UNAVAILABLE is returned, retry with backoff first, and if the text condition remains unavailable, use eq, in, or exists conditions on regular fields instead.

Message

The messages field of the AddMemories API uses the following structure.

Field	Type	Required	Description
`role`	string	Yes	Message role, for example `user`, `assistant`, `system`.
`content`	string	Yes	Message content.
`messageId`	string	No	Message ID, up to 256 characters.
`timestamp`	string	No	RFC3339 formatted time.
`metadata`	object	No	Message-level metadata; both keys and values are strings.

Metadata

Metadata consists of string key-value pairs used to attach business tags. In SearchMemories, Metadata is used for exact full-string matching and filtering; when multiple key-value pairs are provided, results must match all conditions simultaneously. Characters such as *, ?, comma, and equals sign are treated as ordinary characters and do not represent wildcards.

Limit	Value
Maximum number of keys in a single Metadata object	16
Maximum key length	64 Unicode characters
Maximum JSON size of a single Metadata object	65536 bytes (UTF-8, 64 KiB)

The top-level metadata of AddMemories, and the message-level Metadata obtained by merging the top-level metadata with each message's metadata, must each satisfy the preceding limits. A single written value has no separate 1024-character limit; however, each query value in SearchMemories.metadata can be up to 1024 Unicode characters. Stored values exceeding this length can be read but cannot be used as Metadata query conditions.

{
  "source": "chat",
  "topic": "preference"
}

Memory stores whose outputTypes include structured support the preceding full exact matching, which is suitable for retrieving long values such as UUIDs and trace IDs.