Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Cada sessão do Managed Agents começa com um contexto novo por padrão. Quando uma sessão termina, qualquer estado que o agente tenha construído desaparece. Os "memory stores" (armazenamentos de memória) permitem que o agente carregue informações entre sessões: preferências do usuário, convenções do projeto, erros anteriores e contexto de domínio.
Um memory store é uma coleção de documentos de texto com escopo de workspace, otimizada para o Claude. Quando você anexa um store a uma sessão, ele é montado como um diretório dentro do sandbox da sessão. O agente o lê e escreve com as mesmas ferramentas de arquivo que usa para o restante do sistema de arquivos, e uma nota descrevendo cada montagem é adicionada automaticamente ao prompt do sistema, informando ao agente onde procurar. O conjunto de ferramentas do agente é necessário para essas interações; certifique-se de habilitá-lo durante a criação do agente.
Cada memória em um store é endereçada por um caminho e pode ser lida e editada diretamente por meio da API ou do Claude Console, permitindo ajustes, importação e exportação.
Toda alteração em uma memória cria uma versão de memória imutável, fornecendo a você uma trilha de auditoria e recuperação pontual para tudo o que o agente escreve.
Dê ao store um name e uma description. A descrição é passada ao agente, informando o que o store contém.
store_id=$(ant beta:memory-stores create \
--name "User Preferences" \
--description "Per-user preferences and project context." \
--transform id --raw-output)O id do memory store (memstore_...) é o que você passa ao anexar o store a uma sessão.
Pré-carregue um store com material de referência antes que qualquer agente seja executado:
ant beta:memory-stores:memories create \
--memory-store-id "$store_id" \
--path "/formatting_standards.md" \
--content "All reports use GAAP formatting. Dates are ISO-8601..." \
> /dev/nullOs memory stores são anexados no array resources[] da sessão quando a sessão é criada. Diferentemente dos recursos de arquivo, os memory stores só podem ser anexados no momento da criação da sessão; adicionar ou remover um de uma sessão em execução não é suportado.
Opcionalmente, inclua instructions para fornecer orientações específicas da sessão sobre como o agente deve usar esse store. Elas são mostradas ao agente junto com o name e a description do store, e são limitadas a 4.096 caracteres.
Você também pode configurar access. O padrão é read_write (mostrado explicitamente no exemplo a seguir), mas read_only também é suportado.
ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
- type: memory_store
memory_store_id: $store_id
access: read_write
instructions: User preferences and project context. Check before starting any task.
YAMLUm máximo de 8 memory stores é suportado por sessão. Anexe vários stores quando diferentes partes da memória tiverem diferentes proprietários ou regras de acesso. Motivos comuns:
Cada store anexado é montado dentro do sandbox da sessão como um diretório em /mnt/memory/. O nome do diretório é o nome de exibição do store sanitizado para um slug seguro para o sistema de arquivos (em minúsculas; sequências não alfanuméricas se tornam um único hífen), então um store chamado "Demo Memory" é montado em /mnt/memory/demo-memory/. O caminho exato é retornado no campo mount_path do recurso de memory store da sessão; leia-o de lá em vez de construí-lo você mesmo. O agente lê e escreve no store com o conjunto de ferramentas do agente padrão. Escritas sob o caminho de montagem são persistidas de volta no store e permanecem sincronizadas entre as sessões que o compartilham; escritas em qualquer outro caminho sob /mnt/memory/ falham, porque o sandbox monta esse diretório pai como somente leitura. Uma breve descrição de cada montagem (nome de exibição, caminho de montagem, modo de acesso, description do store e quaisquer instructions) é adicionada automaticamente ao prompt do sistema.
access é aplicado no nível do sistema de arquivos: uma montagem read_only rejeita escritas, enquanto escritas em uma montagem read_write produzem versões de memória atribuídas à sessão.
As leituras e escritas do agente aparecem no fluxo de eventos como eventos comuns agent.tool_use e agent.tool_result para qualquer ferramenta que tenha tocado a montagem.
Os memory stores podem ser gerenciados diretamente por meio da API. Use isso para construir fluxos de revisão, corrigir memórias ruins ou preencher stores antes que qualquer sessão seja executada.
Liste as memórias em um store. Os resultados são retornados em uma ordem estável, definida pelo servidor.
path_prefix restringe a lista a um diretório. Deve terminar com / e corresponde a segmentos de caminho inteiros, então path_prefix=/notes/ retorna /notes/todo.md, mas não /notes-archive/todo.md.depth controla a profundidade da listagem abaixo de path_prefix: omita-o (ou passe 0) para listar toda a subárvore, ou passe 1 para listar apenas os filhos imediatos. Outros valores retornam um erro 400.ant beta:memory-stores:memories list \
--memory-store-id "$store_id" \
--path-prefix "/"Consulte a referência de Listar memórias para ver os parâmetros completos e o esquema de resposta.
Buscar uma memória individual retorna o conteúdo completo.
ant beta:memory-stores:memories retrieve \
--memory-store-id "$store_id" \
--memory-id "$mem_id"Consulte a referência de Recuperar uma memória para ver os parâmetros completos e o esquema de resposta.
memories.create cria uma memória em um determinado path. A criação não sobrescreve; para alterar uma memória existente, use memories.update.
mem=$(ant beta:memory-stores:memories create \
--memory-store-id "$store_id" \
--path "/preferences/formatting.md" \
--content "Always use tabs, not spaces." \
--format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")Consulte a referência de Criar uma memória para ver os parâmetros completos e o esquema de resposta.
memories.update modifica uma memória existente por ID. Você pode alterar content, path (uma renomeação) ou ambos. O exemplo renomeia uma memória para um caminho de arquivo morto:
ant beta:memory-stores:memories update \
--memory-store-id "$store_id" \
--memory-id "$mem_id" \
--path "/archive/2026_q1_formatting.md" \
> /dev/nullConsulte a referência de Atualizar uma memória para ver os parâmetros completos e o esquema de resposta.
Para evitar sobrescrever uma escrita concorrente, passe uma pré-condição content_sha256. A atualização só é aplicada se o hash do conteúdo armazenado ainda corresponder ao que você leu; em caso de divergência, releia a memória e tente novamente com o estado atualizado.
ant beta:memory-stores:memories update \
--memory-store-id "$store_id" \
--memory-id "$mem_id" \
--content "CORRECTED: Always use 2-space indentation." \
--precondition "{type: content_sha256, content_sha256: $mem_sha}" \
> /dev/nullant beta:memory-stores:memories delete \
--memory-store-id "$store_id" \
--memory-id "$mem_id" \
> /dev/nullConsulte a referência de Excluir uma memória para ver os parâmetros completos e o esquema de resposta.
Toda mutação em uma memória cria uma versão de memória imutável (memver_...). Use os endpoints de versão para auditar quem alterou o quê e quando, para inspecionar ou restaurar um snapshot anterior e para remover conteúdo sensível do histórico com a redação (redact).
As versões pertencem ao store (não à memória individual) e sobrevivem mesmo depois que a própria memória é excluída, de modo que a trilha de auditoria permanece completa. As versões são retidas por 30 dias; no entanto, as versões recentes são sempre mantidas independentemente da idade, então memórias que mudam com pouca frequência podem reter histórico além de 30 dias. A chamada ao vivo memories.retrieve sempre retorna a versão mais recente; os endpoints de versão fornecem o histórico retido.
Não há um endpoint dedicado de restauração; para reverter, recupere a versão desejada e escreva seu content de volta com memories.update (ou memories.create se a memória pai tiver sido excluída, pois as versões sobrevivem ao seu pai).
Versões de memória antigas podem ser excluídas após 30 dias. Para preservar o histórico de memória por mais tempo, exporte as versões por meio da API.
Liste o histórico de versões de um store, da mais recente para a mais antiga. O exemplo filtra pelo histórico de uma única memória:
versions=$(ant beta:memory-stores:memory-versions list \
--memory-store-id "$store_id" \
--memory-id "$mem_id" \
--format json)
# `list --format json` emite um objeto JSON por item.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")Consulte a referência de Listar versões de memória para ver os parâmetros completos e o esquema de resposta.
Buscar uma versão individual retorna os mesmos campos da resposta de listagem, mais o corpo completo de content.
ant beta:memory-stores:memory-versions retrieve \
--memory-store-id "$store_id" \
--memory-version-id "$version_id"Consulte a referência de Recuperar uma versão de memória para ver os parâmetros completos e o esquema de resposta.
A redação remove o conteúdo de uma versão histórica preservando a trilha de auditoria (quem fez o quê, quando). Use-a para fluxos de conformidade, como remover segredos vazados, PII ou atender a solicitações de exclusão de usuários.
Uma versão que é o head atual de uma memória ativa não pode ser redigida. Escreva uma nova versão primeiro (ou exclua a memória) e depois redija a antiga.
ant beta:memory-stores:memory-versions redact \
--memory-store-id "$store_id" \
--memory-version-id "$version_id"Consulte a referência de Redigir uma versão de memória para ver os parâmetros completos e o esquema de resposta.
Além de create, os memory stores suportam retrieve, update, list, archive e delete.
Liste os stores no workspace. Stores arquivados são excluídos por padrão; passe include_archived: true para incluí-los.
ant beta:memory-stores list --include-archivedConsulte a referência de Listar memory stores para ver os parâmetros completos e o esquema de resposta.
Arquivar torna um store somente leitura e impede que ele seja anexado a novas sessões. O arquivamento é irreversível; não há como desarquivar.
ant beta:memory-stores archive --memory-store-id "$store_id"Consulte a referência de Arquivar um memory store para ver os parâmetros completos e o esquema de resposta.
Para remover permanentemente um store junto com todas as suas memórias e versões, use memory_stores.delete.
Quando um store atinge seu limite de 2.000 memórias, as escritas em novas memórias falham: tanto as chamadas diretas a memories.create quanto as escritas de arquivo do agente em caminhos não mapeados. As memórias existentes permanecem legíveis e editáveis. As práticas a seguir ajudam você a ficar bem abaixo do limite e a se recuperar com elegância caso o atinja.
Use stores focados. Em vez de um grande store de uso geral, use stores menores criados para fins específicos: um por usuário, um para conhecimento de domínio compartilhado e um para contexto específico do projeto. Cada store tem seu próprio limite de 2.000 memórias, então manter os stores com escopo definido reduz a chance de qualquer um deles encher.
Condense ou elimine antes que o store encha. Exclua memórias obsoletas ou redundantes com memories.delete. Você também pode executar uma sessão de dreaming, que consolida conteúdo fragmentado em um novo store de saída separado, em vez de modificar o original. Mude suas sessões para esse store de saída e depois arquive ou exclua o original.
Anexe um novo store quando fizer sentido. Se um store cresceu além de seu escopo útil, anexe um novo para conteúdo novo e anexe o original com acesso read_only. O agente pode ler de ambos enquanto escreve apenas no novo.
Limite o acesso de escrita quando apropriado. Sessões que apenas leem material de referência compartilhado não precisam de read_write. Manter o acesso de escrita restrito às sessões que realmente adicionam novas memórias facilita rastrear de onde vem o crescimento.
Was this page helpful?