记忆存储服务限制与配额：文件记忆、Scope、SDK 与 CLI 版本 - 表格存储

服务范围与资源限制

地域

当前仅在华北 2（北京）地域提供服务。

记忆库限制

项目	限制
记忆库名称字符	只能包含字母、数字和下划线
记忆库名称长度	最长 32 个字符
记忆库描述长度	最长 1024 字节（UTF-8）
`extractInstructions`（自定义抽取指令）长度	最长 4096 个字符

创建记忆库后，待索引初始化完成再执行写入和检索操作。

extractInstructions 是记忆库级别的自定义记忆抽取指令，会注入抽取提示词，影响该库后续写入时的长期记忆抽取行为。可在 CreateMemoryStore 创建时设置，或通过 UpdateMemoryStore 修改（传空字符串清除，不传该字段保持不变）。

记忆操作限制

Scope 规则

操作	Scope 要求	是否允许 `*`
写入记忆	`appId` 必填，其他层级为空时自动补 `__default__`	否
检索长期记忆	`appId`、`tenantId` 必填	`agentId`、`runId` 可用
查询短期记忆	四级 Scope 全部必填	否
获取单条长期记忆	四级 Scope 全部必填	否
更新单条长期记忆	四级 Scope 全部必填	否
删除单条长期记忆	四级 Scope 全部必填	否
列出长期记忆	可按层级指定 Scope	是
列出 Scope（`ListMemoryStoreScopes`）	可按层级指定 Scope	是
查询抽取任务（`ListMemoryTasks`）	可按层级指定 Scope	是
查询请求审计	可按层级指定 Scope	是

通配符必须按层级使用。一旦某一层级使用 *，后续层级也必须使用 * 或留空。例如 app-001/user-001/*/* 是有效范围，app-001/*/agent-001/* 不是有效范围。

文件记忆与文件视图限制

项目	限制或行为
Scope	`appId`、`tenantId`、`agentId`、`runId` 四段全部必填，不支持通配符 `*`
文件路径	规范路径以 `/` 开头，最长 800 个 UTF-8 字节；不能是根目录，不能包含空路径段、`.`、`..` 或 NUL 字符
文件内容	仅支持有效 UTF-8 文本
单文件大小	最大 100 KiB（102400 字节）
单 Scope 当前文件数	默认最多 2000 个
文件列表分页	`limit` 默认 `100`，最大 `500`
并发写入	`expectedSha256` 可选；存在多个写入方时建议传入最近一次读取到的摘要
历史版本脱敏	不可逆；仅清除选中历史版本，不修改当前文件
文件视图	只读；通过 SDK 或 CLI 等结构化接口维护记忆

文件内容、路径和数量超过限制时，分别返回 PAYLOAD_TOO_LARGE、VALIDATION_ERROR 或 QUOTA_EXCEEDED。并发摘要不匹配返回 SHA_MISMATCH，应用应重新读取最新文件后再决定是否重试。

写入记忆限制

项目	限制
`messages` 数量	最多 20 条
`messages` 总内容长度	最长 32000 字节（UTF-8）
`text` 长度	最长 32000 字节（UTF-8）
`messageId` 长度	最长 256 个字符
`metadata` 键数量	最多 16 个
`metadata` 键长度	最长 64 个字符
`metadata` 值长度	最长 1024 个字符

messages 和 text 至少提供其中一个。写入记忆时 Scope 不允许使用通配符 *。

异步写入可见性

AddMemories.sync 默认值为 false，即异步写入。异步写入的可见性如下：

原始消息先写入，可立即作为短期记忆查询。
长期记忆抽取在后台执行。
长期记忆抽取和索引刷新完成后，可通过 SearchMemories 召回。

需要在测试场景写入后立即查看抽取结果时，将 sync 设置为 true。同步写入完成后，长期记忆检索仍存在短暂的索引刷新延迟。也可通过 GetMemoryTask（传入 AddMemories 返回的 requestId）查询异步抽取任务的状态与抽取出的记忆单元 ID。

检索记忆默认值

参数	默认值	说明
`topK`	`10`	最多返回数量，默认 10，上限 50；相关性过滤或语义去重后结果可能少于 topK
`enableRerank`	`true`	是否启用 Rerank
`includeEvidence`	`false`	是否在结果中附带短期记忆源证据（`evidence` 字段）
`minSimilarity`	`0`	相关性过滤阈值，取值范围 `0~1`；`0` 表示不过滤，大于 `0` 时过滤掉相关性得分低于该值的结果（启用 Rerank 时为 Rerank 相关性得分，未启用 Rerank 时为归一化余弦相似度）

检索长期记忆时，appId 和 tenantId 必填；agentId 和 runId 可使用通配符 *。

短期记忆查询

ListMemoryStoreMessages 用于查询原始会话消息，要求 appId、tenantId、agentId 和 runId 四级 Scope 全部填写，不支持通配符。

适用场景：

查看原始会话消息。
回放指定会话。
排查长期记忆抽取问题。

记忆整理（Dream）限制

记忆整理（Dream）是对已写入记忆进行二次提炼、归并与技能/画像提取的异步任务。相关接口为 CreateMemoryDreamTask、GetMemoryDreamTask、ListMemoryDreamTasks、ListMemoryDreamActions、ApplyMemoryDreamActions、CancelMemoryDreamTask。

创建记忆整理任务限制

项目	限制
`scopes` 数量	必填，最多 20 个
`maxSessions`	`0~100`
`maxMessages`	`0~20000`
`maxMemories`	`0~5000`
`expandedScopeLimit`	`0~1000`
`instructions` 长度	最长 4000 字节（UTF-8）
`actionIds`（`ApplyMemoryDreamActions`）	单次最多 100 个

枚举取值

字段	取值
`taskType`	`memory`（默认）/ `skill` / `profile`
`applyMode`	`proposal`（默认）/ `safe_auto`，仅 `taskType`=`memory` 支持
`scopeOutputMode`	`preserve_scope`（默认）/ `promote_scope`
`confidenceThresholds` 键	`add` / `update` / `merge`，值取值范围 `0~1`；`DELETE` 不支持自动置信度阈值
任务状态（task `status`）	`queued` / `running` / `planning` / `applying` / `completed` / `completed_with_failures` / `failed` / `cancelled`
动作类型（`action`）	`ADD` / `UPDATE` / `DELETE` / `MERGE` / `NOOP` / `EMIT_SKILL` / `EMIT_PROFILE`
动作状态（action `status`）	`proposed` / `applied` / `skipped` / `failed`

applyMode=proposal 时，整理产生的动作以 proposed 状态生成，需调用 ApplyMemoryDreamActions 显式应用；safe_auto 时，达到置信度阈值的安全动作由服务自动应用。EMIT_SKILL / EMIT_PROFILE 动作由整理任务直接写入，没有手动 apply 流程。

异步任务与列表分页

接口	默认 limit	最大 limit
`ListMemoryTasks`	50	100
`ListMemoryStoreScopes`	100	100
`ListMemoryDreamTasks`	50	100
`ListMemoryDreamActions`	100	100

抽取任务状态（ListMemoryTasks.status / GetMemoryTask 返回的 task.status）取值：queued / running / completed / failed / needs_reconcile。

GetMemoryTask 和 ListMemoryTasks 依赖任务索引。首次写入后，服务端需要一定时间建立任务索引。在此期间，调用上述接口可能返回 409 CONFLICT（ingest task index is still building, please retry shortly）。请稍后重试。

CLI、SDK 与插件

CLI 分页行为

CLI 的记忆类列表命令仅返回单页结果，不会自动翻页。需要继续读取下一页时，使用响应中的 nextToken。

示例：

tablestore-agent-cli memory list-units \
  --store agent_memory \
  --app-id app-001 \
  --next-token <token>

CLI 自动创建实例

未配置 ots_endpoint 和 ots_instance_name 时，CLI 在执行 doctor 命令或实际操作时会自动在华北 2（北京）地域创建并复用托管 Tablestore 实例。自动创建需要一定时间，创建结果会写入本地配置文件。

后续手动设置实例 Endpoint 和实例名称时，CLI 使用显式配置的实例。

SDK 与 CLI 版本

SDK 或工具	版本要求
Python SDK	`tablestore >= 6.4.7`（`6.4.5` 起支持基础记忆接口，`6.4.7` 起支持任务与记忆整理接口）
Node.js SDK	`tablestore >= 5.6.5`
Agent Storage SDK（Python）	`tablestore-agent-storage >= 1.0.10`
Agent Storage SDK（TypeScript）	`@tablestore/agent-storage >= 0.0.11`
Agent Storage SDK（Go）	`github.com/aliyun/tablestore-agent-storage-sdk/go`
CLI	`@tablestore/tablestore-agent-cli >= 0.2.5`

Agent 插件说明

Hermes 和 OpenClaw 插件在检索时默认使用当前租户下的跨 Agent、跨会话范围，即 agentId=*、runId=*。如果业务不允许跨 Agent 或跨会话共享记忆，通过 SDK 自行控制检索 Scope，或调整插件配置。

滚动升级与回滚限制

以下三个开关默认关闭且相互独立：

memory_unit_v2_write_enabled=false：不生成或接受 V2 写字段。
memory_unit_v2_projection_enabled=false：保持旧文件投影字节格式。
search_session_affinity_mode=off：保持旧单 lane 检索与响应字段。

上线顺序必须为 server-first：先让所有副本升级到能读取 V2 列、识别 contextScope 和新响应字段的版本，并保持开关关闭；确认旧副本全部退出后，客户端才能开始发送 contextScope，再依次使用 shadow、on。旧服务端采用严格未知字段校验，混合版本期间提前发送 contextScope 会返回 400。

混合版本集群不得启用 V2 写入或 V2 文件投影。只要已经写入任何 V2 行，就不得直接回滚到不认识 V2 列的旧解析器/写入器，否则旧版本的整行写可能覆盖或丢失新字段。需要回滚业务行为时，应先回到“能读取 V2、但所有新开关关闭”的兼容版本，而不是回到 V2 之前的二进制。