Troubleshooting com AI Memory: como guardo um problema para não resolver do zero

Já faz uns quatro meses que uso o AI Memory todo dia. Instalei no fim de maio, só para ver se funcionava. Hoje ele guarda mais de 5 mil páginas e quase 3.900 sessões minhas.

Eu imaginava que ia usar para lembrar onde parei. O uso que mais me paga de volta acabou sendo outro: lembrar do problema que eu já resolvi.

Porque trabalhando aparece problema toda hora. Você resolve, respira e segue. Duas semanas depois ele volta com outra cara, e você começa do zero. Admito que isso acontecia comigo o tempo todo.

Este texto é sobre como guardo esses problemas hoje. Bora lá.

Sobre o AI Memory

O AI Memory é um servidor de memória de longo prazo para agentes de LLM. É open source, do Fabio Akita, e roda local. No meu caso, um container Docker com SQLite que o Claude Code acessa via MCP.

Funciona em duas pontas. Os hooks do Claude Code registram sozinhos o que acontece em cada sessão. Depois o servidor consolida isso em páginas de wiki, e o agente busca nelas quando precisa de contexto.

A busca mistura texto exato e embeddings. Isso importa para o que vem a seguir.

Os embeddings eu gero na minha própria máquina: um notebook Dell G15 com Core i7-11800H, 32 GB de RAM e uma RTX 3060 Laptop de 6 GB, no Ubuntu 24.04. O modelo é o bge-m3, servido pelo Ollama.

Ele roda 100% na GPU e ocupa menos de 1 GB de VRAM, então sobra espaço para o resto. Um passo por hora gera os vetores das páginas novas. Nada sai da máquina e não pago por token.

Olhando o log, cada rodada leva de 2 a 5 segundos. Para os meus 11 mil vetores, o notebook que eu já tinha dá conta.

Não vou entrar na instalação. O repositório explica melhor do que eu. O foco aqui é o que eu faço com ele.

Como guardo um problema

Preciso corrigir uma impressão logo de cara: eu quase não escrevo essas páginas à mão. O auto-improve do AI Memory revisa as sessões e propõe os registros. Das 439 páginas de gotchas que tenho hoje, todas foram geradas pelo próprio AI Memory, e 72% passaram pelo auto-improve.

Isso tem um custo, e fui medir. O formato varia de página para página. A causa aparece como “Root cause”, “Causa” ou “Causa raiz”. Só 38% das páginas têm causa raiz explícita, 26% têm o sintoma e 11% falam de prevenção.

Admito que eu nunca tinha olhado isso de perto.

O formato que quero tornar padrão tem cinco partes:

1. Sintoma, com o texto exato do erro.
2. Causa raiz, separada do sintoma.
3. O que não é o problema.
4. Como recuperar.
5. Como prevenir.

A terceira quase não existe hoje: aparece em 4% das páginas. E é a que mais me serviu. Vou mostrar com um caso real que já segue esse formato.

Um dia o claude --resume parou de achar uma sessão e, no encerramento, três hooks falharam com ENOENT ... posix_spawn '/bin/sh'. Dois sintomas, aparentemente sem relação.

A causa era uma só: eu tinha renomeado a pasta do projeto com a sessão aberta. O Claude Code guarda o histórico pelo caminho da pasta, e roda os hooks a partir dela. Pasta que sumiu, os dois quebram.

A página registra também o que não é o problema: os scripts de hook existem e o settings.json é válido, então não adianta mexer neles. Parece detalhe. Sem essa linha, o eu do futuro “conserta” uma configuração saudável.

Problemas diferentes, mesma causa

Aqui entra a busca semântica. Eu raramente procuro pelo nome da causa. Procuro pelo que estou vendo: “hook falhando ao fechar sessão”, “resume não encontra”.

Os erros podem não ser iguais, mas podem ser semanticamente parecidos. Essa é a ideia por trás de algo como a cosine similarity: textos com significado próximo ficam perto um do outro no espaço dos vetores, mesmo com palavras diferentes. Por isso a página aparece quando a busca também usa embeddings, e as palavras não batem com as que usei na época.

Não vou fingir que domino isso. Não sei dizer se é exatamente o cosseno que o AI Memory usa por baixo, e ainda preciso estudar mais os assuntos específicos de RAG, como chunking e ranking. Essa mesma ideia volta mais abaixo, na minha melhoria contínua.

O AI Memory ainda mantém relações tipadas entre as páginas. O status dele lista hoje 74 do tipo fixes e 32 do tipo causes.

Não sei dizer quantas vezes isso já me salvou. Tenho alguns casos na cabeça e a sensação de que compensa, mas contar mesmo, nunca contei.

E guardar não é lembrar na hora certa. Um problema de configuração de testes (o phpunit.xml perdendo para uma variável do shell) me pegou pela terceira vez, com a causa conhecida desde setembro. Estava tudo registrado. Eu e o agente simplesmente não consultamos antes.

No fim do dia, essa foi a lição mais cara: a memória só ajuda se alguém consulta.

Quando o problema vira cascata

Alguns problemas não se resolvem em uma tarde. Em agosto, a consolidação por LLM do próprio AI Memory começou a falhar com erro 429. Levei três dias para perceber, porque o sistema caía para um modo mais simples e só deixava um aviso discreto no log.

A hipótese que eu tinha anotada na memória era: “divide cota com o Claude Code e estoura no pico”. Parecia razoável. Estava errada.

O que derrubou a hipótese, em ordem:

1. O horário. Nove falhas entre 00h30 e 08h30, comigo dormindo. Concorrência não explica.
2. Uma requisição de 1 token. Falhava igual. Volume não explica.
3. Trocar uma variável só. Isolou a causa: o token era de assinatura, não uma API key de billing.

Corrigi a página que culpava a cota. E registrei também o que não consegui resolver: a consolidação seguiu indisponível, agora por outro motivo e com data para voltar.

Registrar o “não resolvido” faz parte. Sem isso, a próxima sessão acha que o problema acabou.

Ficou uma frase na minha wiki que repito bastante: a mensagem de erro da ferramenta é uma hipótese, não um laudo. E a memória também erra. A minha errou, e eu só descobri porque medi.

Memória do agente e wiki curada

Eu mantenho duas camadas, e elas têm donos diferentes.

O AI Memory é a camada quente: o que falhou, quais hipóteses estão abertas, onde a sessão parou.

A camada fria é a minha wiki curada, o Anvilore. Ali ficam notas sobre o meu trabalho, documentação e anotações de reunião, com informação já revisada.

Se você quer entender como ela nasceu, escrevi sobre isso em Capturar notas é fácil. Destilar é a parte que dói. e em Mil páginas depois. O método vem da wiki do cooperacode (MIT), que adaptei.

Até agora, não tive problema em ter as duas. O problema cru vai para o AI Memory. Quando vira regra ou decisão que eu aceito, promovo para a wiki, à mão.

Tem um ponto em aberto, e prefiro dizer: o AI Memory tem uma wiki interna que aprova as próprias propostas, e isso concorre com a curada. Deixei anotado. Ainda não resolvi.

O pedido de última hora

Foi o caso que me convenceu de que o hábito vale.

A liderança me pediu um relatório, de última hora, para uma reunião no dia seguinte.

Eu tinha tudo anotado: minhas notas sobre as reuniões, os insights e o meu relatório pessoal de entregas. Em pouco mais de 1h30 o relatório estava fechado, e enviei no dia seguinte, antes do prazo.

Nesse dia, o trabalho virou consulta e conferência.

Para mim, isso funciona como ansiolítico. Saber que está tudo guardado tira o peso do pedido de última hora.

Foi um caso só, então não sei dizer quanto tempo isso me poupou. Mas imagine fazer esse relatório de memória, juntando nota solta. E mesmo com tudo anotado, pedi para outro modelo revisar antes de enviar. Ele achou números errados.

Sobre o backup

Se a memória virou parte do meu trabalho, perdê-la dói. Então faço backup todo dia às 3h da manhã, com um cron e um script em shell.

O script faz duas coisas. Gera um tarball com o banco, a wiki e a configuração (hoje cada um passa de 1 GB) e guarda só os 14 mais recentes. Depois dá push do export em markdown da wiki para um repositório git privado meu. Antes de cada atualização do AI Memory, gero mais um tarball. Já são seis.

Não sei se essa é a melhor forma. Está dando certo, mas conheço os furos. Os tarballs ficam na mesma máquina. O que vai para fora é só o markdown, sem o banco com os vetores. E o cron roda num notebook: nos dias em que ele está desligado às 3h, o backup não acontece. Olhando o log, tem uns dias faltando.

O próximo passo, quando eu tiver tempo, é mandar os tarballs para a minha nuvem. Ainda não fiz.

Sobre a versão 2.6

Atualizei para a 2.6 em 7 de outubro, o dia do lançamento. Duas novidades me chamaram a atenção.

A primeira é o perfil entre projetos. Ele detecta as preferências que repito em projetos diferentes e injeta um resumo no início de toda sessão. A ideia é boa.

No meu caso, a execução ficou fraca: das 200 entradas que ele gerou, 133 tinham evidência de um projeto só, e a mesma regra de código apareceu 24 vezes, cada uma com uma paráfrase. Por isso uso como lista de candidatos a regra, revisada à mão, e não deixo aplicar sozinho.

A segunda é o experience pass. Ele lê os resumos das últimas sessões e propõe procedimentos que se repetem. Liguei no mesmo dia, para rodar a cada 5 sessões novas, olhando as últimas 10. Pelo log, já rodou 75 vezes e fez 37 propostas.

Ainda não avaliei se essas propostas prestam.

Teve também um velho conhecido: o erro 429 voltou, em escala menor. Foram 10 vezes na madrugada do dia 8, na hora de unir as entradas do perfil. Dessa vez o sistema só manteve a versão mais nova e seguiu em frente. Vou ficar de olho.

O experience pass e a minha melhoria contínua

Eu já tinha um jeito de aprender com as sessões: uma skill chamada melhoria-continua. Ela nasce da regra do determinismo vira script e tem duas peças minhas e uma do AI Memory.

Já aviso: ainda estou tentando acertar essa parte. Mexo nela toda semana e ainda não sei qual é o arranjo certo.

A primeira, o recorrencia, é um script que conta o código que reescrevo nos comandos Bash entre sessões. A segunda é um registro de fluxo, onde anoto a sequência de passos que repito. A terceira são as lições, que ficam com o auto-improve.

O experience pass cai na segunda. Ele também procura sequências que se repetem entre sessões, só que sem eu preencher nada à mão, que é o ponto fraco do meu registro. Na primeira ele não entra: pelo que a leitura do código mostrou, o AI Memory não guarda o corpo dos comandos, então não enxerga código repetido.

O limite é a natureza da resposta. Ele devolve texto de LLM, sem contagem e sem vocabulário fechado. A spec do recorrencia já tinha descartado “modelo procurando repetição”, porque o resultado varia de uma execução para outra.

Aqui a busca semântica volta. O recorrencia hoje só agrupa por forma: se o código se repete quase igual, ele pega. O mesmo procedimento com código diferente fica de fora, como dois erros com a mesma causa e textos diferentes. É a mesma lacuna, vista de outro lado.

A minha regra do determinismo já avisava: a repetição semântica é a mais cara de enxergar, porque nenhum rg a encontra. Talvez o caminho seja usar embeddings para aproximar esses casos. Ainda não sei, e volto a isso quando entender melhor de RAG.

Então a pergunta que quero responder é simples: as propostas dele batem com os meus registros? Vou rodar num projeto de QA e comparar. Ainda não fiz.

Como começar

Você não precisa do AI Memory para isso. Um arquivo markdown por problema já resolve boa parte. O que importa é o hábito:

1. Separe o sintoma da causa raiz. Dois sintomas podem ter uma causa só.
2. Escreva o que não é o problema. Evita consertar o que está saudável.
3. Marque a hipótese como hipótese, com data. Quando cair, corrija a página.
4. Anote o que não resolveu. Pelo menos com o motivo e o que falta.
5. Leia antes de depurar. É o passo que eu mais esqueço.

O AI Memory entra para fazer a captura e a busca por você. A disciplina continua sendo sua.

Conclusão

Por fim, a ferramenta é a parte menos importante. O que mudou para mim foi tratar o problema resolvido como material de consulta.

Tenho só quatro meses de uso e ainda estou ajustando. A promoção para a wiki é manual, a consulta antes de depurar falha, e a memória erra. Mesmo assim, voltar atrás não está nos meus planos.

Espero que este artigo tenha ajudado a pensar no assunto. E você, onde moram hoje os problemas que já resolveu? Na sua cabeça, ou num chat que você nunca mais vai abrir?