Tablestore:Memory Dream

How it works

Dream takes data in the memory store as input; the service analyzes it in the background and produces consolidation actions. Based on the consolidation target, tasks fall into three types. Actions from memory tasks are written back to the memory store, whereas actions from skill / profile tasks are produced only as standalone events, are not written to the memory store, and are consumed by the caller as needed.

Depending on how much your business trusts the consolidation results, you can choose one of the following apply modes.

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. Create the consolidation task
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": "Merge duplicate memories and delete outdated items",
    "clientToken": "dream-001",
})
dream_id = resp.get("dreamId")

# 2. Poll the task status until it reaches a terminal state
task = client.get_memory_dream_task({
    "memoryStoreName": "agent_memory",
    "dreamId": dream_id,
})
print(f"status: {task.get('status')}, actions: {task.get('actions')}")

# 3. Review action proposals
actions = client.list_memory_dream_actions({
    "memoryStoreName": "agent_memory",
    "dreamId": dream_id,
    "limit": 100,
}).get("actions", [])

# 4. Apply the selected actions (skip 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",
})

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. Create the consolidation task
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: 'Merge duplicate memories and delete outdated items',
  clientToken: 'dream-001',
});
const dreamId = created.dreamId;

// 2. Poll the task status until it reaches a terminal state
const task = await client.getMemoryDreamTask({
  memoryStoreName: 'agent_memory',
  dreamId,
});
console.log(task.status, task.actions);

// 3. Review action proposals
const { actions } = await client.listMemoryDreamActions({
  memoryStoreName: 'agent_memory',
  dreamId,
  limit: 100,
});

// 4. Apply the selected actions (skip NOOP)
await client.applyMemoryDreamActions({
  memoryStoreName: 'agent_memory',
  dreamId,
  mode: 'actions',
  actionIds: actions.filter((a) => a.action !== 'NOOP').map((a) => a.actionId),
  applier: 'operator-001',
});

Key parameters

The following table lists the key parameters for creating a consolidation task. For the value range of each parameter, see Limitations and notes.

Usage recommendations

• Do not block online request paths while waiting for consolidation results. Consolidation tasks run asynchronously in the background; poll GetMemoryDreamTask to get progress.

• In production, prefer proposal mode and apply only after manual or programmatic confirmation with apply. When you trust the results enough, set reasonable add / update / merge for confidenceThresholds, and enable safe_auto mode.

• For scheduled consolidation, use incremental=true to avoid reprocessing everything each time.

Applicability

Before you use file memory Dream, make sure the memory store meets the following conditions:

• The memory store was created with inputType=file and outputTypes=["file"]. Read-only files generated from messages do not support file Dream.

• The input and output must belong to the same memory store. The input can span scopes, but the output must be a complete four-level scope without wildcards.

• Only UTF-8 text files are consolidated; binary files and the /.wiki/ system path are excluded from consolidation.

• A single task accepts up to 8 scope selectors. Wildcard scopes are expanded by level from the right, and the number of expanded scopes is limited by expandedScopeLimit.

Scenarios suited to file Dream include merging multiple run records of the same agent into a shared handbook, consolidating project conventions from multiple agents, merging duplicate files, or reorganizing directories while preserving source differences.

Quick start

The following example consolidates all run records of two agents into a shared scope.

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. Create the task: read files from multiple input scopes; the consolidated result is automatically written to the single output 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": "Organize project materials by topic and remove duplicate content; when conflicts exist, preserve the applicable scope and the differences.",
    "maxItems": 1000,
    "expandedScopeLimit": 200,
    "clientToken": "project-file-dream-001",
})
dream_id = resp.get("dreamId")

# 2. Poll the task until it reaches a terminal state
task = client.get_memory_dream_task({
    "memoryStoreName": "agent_files",
    "dreamId": dream_id,
})
print(f"status: {task.get('status')}, actions: {task.get('actions')}")

# 3. Check the file changes actually performed by the service
actions = client.list_memory_dream_actions({
    "memoryStoreName": "agent_files",
    "dreamId": dream_id,
    "limit": 100,
}).get("actions", [])

# 4. Read back the result files under the output 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"))

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. Create the task: read files from multiple input scopes; the consolidated result is automatically written to the single output 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: 'Organize project materials by topic and remove duplicate content; when conflicts exist, preserve the applicable scope and the differences.',
  maxItems: 1000,
  expandedScopeLimit: 200,
  clientToken: 'project-file-dream-001',
});
const dreamId = created.dreamId;

// 2. Poll the task until it reaches a terminal state
const task = await client.getMemoryDreamTask({
  memoryStoreName: 'agent_files',
  dreamId,
});
console.log(task.status, task.actions);

// 3. Check the file changes actually performed by the service
const { actions } = await client.listMemoryDreamActions({
  memoryStoreName: 'agent_files',
  dreamId,
  limit: 100,
});

// 4. Read back the result files under the output 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);
}

Limits and considerations

During task execution, every update and delete uses file versions for concurrency protection. When other callers modify the output files at the same time, actions may fail; re-read the current files and then create a new consolidation task.

Cancellation or failure does not roll back file actions that have already been applied. When you handle a non-successful terminal state, first list all actions and read back the output scope, then decide whether to keep, fix, or re-consolidate.