记忆整理（Dream） - 表格存储

记忆整理（Dream）异步分析记忆库中的已有内容，完成归并、去重、纠错和重组。

Dream 支持结构化和文件两种记忆库，任务接口相同，结果应用方式不同。

记忆库	输入	输出方式
结构化记忆库	长期记忆和原始消息	生成提案，或按置信度/已批准计划应用长期记忆动作
可写文件记忆库	一个或多个 Scope 中的文本文件	自动写入一个确定的输出 Scope

结构化记忆 Dream

随着对话不断写入，长期记忆会出现重复、表述不一致、可合并或已过时的情况。结构化记忆 Dream 在后台对已入库的长期记忆和原始消息二次提炼，产出可应用的整理动作，让记忆库长期保持精炼一致。它支持先生成提案再人工确认，以及达到阈值后自动应用两种模式。

工作原理

记忆整理（Dream）以记忆库中的数据为输入，由服务在后台分析并产出整理动作。按整理对象不同，任务分为三种类型。其中 memory 类型任务的动作会回写记忆库；skill / profile 类型任务的动作仅作为独立事件产出，不写入记忆库，由调用方按需消费。

taskType	整理对象	产出动作类型
`memory`（默认）	长期记忆：改写、合并、去重、删除过时项。动作应用后直接更新记忆库。	`ADD` / `UPDATE` / `DELETE` / `MERGE` / `NOOP`
`skill`	从历史交互中提取可复用的技能。动作以事件形式产出，不写入记忆库。	`EMIT_SKILL`
`profile`	沉淀结构化用户画像。动作以事件形式产出，不写入记忆库。	`EMIT_PROFILE`

根据业务对整理结果的信任度，可选择以下应用模式。

applyMode	行为
`proposal`（默认）	整理只生成 `proposed` 状态的动作提案，由调用方通过 `ApplyMemoryDreamActions` 显式应用。
`safe_auto`	达到置信度阈值（`confidenceThresholds`）的动作由服务自动应用，其余仍以提案形式保留。
`plan`	高强度整理先生成包含删除白名单的计划并进入 `awaiting_plan_approval`，经调用方批准后再执行。

说明

applyMode 仅支持 taskType=memory，传 skill / profile 时会返回 400 参数错误。skill / profile 任务的动作（EMIT_SKILL / EMIT_PROFILE）作为事件产出，不写入记忆库，由调用方自行消费处理，无 apply 流程。
effort 控制整理强度：low（默认）执行一次有界分析；high 允许多轮分析。effort=high 的记忆整理必须显式选择 safe_auto 或 plan；applyMode=plan 必须使用 effort=high。

快速开始

结构化记忆 Dream 的完整流程为：创建整理任务 → 轮询任务状态 → 查看动作提案 → 应用动作，应用后可回读长期记忆验证结果。

常见状态流转为：queued → running → planning →（可选 applying）→ completed；plan 模式会在执行前进入 awaiting_plan_approval，其他终态包括 completed_with_failures、failed、cancelled。以下以 proposal 模式为例：

控制台

步骤 1：创建整理任务

登录记忆库，在左侧导航选择 Agentic Task > 记忆整理 Dream。

单击右上角 创建任务，在弹窗中配置以下参数：

表单项	说明	对应参数
任务类型	选择记忆整理。	`taskType=memory`
输入 Scope	待整理的 Scope，可用 `*` 通配覆盖多个层级。	`scopes`
处理深度	标准（一次有界分析）或高强度（多轮分析）。	`effort=low` / `high`
应用模式	仅生成建议（推荐，人工确认后再应用）。	`applyMode=proposal`
输出 Scope 模式	保持原 Scope 或提升 Scope。	`scopeOutputMode=preserve_scope` / `promote_scope`
整理指令	可选，自定义整理要求。	`instructions`

提交后任务异步运行，生成任务 ID（dreamId），状态从 queued 开始流转。
处理深度选择高强度时，应用模式必须为 safe_auto 或 plan（对应 effort=high 的约束）。

步骤 2：查看任务与建议

在 记忆整理 Dream 任务列表中，等待目标任务状态变为已完成（completed），可单击刷新更新状态。
单击该任务进入详情，查看产出的动作列表。每条动作包含：动作类型（ADD / UPDATE / DELETE / MERGE / NOOP）、目标记忆、整理后的新内容、理由（reason）、置信度（confidence）和状态。
proposal 模式下，所有动作初始为待应用（proposed），在应用前不会改动记忆库。

步骤 3：应用动作并验证

在任务详情中勾选要应用的动作（NOOP 表示无需变更，可不勾选）。
单击应用，服务按所选动作更新长期记忆。DELETE 动作删除后不可恢复。
plan 模式下需先批准计划中的删除白名单，再执行。
应用后，在 记忆数据管理 > 长期记忆 回读记忆列表，确认整理结果符合预期。

SDK

依次调用创建任务、轮询状态、查看动作提案、应用动作四个接口。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 1. 创建整理任务
resp = client.create_memory_dream_task({
    "memoryStoreName": "agent_memory",
    "scopes": [{"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"}],
    "taskType": "memory",
    "effort": "low",
    "applyMode": "proposal",
    "instructions": "归并重复的记忆，删除过时项",
    "clientToken": "dream-001",
})
dream_id = resp.get("dreamId")

# 2. 轮询任务状态，直到进入终态
task = client.get_memory_dream_task({
    "memoryStoreName": "agent_memory",
    "dreamId": dream_id,
})
print(f"status: {task.get('status')}, actions: {task.get('actions')}")

# 3. 查看动作提案
actions = client.list_memory_dream_actions({
    "memoryStoreName": "agent_memory",
    "dreamId": dream_id,
    "limit": 100,
}).get("actions", [])

# 4. 应用选定的动作（跳过 NOOP）
client.apply_memory_dream_actions({
    "memoryStoreName": "agent_memory",
    "dreamId": dream_id,
    "mode": "actions",
    "actionIds": [a["actionId"] for a in actions if a["action"] != "NOOP"],
    "applier": "operator-001",
})

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

// 1. 创建整理任务
const created = await client.createMemoryDreamTask({
  memoryStoreName: 'agent_memory',
  scopes: [{ appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' }],
  taskType: 'memory',
  effort: 'low',
  applyMode: 'proposal',
  instructions: '归并重复的记忆，删除过时项',
  clientToken: 'dream-001',
});
const dreamId = created.dreamId;

// 2. 轮询任务状态，直到进入终态
const task = await client.getMemoryDreamTask({
  memoryStoreName: 'agent_memory',
  dreamId,
});
console.log(task.status, task.actions);

// 3. 查看动作提案
const { actions } = await client.listMemoryDreamActions({
  memoryStoreName: 'agent_memory',
  dreamId,
  limit: 100,
});

// 4. 应用选定的动作（跳过 NOOP）
await client.applyMemoryDreamActions({
  memoryStoreName: 'agent_memory',
  dreamId,
  mode: 'actions',
  actionIds: actions.filter((a) => a.action !== 'NOOP').map((a) => a.actionId),
  applier: 'operator-001',
});

关键参数

下表列出创建整理任务时的关键参数。各参数的取值范围详见使用限制。

参数	说明
`scopes`	待整理的 Scope 列表，必填，最多 20 个。
`actionIds`	应用动作时的动作 ID 列表，`ApplyMemoryDreamActions` 必填，不支持空数组；从 `ListMemoryDreamActions` 的返回中获取。
`confidenceThresholds`	自动应用阈值。键为 `add` / `update` / `merge`，值范围 `0~1`。`DELETE` 动作不支持自动阈值，始终以提案形式保留。
`scopeOutputMode`	整理结果归属：`preserve_scope`（默认，保留原 Scope）/ `promote_scope`（上提到更高层级）。
`incremental`	`true` 时从上次成功处理的进度增量整理（适合定时触发）；默认 `false` 全量整理。
`minTimestamp` / `maxTimestamp`	限定整理的消息时间范围。
`maxSessions`	单次整理最多处理的 Session 数上限。
`maxMessages`	单次整理最多处理的 Message 数上限。
`maxMemories`	单次整理最多处理的 Memory 数上限。
`expandedScopeLimit`	Scope 展开后的最大数量上限。
`instructions`	自定义整理指令，最长 4000 字符。

使用建议

在线链路不要阻塞等待整理结果。整理任务为后台异步执行，通过轮询 GetMemoryDreamTask 获取进度。
生产环境优先使用 proposal 模式，人工或程序确认后再 apply；对结果信任度足够时，可对 add / update / merge 设置合理的 confidenceThresholds 阈值，并启用 safe_auto 模式。
定时整理使用 incremental=true，避免每次全量重新处理。

文件记忆 Dream

文件记忆 Dream 对可写文件记忆库中的文本文件进行异步整理。它可以从一个或多个 Scope 读取已有文件，把去重、归纳、纠错和重组后的完整结果自动写入一个确定的输出 Scope。

适用范围

使用文件记忆 Dream 前，请确认记忆库满足以下条件：

创建记忆库时使用 inputType=file 和 outputTypes=["file"]。由消息生成的只读文件不支持文件 Dream。
输入和输出必须属于同一个记忆库。输入可以跨 Scope，输出必须是一个完整、无通配符的四级 Scope。
只整理 UTF-8 文本文件；二进制文件和 /.wiki/ 系统路径不参与整理。
一次任务最多传入 8 个 Scope 选择器。通配 Scope 按层级从右侧展开，展开后的 Scope 数量受 expandedScopeLimit 限制。

适合使用文件 Dream 的场景包括：把同一 Agent 的多次运行记录归并为共享手册、汇总多个 Agent 的项目约定、合并重复文件，或在保留来源差异的前提下重新组织目录。

快速开始

以下示例将两个 Agent 的全部运行记录整理到共享 Scope。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

output_scope = {
    "appId": "project-app",
    "tenantId": "team-a",
    "agentId": "shared-agent",
    "runId": "knowledge",
}

# 1. 创建任务：从多个输入 Scope 读取文件，整理结果自动写入唯一输出 Scope
resp = client.create_memory_dream_task({
    "memoryStoreName": "agent_files",
    "scopes": [
        {"appId": "project-app", "tenantId": "team-a", "agentId": "research-agent", "runId": "*"},
        {"appId": "project-app", "tenantId": "team-a", "agentId": "coding-agent", "runId": "*"},
    ],
    "outputScope": output_scope,
    "instructions": "按主题整理项目资料，删除重复内容；存在冲突时保留适用范围和分歧。",
    "maxItems": 1000,
    "expandedScopeLimit": 200,
    "clientToken": "project-file-dream-001",
})
dream_id = resp.get("dreamId")

# 2. 轮询任务，直到进入终态
task = client.get_memory_dream_task({
    "memoryStoreName": "agent_files",
    "dreamId": dream_id,
})
print(f"status: {task.get('status')}, actions: {task.get('actions')}")

# 3. 核对服务实际执行的文件变更
actions = client.list_memory_dream_actions({
    "memoryStoreName": "agent_files",
    "dreamId": dream_id,
    "limit": 100,
}).get("actions", [])

# 4. 回读输出 Scope 下的结果文件
items = client.list_items({
    "memoryStoreName": "agent_files",
    "scope": output_scope,
    "limit": 100,
}).get("items", [])
for it in items:
    doc = client.get_item({
        "memoryStoreName": "agent_files",
        "scope": output_scope,
        "path": it["path"],
    })
    print(doc.get("path"), doc.get("content"))

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const outputScope = {
  appId: 'project-app',
  tenantId: 'team-a',
  agentId: 'shared-agent',
  runId: 'knowledge',
};

// 1. 创建任务：从多个输入 Scope 读取文件，整理结果自动写入唯一输出 Scope
const created = await client.createMemoryDreamTask({
  memoryStoreName: 'agent_files',
  scopes: [
    { appId: 'project-app', tenantId: 'team-a', agentId: 'research-agent', runId: '*' },
    { appId: 'project-app', tenantId: 'team-a', agentId: 'coding-agent', runId: '*' },
  ],
  outputScope,
  instructions: '按主题整理项目资料，删除重复内容；存在冲突时保留适用范围和分歧。',
  maxItems: 1000,
  expandedScopeLimit: 200,
  clientToken: 'project-file-dream-001',
});
const dreamId = created.dreamId;

// 2. 轮询任务，直到进入终态
const task = await client.getMemoryDreamTask({
  memoryStoreName: 'agent_files',
  dreamId,
});
console.log(task.status, task.actions);

// 3. 核对服务实际执行的文件变更
const { actions } = await client.listMemoryDreamActions({
  memoryStoreName: 'agent_files',
  dreamId,
  limit: 100,
});

// 4. 回读输出 Scope 下的结果文件
const { items } = await client.listItems({
  memoryStoreName: 'agent_files',
  scope: outputScope,
  limit: 100,
});
for (const it of items) {
  const doc = await client.getItem({
    memoryStoreName: 'agent_files',
    scope: outputScope,
    path: it.path,
  });
  console.log(doc.path, doc.content);
}

文件 Dream 的 taskType 固定为 memory（可省略），effort 固定为 high、applyMode 固定为 auto（均可省略）。不要传入消息时间窗口、incremental、scopeOutputMode、confidenceThresholds、maxSessions、maxMessages 或 maxMemories。同一业务请求重试时复用同一个 clientToken，避免创建重复任务。
get_memory_dream_task 会回显输入选择器、实际展开的 Scope、输出 Scope 和冻结的文件数量。终态包括 completed、completed_with_failures、failed、cancelled；只有 completed 且动作失败数为 0 时才算完整成功。
文件动作使用 ADD、UPDATE、DELETE；改名表现为带新 path 的 UPDATE。itemChange.sourceVersionIds 记录整理依据的文件版本，成功写入时返回 resultItemId 和 resultVersionId。若 list_memory_dream_actions 返回 nextToken，继续翻页直到为空。
文件动作在任务执行期间自动应用，无需人工确认。不要只根据任务状态或动作数量判断整理质量，应回读输出目录、正文、版本和来源是否符合业务要求。

限制与注意事项

项目	限制或行为
输入 Scope 选择器	1～8 个
输出 Scope	一个完整四级 Scope，不允许通配符
`expandedScopeLimit`	默认 200，最大 1000
`maxItems`	默认 1000，最大 5000；包含去重后的输入文件和输出 Scope 已有文件
`instructions`	最大 4000 字节（UTF-8）
文件类型	仅 UTF-8 文本文件，单文件最大 100 KiB
系统路径	不读取或写入 `/.wiki/`
应用方式	自动写入，不支持 `proposal`、`safe_auto`、`plan` 或人工 Apply

任务执行期间，每次更新和删除都使用文件版本进行并发保护。其他调用方同时修改输出文件时，动作可能失败；重新读取当前文件后再创建新的整理任务。

取消或失败不会撤销已经应用的文件动作。处理非成功终态时，应先列出全部动作并回读输出 Scope，再决定保留、修复或重新整理。