Tutorial 20: Memória Persistente — Memória de Longo Prazo

Esta é parte da série oficial de tutoriais do Hermes Agent. Ver todos os tutoriais

Pense neste recurso como um bilhete adesivo na sua mesa: o Hermes Agent anota coisas importantes sobre você e seus projetos para não esquecê-las entre conversas. Chega de repetir tudo toda vez que você inicia um novo chat.

O Que a Memória Persistente Faz?

Normalmente, um agente de IA começa do zero a cada sessão — ele esquece tudo quando a conversa termina. A Memória Persistente muda isso. O Hermes Agent mantém dois pequenos arquivos de texto no seu computador. Ele os lê no início de cada sessão, então lembra instantaneamente das suas preferências, detalhes do seu projeto e qualquer outra coisa que você ensinou.

Passo 1: Conheça os Dois Arquivos de Memória

A memória do agente fica em dois arquivos, armazenados em ~/.hermes/memories/:

Arquivo	O Que Armazena	Limite de Tamanho
MEMORY.md	Notas pessoais do agente — fatos do ambiente, convenções, coisas que aprendeu	2.200 caracteres (~800 tokens)
USER.md	Seu perfil — preferências, estilo de comunicação, expectativas	1.375 caracteres (~500 tokens)

Os limites são intencionais. Eles forçam o agente a manter apenas o que é importante, como um caderno bem organizado em vez de uma gaveta bagunçada.

Passo 2: Veja Como a Memória Aparece no Prompt

No início de cada sessão, o agente carrega ambos os arquivos e os mostra como um instantâneo congelado no seu prompt de sistema. Aqui está um exemplo do que o agente “vê”:

══════════════════════════════════════════════
MEMÓRIA (suas notas pessoais) [67% — 1.474/2.200 caracteres]
══════════════════════════════════════════════
O projeto do usuário é um serviço web em Rust em ~/code/myapi usando Axum + SQLx
§
Esta máquina roda Ubuntu 22.04, tem Docker e Podman instalados
§
Usuário prefere respostas concisas, não gosta de explicações longas

Observe os detalhes:

Um cabeçalho mostrando qual armazenamento é (MEMÓRIA ou PERFIL DO USUÁRIO)
Porcentagem de uso e contagem de caracteres — para o agente saber quanto espaço resta
Entradas separadas por § (sinal de seção)
Entradas podem ter várias linhas

Importante: Este instantâneo é capturado uma vez no início da sessão e nunca muda no meio dela. Se o agente atualizar sua memória durante a conversa, as mudanças são salvas no disco imediatamente, mas não aparecerão no prompt até a próxima sessão. Isso mantém tudo rápido, preservando o cache do modelo.

Passo 3: O Agente Gerencia a Própria Memória

O agente usa uma ferramenta chamada memory com três ações:

add — Adicionar uma nova entrada de memória
replace — Substituir uma entrada existente (usa correspondência de substring com old_text)
remove — Excluir uma entrada que não é mais relevante (também usa old_text)

Não há ação read porque a memória já é injetada no prompt — o agente sempre a vê.

Aqui está um exemplo simples de como o agente pode usar a ferramenta:

memory action=add content="Usuário prefere marcadores em vez de parágrafos"

Ou substituindo uma preferência antiga:

memory action=replace old_text="Usuário prefere respostas concisas" new_text="Usuário prefere respostas de uma linha com emojis"

Passo 4: O Que Acontece Quando a Memória Está Cheia?

A memória não é compactada automaticamente. Quando uma gravação excederia o limite, a ferramenta memory retorna um erro em vez de descartar entradas silenciosamente. O agente então abre espaço por conta própria — consolidando ou removendo entradas na mesma rodada antes de tentar novamente.

Observe também: replace também está sujeito ao limite. Trocar uma entrada por uma mais longa pode estourar o limite, então o novo conteúdo deve ser encurtado (ou outra entrada removida) para caber.

Passo 5: Um Agente por Diretório Hermes (Importante!)

Não aponte dois processos de agente para o mesmo diretório home do Hermes. As gravações de memória são automáticas e carregadas de volta no prompt de sistema no início da sessão, então dois escritores compartilhando um mesmo home vão acumular as entradas um do outro em uma bagunça que nenhum dos dois criou. A memória é limitada por perfil por design — dê a um segundo agente seu próprio perfil. Se eles precisarem de memória compartilhada, use um provedor de memória externo.

Resumo

A Memória Persistente dá ao Hermes Agent uma maneira simples e limitada de lembrar de você entre sessões. Dois arquivos pequenos — MEMORY.md e USER.md — guardam notas selecionadas, injetadas como um instantâneo congelado no início da sessão. O agente gerencia esses arquivos sozinho usando a ferramenta memory, e os limites de caracteres mantêm tudo focado. Só lembre: um agente por diretório home, e o instantâneo só é atualizado no início da sessão.

A seguir: Tutorial 21 — Tarefas Agendadas: configurando automações que rodam sozinhas em um temporizador.