Tablestore:File memory

1. Criar um armazenamento de memória

Crie um armazenamento de memória que gere tanto memória estruturada quanto arquivos:

Console

1. Faça login no console do Agent Storage, acesse Memory store management e clique em Create memory store.

2. Em Input type, selecione Short-term messages. Em Output type, selecione File memory. Para utilizar recuperação semântica simultaneamente, marque também Structured memory.

3. Clique em OK para concluir a criação.

SDK

from tablestore_agent_storage import AgentStorageClient

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

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Conversation memory for an agent",
    "inputType": "messages",
    "outputTypes": ["structured", "file"],
})

Caso precise apenas de arquivos, defina outputTypes como ["file"]. Não é possível modificar inputType após a criação. Para armazenamentos de memória que usam messages como entrada, ajuste outputTypes por meio de UpdateMemoryStore.

2. Gravar conversas

Grave as mensagens da conversa no armazenamento de memória. O service gera os arquivos somente leitura de forma assíncrona.

Console

1. Abra o armazenamento de memória de arquivos, acesse a página Short-term memory e clique em Write memory.

2. Em Input mode, selecione Conversation messages (JSON). Preencha o escopo completo de quatro níveis: ApplicationappId, Tenant/UsertenantId, AgentagentId e SessionrunId.

3. Cole o JSON das mensagens da conversa e clique em OK para enviar. Os arquivos são gerados assincronicamente. Após o envio, verifique o status da tarefa de geração na página Request log.

SDK

Chame AddMemories para gravar as mensagens. A saída de arquivo suporta apenas geração assíncrona, portanto sync deve ser false ou omitido.

resp = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "shopping-app",
        "tenantId": "user-001",
        "agentId": "shopping-assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "I usually drink Americano coffee without sugar."},
        {"role": "assistant", "content": "Okay, I will remember your beverage preference."},
    ],
    "sync": False,
})
request_id = resp["requestId"]

Salve o requestId da resposta.

3. Aguardar a conclusão da geração de arquivos

Consulte o status da tarefa de geração para confirmar que o service criou os arquivos somente leitura.

Console

1. Abra o armazenamento de memória de arquivos e acesse a página Request log.

2. Localize o registro correspondente pelo Request ID salvo, verifique a coluna Status e aguarde até que o status seja completed.

SDK

Utilize o requestId retornado por AddMemories para chamar GetMemoryTask:

task = client.get_memory_task({
    "memoryStoreName": "agent_memory",
    "requestId": request_id,
})
print(task["task"]["status"])

Quando task.status for completed, todas as saídas configuradas foram geradas. Em armazenamentos de memória com saída dupla, a tarefa geral só atinge o status completed após a geração tanto da memória estruturada quanto dos arquivos.

4. Listar e ler arquivos

Use exatamente o mesmo escopo de quatro níveis da operação de gravação para navegar pelos arquivos somente leitura gerados pelo service. Arquivos gerados pelo service não aceitam escopos com caracteres curinga.

Console

1. Faça login no console do Agent Storage, abra o armazenamento de memória de arquivos e acesse a página Long-term memory.

2. Mude para File memory e selecione o escopo completo utilizado durante a gravação.

3. Navegue pelos arquivos somente leitura gerados na árvore de arquivos. Clique em um arquivo para visualizar seu conteúdo e histórico de versões.

SDK

Chame ListItems para listar os arquivos e, em seguida, leia cada um deles.

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

page = client.list_items({
    "type": "memoryfile",
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "limit": 20,
})

# Get the actual path from items, then read the content
for entry in page["items"]:
    item = client.get_item({
        "type": "memoryfile",
        "memoryStoreName": "agent_memory",
        "scope": scope,
        "path": entry["path"],
        "view": "full",
    })
    print(item["path"], item["content"])

O campo de resposta de nível superior readOnly é true quando o service mantém esses arquivos. Defina view=full para ler o conteúdo deles.

Preparar o ambiente

Antes de montar a memória de arquivos, certifique-se de que as seguintes condições sejam atendidas:

• O executável Linux agent-memory-fuse compatível com a arquitetura do seu runtime está disponível e possui permissões de execução.

• O kernel Linux tem o FUSE habilitado e o usuário ou contêiner atual consegue acessar /dev/fuse.

• O fusermount3 está instalado. Em alguns sistemas, o comando chama-se fusermount.

• Um armazenamento de memória de arquivos com storageMode=filemem foi criado. O endpoint HTTPS da instância, o nome da instância e o escopo completo de quatro níveis estão disponíveis.

• Uma chave de API, um par de AccessKey ou uma credencial temporária do Security Token Service (STS) está disponível. Chaves de API devem ser usadas com endpoints HTTPS.

Ao executar em um contêiner, geralmente é necessário mapear /dev/fuse e conceder CAP_SYS_ADMIN ou permissão equivalente de montagem no namespace do usuário. Utilize uma configuração de privilégio mínimo para o seu ambiente de runtime.

Conceda permissão de execução ao binário e crie o diretório de montagem:

chmod +x ./agent-memory-fuse
mkdir -p /mnt/agent-memory

Montar a memória de arquivos

Execute o comando a seguir. O escopo no exemplo corresponde ao objeto scope do início rápido. Envolva o escopo completo entre aspas para evitar que o shell interprete caracteres especiais inesperadamente.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-session-001 \
  /mnt/agent-memory

O comando de montagem executa em primeiro plano e gerencia o ciclo de vida da montagem. O log a seguir indica que o carregamento inicial do diretório e a montagem foram bem-sucedidos:

mounted /mnt/agent-memory: store=agent_files files=1 readOnly=false

Mantenha esse processo em execução e acesse o diretório de montagem a partir de outro terminal ou processo da aplicação. Em ambientes de produção, utilize systemd ou um sistema de orquestração de contêineres para gerenciar o processo. Não encerre o processo forçadamente enquanto a montagem ainda estiver em uso.

A tabela a seguir descreve os principais parâmetros.

Ler e gravar arquivos

Após a montagem ser concluída com sucesso, você pode ler, criar, modificar, renomear e excluir arquivos como faria em um diretório comum.

# View existing server-side files
find /mnt/agent-memory -type f
cat /mnt/agent-memory/profile/preferences.md

# Create or update files
mkdir -p /mnt/agent-memory/projects/alpha
printf '%s\n' '# Project decisions' '' '- Use an event-driven architecture' \
  > /mnt/agent-memory/projects/alpha/decisions.md
cat /mnt/agent-memory/projects/alpha/decisions.md

# Rename and delete files
mv /mnt/agent-memory/projects/alpha/decisions.md \
  /mnt/agent-memory/projects/alpha/architecture.md
rm /mnt/agent-memory/projects/alpha/architecture.md

Os arquivos são sincronizados com o servidor nas operações de flush, fsync ou close.

Os diretórios são formados a partir dos prefixos dos caminhos dos arquivos. Diretórios que contêm arquivos podem ser restaurados entre processos e remontagens. Diretórios vazios existem apenas no processo de montagem atual.

Montagem somente leitura

Se o agente precisar apenas ler a memória, adicione --read-only antes do argumento do diretório de montagem.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-reader-001 \
  --read-only \
  /mnt/agent-memory

Para visualizações de arquivos somente leitura geradas a partir de memória estruturada, o servidor muda automaticamente a montagem para somente leitura. Operações de gravação em uma montagem somente leitura retornam EROFS.

Rotacionar credenciais STS

Ao montar com credenciais STS, é possível rotacionar o AccessKey ID, o AccessKey secret e o token do Security Token Service completos sem desmontar o diretório. O provedor de credenciais deve gravar o seguinte JSON na saída padrão e canalizá-lo para o comando de rotação.

{"accessKeyId":"new-access-key-id","accessKeySecret":"new-access-key-secret","stsToken":"new-sts-token"}

your-credential-provider | \
  ./agent-memory-fuse rotate-credential --mountpoint /mnt/agent-memory

O comando de rotação lê as credenciais da entrada padrão para evitar colocar novas credenciais nos argumentos da linha de comando. Um comando bem-sucedido indica que as novas credenciais foram instaladas no processo de montagem local. Solicitações subsequentes de arquivo confirmam se as credenciais são válidas. Apenas processos confiáveis podem acessar o ponto de montagem e realizar a rotação de credenciais.

Desmontar a memória de arquivos

Após concluir as operações de arquivo e fechar todos os arquivos abertos, execute o seguinte comando.

./agent-memory-fuse umount /mnt/agent-memory

Após a desmontagem ser concluída com sucesso, o processo de montagem em primeiro plano é encerrado. Se o sistema não possuir nem fusermount3 nem fusermount, o comando de desmontagem retornará um erro. Instale primeiro as ferramentas de espaço de usuário do FUSE.

Limites e solução de problemas

Limites e erros de memória de arquivos surgem no diretório montado como valores errno padrão do Linux. Para limites gerais de arquivos e cotas, consulte Limits.

• Conteúdo que não seja UTF-8 válido retorna EILSEQ, e um arquivo que exceda o tamanho máximo individual retorna EFBIG.

• Gravações que excedam a cota de arquivos atuais de um escopo retornam ENOSPC.

• Quando vários clients modificam simultaneamente o mesmo arquivo, identificadores de arquivo obsoletos podem retornar ESTALE. Reabra o arquivo e leia o conteúdo mais recente antes de decidir se deve tentar novamente.

• Credenciais inválidas ou um token STS expirado retornam EACCES. Rotacione as credenciais ou remonte com credenciais válidas.

• Limitação de taxa do service ou indisponibilidade breve podem retornar EAGAIN. A ferramenta realiza tentativas limitadas inicialmente. As aplicações ainda devem usar estratégias de backoff para lidar com erros finais.

• Links simbólicos, hard links, ACLs, atributos estendidos, arquivos esparsos e bloqueios de arquivo entre sessões não são suportados.

• Se você vir operation not permitted ou não conseguir abrir /dev/fuse, verifique o mapeamento do dispositivo, as permissões do usuário atual e as capacidades de montagem do contêiner.

• Se encontrar um erro de initial directory load, verifique se o endpoint, o nome da instância, as credenciais, o nome do armazenamento de memória e o escopo correspondem.

Ler apenas metadados

Console

Selecione o arquivo alvo na lista de arquivos à esquerda. O painel de detalhes à direita exibe o conteúdo do arquivo, Creation time, Update time e o Version ID atual. Nenhuma operação adicional é necessária para visualizar os metadados.

SDK

Defina includeContent como False. A resposta não incluirá content, o que é adequado para verificar resumos de arquivos e horários de atualização.

current = client.get_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "includeContent": False,
})
print(current["contentSha256"], current["updatedAt"])

Atualizar o conteúdo do arquivo

Console

Selecione o arquivo, clique em Edit or replace data, modifique o File content e salve. O console realiza validação de concorrência com base na versão atual. Se outra solicitação tiver modificado o arquivo, o salvamento falhará. Clique em Refresh e tente novamente.

SDK

Para gravações concorrentes, passe o contentSha256 da última leitura como expectedSha256. Se outra solicitação tiver modificado o arquivo, o service rejeitará a substituição. Leia o arquivo novamente e decida se deve tentar outra vez.

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# User preferences\n\n- Prefers latte\n- Prefers concise responses\n",
    "expectedSha256": current["contentSha256"],
})

Renomear um arquivo

Console

Selecione o arquivo, clique em Rename, insira o novo File path e confirme. Se o caminho de destino já existir, um conflito será reportado.

SDK

O UpdateItem lida tanto com atualizações de conteúdo quanto com renomeações. Uma única solicitação deve especificar exatamente um entre content ou newPath.

renamed = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "newPath": "/profile/user-preferences.md",
    "expectedSha256": updated["contentSha256"],
})

Se o caminho de destino já existir, o service retorna um conflito por padrão. Defina "overwrite": True apenas quando sua lógica de negócio confirmar que a substituição do arquivo de destino é permitida.

Listar arquivos com paginação

Console

Na página Long-term memory, selecione um escopo e navegue pela lista de arquivos paginada por Path prefix à esquerda. Clique em Refresh para obter a lista mais recente.

SDK

O ListItems retorna 100 arquivos por página por padrão, com um máximo de 500 por página. Quando a resposta incluir nextToken, passe-o exatamente como está na próxima solicitação.

next_token = None
while True:
    request = {
        "memoryStoreName": "agent_files",
        "scope": scope,
        "pathPrefix": "/profile/",
        "limit": 100,
    }
    if next_token:
        request["nextToken"] = next_token

    page = client.list_items(request)
    for entry in page["items"]:
        print(entry["path"])

    next_token = page.get("nextToken")
    if not next_token:
        break

Excluir um arquivo

Console

Selecione o arquivo, clique em Delete e confirme. A exclusão remove o arquivo atual e cria uma versão de exclusão. Versões históricas permanecem disponíveis em Version history.

SDK

client.delete_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/user-preferences.md",
    "expectedSha256": renamed["contentSha256"],
})

A operação de exclusão remove o arquivo atual, mas ainda é possível consultar versões históricas pelo ID do arquivo.

Redigir versões históricas

O RedactItemVersion limpa o caminho, o conteúdo, o hash do conteúdo e o tamanho de um snapshot histórico. Ele preserva o tipo de operação, a sequência da versão, o horário de criação e as informações de auditoria da redação. Solicitações repetidas são idempotentes. A redação não modifica o arquivo atual nem cria uma nova versão.

redacted = client.redact_item_version({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": version["itemId"],
    "versionId": version["versionId"],
    "versionSeq": version["versionSeq"],
    "sessionId": "privacy-job-001",
})
print(redacted["redacted"], redacted["redactedAt"])

Após a redação, chamar GetItemVersion ainda retorna a versão, mas a resposta não inclui mais content.