Usando a memória do agente
Dê aos seus agentes memória persistente que sobrevive entre sessões usando memory stores.
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 de projeto, erros anteriores e contexto de domínio.
Visão geral
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 é 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. Em sandboxes auto-hospedados, esse diretório não é uma montagem ativa. Em vez disso, o worker do seu ambiente baixa cada store anexado para o seu sandbox antes que as ferramentas do agente sejam executadas e mantém essa cópia sincronizada com o store.
Cada memória em um store é endereçada por um caminho e pode ser lida e editada diretamente pela API ou pelo 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 no tempo para tudo o que o agente escreve.
Criar um memory store
Dê ao store um name e uma description. A descrição é passada ao agente, informando o que o store contém.
ant apply memory_store.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.O id do memory store (memstore_...) é o que você passa ao anexar o store a uma sessão.
Preenchê-lo com conteúdo (opcional)
Pré-carregue um store com material de referência antes que qualquer agente seja executado:
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)Anexar um memory store a uma sessão
Os 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. Você anexa memory stores da mesma forma para sessões em ambientes na nuvem e auto-hospedados; ambientes auto-hospedados aceitam apenas recursos memory_store.
Opcionalmente, inclua instructions para fornecer orientações específicas da sessão sobre como o agente deve usar este 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.
session = client.beta.sessions.create(
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.",
}
],
)Um máximo de 8 memory stores é suportado para cada sessão. Anexe vários stores quando diferentes partes da memória tiverem diferentes proprietários ou regras de acesso. Motivos comuns:
- Material de referência compartilhado: um store somente leitura anexado a muitas sessões (padrões, convenções, conhecimento do domínio), mantido separado do store de leitura e escrita de cada sessão
- Mapeamento para a estrutura do seu produto: um store para cada usuário final, equipe ou projeto, compartilhando uma única configuração de agente
- Ciclos de vida diferentes: um store que sobrevive a qualquer sessão individual, ou um que você deseja arquivar em seu próprio cronograma
Como o agente acessa a memória
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, com cada sequência de caracteres não alfanuméricos substituída por 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 o 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.
Visualizar e editar memórias
Os memory stores podem ser gerenciados diretamente pela API. Use isso para construir fluxos de revisão, corrigir memórias ruins ou preencher stores antes que qualquer sessão seja executada.
Listar memórias
Liste as memórias em um store. Os resultados são retornados em uma ordem estável, definida pelo servidor.
path_prefixrestringe a lista a um diretório. Ele deve terminar com/e corresponde a segmentos de caminho inteiros, entãopath_prefix=/notes/retorna/notes/todo.md, mas não/notes-archive/todo.md.depthcontrola a profundidade da lista abaixo depath_prefix: omita-o (ou passe0) para listar toda a subárvore, ou passe1para listar apenas os filhos imediatos. Outros valores retornam um erro400.
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)Consulte a referência Listar memóriasPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Ler uma memória
Buscar uma memória individual retorna o conteúdo completo.
retrieved = client.beta.memory_stores.memories.retrieve(
mem.id,
memory_store_id=store.id,
)
print(retrieved.content)Consulte a referência Recuperar uma memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Criar uma memória
client.beta.memory_stores.memories.create() cria uma memória em um determinado path. A criação não sobrescreve; para atualizar uma memória existente, use client.beta.memory_stores.memories.update().
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)Consulte a referência Criar uma memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Atualizar uma memória
client.beta.memory_stores.memories.update() modifica uma memória existente pelo ID. Você pode alterar content, path (uma renomeação) ou ambos. O exemplo renomeia uma memória para um caminho de arquivo morto:
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)Consulte a referência Atualizar uma memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Edições de conteúdo seguras (concorrência otimista)
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, leia a memória novamente e tente de novo com base no estado atualizado.
client.beta.memory_stores.memories.update(
memory_id=mem.id,
memory_store_id=store.id,
content="CORRECTED: Always use 2-space indentation.",
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)Excluir uma memória
client.beta.memory_stores.memories.delete(
mem.id,
memory_store_id=store.id,
)Consulte a referência Excluir uma memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Auditar alterações de memória
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 redact.
As versões pertencem ao store (não à memória individual) e não são excluídas quando a própria memória é excluída, então a trilha de auditoria também cobre memórias excluídas, sujeita à retenção descrita mais adiante. As versões são retidas por 30 dias após serem escritas; no entanto, as versões recentes de uma memória ativa 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 client.beta.memory_stores.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 client.beta.memory_stores.memories.update() (ou client.beta.memory_stores.memories.create() se a memória pai tiver sido excluída, desde que a versão desejada ainda esteja retida).
Versões de memória anteriores podem ser excluídas após 30 dias. Para preservar o histórico de memória por mais tempo, exporte as versões pela API.
Listar versões
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 = client.beta.memory_stores.memory_versions.list(
store.id,
memory_id=mem.id,
)
for version in versions:
print(f"{version.id}: {version.operation}")
version_id = versions.data[1].idConsulte a referência Listar versões de memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Recuperar uma versão
Buscar uma versão individual retorna os mesmos campos da resposta de listagem, mais o corpo completo de content.
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)Consulte a referência Recuperar uma versão de memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Redigir uma versão
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 ou dados pessoais identificáveis (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.
client.beta.memory_stores.memory_versions.redact(
version_id,
memory_store_id=store.id,
)Consulte a referência Redigir uma versão de memóriaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Gerenciar memory stores
Além de createPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar., os memory stores suportam retrievePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar., updatePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar., listPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar., archivePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. e deletePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..
Listar stores
Liste os stores no workspace. Stores arquivados são excluídos por padrão; defina include_archived como true para incluí-los.
for memory_store in client.beta.memory_stores.list(include_archived=True):
print(memory_store.id, memory_store.name, memory_store.archived_at)Consulte a referência Listar memory storesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Arquivar um store
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.
client.beta.memory_stores.archive(store.id)Consulte a referência Arquivar um memory storePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. para ver todos os parâmetros e o esquema de resposta.
Para excluir permanentemente um storePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. junto com todas as suas memórias e versões, chame client.beta.memory_stores.delete().
Melhores práticas para gerenciamento de memória
Quando um store atinge seu limite de 10.000 memórias, as escritas de novas memórias falham: tanto as chamadas diretas a client.beta.memory_stores.memories.create() quanto as escritas de arquivo do agente em caminhos não mapeados. As memórias existentes continuam legíveis e editáveis. As práticas a seguir ajudam você a ficar bem abaixo do limite e a se recuperar adequadamente caso o atinja.
-
Use stores focados. Em vez de um grande store de uso geral, use stores menores e específicos: um para cada 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 10.000 memórias, então manter os stores com escopo definido reduz a chance de que qualquer um deles fique cheio.
-
Condense ou remova antes que o store fique cheio. Exclua memórias obsoletas ou redundantes com
client.beta.memory_stores.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 do 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.
Disponibilidade
Claude API
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
- Observação
Enviar
managed-agents-2026-04-01junto comagent-memory-2026-07-22em uma chamada de armazenamento de memória retorna um erro 400.
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
- Observação
No Claude Platform on AWS, sessões em ambientes auto-hospedados não podem anexar armazenamentos de memória. Enviar
managed-agents-2026-04-01junto comagent-memory-2026-07-22em uma chamada de armazenamento de memória retorna um erro 400.
Claude Models on Google Cloud (Anthropic managed)
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
- Observação
No Claude Models on Google Cloud (Anthropic managed), armazenamentos de memória não são compatíveis com sessões em ambientes auto-hospedados. Enviar
managed-agents-2026-04-01junto comagent-memory-2026-07-22em uma chamada de armazenamento de memória retorna um erro 400.
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/agents/v1/sessions/v1/environments
Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua. Saiba mais
Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents.
Esta página foi útil?