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

> Como guardo os problemas que resolvo no AI Memory, o que a memória não faz sozinha e como isso conversa com a minha wiki curada.

- URL: https://iagofrota.com.br/blog/troubleshooting-com-ai-memory/
- Data: 2026-10-09
- Tags: ai-memory, troubleshooting, memoria-de-agentes, claude-code, anvilore, segundo-cerebro

Já faz uns quatro meses que uso o [AI Memory](https://github.com/akitaonrails/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](https://iagofrota.com.br/blog/como-resolver-o-problema-de-alto-consumo-de-cpu-pelo-processo-awcc-background-server-no-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](https://github.com/iagofrota/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.](https://iagofrota.com.br/blog/capturar-notas-e-facil-destilar-e-a-parte-que-doi/) e em [Mil páginas depois](https://iagofrota.com.br/blog/mil-paginas-depois-o-que-quebrou-na-minha-wiki-mantida-por-llm/). O método vem da wiki do [cooperacode](https://github.com/cooperacode/wiki-wonka) (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](https://iagofrota.com.br/blog/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?