Tablestore:Memory Dream

Como funciona

O Memory Dream usa os dados do repositório de memória como entrada. O service analisa os dados em segundo plano e produz ações de consolidação. As tarefas dividem-se em três tipos com base em seus alvos de consolidação. O sistema grava as ações das tarefas memory de volta no repositório de memória. O sistema produz as ações das tarefas skill e profile apenas como eventos independentes; elas não são gravadas no repositório de memória e o chamador as consome conforme necessário.

Escolha um modo de aplicação com base no nível de confiança nos resultados da consolidação.

As seguintes regras aplicam-se a applyMode e effort:

• Restrição de tipo de tarefa — O applyMode aceita apenas taskType=memory. A inclusão de skill ou profile resulta em erro de parâmetro 400. O sistema gera as ações das tarefas skill e profile (EMIT_SKILL e EMIT_PROFILE) como eventos, não as grava no repositório de memória, e o chamador as consome e trata. Não há fluxo apply disponível.

• Intensidade de consolidação — O effort controla a intensidade da consolidação. O valor low (padrão) realiza uma única análise delimitada, enquanto high permite várias rodadas de análise. Para a consolidação de memória com effort=high, é necessário selecione explicitamente safe_auto ou plan. O applyMode=plan exige o uso de effort=high.

Início rápido

O fluxo de trabalho completo para o Memory Dream estruturado consiste em: crie uma tarefa de consolidação, consultar o status da tarefa, revisar as propostas de ação e aplicar as ações. Após a aplicação das ações, leia a memória de longo prazo novamente para que verifique os resultados.

O fluxo de status típico é o seguinte: queued → running → planning → (opcional) applying → completed. No modo plan, a tarefa entra em awaiting_plan_approval antes da execução. Outros status terminais incluem completed_with_failures, failed e cancelled. O exemplo a seguir usa o modo proposal:

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 a 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 a 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',
});

Parâmetros principais

A tabela a seguir descreve os parâmetros principais para a criação de uma tarefa de consolidação. Para os valores válidos de cada parâmetro, consulte Limitations and notes.

Recomendações de uso

• Não bloqueie caminhos de requisição online — As tarefas de consolidação são executadas assincronamente em segundo plano. Consulte GetMemoryDreamTask para obter o progresso em vez de aguardar os resultados da consolidação na mesma requisição.

• **Comece com o modo proposal** — Em um ambiente de produção, prefira o modo proposal e aplique ações apenas após a confirmação manual ou programática. Ao confiar suficientemente nos resultados, defina valores apropriados de confidenceThresholds para add, update e merge e, em seguida, ative o modo safe_auto.

• execute a consolidação agendada incrementalmente — Para consolidação agendada, use incremental=true para evitar o reprocessamento completo a cada execução.

Aplicabilidade

Antes de usar o Memory Dream de arquivos, certifique-se de que o repositório de memória atenda às seguintes condições:

• Configuração do repositório de memória — crie o repositório de memória com inputType=file e outputTypes=["file"]. O Dream de arquivos não suporta arquivos somente leitura gerados a partir de mensagens.

• Alinhamento de entrada e saída — A entrada e a saída devem pertencer ao mesmo repositório de memória. A entrada pode abranger vários escopos, mas a saída deve ser um escopo completo de quatro níveis sem curingas.

• Tipos de arquivo suportados — O sistema consolida apenas arquivos de texto UTF-8. A consolidação exclua arquivos binários e o caminho de sistema /.wiki/.

• Seletores de escopo — Uma única tarefa aceita até 8 seletores de escopo. O sistema expande escopos com curingas por nível a partir da direita, e o expandedScopeLimit limita o número de escopos expandidos. O Dream de arquivos é adequado para os seguintes cenários:

• Consolidar vários registros de execução do mesmo agente em um manual compartilhado

• Coletar convenções de projeto de vários agentes

• Mesclar arquivos duplicados

• Reorganizar diretórios preservando as diferenças de source

Início rápido

O exemplo a seguir consolida todos os registros de execução de dois agentes em um escopo compartilhado.

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 a task: read files from multiple input scopes and automatically write the consolidated result 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 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 a task: read files from multiple input scopes and automatically write the consolidated result 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 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);
}

As seguintes regras aplicam-se às tarefas do Memory Dream de arquivos:

• Valores de parâmetros fixos — Para o Dream de arquivos, taskType é fixo em memory (e pode ser omitido), effort é fixo em high e applyMode é fixo em auto (ambos podem ser omitidos). Não informe uma janela de tempo de mensagem, incremental, scopeOutputMode, confidenceThresholds, maxSessions, maxMessages ou maxMemories.

• Retentativas idempotentes — Reutilize o mesmo clientToken ao repetir a mesma requisição de negócios para evitar a criação de tarefas duplicadas.

• Resposta da tarefa — get_memory_dream_task retorna os seletores de entrada, os escopos efetivamente expandidos, o escopo de saída e o número de arquivos congelados. Os status terminais incluem completed, completed_with_failures, failed e cancelled. Apenas o status completed com zero ações com falha representa um sucesso completo.

• Ações de arquivo — As ações de arquivo usam ADD, UPDATE e DELETE. O sistema representa uma renomeação como um UPDATE com um novo path. itemChange.sourceVersionIds registra as versões de arquivo usadas para consolidação. Uma gravação bem-sucedida retorna resultItemId e resultVersionId. Se list_memory_dream_actions retornar um nextToken, continue a paginação até que ele esteja vazio.

• Aplicação automática — O sistema aplica as ações de arquivo automaticamente durante a execução da tarefa, e elas não exigem confirmação manual. Não avalie a qualidade da consolidação apenas pelo status da tarefa ou pela contagem de ações. Leia novamente o diretório de saída, o conteúdo, as versões e as source para confirme se atendem aos requisitos de negócios.

Limites e considerações

Os seguintes limites aplicam-se ao Memory Dream de arquivos:

Além desses limites, observe o seguinte comportamento:

• Modificações simultâneas — Durante a execução da tarefa, cada atualização e exclusão utiliza versões de arquivo para proteção contra simultaneidade. Se outros chamadores modifique os arquivos de saída ao mesmo tempo, as ações podem falhar. Leia novamente os arquivos atuais antes de criar uma nova tarefa de consolidação.

• Sem reversão em caso de cancelamento ou falha — O cancelamento ou a falha não reverte as ações de arquivo já aplicadas. Ao lidar com um status terminal de não sucesso, liste primeiro todas as ações, leia novamente o escopo de saída e, em seguida, decida se deve manter, corrigir ou consolidar novamente.