Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Cada sessão de Managed Agents começa com um contexto novo por padrão. Quando uma sessão termina, qualquer estado que o agente construiu é perdido. Memory stores 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 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 é automaticamente adicionada 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 através da API ou do Console, permitindo ajustes, importação e exportação.
Cada alteração em uma memória cria uma versão de memória imutável, fornecendo uma trilha de auditoria e recuperação pontual para tudo 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 de qualquer execução do agente:
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/nullMemory stores são anexados no array resources[] da sessão quando a sessão é criada. Diferentemente de recursos de arquivo e repositório, 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ção específica da sessão sobre como o agente deve usar este store. Isso é mostrado ao agente junto com o name e a description do store, e é limitado 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 múltiplos stores quando diferentes partes da memória tiverem diferentes proprietários ou regras de acesso. Razões comuns:
Cada store anexado é montado dentro do sandbox da sessão como um diretório sob /mnt/memory/. O nome do diretório é o nome de exibição do store sanitizado para um slug seguro para 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 no 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 sessões que o compartilham; escritas em qualquer outro caminho sob /mnt/memory/ caem em um espaço temporário local do contêiner e são perdidas quando a sessão termina. Uma breve descrição de cada montagem (nome de exibição, caminho de montagem, modo de acesso, description do store e quaisquer instructions) é automaticamente adicionada 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.
Memory stores podem ser gerenciados diretamente através da API. Use isso para construir fluxos de trabalho de revisão, corrigir memórias ruins ou preencher stores antes de qualquer execução de sessão.
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 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 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 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 arquivamento:
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 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 os parâmetros completos e o esquema de resposta.
Cada 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 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 ativa 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, porque 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 através da API.
Liste o histórico de versões de um store, das mais recentes para as mais antigas. O exemplo filtra para o 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 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 os parâmetros completos e o esquema de resposta.
Redact remove conteúdo de uma versão histórica enquanto preserva a trilha de auditoria (quem fez o quê, quando). Use-o para fluxos de trabalho de conformidade, como remoção de segredos vazados, PII ou 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, em seguida, 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 os parâmetros completos e o esquema de resposta.
Além de create, 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 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 é unidirecional; não há desarquivamento.
ant beta:memory-stores archive --memory-store-id "$store_id"Consulte a referência de Arquivar um memory store para 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, escritas em novas memórias falham: tanto chamadas diretas de memories.create quanto as escritas de arquivo do agente em caminhos não mapeados. 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 de forma adequada se atingi-lo.
Use stores focados. Em vez de um grande store de propósito geral, use stores menores construídos 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 reduzido diminui a chance de qualquer um deles encher.
Condense ou remova 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. Migre suas sessões para esse store de saída e, em seguida, 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 onde for apropriado. Sessões que apenas leem material de referência compartilhado não precisam de read_write. Manter o acesso de escrita restrito a sessões que realmente adicionam novas memórias facilita rastrear de onde vem o crescimento.
Was this page helpful?