Agentes ignoraram a dica de ler a memória em 7 de 7 sessões: análise de 13 mil logs

A equipe da kaeru, que desenvolve memória de longo prazo para agentes de IA como Claude Code, Codex e Cursor, publicou uma análise dos próprios logs: mais de 13 mil arquivos de sessões de trabalho, de junho a setembro. O principal resultado: nas 7 sessões em que o agente viu a dica “você pode ler os raciocínios salvos”, ele não leu nenhum deles, embora tenha seguido 751 vezes outra dica, “vincule o registro ao anterior”. Durante vários meses, os autores projetaram o produto “por intuição” e só depois verificaram como os agentes realmente usam a memória.

Muita coisa não saiu como esperavam, e a maioria das conclusões vale não só para a kaeru, mas para qualquer pessoa que escreva servidores MCP, hooks ou instruções longas para agentes.

O que é a kaeru e o que foi verificado

A kaeru é um servidor local ao qual o agente se conecta via MCP, protocolo padrão para chamar ferramentas externas. Ao longo do trabalho, o próprio agente escreve registros: observações, decisões, tarefas com prazo e hipóteses com o resultado da verificação. Os registros se ligam por vínculos ponderados, o que permite salvar uma cadeia de raciocínio inteira. Um fato corrigido não é sobrescrito: a versão antiga é encerrada com uma data. Ao entrar em um projeto, o agente recebe um resumo com o que está em vigor, o que está atrasado e quais raciocínios já existem. Tudo isso só funciona se o agente ler a memória antes de perguntar, registrar o que descobriu e marcar o que ficou desatualizado.

Os autores apontam as limitações com franqueza: são logs próprios, não uma amostra do mercado. O tamanho das amostras varia entre as seções, indo de milhares de eventos a sete sessões ou aos logs de um único usuário. Mediram o comportamento dos agentes, não o benefício: a equipe ainda não sabe quanto tempo ou quantos tokens a memória economiza por tarefa e prepara um benchmark próprio.

Dívida é cumprida, oportunidade é ignorada

Na entrada do projeto, foi adicionada a dica “há raciocínios salvos neste projeto, você pode ler”. Em quatro dias, o modelo a viu em 7 sessões e não leu nenhuma vez, embora, no mesmo período, os agentes tenham salvado 17 novos raciocínios. Eles estão dispostos a escrever, mas não a reler.

Outra dica, “vincule este registro àquele de onde ele se originou”, aparecia logo depois da gravação e foi cumprida 751 vezes. É a ação mais frequente de todo o produto. Na versão 0.8, o vínculo é informado diretamente na chamada de gravação, e a dica separada deixou de ser necessária. A diferença está no momento: a segunda dica continua o que o agente já está fazendo, enquanto a primeira pede que ele largue a tarefa e cuide de algo alheio a ela.

O mesmo padrão aparece no resumo. Diante da linha “2 registros em dúvida, aguardam decisão”, os agentes trataram registros controversos 8 vezes, as tarefas atrasadas são fechadas direitinho, e a linha “você pode ler os raciocínios salvos” não funcionou nenhuma vez. Agora, tudo no resumo é formulado como dívida.

Hooks, instruções truncadas e parâmetros opcionais

Nos logs de um único usuário, 80% das perguntas do agente ao humano foram feitas sem nenhuma consulta à memória nos dez minutos anteriores; a mediana foi de 74 minutos desde a última leitura. Para resolver isso, foi criado um hook, um script que o cliente executa em um momento definido. Quando o agente está prestes a passar a vez ao humano, o hook busca na memória materiais sobre o tema e manda o agente lê-los uma única vez.

A primeira versão identificava o pedido ao humano pelo sinal “?”. Entre as 2 608 paradas do agente, em 1 164 houve contato com o humano; a primeira versão detectou 201 delas, ou seja, 17%.

Em 856 casos, eram pedidos no imperativo: “diga”, “envie o relatório”, “preciso da sua resposta sobre o fornecedor”. Os agentes pedem mais do que perguntam.

A descoberta mais desagradável: o cliente truncou a instrução do servidor MCP em 2 048 caracteres, e ninguém notou por dois meses. Entre as ferramentas citadas antes do corte, 9% não eram usadas. Entre as citadas depois do corte, 31%, o mesmo índice das ferramentas que a instrução nem menciona. Para o modelo, o final da instrução simplesmente não existia. Hoje, o texto introdutório da kaeru ocupa 1 499 caracteres.

Com os parâmetros, aconteceu o mesmo. O peso do vínculo era opcional, com valor padrão. Em 6 003 chamadas das ferramentas de memória, os agentes criaram 1 262 vínculos e nunca informaram o peso. Na 0.8, ele passou a ser obrigatório. Nos lembretes, o prazo de exibição é obrigatório desde o início: “o certificado expira” e “meça o número de novo antes de citar” exigem prazos diferentes, e só o autor do registro sabe quais.

O que funcionou melhor foi a limpeza em segundo plano, que não pede nada ao agente: já na primeira passada, ela organizou sozinha em camadas 33 registros acumulados.

A conclusão prática da equipe cabe em cinco regras:

• o que é necessário deve chegar sozinho, dentro de uma resposta que o agente já recebe de qualquer forma;
• formular como dívida: “aguarda decisão”, e não “você pode dar uma olhada”;
• dar a dica no momento da ação, e não tudo de uma vez no início da sessão;
• tornar obrigatórios os parâmetros, sem valores padrão;
• manter a instrução curta e verificar quanto dela chega ao modelo no seu cliente.

O código-fonte da kaeru está publicado no GitHub, e o próximo artigo da série vai mostrar como fica um dia de trabalho com base nessas conclusões.