A jornada para aprimorar a capacidade de 'memória' de agentes de código é um campo repleto de desafios. O desenvolvedor por trás do ai-memory, após uma experiência frustrante com o agentmemory, mergulhou de cabeça na criação de uma solução open source. A motivação veio da necessidade de um organizador de conhecimento mais robusto, que não 'saísse do caminho' durante sessões longas de desenvolvimento.
Em um post anterior, o autor havia recomendado o agentmemory como a solução ideal para a gerência de memória de agentes de código, inspirada na LLM Wiki de Karpathy. Contudo, após uma semana de uso em produção pessoal, a realidade se impôs, revelando problemas estruturais que inviabilizavam sua continuidade.
Por que o agentmemory não rolou?
Apesar de conter ideias promissoras, o agentmemory apresentou falhas significativas na prática. As dores de cabeça do dia a dia levaram o desenvolvedor a buscar uma alternativa.
“O agentmemory tem as ideias certas (LLM Wiki do Karpathy, consolidação em tiers, hooks de captura automática, MCP) mas a implementação tem problemas estruturais que doem em uso diário.”
Entre os problemas mais críticos, a reindexação do BM25 a cada reinício se destacou. Com mais de 10 mil observações, o processo de reconstrução do índice podia levar cerca de cinco minutos, com o arquivo persistido ficando vazio. A questão foi registrada no issue #309.
Outro ponto de falha era a janela de perda de dados de cinco segundos. Toda persistência no agentmemory passava por um debounce de cinco segundos do IndexPersistence. Quando o tempo limite de 30 segundos do state::set era ultrapassado, o processo Node encerrava abruptamente, resultando na perda de dados em memória, conforme detalhado no #204.
A inconsistência na leitura de configurações também gerou transtornos. O uso de process.env direto em um lugar e getMergedEnv() em outro gerava o cenário de “setei a variável e nada mudou”, um problema de configuração que pode ser encontrado no #456.
Além disso, um erro no hook para tool calls do Claude Code fez com que cerca de 47% das observações sumissem silenciosamente por seis semanas. O hook lia data.tool_output, enquanto o Claude Code enviava tool_response, um desencontro registrado no #539. Por fim, a execução da engine no diretório de trabalho do chamador causou problemas para usuários de Windows, que achavam que haviam perdido memórias por cada terminal abrir o state store em um caminho diferente ( #303).
Esses problemas, e outros documentados no repositório de pesquisa do autor ( aqui), indicam que a arquitetura do agentmemory – que envolve TypeScript MCP, iii-engine Rust separado, quatro portas, três processos e índices em memória persistidos via KV remoto – acumulava uma classe de bugs que não poderiam ser resolvidos sem uma reescrita substancial. A questão, segundo o autor, era estrutural, não uma falha de esforço do mantenedor.
A experiência com outras soluções testadas não foi diferente. Muitas se mostravam incompletas, excessivamente focadas em tecnologias específicas (como um vector DB proprietário ou um knowledge graph que exigia Neo4j) ou demandavam que o usuário acionasse manualmente o comando write_note para salvar informações. Nenhum desses sistemas oferecia a autonomia e a confiabilidade necessárias para sessões de trabalho prolongadas.
A necessidade de um organizador de conhecimento se fez clara desde o início da maratona de 37 dias de vibe coding do desenvolvedor. Após mais de 500 horas de experimentação, ele conseguiu cristalizar as funcionalidades que realmente buscava em uma solução.
Para quem utiliza apenas um dos três principais agentes (Claude Code, ou Codex, ou opencode), a necessidade de uma ferramenta extra pode ser menor, já que eles oferecem um gerenciamento razoável de memória dentro da sessão. O Claude Code, por exemplo, possui três níveis de compactação (microcompact por gap temporal, autocompact por threshold de token e o experimental sessionMemoryCompact). O Codex, por sua vez, conta com auto_compact_token_limit por modelo, e o opencode também dispõe de funcionalidades de compactação.