Em julho eu publiquei Novidades no meu AI-MEMORY, onde mostrei o ai-memory run: trocar de Claude Code pra Codex sem perder a linha de trabalho. Naquele dia estávamos na versão 1.17.1.

Hoje saiu a 2.0. E dessa vez não vou repetir como os hooks funcionam nem como uma sessão vira página de wiki. Isso já está nos textos anteriores. Aqui eu quero falar de onde o ai-memory chegou frente à concorrência, o que a 2.0 traz e por que ela mereceu virar um “2”.

Se você nunca ouviu falar do projeto, o resumo é curto. O ai-memory é um servidor de memória de longo prazo pros seus agentes de código. Ele captura o que aconteceu na sessão, consolida em páginas Markdown e devolve o contexto certo pro próximo agente, seja qual for o harness ou a máquina.

Essa é a interface web que vem junto, boa pra auditar o que os agentes gravaram e pra navegar entre os projetos. Repare que cada projeto vive separado, com sua própria contagem de páginas, tudo saído das sessões de verdade.

Por que virou 2.0

Pra mim, o primeiro número de uma versão carrega um compromisso.

A família 1.x cresceu rápido demais. Saímos da 1.1 e chegamos na 1.39 em pouco mais de dois meses, empilhando funcionalidade atrás de funcionalidade em releases menores. Funcionou pra iterar, mas embaralhou o significado dos números.

A 2.0 arruma isso. Ela junta as poucas mudanças que quebram compatibilidade num único major, e a partir daqui o versionamento passa a seguir Semantic Versioning de verdade. Correção vira patch. Funcionalidade nova vira minor. Só quebra de formato ou de contrato vira major, e sempre com aviso. O novo guia de contribuição deixa essa regra explícita pra qualquer PR.

A quebra principal é o novo formato em disco. Na primeira vez que você sobe a 2.0, ela migra sua wiki sozinha. Antes de mexer em qualquer coisa, ela compacta todo o seu diretório de dados num backup verificado com data no nome. Se o backup não puder ser gravado e conferido, a migração aborta e o servidor se recusa a subir. Nada de “confia em mim”.

Esse é o aviso que aparece uma vez, depois da migração: ele diz onde ficou o backup, o tamanho do arquivo e como voltar atrás se algo parecer errado. Quando você confirma que está tudo certo, é só apagar o backup e o lembrete some.

OKF: sua memória não fica presa no ai-memory

Essa é a mudança que mais me deixou satisfeito.

A partir da 2.0 a wiki do ai-memory é, nativamente, um bundle no Open Knowledge Format, o formato aberto que o Google publicou em 2026. Cada página de memória é um arquivo OKF válido: Markdown comum com metadados padronizados. Não existe passo de exportação que gera uma cópia divergente. Os arquivos da wiki já são os arquivos OKF.

Na prática isso quer dizer que sua memória deixou de ser refém do meu projeto. Você pode ler tudo com grep, abrir no Obsidian, versionar no Git ou entregar o bundle pra um colega que usa outra ferramenta compatível com OKF. Tem até um ai-memory export-okf pra empacotar um projeto inteiro num tarball validado.

Sempre foi essa a tese: modelo e harness são alugados, a memória do projeto é sua. Agora o formato reforça isso por escrito.

Embeddings locais, ligados por padrão

Até a 1.x, busca semântica de verdade dependia de você configurar um provider de embeddings. Ou pagava uma API e mandava cada página e cada query pra fora, ou subia um Ollama do lado. As duas opções têm custo.

A 2.0 traz um provider local que roda o modelo de embeddings dentro do próprio processo, em Rust puro, com o all-MiniLM-L6-v2. Sem chave de API, sem servidor externo, sem GPU e sem mandar seus dados pra lugar nenhum. E agora vem ligado por padrão. Na primeira execução ele baixa o modelo (uns 87 MB, com checksum fixo) em background e liga a busca híbrida no próximo restart.

O ganho é mensurável. No benchmark LongMemEval-S, o hit@5 sobe de 0.617 só com full-text para 0.779 com os embeddings locais. Se por algum motivo você não quiser, um embedding_provider = "none" desliga.

Detalhe que importa: escolhi candle de propósito, em vez do runtime nativo que a concorrência usa. Foi justamente essa camada nativa que gerou um tipo de crash recorrente em outros projetos de memória. Preferi não herdar o problema.

Vários agentes ao mesmo tempo, no mesmo projeto

Aqui começa a parte que motivou boa parte do trabalho antes da 2.0.

O caso do ai-memory run que mostrei em julho era sequencial: fecho o Claude, abro o Codex, continuo. Mas e quando eu deixo dois ou três harnesses abertos ao mesmo tempo no mesmo projeto? Claude numa aba, Codex noutra, OpenCode numa terceira.

O ai-memory trata isso sem ninguém pisar no pé do outro. Cada chamada de memória descobre sozinha a qual projeto pertence, a partir do diretório da sessão. O ponteiro de “projeto atual” agora é por ator, então dois harnesses no mesmo checkout mantêm cada um a sua noção de contexto. E a identidade do projeto vem do nome do checkout. O caminho absoluto no disco não pesa, então o mesmo projeto no laptop e no desktop cai no mesmo lugar.

Quando duas janelas gravam na mesma página, a segunda não apaga a primeira. Ela cria uma versão nova que passa a ser a mais recente, e a anterior continua alcançável na cadeia de versões. Regravar algo idêntico não gera versão nova. Todas as escritas passam por um único writer, com fila e backpressure, então uma rajada não corrompe nada.

Isso não é teoria. Tem teste de aceitação chamando Claude, Codex, OpenCode, Pi, Crush e mais alguns de verdade, dentro de uma mesma workstream, cobrindo lease, adoção de sessão e entrega de contexto entre harnesses.

Um time inteiro no mesmo projeto

O segundo cenário é o que dá título ao post. Aqui já são várias pessoas, um time inteiro apontando os agentes pro mesmo servidor.

A forma de rodar é simples. Alguém sobe um servidor, normalmente um container num homelab ou numa máquina da rede, e cada pessoa aponta os agentes dela pra aquela URL. HTTPS entra na frente com um proxy reverso, se você quiser. O banco continua sendo um SQLite só.

Todo mundo enxerga as mesmas páginas do projeto. O que uma pessoa aprendeu numa sessão, o agente da outra recupera. E cada sessão nova recebe um briefing com o estado do projeto logo no início. Vou ser honesto com o termo “tempo real”. O que existe é um store central compartilhado, com leitura imediata, mais o briefing na abertura. A nota que um colega gravou aparece na hora pra próxima consulta ou próxima sessão de qualquer um. Uma sessão que já está rodando só recebe a novidade na consulta seguinte ou na próxima abertura, sem interrupção no meio.

O que muda no modo multiusuário é a atribuição. Cada escrita registra quem fez. Existe log de auditoria e a interface mostra “editado por fulano”. Isso já vem no pacote, de graça. E não existe permissão por página, de propósito. A atribuição serve pra registrar autoria; qualquer pessoa autenticada pode escrever, e o histórico é que guarda quem foi.

Tem uma distinção de segurança importante entre o que é compartilhado e o que é pessoal. As páginas são de todos. Mas o handoff é um bastão de um dono só: exatamente uma sessão pega, e um segundo accept não rouba o bastão de ninguém. O handoff que você deixou pendente não é entregue nem consumido por um colega. Do mesmo jeito, os “slots” de “no que estou trabalhando agora” são por pessoa, então o seu contexto pessoal não vaza no briefing do time inteiro.

Também existe uma bateria de testes de concorrência real cobrindo esses casos: escrita simultânea, isolamento por ator sob carga, o bastão do handoff que não é roubado e os slots pessoais que não vazam.

Onde o ai-memory fica frente à concorrência

Antes da 2.0 fizemos outra rodada de pesquisa sobre o cenário de 2026, documentada no repositório. Ela foi a base pra decidir o que a 2.0 precisava cobrir. Vou resumir o campo.

Tem o agentmemory, que é um MCP server em TypeScript preso a um sidecar nativo e a uma superfície gigante de dezenas de ferramentas. Tem o basic-memory, em Python, Markdown no disco, mas com captura manual: você tem que pedir pra ele lembrar. Tem o cognee, que junta grafo, vetor e relacional num pipeline pesado que pede vários gigas de RAM. Tem o MemPalace, que viralizou com quase 50 mil estrelas em duas semanas por causa de um número de benchmark que, auditado, se mostrou inflado, além de sofrer de corrupção quando duas escritas acontecem juntas. E tem os grafos temporais como Zep, os “memory OS” como Letta (o antigo MemGPT) e os extratores de fato como o Mem0.

Tem ainda a memória nativa que o próprio Claude Code passou a ligar por padrão. Essa eu trato como o funil que apresenta a categoria pras pessoas. Como concorrente ela fica limitada: presa a uma máquina, presa a um agente, sem busca de verdade e sem história de time.

A 2.0 fecha as lacunas que a pesquisa apontou. Passamos a publicar benchmark reproduzível com o LongMemEval, rodando o servidor de verdade. Ganhamos o formato aberto OKF. Ganhamos ligações tipadas entre páginas, com causes, fixes e contradicts, que ainda alimentam uma checagem de contradição sem gastar LLM. Ganhamos consulta com as_of, pra perguntar o que a gente sabia sobre um assunto numa certa data. Ganhamos os embeddings locais. E ganhamos uma passada opcional de “experiência” que revê várias sessões pra achar padrões que só aparecem no conjunto.

Agora a parte que interessa pra quem vai escolher. O que o ai-memory tem que os outros não têm, tudo junto:

• Ele te acompanha entre agentes. Mais de vinte harnesses alimentam uma memória só, e o handoff aqui é um protocolo de verdade: tipado, com dono e reivindicado uma vez só.
• Ele te acompanha entre máquinas. A memória vive num servidor que é seu. O projeto que você largou no desktop é o que você retoma no laptop.
• Ele funciona pra time. Autenticação multiusuário, atribuição por pessoa e log de auditoria já vêm no pacote, de graça.
• Sua memória é Markdown puro. A fonte da verdade é uma wiki versionada no Git. O banco é um índice derivado que dá pra reconstruir a qualquer momento a partir dos arquivos, sem vector store pra ficar de babá e sem nada preso num blob binário.
• Ele captura o trabalho sozinho e em silêncio. Sem cerimônia de “lembra disso”. E o caminho padrão roda com zero chamada de LLM.
• Ele é um binário só. Sem sidecar, sem três bancos pra sincronizar. Todas as escritas passam por um único writer, com um teto de escrita que a gente mediu de verdade, com teste real. Foi exatamente esse desenho que evitou a corrupção de escrita concorrente que derrubou os outros.

Nenhum concorrente entrega esse conjunto. Alguns têm um ou outro pedaço. O ai-memory tem o pacote, e agora com paridade nos itens onde antes ficava atrás.

A 2.0 é de todo mundo

Quando escrevi o post de julho, quinze pessoas tinham PR mergeado no projeto. Hoje são cerca de setenta. Faz tempo que isso deixou de ser um programinha de fim de semana.

Os números até a 2.0: mais de 1.500 commits, 371 pull requests mergeados e 181 issues fechadas. Isso saiu de gente usando de verdade e mandando correção, funcionalidade e documentação.

Preciso agradecer em especial ao Djalma Júnior, que sozinho passou de 50 PRs mergeados, e ao Samir Hanna Verza, com mais de 20. Logo atrás vêm lhzapata, pedrofjr, mrpaiva, lucasliet, lihuiyang1024, Murillofilho86 e Matheus Rodrigues. E tem uma cauda longa de dezenas de outras pessoas com PR mergeado que seria injusto tentar listar inteira aqui.

Se você quer entrar nessa, o guia de contribuição foi reescrito pra deixar tudo claro: como configurar o ambiente, os gates que o CI cobra, a regra do CHANGELOG e a política de versionamento. Bug fix costuma sair rápido no próximo patch. Funcionalidade pequena, como um novo harness ou provider, entra no próximo minor. Tem issue marcada pra quem está começando.

Como pegar a 2.0

A página do projeto tem todos os métodos de instalação, incluindo AUR, Homebrew e binários de release:

• ai-memory no GitHub
• Notas da release v2.0.0

Depois de atualizar, na primeira execução deixe a migração fazer o backup e converter sua wiki pro formato OKF. Se você usa o modo gerenciado, reinstale os hooks dos harnesses que pretende usar.

Conclusão

A 1.x provou que a ideia funcionava. A 2.0 é a versão que eu recomendaria sem asterisco pra outra pessoa botar num time.

O formato é aberto, então sua memória não fica presa. A busca semântica roda local, então você não paga nem vaza. Vários agentes e várias pessoas trabalham no mesmo projeto sem se atropelar. E o desenho de um binário só, com um writer só, é o que evita justamente os problemas que afundaram metade da concorrência.

LLM e assinatura eu continuo alugando de quem estiver melhor no mês. A memória do projeto fica comigo, com o time, e agora num formato que ninguém tira de mim.

No mesmo dia saiu a versão 1.1.0. Hoje, 20 de julho, estamos na 1.17.1.

Versão sozinha não quer dizer grande coisa, então fui contar o que aconteceu de verdade desde o horário daquele post. Foram 31 releases, 55 pull requests mergeados e 46 issues fechadas. Eu contei 24 grupos de funcionalidades novas voltadas ao usuário no CHANGELOG, ignorando correções, documentação e detalhes internos da mesma entrega. Se eu quebrasse a nova família ai-memory run em auto-seleção, adoção de sessão, suporte a Crush, --yolo, busca e recuperação, passava disso fácil.

Quinze pessoas tiveram PRs mergeados nesse período, quatorze além de mim. Preciso agradecer em especial ao Djalma Júnior, que sozinho teve 24 PRs mergeados, Matheus Rodrigues, com cinco, lhzapata, com quatro, Thiago Silva e Cristiano Dewes, com dois cada. Mais nove contribuidores tiveram PR mergeado. Faz tempo que isso deixou de ser “um programinha que eu fiz num fim de semana”.

Não vou despejar 55 PRs aqui. Quero falar da mudança que mais afeta meu uso diário: o novo ai-memory run.

A sessão também faz parte do projeto

Código é o resultado que sobreviveu. Ele não guarda a investigação inteira.

O Git mostra que você trocou Redis por SQLite. Talvez o commit explique uma parte. Mas onde ficou o experimento com Redis? Onde está o bug intermitente que só aparecia com dois workers? Quem lembrou que a primeira solução quebrava no Windows? Por que o time mudou de ideia depois de três horas? Qual workaround era temporário e qual virou decisão?

Boa parte disso só existe na sessão do agente.

Quando programo com Claude Code ou Codex, a sessão acumula o raciocínio operacional do projeto: perguntas, correções, tentativas descartadas, resultados de testes, surpresas, decisões e mudanças de direção. O código final mostra o que ficou. A sessão explica por que chegamos ali.

E sessão de LLM, no fim das contas, é texto. Claude Code grava JSONL. Codex também. OpenCode usa SQLite. Pi, OMP e Crush têm seus próprios formatos e diretórios. Cada harness empacota a conversa de um jeito, mas o conteúdo visível continua sendo mensagens e resultados de ferramentas.

Por que eu deveria deixar a parte mais cara do trabalho presa ao harness?

Anthropic pode mudar limite, preço, modelo ou formato amanhã. OpenAI também. Um agente pode estar excelente esta semana e insuportável na próxima. Eu quero trocar o motor sem jogar fora a viagem inteira.

Essa é a tese do ai-memory desde o começo: o programador tem que continuar independente das vontades dos providers. Modelo e harness são substituíveis. A memória do projeto é minha.

O handoff resolvia só metade

O ai-memory já fazia passagem de bastão. Eu encerrava Claude Code, os hooks consolidavam a sessão e o Codex seguinte recebia um resumo curto com o que foi feito, perguntas abertas e próximos passos.

Isso continua existindo e continua útil. Quem abre claude, codex ou opencode diretamente mantém o comportamento anterior. O launcher novo é opt-in.

Mas handoff é uma compressão deliberadamente lossy. Ele preserva o que parece mais importante naquele momento. Não pretende transportar a sessão inteira, nem retomar a sessão nativa de cada harness. Se o resumo omitiu uma tentativa antiga que voltou a ser relevante duas horas depois, você precisa procurar na wiki ou nos registros.

O ai-memory run acrescenta outra camada: uma workstream gerenciada, uma linha de trabalho que atravessa os harnesses.

Claude hoje, Codex daqui a pouco

O uso básico é esse:

cd ~/Projects/meu-projeto

ai-memory run claude
# trabalha, encerra o Claude Code normalmente

ai-memory run codex --yolo
# Codex continua a mesma linha de trabalho

ai-memory run claude --model opus
# volta pra sessão nativa anterior do Claude

ai-memory run
# ou deixa o ai-memory escolher o harness certo pra continuar

Não precisa de -- pra separar os argumentos. Tudo depois do nome do harness segue pra ele, com uma exceção proposital: o --yolo pertence ao wrapper e é traduzido pra opção perigosa nativa de Claude Code, Codex, OpenCode, Pi ou Crush.

Por baixo, o ai-memory não tenta converter um arquivo do Codex num arquivo do Claude. Isso seria frágil e provavelmente quebraria na próxima atualização. Cada harness mantém sua própria sessão nativa. A workstream liga essas sessões a um ledger portátil com a parte visível da conversa.

Pensa assim:

sessão nativa do Claude ─┐
sessão nativa do Codex  ─┼─ workstream ─ contexto portátil
sessão do OpenCode      ─┤                 + busca completa
sessão nativa do Pi     ─┘

Na primeira vez que Claude entra naquela workstream, ele ganha uma sessão nativa. Quando você troca pra Codex, o Codex ganha a sessão nativa dele e recebe o delta portátil que ainda não viu. Ao voltar pro Claude, o launcher usa o --resume do próprio Claude Code e entrega apenas o que aconteceu nos outros harnesses desde a última vez.

Isso é bem diferente de começar um chat novo com um resumo colado no prompt. O Claude volta pra sessão real dele. O Codex volta pra sessão real dele. O ai-memory cuida da continuidade entre os dois.

Hoje o modo gerenciado suporta Claude Code, Codex, OpenCode, Pi, Crush e OMP. O suporte geral do ai-memory é maior, com MCP e hooks pra outros clientes, mas isso não quer dizer que todo cliente já tenha adapter de sessão nativa pro run. São contratos diferentes e eu prefiro deixar isso explícito.

O que entra na workstream

Quando o harness encerra, o ai-memory lê o final da sessão nativa sem modificar o store original. Entram mensagens visíveis de usuário e assistente, tool calls concluídas com seus resultados, resumos de compaction e um checkpoint não mutante do Git. Cada evento mantém a origem: veio do Claude, Codex, OpenCode, Pi, Crush ou OMP.

Credenciais do provider, registros criptografados, system/developer prompts e hidden reasoning ficam de fora. Formatos privados que o adapter não entende também ficam de fora e geram uma anotação de perda, em vez de o sistema fingir que importou tudo.

Os registros passam pelo sanitizer antes de entrar no ledger pesquisável e nos segmentos JSONL imutáveis do ai-memory. Os stores nativos são abertos read-only pelo adapter; quem continua escrevendo neles é o próprio harness.

Também não enfio a sessão inteira no próximo prompt. Isso recriaria o problema que o projeto tenta resolver: contexto bruto demais, caro demais e cheio de ruído. O próximo agente recebe um delta recente com tamanho limitado. Se uma decisão velha voltar a importar, o ledger completo continua pesquisável:

ai-memory workstream-search "por que desistimos do Redis"
ai-memory workstream-search --limit 50 --json "migration que falhou"

Dentro de um ai-memory run, o ID da workstream já entra no ambiente. O agente não precisa descobrir UUID nenhum.

E o ledger não substitui a wiki. Ele resolve continuidade operacional. Decisões, regras, procedimentos e gotchas que precisam sobreviver por meses continuam merecendo páginas Markdown consolidadas. Sessão bruta é evidência. Wiki é conhecimento organizado.

Posso manter mais de uma linha de trabalho?

Sim. A workstream padrão se chama default, selecionada por repositório e worktree. Se eu quiser abrir uma linha independente pra uma investigação sem contaminar o trabalho principal:

ai-memory run --new investigar-race claude

# depois continuo aquela linha com outro harness
ai-memory run --workstream investigar-race codex

Uma lease impede duas janelas de escreverem ao mesmo tempo na mesma workstream. Em encerramento normal, o launcher importa o final da sessão e libera imediatamente. Se alguém matar o processo sem cleanup, a lease expira em até 90 segundos e a próxima execução retoma do último cursor confirmado, sem duplicar os eventos já importados.

Uma irritação besta que eu tinha o tempo todo: voltava pra um projeto depois de alguns dias e não lembrava se a sessão mais recente estava no Claude ou no Codex. Eu chutava um, abria, percebia que o contexto estava no outro, fechava e tentava de novo.

Agora só rodo:

ai-memory run

# ou com a mesma seleção automática em YOLO mode
ai-memory run --yolo

Numa workstream vazia, o ai-memory procura sessões locais daquele checkout em Claude Code, Codex, OpenCode, Pi e Crush, descobre qual é a mais recente e abre o harness certo pra mim. Numa workstream já estabelecida, a memória do servidor vence o timestamp de arquivo: ele volta ao último harness ligado àquele trabalho, em vez de adotar por engano uma sessão velha que só recebeu uma gravação mais recente. OMP continua disponível quando escolhido explicitamente, mas ainda não participa da seleção automática.

Na primeira execução explícita, o launcher também pode oferecer sessões existentes do mesmo checkout pra adoção. Dá pra começar a usar sem abandonar o chat que já estava aberto antes de atualizar o ai-memory.

Outras novidades que eu realmente uso

Eu prometi não ler o changelog inteiro em voz alta, mas algumas mudanças desse mês merecem menção porque reduzem trabalho do programador.

Briefing antes da primeira pergunta

Um projeto pode pedir um briefing automático no início de cada sessão:

[briefing]
inject_on_session_start = "true"
max_chars = 4000

O ai-memory recompõe um pacote com páginas pinned, _rules/, _slots/ e títulos recentes. O agente começa sabendo as regras e o estado básico do projeto, em vez de gastar a primeira conversa redescobrindo a arquitetura. É opt-in porque consome contexto em todo SessionStart, inclusive depois de um /clear do Claude.

Preferências globais e busca entre projetos

Preferências que valem pra todo meu trabalho agora podem viver no escopo reservado _global: estilo de código, ferramentas que prefiro, regras pessoais e convenções que não pertencem a um repositório específico. Consultas normais já fazem union desse escopo com o projeto atual.

Pra meta-repos que precisam consultar vários projetos irmãos o tempo todo, existe outro opt-in:

[recall]
default_global = "true"

Assim memory_query e memory_recent sem escopo explícito procuram em todos os projetos. Não ligo isso em qualquer repo porque busca global à toa só traz ruído.

Menos instrução fixa, mais Agent Skills

O bloco de routing em CLAUDE.md ou AGENTS.md ficou pequeno. As instruções detalhadas de quando buscar memória, consolidar, guardar decisão ou criar handoff foram movidas pra Agent Skills gerenciadas. Um comando instala ou atualiza os dois sem atropelar o resto do arquivo:

ai-memory install-instructions

Isso também reduz drift. Quando o protocolo muda, atualizo o pacote gerenciado em vez de caçar um prompt velho copiado em quarenta repositórios.

Privacidade antes da rede

Agora cada repo pode excluir caminhos da captura:

[capture]
ignore_paths = ["private/**", "~/personal-notes/**"]

Quando uma integração reconhece uma file tool e o caminho bate, o evento é descartado localmente antes de spool, fila, rede ou servidor. Isso tem limites claros: não é DLP mágico, não interpreta qualquer shell command e não rastreia conteúdo citado em texto livre. Mas resolve o caso verificável sem vender uma garantia falsa.

Também entraram integrações com Kimi Code, Grok Build CLI, Devin e Zero, um provider OpenCode Zen/Go, finalize-session pro Codex e melhorias na administração de workspaces. Reforço: ter MCP e hook não significa automaticamente ter ai-memory run. O README separa esses níveis.

Bônus: ai-jail por fora, YOLO por dentro

Há pouco mais de uma semana escrevi como me protejo pra agentes não apagarem minhas coisas. Minha recomendação continua a mesma: YOLO mode dá a melhor experiência, desde que o sistema limite o estrago possível.

O ai-jail chegou à versão 1.15.0 e agora entende o launcher do ai-memory. O jeito que mais estou gostando de trabalhar virou:

ai-jail ai-memory run codex --yolo

Ou, se quero que o ai-memory escolha qual harness deve continuar:

ai-jail ai-memory run --yolo

A ordem importa. ai-jail fica por fora para manter tanto o launcher quanto o processo filho na mesma sandbox. ai-memory run sozinho gerencia a sessão, mas não cria sandbox.

O --yolo desliga a cerimônia de aprovação do harness. O ai-jail faz a contenção: projeto atual read-write, home substituído por tmpfs, partes necessárias do estado dos agentes montadas seletivamente e diretórios sensíveis como .ssh, .gnupg e .aws fora da jaula. O suporte novo também deixa o estado local do ai-memory gravável pros hooks manterem spool e cursores entre execuções.

ai-jail reconhece tanto a camada ai-memory quanto o harness selecionado. Se você tem configuração global específica pra Codex, por exemplo, ela continua sendo aplicada quando o comando real é ai-memory run codex. Até o ajuste de redraw da status bar entende que o filho é Codex.

Essa combinação resolve as duas irritações ao mesmo tempo: o agente para de pedir confirmação a cada comando e a sessão para de pertencer ao agente. Fluidez sem dar o home inteiro de presente.

One more thing: ai-usagebar também cresceu

Quando publiquei o ai-usagebar original, ele monitorava Claude, Codex, Z.AI e OpenRouter num widget da Waybar ou numa TUI. A versão 0.14.0 já cobre onze integrações de uso, gasto ou saldo.

Kimi ganhou as duas informações que realmente importam pra coding: quota semanal da assinatura e janela móvel de cinco horas. Kilo, Novita, Moonshot e Grok mostram saldo restante. Uma integração separada da Anthropic Console mostra gasto de API no mês, sem confundir isso com a assinatura do Claude Code. Ela deixa explícito que o Cost API não inclui Priority Tier.

Também dá pra cadastrar várias contas da Anthropic, ver limites semanais específicos de modelos como Fable e enxergar um marcador de ritmo. A barra não fica vermelha só porque chegou em 40%; ela compara o percentual gasto com quanto da janela já passou. Se usei 40% em 20% da semana, estou rápido demais. Essa é a informação útil.

O projeto deixou de ser só Waybar. Tem app nativo de menu bar no macOS, extensão do GNOME e a TUI standalone. E a novidade mais recente é um monitor local de contexto do Claude Code: aperto c, escolho uma das sessões recentes e vejo quanto da janela já foi consumido. Ele lê caudas limitadas dos JSONL locais e não inventa porcentagem quando não consegue determinar o tamanho da janela.

No meu fluxo, o trio acaba se encontrando naturalmente. ai-usagebar mostra qual assinatura ainda tem espaço. ai-memory run troca de harness sem jogar fora o trabalho. ai-jail deixa o escolhido trabalhar em YOLO sem acesso irrestrito à máquina.

Atualizando

As páginas de instalação dos três projetos têm todos os métodos, incluindo AUR, Homebrew e binários de release:

• ai-memory
• ai-jail
• ai-usagebar

Depois de atualizar o ai-memory, reinstale os hooks dos harnesses que pretende usar no modo gerenciado. Os três principais no meu caso:

ai-memory install-hooks --agent claude-code --apply
ai-memory install-hooks --agent codex --apply
ai-memory install-hooks --agent opencode --apply

Crush não precisa de hook no modo gerenciado; ele recebe o contexto por um arquivo temporário configurado só pro processo lançado. A documentação de managed workstreams tem os detalhes de instalação, privacidade, recuperação e os argumentos nativos de cada adapter.

Conclusão

Um mês atrás, o ai-memory já conseguia transformar sessão em wiki e entregar um handoff pro próximo agente. Agora ele consegue gerenciar a própria linha de trabalho: adota uma sessão existente, mantém uma sessão nativa por harness, transporta o histórico visível, retoma cada cliente no formato dele e deixa o ledger inteiro pesquisável.

Pra mim, é aí que está o valor. O código contém a implementação que venceu. A sessão contém as decisões, experimentos que falharam, gotchas, bugs inesperados e mudanças de ideia que produziram aquela implementação. Jogar isso fora toda vez que muda de provider é desperdício.

Raw transcript também não resolve sozinho. É grande, repetitivo e caro pra enfiar em qualquer contexto. O ai-memory mantém a evidência, entrega só o delta recente e usa consolidação pra transformar o que merece sobreviver em páginas Markdown curtas.

Ainda há formatos novos pra suportar, arestas de plataforma e muito teste pela frente. A diferença é que agora existe uma base real, com acceptance test chamando harness de verdade, 14 contribuidores externos com PR mergeado em pouco mais de um mês e uso diário empurrando o desenho.

LLM e assinatura eu alugo de quem estiver entregando melhor hoje. A sessão do meu projeto fica comigo.

Hoje quero falar do outro lado: pra que isso serve no dia a dia e como o projeto incorpora uma ideia inspirada no Hermes Agent: um loop de auto-aprendizado com validação, trilha de auditoria e uma opção de revisão manual quando você quer mais controle.

Se você caiu de paraquedas, a sequência até aqui foi:

1. Primeiro escrevi sobre memória de agentes, Karpathy LLM Wiki e agentmemory. Ali eu ainda estava avaliando o agentmemory original.
2. Depois eu publiquei o post principal: criei um sistema de memória pra agentes de código: ai-memory. Esse é o texto que explica a base do projeto.
3. No toolkit de IA, eu posicionei o ai-memory junto com ai-jail e ai-usagebar: ferramentas pequenas pra resolver dores reais de quem usa agentes todo dia.
4. E ontem veio o post de arquitetura emergente, mostrando como o projeto evoluiu com contribuidores.

Esse post é a continuação prática. A ideia do ai-memory é transformar sessões longas de desenvolvimento numa wiki de projeto que um agente consegue consultar daqui a semanas, sem você virar suporte humano de contexto.

O problema real: sessão longa vira amnésia longa

Quem usa Claude Code, Codex, OpenCode, Cursor, Gemini CLI ou qualquer agente desses já conhece o ciclo. Você começa uma sessão, explica o projeto, mostra os arquivos importantes, corrige uma alucinação, descobre uma armadilha, decide uma arquitetura, roda teste, falha, corrige, roda de novo. Depois de duas horas, o agente finalmente está “aquecido”. Ele sabe o que não deve fazer. Sabe onde estão os buracos. Sabe que aquela função parece errada mas existe por compatibilidade legada. Sabe que o teste só passa se subir o serviço X antes.

Aí a sessão acaba.

No dia seguinte você abre outro agente, ou o mesmo agente em outra janela, ou troca de Claude Code pra Codex porque quer comparar. E começa tudo de novo. “Não, esse projeto usa isso.” “Não, já tentamos esse caminho.” “Não, essa API não existe.” “Não, esse arquivo é gerado.” Você vira o cache humano do agente.

Janela de contexto grande ajuda só até certo ponto. Ela pertence à sessão atual, não ao mês inteiro do projeto. E contexto bruto continua sendo contexto bruto. Jogar cem mil tokens de log dentro do prompt é diferente de ter uma página curta dizendo:

• decisão: usamos SQLite como índice derivado, markdown é a fonte da verdade;
• armadilha: no Windows não confie em inode, use índice próprio;
• regra: não editar content/_index.md manualmente, rodar o gerador;
• procedimento: pra publicar post novo, escrever PT primeiro, humanizar, validar Hugo, só traduzir depois de aprovação.

Isso é memória útil. Não é transcrição. É síntese.

O modelo mental: Karpathy Wiki

O nome que eu gosto pra esse padrão é o que o Karpathy chamou de LLM Wiki: em vez de depender de histórico bruto, você mantém uma wiki em markdown, versionada, que o agente consegue consultar. Páginas pequenas, com nomes estáveis, separadas por tipo de conhecimento. O agente não precisa lembrar tudo. Ele precisa saber procurar.

O ai-memory implementa isso com uma ideia simples: hooks capturam o que aconteceu, o servidor organiza o material numa wiki markdown e os agentes consultam essa wiki quando precisam continuar o trabalho.

Algumas páginas são resumos de sessão. Outras viram decisões, armadilhas, procedimentos ou regras do projeto. O usuário não precisa decorar a taxonomia. O ponto é que o conhecimento deixa de ficar preso na janela do chat e passa a existir como arquivo legível.

Repara nessa última parte: a fonte de verdade é markdown. Você pode abrir no Obsidian, fazer grep, versionar, fazer backup com rsync, ver diff no git. O banco SQLite ajuda na busca, mas é índice derivado. Se amanhã eu jogar o banco fora, o sistema consegue reconstruir o índice a partir da wiki.

É aqui que eu fico chato. Quero arquivo que eu consigo ler, não uma caixa-preta de embeddings que “talvez” lembre.

A base: memória que atravessa agentes

Desde cedo, o ai-memory já resolvia a dor principal: contexto que sobrevive ao agente usado naquele momento.

Você podia encerrar uma sessão no Claude Code, abrir Codex no mesmo diretório, e o próximo agente receber um resumo curto dizendo onde parou, quais perguntas ficaram abertas e quais próximos passos faziam sentido.

Além disso, o agente podia consultar a wiki antes de responder. Em vez de depender só do que ainda cabe na janela de contexto, ele podia procurar decisões antigas, armadilhas conhecidas, páginas recentes e regras permanentes do projeto.

Na prática, o agente para de responder arquitetura no chute. Ele pode consultar: “o que a gente decidiu sobre autenticação?”, “já tentamos usar Redis aqui?”, “qual era a armadilha do Docker nesse projeto?”. E o resultado não vem como mil eventos crus, vem como página de wiki.

Em projeto de software isso faz diferença porque “qual arquivo existe” é a parte fácil. Isso o agente acha com grep. O conhecimento caro é por que uma coisa é daquele jeito. Por que deixamos biblioteca X de lado. Por que esse teste é estranho. Por que a configuração de CI tem uma exceção. Por que aquela refatoração foi adiada.

É isso que uma memória de longo prazo precisa preservar.

O que veio do uso real

Ontem eu citei alguns números e agradeci contribuidores, mas vale reforçar as funcionalidades novas porque elas mudam o perfil do projeto. O ai-memory deixou de ser “meu daemon local” e virou algo que dá pra rodar num homelab ou servidor compartilhado.

O resumo das mudanças é:

• Dá pra usar sozinho ou em equipe. O sistema agora entende usuários, projetos e workspaces. Isso permite rodar num homelab ou servidor compartilhado sem misturar clientes, repositórios e sessões.
• O escopo ficou previsível. Um arquivo .ai-memory.toml pode dizer a qual projeto aquele diretório pertence. Isso ajuda em monorepos, worktrees, consultoria e separação trabalho/pessoal.
• Mais agentes conseguem participar. Além de Claude Code, Codex e OpenCode, entraram Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, OpenClaw, Oh My Pi/OMP, VS Code GitHub Copilot e Claude Desktop. Alguns têm hooks completos, outros só conseguem consultar via MCP, mas todos podem se beneficiar da mesma wiki.
• Administração e recuperação ficaram menos frágeis. Renomear ou mover projetos, restaurar páginas, reconstruir índice, usar a interface web e auditar mudanças são recursos chatos de explicar, mas importantes quando a ferramenta vira parte do fluxo diário.

Não vou entrar em cada detalhe aqui. Pra isso existe a documentação no GitHub. O importante é entender a mudança de categoria: deixou de ser um daemon local meu e virou uma memória compartilhável de projeto.

Isso veio de uso real. Djalma Júnior, wlech, Pedro de Freitas Jr, Mauro Couto de Paiva, Gustavo Cateim, Lucas Oliveira, Pablo Winter, azevedo-luis, zanlucathiago e outros foram empurrando o projeto pra cenários que eu não tinha previsto. É assim que software cresce sem virar arquitetura de PowerPoint: a necessidade puxa a arquitetura, não o contrário.

Auto-improve: sessão vira memória

Hoje, o ai-memory já tem um loop de auto-aprendizado seguro: quando há um provedor de LLM configurado, um job de fundo pode revisar sessões novas, separar ruído de aprendizado real e transformar as lições úteis em páginas duráveis da wiki.

Esse é o ponto que importa pro usuário: você não precisa lembrar de abrir um arquivo de notas no fim do dia, nem escrever manualmente “aprendizados da sessão”. Se a sessão revelou uma decisão, uma armadilha reproduzível ou um procedimento que vale repetir, o sistema consegue promover isso pra memória de projeto.

Por baixo, ele usa a sessão consolidada, procura sinais fortes, pede pra um LLM sugerir edições pequenas, valida caminhos, evidência, tamanho e confiança, registra a proposta numa trilha de auditoria e aplica a escrita pela trilha normal da wiki.

Se você quiser revisão humana antes da escrita final, basta configurar [auto_improve] require_approval = true. Aí as propostas ficam pendentes até alguém revisar, aprovar ou rejeitar.

No diagrama acima ele aparece do lado de manutenção, nas tarefas que dependem de LLM configurado. Não é parte do caminho quente do hook. Isso é de propósito. Hook tem que capturar rápido, devolver 202 ou 429, e sair da frente. Revisão com LLM é outra categoria de trabalho.

O detalhe importante: isso não entra no caminho quente do agente.

O usuário continua trabalhando normalmente. Hooks capturam a sessão. A passagem de bastão continua curta e acionável. O auto-improve roda como manutenção: olha pra trás, identifica o que merece sobreviver e transforma aprendizado em memória consultável. A funcionalidade existe pra responder uma pergunta:

“O que essa sessão ensinou que vale transformar em memória permanente?”

E a resposta vira conhecimento reaproveitável, com rastro de proposta e evidência, não um chute solto dentro do prompt.

Isso parece pequeno, mas é a diferença entre uma memória útil e um agente que polui seu projeto com lixo confiante. Se você deixa um LLM escrever regra automaticamente toda vez que algo dá errado, em uma semana sua wiki vira cemitério de superstição: “nunca use ferramenta X”, “sempre rode comando Y”, “biblioteca Z está quebrada”. Só que muitas dessas coisas eram falhas transitórias: PATH errado, token expirado, rede fora, dependência desatualizada, erro corrigido cinco minutos depois.

Memória ruim é pior que falta de memória. Falta de memória te obriga a perguntar. Memória ruim te dá certeza falsa.

O que é Hermes Agent

A inspiração veio do Hermes Agent, que trata aprendizado como parte do ciclo normal do agente. Depois de trabalhar, ele pode olhar pra trás e perguntar: “isso gerou alguma memória ou skill útil para a próxima vez?”

O ponto que me interessou foi a separação. O agente faz o trabalho primeiro. Depois, em segundo plano, revisa o que aconteceu. Existe também uma manutenção mais lenta, que procura conhecimento velho, duplicado ou pouco útil. Um loop aprende com a sessão; o outro limpa o jardim.

Essa separação evita o erro comum de criar um daemon mágico que muda tudo o tempo todo. Parece poderoso, mas fica impossível de confiar. Se quiser detalhes do estudo, deixei isso na documentação do loop de auto-improvement.

Como adaptamos Hermes pro ai-memory

O ai-memory não copia Hermes literalmente. Hermes trabalha com memórias e skills. O ai-memory trabalha com páginas de wiki. Então a adaptação é simples: quando uma sessão ensina algo útil, o sistema tenta transformar isso em uma página pequena, legível e consultável.

O LLM sugere, mas o produto impõe fronteiras. A sugestão precisa ter evidência, caminho válido, tamanho razoável e confiança mínima. Isso evita que uma sessão confusa contamine a wiki inteira.

O desenho atual é esse:

1. A sessão termina e vira sessions/<id>.md como já acontecia.
2. Um job de fundo revisa sessões concluídas elegíveis, depois do watermark inicial e da idade mínima configurada.
3. O revisor procura decisões, armadilhas, procedimentos e regras que valem guardar.
4. O sistema valida a sugestão e registra o rastro de auditoria.
5. Por padrão, a memória entra na wiki; se você quiser, pode exigir revisão manual antes disso.

Essa trilha é a peça que faltava entre “o LLM sugeriu” e “isso virou verdade do projeto”. Memória de projeto não pode ser uma caixa-preta.

O tipo de coisa que deve virar memória

Essa parte é mais importante que a ferramenta: nem tudo que acontece numa sessão merece virar memória permanente.

O que vale guardar é o que ajuda o próximo agente a trabalhar melhor: uma decisão que afeta o futuro, uma armadilha reproduzível, um procedimento que vai se repetir, uma preferência explícita do usuário ou um padrão importante do projeto.

O que não vale guardar é ruído: um comando de teste, um erro transitório, uma falha causada pelo ambiente daquele dia ou uma narrativa inteira de sessão que já está preservada em sessions/.

Esse filtro é a diferença entre uma wiki que ajuda e uma wiki que atrapalha. O auto-improve não existe pra capturar mais coisa. Existe pra promover seletivamente o que merece sair da camada episódica e entrar na memória durável do projeto.

Hooks, MCP e prompts: a parte que deixa usável

A outra metade do sistema é menos glamourosa, mas é o que faz parecer natural. O usuário trabalha normalmente. Os hooks capturam o ciclo da sessão. O MCP dá ao agente um jeito de consultar a memória. E o bloco de instruções em CLAUDE.md ou AGENTS.md ensina quando usar tudo isso.

Quando a integração é completa, a experiência fica quase invisível: você encerra uma sessão, abre outra ferramenta, e o próximo agente já tem como se orientar. Quando o cliente só suporta MCP, ele ainda consegue consultar a wiki, mesmo sem capturar todo o ciclo de vida.

O detalhe importante não é o formato específico de hook de cada ferramenta. Isso está na documentação de instalação. O importante é que o ai-memory tenta esconder essas diferenças e dar ao agente um comportamento simples: antes de decidir, consulte a memória; quando aprender algo durável, preserve.

Por que isso deixa sessões de código mais inteligentes

O fluxo que eu quero é esse.

Você abre o OpenCode num projeto antigo. Antes de responder qualquer coisa séria, ele sabe consultar o ai-memory. Descobre que já existe uma decisão sobre banco. Descobre uma armadilha no build. Descobre que o último agente deixou uma passagem de bastão dizendo que o teste falhava em PaymentImporter. Você não precisa recontar a novela.

Durante a sessão, hooks registram o que acontece. No final, a sessão vira uma narrativa curta. Se foi uma sessão rica, o job de auto-improve pode transformar as lições em páginas como:

• gotchas/payment-importer-timezone.md;
• decisions/use-ledger-table-for-reconciliation.md;
• procedures/run-importer-smoke-test.md.

No modo padrão, isso entra como memória validada e auditável. No modo manual, você olha o diff, aprova ou rejeita. Na próxima semana, outro agente consulta e não pisa no mesmo buraco.

Esse é o ciclo que eu quero: trabalho vira conhecimento, conhecimento melhora o próximo trabalho. Sem virar religião de prompt, sem depender de uma janela infinita, sem confiar em memória opaca.

Cuidado com a palavra “auto”

Tem uma armadilha de marketing aqui. “Auto-aprendizado” soa como ficção científica: o agente aprende sozinho e fica melhor pra sempre. Não é isso que eu quero vender, porque isso vira mentira rápido.

O que temos hoje é bem mais pé no chão: um job que revisa sessões, sugere memória, valida a sugestão, guarda evidência e aplica pela trilha normal da wiki. Se você preferir, existe modo de revisão manual antes da escrita final. E justamente por ser limitado ele é útil. O prompt ativo e a latência dos hooks ficam protegidos. O sistema observa, filtra, valida e deixa rastro.

Esse é o limite correto pra um sistema desses neste momento. Auto-aprovação só depois de validação estrutural e evidência. Revisão humana quando o projeto pedir. Confiança se ganha com histórico, não com entusiasmo.

Fechando

O ai-memory começou como uma resposta simples pra uma frustração simples: cansei de reexplicar o mesmo projeto pra agentes diferentes. Em poucas semanas virou uma wiki versionada, com hooks, MCP, passagem de bastão, multiusuário, multi-workspace, arquivo marcador, suporte a vários CLIs, interface web, recuperação e agora um loop de auto-aprendizado inspirado no Hermes Agent, com validação e auditoria em vez de fé cega no LLM.

A filosofia continua a mesma: memória boa organiza conhecimento em páginas pequenas, legíveis, versionadas, citáveis. É transformar sessão longa em decisão, armadilha, procedimento, regra. É deixar o próximo agente começar do ponto onde o anterior parou.

Se você usa agente pra projeto de software de verdade, esse é o gargalo que começa a doer primeiro. Não é só modelo melhor. É continuidade.

O repositório está aqui: github.com/akitaonrails/ai-memory. Se você já usa com um provedor de LLM configurado, atualize e deixe o auto-improve trabalhar em segundo plano nas novas sessões concluídas.

Se quiser revisão manual antes de aplicar, configure:

[auto_improve]
require_approval = true

No modo manual, não aceite tudo. Esse é o ponto. Leia, critique, aprove só o que merece virar memória. No modo padrão, acompanhe a trilha de auditoria quando quiser entender o que foi promovido e por quê.

Pois é. Em três semanas esse projetinho cresceu de um jeito que merece um post só sobre o processo, porque ele virou um exemplo vivo de uma coisa que eu prego há tempos: software de verdade é cultivado, igual planta. Ninguém monta software bom peça por peça como quem monta um Lego. Vou te mostrar os números, e principalmente a história que eles contam.

Os números, hoje

O ai-memory tem hoje, em 24 dias de vida (do primeiro commit em 21 de maio até agora):

• 482 commits no main, uma média de 20 por dia.
• 26 pessoas commitaram no repositório.
• 10 crates Rust no workspace.
• ~62,7 mil linhas de Rust de produção, mais ~11 mil linhas de teste em tests/, mais de 1.000 funções de teste e 90 módulos #[cfg(test)] espalhados pelo código.
• ~19,7 mil linhas de documentação em markdown (docs/).
• 70 pull requests, dos quais 59 mergeados (84% de aceitação).
• 27 issues, 100% fechadas.
• Saímos do v1.0.0 em 12 de junho e já estamos no v1.0.6.

Vinte e quatro dias. Guarda esse número, porque a parte interessante não é o tamanho final, é a forma como ele chegou aqui.

Como começou: um só de tudo

O ai-memory nasceu pequeno e burro de propósito. Nos dois primeiros dias eu cravei o esqueleto inteiro: bootstrap do workspace, servidor MCP, captura por hooks, handoff entre agentes, versionamento da wiki em git, trait de provider de LLM, embeddings. Tudo isso rodando pra um usuário, uma máquina, um workspace, uma arquitetura (Linux, basicamente). Sem multi-usuário, sem permissão, sem escopo, sem suporte a Windows ou macOS. Era o meu cérebro de agente, na minha máquina, pra mim.

No dia 3, quando a primeira contribuição externa chegou (um fix do Lucas Oliveira pra URLs de provider OpenAI-compatível, o PR #6), o projeto tinha 102 commits e cerca de 22,9 mil linhas de código-fonte. Já eram os mesmos 10 crates de hoje, mas com uma fração da funcionalidade. Era um MVP de um-só-de-tudo que funcionava pra mim e mais ninguém.

E aqui é onde a maioria dos projetos morre, ou pior, onde a maioria dos programadores inexperientes erra a mão.

A falácia do Lego

Tem uma crença muito difundida, principalmente em quem está começando, de que dá pra desenhar tudo que um software vai ser antes de escrever a primeira linha. Você senta, planeja a arquitetura inteira, quebra em pedacinhos bem organizados, com as pastas e as camadas e as interfaces todas previstas, e aí constrói peça por peça. Quando a última peça de Lego se encaixa, o software está pronto. Lindo no papel.

Na prática, é o caminho mais rápido pra deteriorar código. Quanto mais cedo você cristaliza uma estrutura, mais cedo ela vira uma camisa de força. Você previu um sistema de permissões elaborado antes de ter usuários? Parabéns, agora você carrega o peso de manter abstração que ninguém usa, e que quase sempre está errada, porque você a desenhou adivinhando o futuro em vez de responder a uma necessidade real. O programador inexperiente faz engenharia em excesso no começo, e não importa o quanto ele planeje, o resultado começa a apodrecer rápido, porque ele está resolvendo problemas que ainda não existem e errando os que existem.

Eu não acredito em software que termina. Já escrevi sobre isso no “Software nunca está pronto”, e ele se conecta direto com as metodologias Agile originais, as de verdade, antes de virarem ritual corporativo de post-it. Software bom é uma escultura de barro: maleável, sempre úmida, que você fica ajustando, transformando, e que nunca fica pronta. É argila que você modela enquanto ela é usada. A torre de Lego que uma hora fica pronta e acabou é fantasia.

O que os contribuidores construíram

E é aí que entra a melhor parte de ter aberto o código. Aquele MVP de um-só-de-tudo virou um sistema multiplataforma e multiusuário porque muita gente colocou a mão. Eu quero agradecer nominalmente, porque sem essas pessoas o projeto seria uma fração do que é:

Djalma Júnior tocou boa parte da arquitetura pesada (multi-usuário, admin, recall cross-project), com 25 PRs mergeados. wlech com dezenas de commits. Pedro de Freitas Jr em embeddings e correções de web. Mauro Couto de Paiva e Gustavo Cateim tocaram boa parte do suporte a Windows. Pablo Winter, Lucas Oliveira (autor do primeiro PR externo) e Said Rodrigues, entre vários outros. Valeu demais, gente.

O que essas contribuições adicionaram, em destaque:

• Suporte real a Windows, macOS e Linux. O que era Linux-only ganhou compatibilidade com bash 3.2 do macOS, um índice de arquivos NTFS pra rastrear inode no Windows, e comandos de hook nativos por plataforma.
• Frontend API (/api/v1) e UI web customizável. Deixou de ser só MCP + CLI e ganhou uma superfície HTTP de verdade, com links de wiki clicáveis e busca por caminho de arquivo.
• Multi-usuário com atribuição. Tabela de users, comandos de writer/reader, e atribuição de autoria na mesma transação SQL da escrita (pages.author_id + frontmatter).
• Multi-workspace e recall cross-project. Busca global, links entre wikis de projetos diferentes, e isolamento de projeto ativo por sessão e por ator.
• Mais providers e mais agentes. Gemini, Copilot via OAuth, OpenAI-compat strict mode; e suporte a Antigravity, Grok e VS Code Copilot além dos originais.
• Robustez operacional. Recuperação por checkpoint, reindex-from-wiki pra reconstruir o índice a partir do markdown, manifestos _meta.md auto-descritivos.

Repara numa coisa: nada disso estava no plano original. Não existia plano original. Cada uma dessas features entrou porque alguém precisou dela, abriu uma issue ou um PR, e a estrutura foi cedendo espaço pra acomodar. O multi-usuário não foi previsto: ele emergiu.

E só agora a gente parou pra consolidar

Aqui está o ponto central do post. Durante essas três semanas, o código cresceu meio bagunçado de propósito. Quando o suporte a multi-usuário entrou, a lógica de “qual workspace e projeto esse pedido está mirando” foi parar embutida direto no meio de vários handlers do servidor MCP, da API web, do admin, espalhada e duplicada. Cada lugar resolvia escopo do seu jeito. Tinha duplicação. Tinha código que não era bonito. E está tudo bem, porque estava funcionando, e funcionando pra muita gente.

Só depois que o software já rodava na máquina de dezenas de pessoas, em três sistemas operacionais, com multi-usuário de verdade em produção, é que eu parei e falei: “ok, agora é uma boa hora pra refatorar e repensar a fiação interna”. O penúltimo commit grande, o refactor: centralize scope auth and wiki consistency, fez exatamente isso, com 1.239 linhas adicionadas e 249 removidas, criando um ScopeResolver central de 601 linhas e um ActorContext consolidado.

Veja o “antes”. Esse trecho de resolução de escopo vivia duplicado, com variações, em vários métodos:

// ANTES: lógica de escopo embutida, repetida em cada handler
let active = self.active_project.get_for(actor);
if let Some(name) = explicit_project.map(str::trim).filter(|s| !s.is_empty()) {
    if let Some((active_ws, _)) = active
        && let Ok(Some(pid)) = self.reader.find_project(active_ws, name.to_string()).await
    {
        return Ok((active_ws, pid));
    }
    if active.map(|(ws, _)| ws) != Some(self.workspace_id)
        && let Ok(Some(pid)) = self
            .reader
            .find_project(self.workspace_id, name.to_string())
            .await
    {
        return Ok((self.workspace_id, pid));
    }
    return Err(McpError::internal_error(
        format!("project '{name}' not found in the active or default workspace"),
        None,
    ));
}
Ok(active.unwrap_or((self.workspace_id, self.project_id)))

E o “depois”. A mesma resolução, agora delegada pra uma autoridade única no crate de store:

// DEPOIS: um resolvedor central, uma chamada
fn scope_resolver(&self) -> ScopeResolver<'_> {
    ScopeResolver::new(&self.reader, self.workspace_id, self.project_id)
        .with_writer(&self.writer)
        .with_active_project(&self.active_project)
}

// ... e cada handler vira isto:
self.scope_resolver()
    .resolve_current_or_project(explicit_project, actor)
    .await
    .map(ai_memory_store::ResolvedScope::as_tuple)
    .map_err(Self::scope_error)

Três métodos diferentes que antes carregavam 30 linhas de lógica embutida cada um, com lookup_ids, fallback de workspace e tratamento de erro próprio, colapsaram em uma chamada cada. Junto vieram os commits irmãos: harden multi-user admin auth boundaries e prevent scoped fallback bleed. Centralizar permissão, escopo de workspace e usuário, e consistência da wiki, tudo num lugar só, com regra clara.

O detalhe que importa: o ScopeResolver não foi inventado no começo do projeto adivinhando que um dia ia ter multi-usuário. Ele foi extraído de um código que já existia, já funcionava, e já tinha mostrado, na prática, quais eram os padrões que se repetiam. A abstração veio depois do uso, não antes. Eu deixei a estrutura emergir do código, e só quando ela ficou óbvia eu a consolidei.

A ordem certa: make it work, make it right, make it fast

Esse é o resumo de tudo. Tem um ditado antigo, atribuído ao Kent Beck, que eu carrego como mantra: “make it work, make it right, make it fast”. Faça funcionar, depois faça direito, depois faça rápido. Nessa ordem. A maioria dos programadores inexperientes quer fazer “direito” e “rápido” antes de fazer “funcionar”, e aí inventa regra sem ter código pra justificar a regra.

O ai-memory seguiu a ordem certa sem eu nem pensar muito nisso. Primeiro fiz funcionar pra uma pessoa, escopo simples. Depois fiz funcionar uma feature de cada vez, refatorando e endurecendo o código no caminho, mas sem nunca cair na engenharia em excesso e sem nunca reescrever do zero pra encaixar numa estrutura pré-concebida. Eu deixei as estruturas atuais emergirem do código que foi sendo adicionado. Isso significou conviver com alguma duplicação e algum código meia-boca por um tempo, até bater aquele momento de “agora sim é hora de refatorar e repensar a fiação”. E só agora, com o software maduro e em uso, é que eu estabeleci padrões e regras melhores pra código novo. Regras lastreadas em código de verdade, não em adivinhação.

KISS, “keep it simple”, é sobre não resolver problema que você ainda não tem. Não tem nada a ver com escrever pouco código. É deixar a arquitetura emergir do código, e não o contrário. Você não desenha a escultura e despeja o barro dentro do molde. Você pega o barro, começa a modelar, e a forma aparece conforme suas mãos trabalham. O molde, se um dia precisar de um, você constrói depois, em volta da forma que já existe.

Vinte e quatro dias, 482 commits, 26 pessoas, e nenhum deles seguiu um diagrama desenhado no dia 1. Porque não existia diagrama no dia 1. E é exatamente por isso que funcionou.

O ai-memory é open source e continua mudando toda semana: github.com/akitaonrails/ai-memory. Quer ajudar a modelar o próximo pedaço? Tem issue aberta esperando.

Vou repetir uma coisa importante antes que alguém saia clonando todos os meus repositórios achando que virou produto 1.0: a maior parte dos projetos frank-* no meu GitHub são provas de conceito. São experimentos. Alguns funcionam bem pra mim, no meu ambiente, no meu fluxo. Isso não quer dizer que estão prontos pra virar dependência crítica da sua empresa amanhã de manhã. Quer brincar, contribuir, estudar, ótimo. Só não confunda “publiquei no GitHub” com “está production ready”.

Existem exceções. O FrankMD, por exemplo, recebeu uma quantidade decente de contribuições, testes, lapidação, correções de bugs reais, uso real. Hoje ele já é bem mais estável do que era no primeiro post. Ainda assim, o ponto continua: esses projetos nasceram como laboratório de vibe coding, não como plano de produto de 3 anos com roadmap, suporte enterprise e SLA.

Este post é um apanhado do que aprendi nesse laboratório. Algumas ferramentas minhas, alguns hábitos, algumas recomendações. Nada místico. Nenhuma “nova forma revolucionária de programar”. É engenharia velha com ferramenta nova.

Primeiro: pare de colecionar agente

Se você é desenvolvedor normal, você não precisa de 12 agentes, 40 wrappers, 7 orquestradores e um diagrama de Kubernetes pra escolher quem vai escrever um if.

Na prática, foque em Claude Code, Codex ou opencode. Só isso.

Sim, existe Gemini CLI. Sim, existe Cursor. Sim, existe Windsurf, Crush, OpenClaw, Pi, Aider, e amanhã vai aparecer mais meia dúzia. Eu testei um monte. Leia meus posts de benchmark de LLMs, especialmente o “LLM Benchmarks Parte 3: DeepSeek, Kimi, MiMo”. A conclusão é chata e óbvia: hoje, as melhores opções de custo-benefício pra programação pesada são Opus 4.7 e GPT 5.5 nos planos Pro/Plus/Max subsidiados. Nada chega perto quando o assunto é trabalhar várias horas por dia com agente de código de verdade.

Pagar token direto é caro. Pagar plano mensal subsidiado sai muito mais barato. É por isso que eu vivo alternando entre Claude Code e Codex: não porque eu quero “multi-agent architecture”, mas porque os planos têm limites e eu trabalho muitas horas seguidas.

DeepSeek v4 e Kimi 2.6 são mais baratos? Sim. São usáveis? Sim. Eu gosto deles pra vários casos. Mas pra Agile Vibe Coding do jeito que venho defendendo desde o post “Do Zero à Pós-Produção em 1 Semana”, ainda falta. Eles tropeçam mais em continuidade, em refatoração longa, em testes, em entender o projeto inteiro. Dá pra usar? Dá. Mas se o objetivo é produtividade consistente, Opus e GPT ainda são a régua.

Rodar modelo open source local é legal. Eu mesmo brinquei bastante com isso no review do Minisforum MS-S1 Max com AMD AI Max+ 395. Pra one-shot, pra estudar, pra brincar com inferência local, é divertido. Pra Agile Vibe Coding o dia inteiro, todo dia, ainda não é prático. Latência, contexto, qualidade, manutenção do setup, VRAM, tudo cobra imposto.

Também não é prático ficar rodando múltiplos LLMs em paralelo, tipo “planner + executor + reviewer + juiz”. Eu testei isso no post “LLM Benchmarks: Vale a Pena Misturar 2 Modelos?”. A ideia é bonita no papel. Na prática, aumenta custo, aumenta latência, aumenta superfície de erro, e o ganho não paga a complexidade.

O segredo não é ter um monte de agentes. Esquece OpenClaw ou Pi pra programação do dia a dia. O segredo é processo de engenharia. XP. Testes. Clean Code pra agentes de IA. CI. Pair programming. Refatoração constante. Código pequeno. Deploy automatizado. Feedback rápido.

Ferramenta ajuda. Engenharia ganha.

ai-jail: autonomia com cerca

O primeiro projeto que quero destacar é o ai-jail. Ele é um wrapper de sandbox pra rodar agentes de IA com acesso restrito ao sistema. No Linux usa bubblewrap (bwrap) e Landlock. No macOS usa sandbox-exec. A ideia é simples: o agente enxerga o ambiente que precisa pra trabalhar, mas não sai fuçando seu sistema inteiro.

Uso todo dia? Sim. Uso sempre? Não.

Quando sei que não vou fazer nada arriscado, abro claude ou codex direto. Se vou mexer num projeto simples, só rodar testes, editar markdown, refatorar coisa local, muitas vezes nem me preocupo. Em mais de 600 horas de Agile Vibe Coding intenso, mais de meio milhão de linhas de código e documentação, nunca tive um caso desses folclóricos de LLM destruindo meu sistema host de um jeito irrecuperável.

E olha que eu usei agentes explicitamente pra configurar meu Omarchy. ZSH, Hyprland, Waybar, configs de terminal, scripts de login, tudo. Nunca fizeram nada que eu não pedi.

Essas histórias de “o agente deletou meu home inteiro sozinho” eu leio com um pé atrás. Na minha experiência, quando você pede pra deletar algo perigoso, Claude e Codex perguntam confirmação. Você precisa dizer sim. Se você disse sim sem ler, a culpa não é mágica negra do LLM. É usuário no modo zumbi.

Dito isso: nada é garantido. Daí o ai-jail.

Meu uso preferido é combinar ai-jail com o modo sem freio do harness:

ai-jail claude --dangerously-allow-permissions
ai-jail codex --dangerously-bypass-approvals-and-sandbox

Parece contraditório, mas faz sentido. Eu tiro a fricção de confirmação dentro do agente, mas coloco uma cerca no nível do sistema operacional. O agente pode trabalhar rápido dentro do projeto, mas o filesystem do host fica essencialmente read-only. O diretório atual fica read-write. O que eu mapear explicitamente com --rw-map também fica read-write. O resto não é pra tocar.

O README do ai-jail resume bem: é um sandbox wrapper pra agentes como Claude Code, GPT Codex, OpenCode e Crush. No primeiro run ele cria um .ai-jail no projeto, que pode ser commitado. Suporta --dry-run pra ver os mounts antes de executar, --lockdown pra modo mais restritivo, --private-home pra esconder dotfiles reais, --mask .env pra esconder arquivos sensíveis dentro do próprio projeto, e perfis de navegador isolado pra Chromium/Firefox.

O ponto importante: não venda isso como segurança absoluta. Processo sandbox não é VM. Kernel bug existe. Side channel existe. macOS tem limitações. O próprio README é claro: se você precisa isolar workload hostil de verdade, use uma VM descartável. Eu não uso ai-jail como “blindagem militar”. Uso como mais uma camada, boa o suficiente pro fluxo de desenvolvimento.

E mesmo dentro do projeto, tudo é Git. Eu faço push frequente pro GitHub ou pro meu Gitea privado. Então o pior caso realista é o agente destruir o diretório do projeto. Chato? Sim. Catastrófico? Não. Clono de novo. Volto do remote. Refaço o que estava local. Se o .git corromper, apago tudo e clono de novo.

Secrets também têm cópia fora. .env, tokens, keys, tudo que importa fica no Bitwarden. Self-hosted em Vaultwarden, claro. Então se eu perder o diretório local, não perdi a chave do reino.

O risco mais comum não é o agente deletar tudo. É você vazar segredo no Git. Isso aconteceu comigo mais de uma vez. Você dá git add ., esquece um .env, empurra pro remote, parabéns. Acontece. Por isso tem que olhar git status, git diff --cached, e pensar antes de dar push.

Mesmo quando acontece, os LLMs são muito competentes pra ajudar a reescrever histórico. Peço pra limpar o segredo do Git, forçar push, revisar se sumiu, e depois eu rotaciono a key. Não é bonito, mas é administrável.

Então sim, recomendo usar Claude/Codex com permissões perigosas dentro do ai-jail. Existe a chance de 0,001% de acidente irrecuperável? Existe. Mas se você é bom engenheiro, isso não deveria te matar. Eu tenho camadas: snapshots automáticos em Btrfs, restic pro NAS, NAS arquivando offsite em AWS Glacier, Git remoto, Bitwarden. Ferramenta nenhuma substitui backup.

ai-memory: contexto que sobrevive ao harness

O segundo é o ai-memory, que expliquei em detalhes no post “Criei um Sistema de Memória pra Agentes de Código: ai-memory”.

A motivação é simples: harnesses perdem contexto. Claude Code compacta. Codex compacta. opencode compacta. Sessão acaba. Você abre outro agente e ele não sabe o que aconteceu nas últimas 4 horas. Se você usa só um harness, talvez isso não incomode tanto. Se você alterna entre Claude e Codex como eu, incomoda rápido.

Eu queria um consolidador de memória de longo prazo que funcionasse atravessando harnesses diferentes. Algo que permitisse handoff entre Claude, Codex e opencode sem eu ficar escrevendo HANDOFF.md manual toda vez. Algo que capturasse prompts, tool calls e eventos de sessão via hooks, consolidasse em páginas markdown, indexasse com SQLite/FTS5, e expusesse tudo via MCP quando o agente precisasse consultar.

Outro motivador foi o que expliquei no post “RAG Está Morto? Contexto Longo, Grep e o Fim do Vector DB Obrigatório”. Pra projeto de código, quase sempre texto simples resolve mais do que arquitetura afetada de vector DB. Markdown, grep, SQLite FTS5, contexto longo e bons arquivos em docs/ já levam você longe. O ai-memory segue essa linha: compila memória em texto, deixa no disco, indexa simples, e só chama LLM quando vale consolidar.

O ai-memory não foi feito pra ser uma knowledge base navegável por usuário final. Ele tem uma UI web read-only, sim, mas isso é pra auditoria e inspeção. A memória é otimizada pra LLM consumir. É um wiki interno que o harness pode consultar quando acha que precisa. É um lugar onde posso pedir explicitamente “salva isso pra próxima sessão” e esperar que sobreviva mais do que a compactação padrão do Claude ou do Codex.

O README resume bem: agentes de código perdem todo contexto quando a sessão termina; o ai-memory dá a eles um wiki persistente compartilhado. Cada prompt, tool call e decisão pode ser capturado automaticamente. No fim da sessão, páginas relevantes são reescritas como narrativa coerente. Na próxima sessão, outro agente pode receber um handoff já prepended no contexto.

Isso é útil quando você fecha Claude às 18h, abre Codex no dia seguinte no mesmo diretório, e quer que ele saiba que você estava testando session cookies porque rotação de JWT tinha dado problema. Ou quando você volta a um projeto seis semanas depois e não lembra por que descartou Redis.

Mas não confunda com documentação canônica. Se você fez uma pesquisa importante que não quer perder, peça pro agente escrever um markdown em docs/ dentro do projeto. Decisão arquitetural, benchmark, análise de biblioteca, runbook de deploy, tudo que precisa sobreviver com garantia deve virar arquivo explícito no repo. Isso é mais simples, auditável e versionado.

O ai-memory cobre a faixa intermediária: informação transitória que talvez importe depois. Um bug estranho que apareceu. Um raciocínio que levou a uma decisão. Um gotcha de ambiente. Um resumo de sessão. Coisas que você não quer transformar em doc oficial ainda, mas também não quer jogar fora.

Ele ainda é beta. Eu uso em produção pessoal, mas precisa de muito mais gente batendo nele. Tem integração com Claude Code, Codex e opencode mais polida. Gemini CLI, OpenClaw e clientes MCP exóticos ainda precisam de mais teste. PRs são bem-vindos. Bug report também. “Instalei e quebrou no meu setup” é exatamente o tipo de feedback que revela suposição errada.

ai-usagebar: saber quando trocar de cavalo

Como falei acima, eu prefiro usar os planos subsidiados da Anthropic e da OpenAI. O problema é que, se você faz Agile Vibe Coding de verdade, você bate limite. Limite diário. Limite semanal. Limite de sessão. Limite que muda. Limite que não aparece direito em lugar nenhum.

Eu usava o claudebar, que é bom, mas só cobre Claude. Eu queria ver os principais vendors num lugar só. Daí nasceu o ai-usagebar, que apresentei no post “Criei um Widget de Waybar pra Omarchy pra Monitorar Uso de Planos de LLM: ai-usagebar”.

É um widget de Waybar e uma TUI em Rust pra monitorar uso de Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI GLM e OpenRouter. Pra Claude e OpenAI, ele lê as credenciais OAuth que os CLIs oficiais já gravaram. Pra Z.AI e OpenRouter, usa API key. Mostra porcentagem da sessão, reset, limites, saldo, e permite trocar o vendor principal.

O valor disso é banal e por isso mesmo útil: bato o olho na barra e sei se devo continuar no Claude, fazer handoff pro Codex, ou recarregar crédito no OpenRouter. Não quero descobrir que cheguei no limite semanal no meio de uma refatoração grande.

Também tem a TUI standalone:

Se você não usa Omarchy, Hyprland ou Waybar, ainda dá pra rodar ai-usagebar-tui em qualquer terminal. SSH, tmux, terminal normal, tanto faz. A barra é conveniência. A TUI é a forma universal.

ghpending: pendência de GitHub sem ritual

Depois da maratona, fiquei com dezenas de ai-* e frank-* no GitHub. Isso cria um problema chato: issues e pull requests começam a aparecer. Contribuidor abre PR. Alguém reporta bug. Outro manda sugestão. Se eu tiver que abrir o navegador, entrar repo por repo, filtrar aba por aba, eu vou adiar. E se eu adiar, fico semanas sem responder.

Sim, eu poderia usar gh, a CLI oficial do GitHub. Aliás, uso. Mas eu queria uma coisa mais burra e mais rápida: um comando curto pra imprimir um digest de tudo que está pendente nos repos que eu escolhi monitorar. Nasceu o ghpending, que descrevi no post “Criei um CLI pra Checar Pendências no Meu GitHub: ghpending”.

É só isso: ghpending add pra escolher repos, ghpending pra ver o digest, ghpending list, ghpending rm. Sem autenticação funciona com limite de 60 req/h do GitHub. Com GITHUB_TOKEN=$(gh auth token) ghpending, sobe pra 5.000 req/h.

O ponto não é substituir o GitHub. É reduzir atrito. Se eu consigo rodar um comando no terminal e ver “tem 3 PRs e 2 issues pra olhar”, eu olho. Se depende de ritual de navegador, notificações e abas, fica pra depois.

E Claude/Codex são muito bons nesse tipo de trabalho. Dá pra pedir:

“Checa os pull requests abertos, revisa o código, vê se compila, roda os testes, adiciona teste se faltar, faz rebase de master se precisar, mergeia e fecha.”

Ou:

“Checa as issues abertas, avalia se tem bug real, reproduz se der, propõe correção, responde o usuário.”

Eles leem o PR, entendem o diff, rodam teste, fazem rebase, resolvem conflito simples, escrevem resposta pro contribuidor. Não é pra desligar o cérebro. É pra terceirizar o trabalho mecânico que você já sabe fazer.

Refatoração: peça explicitamente, várias vezes

Claude e Codex são muito bons em refatorar, mas não presuma que vão fazer isso automaticamente do jeito que você faria. Eu costumo começar projetos ou features com instruções explícitas:

“Use as melhores práticas de Rust. Evite duplicação desnecessária. Modularize só onde fizer sentido. Adicione unit tests pra toda feature nova. Siga princípios de Clean Code. Não crie abstração antes de precisar.”

Depois de uma feature grande, uma correção grande, ou algumas horas de desenvolvimento, paro e peço:

“Agora que mexemos bastante no código, reavalie com calma. Delete código morto. Refatore duplicações óbvias. Adicione testes faltantes. Remova magic numbers. Veja se tem módulos grandes demais. Não mude comportamento sem teste.”

Antes de release:

“Antes de publicar essa versão, faça uma auditoria de sanidade. Procure vazamento de secrets, permissões perigosas, comandos destrutivos, path traversal, unwraps desnecessários, falta de validação, e qualquer coisa que pareça vulnerabilidade óbvia.”

Isso garante segurança? Claro que não. Nem perto. Mas remove muito erro besta. É mais uma camada. Eu gosto de rodar essa auditoria com Claude e depois com Codex, porque cada um acha coisas diferentes. Mesmo assim, bug passa. Segurança é processo, não ritual mágico.

Experimentos descartáveis: código ficou barato

Antes de escolher biblioteca, framework, arquitetura, modelo ou serviço, eu gosto de criar experiments/.

Exemplo:

“Antes de escolher entre Qwen e DeepSeek, cria um protótipo descartável em experiments/ pra A/B test. Documenta a análise em docs/ com resultado, custo, latência, qualidade e recomendação.”

Isso mudou meu jeito de decidir. Antes, muita decisão de engenharia virava opinião, feeling, fé em benchmark dos outros. Agora código é barato. Peço pro agente fazer duas ou três versões, rodar teste, medir, documentar, jogar fora o que não presta.

Prototipar ficou rápido de verdade. O Frank Karaoke é um bom exemplo: transformar YouTube num app de karaokê era o tipo de ideia que antes eu talvez deixasse numa lista mental por meses, esperando “um fim de semana livre” que nunca chega. Agora dá pra abrir um experiments/, pedir um protótipo tosco, testar o caminho técnico, e decidir se vale virar projeto. Olha meus outros posts de 2026 sobre os projetos frank-* e ai-*: quase todos começaram assim, como código descartável que provou alguma coisa antes de merecer nome.

Mas protótipo barato não significa one-shot. Já escrevi em “Por que as LLMs não te dão o resultado esperado”: prompt bom é conversa iterativa. Você dá contexto, mostra referência, aponta restrição, lê o resultado, corrige direção, manda refazer. Se você joga uma frase vaga e espera produto pronto, o erro é seu.

Também aprendi isso apanhando. No post do Frank Yomik contei meu primeiro fracasso real com vibe coding: quando a direção está errada, insistir no mesmo prompt só cava o buraco. Tem hora que precisa reduzir escopo, isolar o problema, criar teste, trocar estratégia. LLM não transforma plano ruim em engenharia boa.

E tem domínio onde você precisa estudar junto. No post de Driveclub e shadPS4, a IA quase me levou pra todo lado errado porque o problema exigia entender renderização, gamma, shaders, buffers. A ferramenta ajuda a explorar, mas quem decide se a explicação faz sentido ainda é você. Se você não entende o suficiente pra verificar, está só aceitando chute bonito.

Por isso também repito a ideia de “Software Nunca Está Pronto”: deploy não é linha de chegada. O protótipo vira produto quando aguenta bug report, manutenção, refatoração, docs, release, rollback, usuário reclamando. LLM ajuda muito nesse ciclo chato. Mas o ciclo continua existindo.

Se é testável, teste. Se dá pra medir, meça. Se não dá pra medir, pelo menos escreva as premissas. O importante é não escolher só porque “parece melhor”.

Código barato também significa desapego. Faça código pra jogar fora. Faça protótipo feio. Faça benchmark descartável. Peça pro agente documentar o que aprendeu em docs/decision-qwen-vs-deepseek.md, depois apague experiments/ se quiser. O documento fica. O aprendizado fica.

LLMs também são muito bons em documentação. Use isso. Peça pra documentar tudo. Por que escolhemos PostgreSQL em vez de SQLite nesse caso. Por que o deploy usa Docker image multi-stage. Por que o serviço roda atrás de Cloudflare Tunnel. Por que aquele sysctl existe. Mesmo que depois você delete metade, o custo de escrever caiu perto de zero.

Deploy automatizado ou você vai parar de manter

Todo projeto meu que importa tem build automatizado. Muitos rodam no meu homelab, como descrevi em “Migrando meu Home Server com Claude Code”. Quase todo projeto tem um bin/deploy que builda imagem Docker, faz push, rotaciona no servidor, aplica migração se precisar, e valida healthcheck.

Claude e Codex são excelentes em deploy. Eles leem o bin/deploy, entendem Dockerfile, editam GitHub Actions, ajustam release workflow, corrigem assinatura de binário, atualizam Homebrew tap, geram checksum. E sim, eu peço pra Claude/Codex dar SSH no meu homelab e redeployar container Docker. Eles são muito bons nisso. O ai-jail, por exemplo, tem GitHub Actions pra buildar binários assinados pra Linux e macOS.

Se você tem dezenas de projetos, quanto mais automatizado melhor. Eu raramente digito comando administrativo no terminal sozinho. Peço pro LLM fazer, observo, aprovo o que for perigoso, e depois peço:

“Documente o que foi feito e por que foi feito.”

Isso vale pro homelab e pra minha workstation. Meu Omarchy é customizado via Claude: ZSH, Hyprland, Waybar, scripts, atalhos, temas, integrações. Até meus setups de gaming/emulação entram nessa, como mostrei no post dos retrogames de corrida rodando no Distrobox. Esse é um caso onde normalmente não uso ai-jail, porque justamente quero mexer no host. Então olho comandos, leio diffs, aprovo devagar. Mesmo assim, nunca tive o agente quebrando meu sistema de um jeito irrecuperável. Pelo contrário. Meu PC nunca esteve tão estável e documentado.

Dias depois, quando esqueço por que configurei alguma coisa daquele jeito, o contexto está em markdown, Git, ai-memory, ou no próprio histórico do projeto. Eu posso perguntar e o agente tem de onde puxar.

Até este post foi escrito assim

Inclusive, é assim que escrevo estes posts agora. Eu jogo um bloco enorme e bagunçado do meu cérebro no Claude. Peço pra ler posts recentes pra calibrar estilo. Peço pra checar os projetos diretamente e elaborar as partes técnicas. Peço pra usar as screenshots mais recentes, subir pro S3 quando precisa, linkar os posts anteriores, revisar o tom.

Depois eu leio e edito. Corto o que ficou genérico. Troco frase que parece release note. Coloco minhas broncas de volta. O resultado ainda é meu texto, só que agora eu gasto energia no que importa: decidir o que dizer, corrigir nuance, cortar besteira.

“Mas você testou o Pi?”

Toda vez que falo de LLM ou ferramenta de LLM, aparece alguém nos comentários com a mesma pergunta: “mas você testou Pi?”, “mas você testou DeepSeek?”, “mas e o Qwen?”, “mas e o modelo novo que saiu ontem?”. Toda. Santa. Vez.

É irritante pra cacete. E quase sempre vem de três tipos de pessoa: quem não testou nada e quer terceirizar o trabalho, quem já escolheu uma ferramenta e quer que eu valide a escolha dela, ou fanboy que trata vendor de LLM como time de futebol. Todos soam iguais. NPC repetindo diálogo de tutorial.

Engenheiro de software não deveria decidir baseado em opinião dos outros. Nem na minha. Se você escolhe ferramenta porque “o Akita falou”, você entendeu errado. Eu defendo Claude Code e Codex porque usei centenas de horas, em projetos reais, publicando código e post-mortem do que funcionou e do que falhou. E mesmo assim eu não parei em opinião.

Eu criei meu próprio benchmark automatizado: llm-coding-benchmark. Atualizo quando vendor popular solta versão nova. Rodo cenários comparáveis. Publico resultado. Depois ajusto minha opinião baseado nos dados. É por isso que eu tenho segurança pra dizer que, no meu fluxo, Opus e GPT continuam vencendo. Não porque acordei com vontade de defender logo de empresa bilionária.

Se sua primeira reação foi “mas você testou Qwen?”, ótimo. Testa você. Roda o benchmark. Cria cenário melhor. Manda PR. Mostra número. Mostra custo. Mostra latência. Mostra onde falhou. Mostra onde ganhou. Traga dado novo.

Opinião solta é irrelevante. “Pra mim funciona” não escala. “Eu gosto mais” não interessa. “No meu prompt one-shot ele foi melhor” é anedota. Engenharia começa quando dá pra reproduzir, comparar e agir em cima.

Então fica simples: traga dado acionável ou fique quieto. Eu não preciso de torcida organizada de vendor nos comentários. Preciso de gente testando, medindo e contribuindo resultado novo.

Checklist final

Resumo curto, porque este post já ficou grande:

• Foque em Claude Code, Codex ou opencode. Pare de colecionar agente.
• Use Opus 4.7 e GPT 5.5 via planos Pro/Plus/Max quando produtividade diária importa.
• DeepSeek, Kimi e modelos locais são úteis, mas ainda não substituem o fluxo principal.
• Agile Vibe Coding é XP com LLM: testes, Clean Code, CI, pair programming e deploy.
• Use ai-jail quando quiser autonomia do agente com cerca no filesystem.
• Combine ai-jail com permissões perigosas do Claude/Codex quando o projeto estiver protegido por Git.
• Tenha backup de verdade: Btrfs snapshots, restic, NAS, offsite, Git, Bitwarden.
• Revise git add, git diff --cached e pushes pra não vazar secrets.
• Use ai-memory pra contexto transitório e handoff entre agentes.
• Escreva documentação canônica em docs/ quando a informação precisa sobreviver com garantia.
• Use ai-usagebar pra saber quando trocar de Claude pra Codex, ou quando recarregar OpenRouter.
• Use ghpending pra não abandonar issues e PRs.
• Peça refatoração explicitamente depois de features grandes.
• Rode auditoria de segurança antes de release, de preferência com mais de um modelo.
• Crie protótipos descartáveis em experiments/ antes de decidir por fé.
• Se discordar de benchmark, rode o llm-coding-benchmark e traga dado novo.
• Documente decisões em markdown. Código ficou barato. Documentação também.
• Automatize deploy. Se depender de ritual manual, você vai parar de fazer.

No fim, é o mesmo conselho de sempre: ferramenta muda, engenharia não. LLM aumenta a alavanca. Se você já tinha bons hábitos, vai produzir mais. Se não tinha, vai só produzir bagunça mais rápido.

E sim, isso muda a interface do trabalho. Já escrevi sobre isso em “VS Code é o novo Cartão Perfurado”: ficar polindo pixel em editor virou nostalgia de programador velho. A parte difícil agora é escrever intenção direito, revisar execução sem preguiça, medir resultado, jogar fora código barato, e não confundir opinião com dado.

Há cinco dias eu escrevi um post longo sobre memória de agentes de código onde recomendei o agentmemory como solução. Depois de uma semana rodando ele em produção pessoal, voltei atrás. Esse post explica o que deu errado, e o projeto open source que comecei a construir pra resolver: o ai-memory.

Por que o agentmemory não rolou

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. Os principais que peguei na prática:

• Reindexação do BM25 a cada restart. O índice persiste num arquivo (mem:index:bm25.bin) através de um KV remoto chamado iii-engine. Com poucas observações isso voa, mas passa de 10K observações e o state::set começa a dar timeout, o arquivo fica em ~96 bytes vazio, e cada restart paga ~5 minutos reconstruindo do zero (issue #309, aberta).
• Janela de perda de dados de 5 segundos. Toda persistência passa por um debounce de 5s do IndexPersistence. Quando o timeout de 30s do state::set estoura, o processo Node morre levando junto tudo que tava em memória (#204).
• Dois caminhos de leitura de config no mesmo código. process.env direto num lugar, getMergedEnv() em outro. O famoso “setei a variável e nada mudou” (#456).
• Hook errado em ~47% das tool calls do Claude Code. O hook leu data.tool_output, mas o Claude Code manda tool_response. Seis semanas com observações sumindo silenciosamente (#539).
• Engine roda no diretório de trabalho do chamador. Usuários de Windows acharam que perderam memórias porque cada terminal abria o state store num path diferente (#303, aberta).

Tem mais. Documentei aqui no meu repo de pesquisa. O autor é responsivo, o repo tem 15.7K estrelas, e mesmo assim a arquitetura escolhida (TypeScript MCP + iii-engine Rust separado + 4 portas, 3 processos, índices em memória persistidos via KV remoto) acumula uma classe de bug que não tem como fechar sem reescrever metade do sistema. A forma do problema é estrutural, não falta de esforço do mantenedor.

Foi a mesma história com toda outra solução que testei: ou é incompleta, ou focada demais em alguma tecnologia específica (vector DB proprietário, knowledge graph que precisa de Neo4j, pipeline LLM elaborado), ou exige que o usuário grite write_note toda vez que quer salvar algo. Nenhuma “sai do caminho” o bastante pra eu confiar em sessões longas.

O que eu queria desde o começo

Quando comecei minha maratona de 37 dias de vibe coding lá em fevereiro, sabia que precisava de algum organizador de conhecimento. Levei mais de 500 horas de experimentação pra cristalizar o que eu queria de verdade.

Pra quem usa só um dos três (Claude Code, ou Codex, ou opencode) e fica nele, você provavelmente não precisa de nada extra. Os três já fazem um trabalho razoável de gerenciar memória dentro da sessão. Claude Code tem três níveis de compaction (microcompact por gap temporal, autocompact por threshold de token, sessionMemoryCompact experimental). Codex tem auto_compact_token_limit por modelo. opencode tem compaction ancorada com buffer de 20K. Cobri isso em detalhe no post anterior.

A única disciplina extra que vale a pena adotar nesse caso é manter um diretório docs/ no projeto com arquivos markdown organizados por tópico, e pedir pro agente salvar lá quando algo importante acontece. Pesquisas que não devem ser refeitas, pegadinhas conhecidas, justificativa de por que escolheu opção A em vez de B. Funciona. Exige disciplina.

O problema aparece pra quem é como eu, que pula entre agentes no mesmo projeto. Eu uso Claude Code como padrão (acho o harness, o orquestrador de subagentes, e o planning de tarefas longas superior). Mas quando o Claude empaca num problema, eu disparo o Codex no mesmo diretório só pra “agitar”. O Codex pensa mais “fora da caixa” e às vezes encontra uma solução que o Claude não enxergou. Aí volto pro Claude pra implementar com mais cuidado.

Esse vai-e-volta entre agentes é o cenário onde a memória externa importa muito. Sem ela:

• Você fecha o Claude Code, abre o Codex no mesmo diretório, e o Codex não sabe nada do que foi discutido nas últimas 4 horas.
• Você precisa pedir manualmente pro Claude escrever uma nota de handoff em ./HANDOFF.md, depois pedir pro Codex ler. Toda vez.
• Projetos que você deixou parados por semanas: você abre, esqueceu por que decidiu não usar Redis, esqueceu qual era o bug que tinha na biblioteca X.

Karpathy resolveu o conceito da coisa no LLM Wiki dele, que detalhei no post anterior. Mas tem uma frase específica do gist que ficou na minha cabeça:

O index.md é “surpreendentemente bom — em ~100 fontes e algumas centenas de páginas, sem precisar de embeddings”.

Aquela linha resume o que eu queria. Não precisa de tecnologia complicada. Storage simples (markdown em git), índice simples (SQLite com FTS5 e links), instalação simples (um binário ou container), uso automático (hooks que disparam sozinhos), zero manutenção (memória decai sem o usuário mexer).

Foi por isso que comecei o ai-memory.

A pesquisa antes do código

Em vez de só sair codando, pesquisamos o código-fonte e issues dos projetos relevantes pra entender o que cada um acertou e errou. Salvei a pesquisa no próprio repo:

• research-karpathy-llm-wiki.md — o que Karpathy escreveu literal, separado do que a comunidade atribui (parafraseando) a ele. Três princípios fundamentais: compilação em vez de retrieval, três camadas (raw / wiki / schema), três operações (ingest / query / lint). Foi o blueprint conceitual.
• research-agentmemory.md — análise técnica do agentmemory: quatro níveis de consolidação (working → episodic → semantic → procedural), supersessão com is_latest=false em vez de delete, decaimento exponencial, reflexão por cluster. Mantive as ideias do agentmemory, mudei a implementação.
• research-basic-memory.md — Python, MCP-native, markdown puro no disco. O modelo é explicitamente manual: o agente chama write_note quando ele decide salvar. Bom modelo de storage, péssimo modelo de captura (depende do agente lembrar de chamar).
• research-cognee.md — pipeline de cognify (extract → chunk → graph + summarize → embed → persist) com knowledge graph + vector + relational triplo. Excelente pra agente de empresa rica que quer relação semântica entre entidades. Pesado demais pra “memória de sessão de coding”.

A síntese que tirei: agentmemory tem as ideias certas. O resto é execução.

A ideia que eu mais gosto do agentmemory, e que ele herdou parcialmente do LLM Wiki v2, é a consolidação tipo sono: memória curta retém detalhes brutos, memória longa vai consolidando e resumindo, e memória de longo prazo não acessada vai sendo esquecida. Não acumula lixo. Tem accessCount, decaimento exponencial geométrico, reforço por repetição espaçada. É similar e inspirado no que um humano faz dormindo.

No ai-memory eu mantive essa estrutura mas troquei a engenharia por baixo:

• TypeScript → Rust em binário único. Sem KV remoto separado. Sem 3 processos. Um binário escrito em Rust, com um diretório de dados e um servidor Axum.
• Índice persistente em SQLite + FTS5. Nativo. Sem reindex a cada restart. WAL mode, busy_timeout 5s.
• Writer único em thread dedicada via mpsc. Sem janela de perda de 5s, sem timeout de 30s estourando.
• Markdown puro no disco como source of truth. SQLite é só índice derivado. Você pode abrir o wiki no Obsidian. Pode dar grep. Pode versionar com git (e ele versiona automaticamente).
• Isolamento por projeto na estrutura física do disco. <wiki_root>/<workspace_id>/<project_id>/... chaveado por UUIDs estáveis. Renomear projeto é update de uma coluna. Apagar projeto é rm -rf de um subdir. Mesmo nome de página em dois projetos não colide.
• Embedding e LLM são opcionais. Sem chave de provedor, o sistema ainda funciona com FTS5, expansão por links e fallback nas observações brutas. Adicione embeddings quando quiser re-ranking vetorial, e Claude Haiku ou GPT-5.4-mini quando quiser páginas consolidadas com qualidade.

Como funciona no dia a dia

A interação com os agentes é por dois mecanismos: hooks/extensões (captura automática) e MCP (consulta sob demanda).

Claude Code e Codex usam shell hooks. OpenCode usa plugin TypeScript. OMP/Pi usa extensão TypeScript. Cursor e Gemini CLI usam configurações JSON de lifecycle. Todos mandam eventos equivalentes (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd) como POST fire-and-forget pro servidor HTTP do ai-memory (rodando em 127.0.0.1:49374 por padrão). O agente nunca espera. Se o ai-memory tiver fora do ar, a sessão continua normal, só sem captura. Claude Desktop e OpenClaw entram como MCP-only: consultam memória, mas não capturam ciclo de vida automaticamente.

Do lado do agente, o MCP server expõe ferramentas que o LLM pode chamar quando achar útil:

O snippet de routing que vai no CLAUDE.md (ou AGENTS.md pra Codex/OpenCode/Cursor/Gemini/OMP) é o que faz o agente saber quando chamar qual ferramenta. Ele se instala com um comando: peça pro agente “instala o routing do ai-memory neste projeto” e ele invoca a tool MCP memory_install_self_routing, recebe o snippet canônico, e escreve no arquivo certo. Idempotente.

Exemplo de handoff entre agentes

Eis o cenário concreto que motivou o projeto:

$ claude
> "Tô refatorando autenticação. A rotação de JWT tá quebrada, vou
   testar session cookies como alternativa."
[trabalha por uma hora]
> /exit

$ codex   # mesmo diretório, horas ou dias depois
[SessionStart hook do ai-memory busca o handoff e prepende ao contexto]
> "Continuando: você estava investigando session cookies como
   alternativa à rotação de JWT quebrada. Posso seguir?"

Você não fez nada especial. No SessionEnd do Claude Code, o ai-memory consolidou as observações da sessão numa página sessions/<uuid>.md, criou um handoff tipado com open_questions + next_steps, e marcou como “pending”. No SessionStart do Codex, o servidor viu o handoff pending, recuperou e injetou no contexto inicial. O agente lê e continua.

Mesmo cenário se você abandona o projeto por dois meses e volta. O memory_explore calibra a verbosidade automaticamente: faz menos de uma hora desde a última sessão, retorna uma linha. Faz mais de 30 dias, retorna um resumo completo do que rolou.

Adotando ai-memory num projeto que já existe

Se você instalar o ai-memory num projeto que já tem meses de história, o wiki começa vazio e as primeiras sessões são saldo zero. Você tá populando, não recuperando. O comando ai-memory bootstrap resolve isso. Ele coleta seu git log, README, docs/, cabeçalhos de módulo e arquivos de regras do projeto (CLAUDE.md / AGENTS.md), e manda pro servidor que usa o LLM pra gerar páginas-semente do wiki:

cd ~/Projects/meu-projeto
ai-memory bootstrap

Custa cerca de $0.05 com Claude Haiku 4.5 (orçamento capado em 50K input tokens). Rode com --dry-run primeiro pra ver o que seria mandado sem pagar. A partir daí o wiki começa com contexto real, e cada sessão adiciona em cima.

Instalação: três comandos

Eu reduzi a instalação ao essencial. O caminho recomendado é Docker, porque o servidor fica isolado e a atualização é uma linha. Não precisa de mais nada:

# 1. Wrapper script (~3KB) que chama o binário dentro do container
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
    -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

# 2. Sobe o servidor (loopback-only, sem auth — single-user laptop)
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    akitaonrails/ai-memory:latest

# 3. Configura seu agente
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

Pronto. Abra o Claude Code como sempre. Cada prompt e tool call agora aterrissam no ai-memory, e a próxima sessão que você abrir no projeto vai ver um handoff com onde você parou.

Repita o passo 3 com --agent codex, --agent opencode, --agent omp/pi, --client cursor, --client gemini-cli, --client pi/omp, etc. pra outros agentes. Claude Desktop e OpenClaw são MCP-only. Idempotente: re-rodar substitui só a entrada do ai-memory, preserva qualquer outro hook/MCP que você tenha. Faz backup .bak-<timestamp> antes de cada escrita.

O README do projeto cobre as variações (Docker compose, homelab no LAN com bearer token, instalação sem Docker, build do fonte). Recomendo seguir o docs/install.md se seu setup foge do caminho padrão.

Comandos úteis que vale conhecer

Depois de instalado, o dia a dia normal é só usar os agentes. Mas vale conhecer alguns comandos pra quando precisar:

• ai-memory upgrade — auto-atualização do wrapper + docker pull da imagem nova + re-instalação dos hook scripts/plugins/extensões. Idempotente. Se você tem servidor remoto separado, refresca só o cliente local; o servidor você atualiza separadamente.
• ai-memory bootstrap — semeia o wiki a partir de git log + README + docs/ + regras do projeto. Pra projetos que já existem antes do ai-memory entrar.
• ai-memory purge-project --project <nome> --confirm — apaga um projeto inteiro. Atômico: linhas do SQLite, subdir do wiki, sem tocar nos vizinhos.
• ai-memory rename-project --from <nome> --to <novo> — renomeia. Uma coluna no DB, sem mover arquivo no disco. Sem efeito colateral.
• ai-memory backup — snapshot do diretório de dados (wiki + SQLite). ai-memory restore desfaz.
• ai-memory lint / ai-memory forget-sweep / ai-memory embed — manutenção manual. Lint e forget-sweep também rodam no agendamento do servidor por padrão; embedding backfill existe mas fica desligado por default porque pode chamar provedor pago.
• ai-memory generate-auth-token — quando você for expor o servidor além do loopback (ver docs/deploy.md).

Explorando o wiki no navegador

O servidor também pode montar uma UI web read-only em http://127.0.0.1:49374/web quando sobe com --enable-web. Mesmo binário, mesma porta, sem processo extra. Serve pra três coisas práticas: auditar o que o agente vem salvando, conferir se as páginas consolidadas tão coerentes, e compartilhar uma página avulsa com alguém do time sem precisar dar acesso ao agente.

A homepage lista os projetos detectados, cada um com contagem de páginas e tempo desde a última atividade:

Repare no aviso laranja no topo: o wiki é otimizado pra consumo por LLM, com páginas compiladas a partir de observações de sessão pelo LLM consolidador. Pra documentação canônica curada por humano, use o docs/ próprio do projeto. O /web é pra “spelunking” (vasculhar o histórico).

Cada projeto é isolado por UUID na estrutura física do disco. Duas páginas com o mesmo path em projetos diferentes não colidem. Ao clicar num card você cai na árvore de páginas dele:

A sidebar mostra a árvore agrupada por tipo: concepts/ (conhecimento durável), decisions/ (decisões arquiteturais), gotchas/ (pegadinhas), _rules/ (regras de projeto sugeridas pro CLAUDE.md), sessions/ (logs por sessão), e bootstrap.md (manifesto gerado pelo ai-memory bootstrap). A coluna direita mostra atividade recente.

Clicando em qualquer página, você cai no markdown renderizado:

O rendering tem syntax highlighting, badges de tier (working/episodic/semantic/procedural) e kind (decision/gotcha/rule/fact), breadcrumbs, supersession chain visível. A busca combina FTS5, expansão por links e, se configurado, embeddings; modo claro/escuro segue a preferência do sistema via prefers-color-scheme.

Pra editar o wiki você abre os arquivos direto em qualquer editor de markdown (Obsidian funciona bem). A interface web é read-only por design: o LLM consolidador é quem escreve, humanos só leem.

Por que Docker

A escolha de Docker como caminho recomendado foi deliberada. Algumas vantagens práticas:

• Atualização é uma linha. ai-memory upgrade puxa a imagem nova, refresca o wrapper, re-instala hooks/plugins/extensões. Você não compila Rust, não cuida de versão de libsqlite, não briga com mise/Node version churn como acontece com soluções baseadas em Node.
• Isolamento real. O servidor roda no container, lê só /data (volume nomeado), não polui seu sistema. Se quiser limpar, é docker volume rm.
• Mesma imagem em vários setups. Laptop, desktop, homelab. Mesma imagem amd64 ou arm64.
• Restart automático. --restart unless-stopped faz o servidor voltar quando você reinicia o Docker, ou quando liga a máquina (assumindo systemctl enable docker).
• Build de source não é necessário. Quem compila Rust toolchain 1.95+ leva uns 3 minutos em release. Pro usuário final, isso é cerimônia desnecessária. O Docker abstrai tudo.

Tem caminho sem Docker no docs/install.md pra quem prefere. Mas Docker é onde a UX é melhor.

Qual LLM usar pra consolidação

Esse é um caso onde não precisa de modelo pesado. A consolidação é texto entra, texto sai: o agente registra observações brutas durante a sessão, no SessionEnd o LLM compila 1-5 páginas de wiki classificadas como concept / decision / gotcha / rule. Não tem raciocínio complexo, não tem código. Opus 4.7 ou GPT-5.5 thinking são overkill, custam caro e demoram muito pra uma tarefa que aceita modelo leve.

Pra escolher o default rodamos A/B testing sério em 6 provedores diferentes contra 5 fixtures sintéticas, cada uma desenhada pra estressar um modo de falha específico: extração multi-página, restrição (resistir a fabricar página quando a sessão é trivial), classificação correta de rule vs gotcha vs decision, e separação de tópicos não relacionados. A doc completa, com tabelas de parse rate, latência e qualidade por fixture, tá em docs/llm-provider-comparison.md. Resumindo a tabela final:

Por que Haiku ficou como default: hospedado (sempre disponível), o melhor em restrição (resiste a fabricar páginas quando a sessão é trivial, crucial pra wiki não virar coleção de páginas vazias) e o melhor em classificação (acerta kind: rule consistentemente, que é o que faz o roteamento automático pro _rules/<slug>.md funcionar). Custo de $0.02 por consolidação é desprezível pra uso pessoal.

Mas o usuário tem alternativas legítimas:

• GPT-5.4-mini se o orçamento aperta (5× mais barato que Haiku, 2× mais rápido). O único defeito mensurável foi fabricar uma página decisions/docs-spelling.md numa sessão de correção de typo. Over-classification, mas leve.
• qwen3:32b no Ollama se você tem servidor local com ~20GB de RAM/VRAM disponível. Zero custo por consolidação, fidelidade compatível com os hospedados. A latência alta (~92s) não importa porque consolidação roda em background.
• DeepSeek V4 Flash funciona, mas o GPT-mini iguala em qualidade e bate em velocidade.

Quem quiser testar outros modelos, o harness de avaliação tá em evals/ como crate Rust separada. Adiciona um JSON de fixture, roda cargo run -p ai-memory-eval --release, compara dois provedores lado a lado. Os outputs ficam em evals/runs/<timestamp>/{baseline,candidate}/ com o .raw.txt exato que o modelo respondeu mais o .meta.json com latência e parse rate. PRs com novos modelos testados são muito bem-vindos.

Status: beta, falta usuário

O ai-memory tá nas tags v0.2-complete no GitHub. As funcionalidades principais funcionam: captura automática, MCP, web UI opcional, bootstrap, purge/rename/backup, bearer auth, browse, busca FTS5 + graph/link-neighbour RRF, embeddings opcionais, consolidação, decay, manutenção agendada e handoff entre Claude Code / Codex / OpenCode / Cursor / Gemini CLI / OMP-Pi. Eu rodo em produção pessoal há algumas semanas.

Mas é beta. Precisa de muito mais usuário batendo nele pra eu encontrar os bugs que ainda não aparecem na minha máquina. Claude Desktop e OpenClaw funcionam como MCP-only; alguns clientes MCP exóticos ainda precisam de teste real. A integração mais polida hoje é Claude Code, seguida de Codex, OpenCode e OMP/Pi.

Se você tá lendo até aqui, considera instalar e me mandar feedback. Issues no github.com/akitaonrails/ai-memory/issues. PRs são muito bem-vindos — o código é Rust, MIT, e a arquitetura tá documentada em docs/ARCHITECTURE.md e docs/design-decisions.md. Mesmo bug report de “instalei, não rodou no meu setup” ajuda — significa que tem algo que assumi sobre ambientes que não bate com o seu.

A motivação central continua sendo a frase do Karpathy. Memória de agente é texto. Texto fica no disco. Indexa com SQLite. Compila com LLM quando vale o trabalho. Esquece quando ninguém olha mais. Sai do caminho. E quando você troca de agente no meio do projeto, o próximo já sabe onde você parou.

É isso que o ai-memory tenta entregar.

Atualização (23 de maio de 2026): depois de uma semana rodando o agentmemory em produção pessoal, voltei atrás. A arquitetura escolhida acumula uma classe de bug que não fecha sem reescrever metade do sistema (BM25 reindex a cada restart, janela de 5s de perda de dados, hook errado em ~47% das tool calls do Claude Code, etc). Comecei um substituto em Rust chamado ai-memory que resolve esses problemas. Veja Criei um Sistema de Memória pra Agentes de Código: ai-memory com o relato completo, o ranking das alternativas e como instalar. O resto desse post continua válido como background sobre como compaction funciona nos três agentes, o padrão LLM Wiki do Karpathy, e por que memória externa importa.

Todo mundo que mexe com Claude Code, Codex CLI ou opencode em sessões longas em algum momento topou com a mensagem “context approaching limit” ou viu o agente “esquecer” decisões tomadas três horas atrás. Esse post é um mergulho em como funciona a memória desses agentes hoje, onde ela quebra, e o que dá pra fazer pra ter algo mais parecido com memória de longo prazo. Olhei o código-fonte direto do Codex (Rust), do opencode (TypeScript) e do Claude Code (TypeScript, via o vazamento que circulou recentemente), e fechei testando o agentmemory, um servidor MCP open source que tenta resolver o problema de forma sistemática.

Antes de tudo: o que é “contexto”

Um modelo de linguagem (LLM) não tem memória persistente. O que ele “lembra” durante uma conversa é só o conjunto de tokens que cabem na janela de contexto dele. Cada mensagem trocada, cada arquivo lido, cada saída de comando, cada chamada de ferramenta — tudo isso entra na janela. Quando você usa Claude Code, Codex ou opencode, o agente está montando uma sequência de mensagens (system prompt + histórico + ferramentas + saída delas) e mandando inteira pra API a cada turno.

Isso tem dois efeitos diretos. O primeiro é comportamental: o agente performa melhor quando a parte relevante da conversa está fresca no contexto, e piora à medida que informação importante fica enterrada sob páginas de output de ls e grep. O segundo é financeiro: cada token enviado é cobrado (ou descontado da sua cota), e janelas grandes têm latência maior. Opus 4.7 tem 1M de contexto, GPT 5.5 também, mas só porque a janela cabe não significa que vale a pena enchê-la. Quanto mais cheia, mais lenta a inferência e mais cara a request.

Por isso todos os agentes implementam algum mecanismo de compaction: quando o contexto se aproxima do limite, o agente roda uma chamada LLM extra que resume a conversa até ali em um texto bem menor, descarta o histórico bruto, e continua a sessão em cima desse resumo. O ganho é óbvio (mais espaço pra trabalhar) e o custo também (a parte resumida perde detalhe).

Vamos ver como cada um dos três grandes implementa isso.

Codex CLI: limite por modelo + handoff explícito

O Codex CLI é open source (github.com/openai/codex), então dá pra ler o código direto. A lógica de auto-compaction vive em codex-rs/core/src/session/turn.rs e dispara assim:

let auto_compact_limit = model_info.auto_compact_token_limit().unwrap_or(i64::MAX);
// ... a cada turno ...
let total_usage_tokens = sess.get_total_token_usage().await;
let token_limit_reached = total_usage_tokens >= auto_compact_limit;

if token_limit_reached && needs_follow_up {
    let reset_client_session = match run_auto_compact(
        &sess, &turn_context, &mut client_session,
        InitialContextInjection::BeforeLastUserMessage,
        CompactionReason::ContextLimit,
        CompactionPhase::MidTurn,
    ).await { /* ... */ }
}

O limite é por modelo (auto_compact_token_limit vem de ModelProviderInfo). Quando bate, o Codex chama o próprio LLM com um prompt específico de compaction (em codex-rs/core/templates/compact/prompt.md):

Você está executando um CHECKPOINT DE COMPACTAÇÃO DE CONTEXTO. Crie um resumo de handoff pra outro LLM que vai retomar a tarefa.

Inclua:

• Progresso atual e principais decisões tomadas
• Contexto importante, restrições ou preferências do usuário
• O que ainda falta ser feito (próximos passos claros)
• Quaisquer dados críticos, exemplos ou referências necessárias pra continuar

A resposta vira o novo contexto, prefixada com um preâmbulo que diz literalmente “another language model started to solve this problem and produced a summary of its thinking process”. O Codex emite eventos pre_compact e post_compact que hooks podem interceptar (rodam em codex-rs/core/src/hook_runtime.rs). Esses hooks são o ponto onde ferramentas externas (como o agentmemory) se plugam pra salvar o estado antes da compaction destruir o histórico.

opencode: buffer de 20K + summarização ancorada

O opencode (github.com/sst/opencode) faz a mesma coisa com uma matemática diferente. Em packages/opencode/src/session/overflow.ts:

const COMPACTION_BUFFER = 20_000

export function usable(input: { cfg, model, outputTokenMax? }) {
  const context = input.model.limit.context
  const reserved = input.cfg.compaction?.reserved
    ?? Math.min(COMPACTION_BUFFER, ProviderTransform.maxOutputTokens(input.model, input.outputTokenMax))
  return input.model.limit.input
    ? Math.max(0, input.model.limit.input - reserved)
    : Math.max(0, context - ProviderTransform.maxOutputTokens(input.model, input.outputTokenMax))
}

export function isOverflow(input) {
  if (input.cfg.compaction?.auto === false) return false
  const count = input.tokens.total
    || input.tokens.input + input.tokens.output + input.tokens.cache.read + input.tokens.cache.write
  return count >= usable(input)
}

Por padrão, opencode reserva 20K tokens como buffer entre o conteúdo e o limite da janela. Quando o total de tokens passa de usable(), marca a sessão como needsCompaction = true e dispara o fluxo de compaction no próximo turno. O prompt de summarization (em packages/opencode/src/agent/prompt/compaction.txt) é mais cirúrgico que o do Codex:

Você é um assistente de sumarização de contexto ancorado pra sessões de coding.

Resuma apenas o histórico de conversa que recebeu. Os turnos mais recentes podem ser mantidos verbatim fora do seu resumo, então foque no contexto mais antigo que ainda importa pra continuar o trabalho.

Se o prompt incluir um bloco <previous-summary>, trate ele como o resumo ancorado atual. Atualize com o histórico novo preservando detalhes que continuam verdadeiros, removendo detalhes obsoletos e mesclando fatos novos.

Repare na diferença: o opencode mantém um “anchored summary” que é atualizado a cada compaction, não regenerado do zero. Os turnos mais recentes ficam verbatim, e só o histórico antigo é colapsado. É um meio-termo entre o handoff completo do Codex e manter tudo cru.

Claude Code: três níveis de compaction + summary detalhado

O Claude Code é proprietário, mas um vazamento recente expôs a fonte (TypeScript, igual o opencode mas com arquitetura bem diferente). O código mostra que a Anthropic foi mais longe que os concorrentes: o Claude Code tem três níveis de compaction rodando em paralelo, não um.

O primeiro é o microcompact time-based, em src/services/compact/microCompact.ts e timeBasedMCConfig.ts. Quando o gap desde a última mensagem do assistente passa de 60 minutos, o cache de prompt do servidor (TTL de 1h) está garantidamente expirado, então o prefixo inteiro vai ser reescrito de qualquer jeito na próxima request. Antes de mandar, o Claude Code limpa o conteúdo de resultados antigos de ferramentas (Read, Grep, Glob, WebFetch, Bash, etc.) e substitui por [Old tool result content cleared]. Reduz o tamanho da request sem entrar no fluxo caro de summarization. Comentário no código:

/** Trigger when (now − last assistant timestamp) exceeds this many minutes.
 *  60 is the safe choice: the server's 1h cache TTL is guaranteed expired
 *  for all users, so we never force a miss that wouldn't have happened. */
gapThresholdMinutes: number

O segundo nível é o autoCompact, em src/services/compact/autoCompact.ts. Análogo ao do opencode, mas com mais cuidado:

const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000
export const AUTOCOMPACT_BUFFER_TOKENS = 13_000
export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000
export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000

export function getAutoCompactThreshold(model: string): number {
  const effectiveContextWindow = getEffectiveContextWindowSize(model)
  return effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS
}

Reserva 20K tokens pra saída da summarization, 13K de buffer pra disparar a compaction, e tem warning + error thresholds 20K abaixo desse limite (a barra de status do TUI fica amarela quando passa do warning, vermelha no error). Tem também um circuit breaker: depois de 3 falhas consecutivas de auto-compact, para de tentar — um comentário interno revela que sem isso “1,279 sessions had 50+ consecutive failures (up to 3,272), wasting ~250K API calls/day globally”.

O terceiro nível é o sessionMemoryCompact em sessionMemoryCompact.ts, marcado como experimental, que cruza com o sistema de memória persistente entre sessões.

A diferença mais visível em comparação com Codex e opencode está no prompt de summarization. Onde o Codex pede 4 bullets curtos e o opencode pede um update do “anchored summary”, o Claude Code pede uma estrutura de 9 seções explícitas (src/services/compact/prompt.ts):

1. Pedido e Intenção Primária: Capture todos os pedidos e intenções explícitas do usuário em detalhe
2. Conceitos Técnicos-Chave: Liste todos os conceitos técnicos, tecnologias e frameworks discutidos.
3. Arquivos e Trechos de Código: Enumere arquivos e trechos específicos que foram examinados, modificados ou criados…
4. Erros e correções: Liste todos os erros que apareceram e como foram corrigidos…
5. Resolução de Problemas: Documente problemas resolvidos e investigações em andamento.
6. Todas as mensagens do usuário: Liste TODAS as mensagens do usuário que não são resultados de ferramentas. São críticas…
7. Tarefas Pendentes: Liste tarefas pendentes que foram explicitamente solicitadas.
8. Trabalho Atual: Descreva em detalhe precisamente o que estava sendo feito imediatamente antes desse pedido de resumo…
9. Próximo Passo Opcional: Liste o próximo passo que você vai tomar…

A seção 6 (“All user messages”) é a mais incomum: o resumo precisa conter a lista verbatim de cada mensagem do usuário que não seja resultado de ferramenta. Ou seja, mesmo depois da compaction, o Claude Code preserva o que você pediu, literal. Isso explica por que sessões compactadas no Claude Code parecem manter o tom da conversa melhor que as do Codex (onde o handoff é mais executivo e menos narrativo).

Existe também uma variante PARTIAL_COMPACT_PROMPT que summariza só o trecho mais recente quando há um summary anterior preservado, e uma PARTIAL_COMPACT_UP_TO_PROMPT pra preservar cache hit ao colocar o resumo no início. O comando /compact continua disponível como força manual, e os hooks PreCompact / PostCompact rodam como nos outros agentes.

Comparando os três lado a lado

A escolha de design conta uma história. O Claude Code investe em preservar narrativa do usuário (as 9 seções, especialmente a 6) e otimizar custo de cache (microcompact por gap, separação clara entre 3 caminhos). O Codex prioriza handoff entre modelos (a frase “summary produced by the other language model” no prefixo do resumo mostra a expectativa de que o próximo turno pode ser executado por outro LLM). O opencode escolheu summarização incremental: o anchored summary é atualizado a cada ciclo, em vez de regenerado. Cada estratégia tem trade-offs, mas é a primeira vez que dá pra olhar lado a lado o código real dos três.

“Vendor lock”? Não existe pra esse tipo de memória

Uma preocupação que aparece muito é que ao começar com Claude Code você fica “preso” a ele, e não dá pra migrar pra opencode ou Codex depois. Isso é mito. Memória de agente, como vimos, é só texto. Não tem formato proprietário binário, não tem schema fechado, não tem state que só o vendor sabe ler. Tudo que o agente carrega é prompt + histórico de mensagens + arquivos de contexto.

Na prática você pode fazer handoff manual entre agentes. Pede pro Claude Code: “escreva um documento markdown em ./HANDOFF.md com o estado atual do projeto, decisões tomadas, próximos passos, e qualquer contexto importante pra um agente diferente continuar.” Sai uma sessão bem feita, fecha o Claude Code, abre o opencode, pede “leia ./HANDOFF.md e continue de onde parou.” E o opencode pega de onde o Claude parou, sem perda significativa (a perda é exatamente a mesma que uma compaction interna teria provocado).

Esse padrão de exportar contexto explicitamente é, inclusive, melhor do que confiar na compaction automática. Você decide quando e o que preservar, ao invés de deixar o agente decidir baseado em pressão de tokens.

O problema: long-term memory desaparece junto

Compaction resolve o problema imediato (espaço no contexto) mas cria um problema mais sutil: informação do início da sessão é eliminada primeiro. Se você passou 30 minutos no turno 5 explorando uma arquitetura, decidiu três trade-offs e descartou duas abordagens, no turno 50 essa exploração inteira pode ter virado uma linha de bullet point. Se você precisar voltar pra um daqueles trade-offs descartados (“por que decidimos não usar Redis aqui?”), o agente não sabe mais.

A solução que venho usando há meses é forçar o agente a escrever em arquivos manualmente. Em projetos importantes mantenho um diretório ./.docs/ ou ./docs/ com arquivos markdown organizados por tópico: arquitetura, decisões, pegadinhas conhecidas, configurações esquisitas, links pra issues relevantes. Quando alguma coisa importante acontece numa sessão, peço: “salva isso em ./.docs/<topico>.md”. Aí na próxima sessão, ou depois de uma compaction, o agente pode reler o arquivo se precisar.

O custo dessa abordagem é disciplina. Eu tenho que lembrar de pedir pra salvar. O agente não vai fazer isso sozinho. E eu tenho que organizar os arquivos pra que ele consiga achar o que precisa depois (o que normalmente significa um arquivo MEMORY.md ou CLAUDE.md no root listando os tópicos).

Existe uma forma mais sistemática de fazer isso. O nome dela é LLM Wiki, popularizada pelo Andrej Karpathy em abril de 2026 num gist no GitHub.

O padrão LLM Wiki do Karpathy

A ideia é simples e poderosa: em vez de tratar conhecimento como algo a recuperar sob demanda (RAG), trata como algo a compilar ao longo do tempo, igual código. A arquitetura tem três camadas:

1. Raw Sources — documentos imutáveis (papers, artigos, transcrições, notas) que servem como source of truth.
2. Wiki Layer — arquivos markdown gerados e mantidos pelo LLM. Cada conceito vira uma página. Páginas referenciam outras páginas. O LLM atualiza, faz cross-reference, marca contradições.
3. Schema — um arquivo (estilo CLAUDE.md ou SCHEMA.md) que define convenções: como nomear páginas, taxonomia de tags, estrutura mínima de cada entrada.

O workflow tem três operações. Ingest: quando uma fonte nova chega, o LLM lê, extrai o que importa, atualiza 10-15 páginas existentes, cria as que faltam, conserta cross-references. Query: perguntas ganham resposta sintetizada com citações; insights valiosos viram páginas novas. Lint: passes periódicos detectam contradições, claims desatualizadas, conexões faltando.

A vantagem central sobre RAG é que conhecimento compõe. RAG re-derive resposta a cada query, partindo dos mesmos documentos brutos. A wiki sintetiza uma vez, e a próxima query parte da síntese, não dos brutos. Pra programação isso vale ouro: a primeira vez que você descobre que uma biblioteca tem uma pegadinha esquisita com timezone, vira página da wiki. Da segunda vez que o assunto aparece, o agente lê a página, não re-descobre o problema.

O trabalho manual de manter uma wiki sempre matou wikis humanas. Por isso elas morrem. Mas LLMs são bons em escrita e manutenção repetitiva. A aposta do Karpathy é que finalmente temos uma máquina que faz o trabalho chato de manter a wiki viva.

agentmemory: implementação prática do padrão

Eu vinha fazendo essa wiki manualmente em ./.docs/ há meses. Essa semana migrei pra uma ferramenta que automatiza a maior parte do processo: o agentmemory do Rohit Ghumare. É open source (Apache-2.0), e é literalmente uma implementação do padrão LLM Wiki com algumas extensões (confidence scoring, lifecycle de memórias, knowledge graph, hybrid search).

O que ele é, na prática:

• Um daemon Node rodando localmente em 127.0.0.1:3111 (REST) e :3113 (viewer web com timeline e replay de sessão). Storage em SQLite + index vetorial em memória, zero dependência externa.
• Um servidor MCP (@agentmemory/mcp) que qualquer agente compatível com MCP (Claude Code, Codex, opencode, Cursor, Gemini CLI, etc.) carrega como stdio server. Expõe 51 tools de memória (memory_smart_search, memory_save, memory_sessions, memory_consolidate, etc.).
• Plugins de hooks pra Claude Code (12 hooks) e Codex (6 hooks) que capturam observações automaticamente em cada tool call, prompt e evento de compaction.
• Retrieval híbrida: BM25 + vetor + knowledge graph, fundidos com Reciprocal Rank Fusion (RRF, k=60), com diversificação por sessão.
• 4-tier memory consolidation inspirada em como o cérebro humano processa memória durante o sono: Working (raw observations) → Episodic (resumos de sessão) → Semantic (fatos e padrões extraídos) → Procedural (workflows e padrões de decisão).

A última parte é o que torna isso interessante. Não é só um log de tudo que aconteceu. Tem decay (Ebbinghaus curve — memórias que não são acessadas decaem), reforço (memórias acessadas frequentemente fortalecem), eviction de stale, detecção e resolução de contradições. É exatamente o que falta no padrão “escrever em ./.docs/ manualmente”.

Instalação rápida

Tem três jeitos: npm global, npx, ou (o que eu fiz) um prefixo dedicado pra fugir do mise/Node version churn. A versão one-liner do README do projeto:

npm install -g @agentmemory/agentmemory     # uma vez — `agentmemory` no PATH
agentmemory                                  # sobe o daemon em :3111
agentmemory demo                             # popula sessões de exemplo + valida recall
agentmemory connect claude-code              # configura seu agente (também: codex, cursor, gemini-cli, ...)

Pra detalhes completos, o README do agentmemory cobre todas as variações (Docker, source build, Windows, embedding providers). Pra quem usa mise pra gerenciar Node, vale instalar num prefixo dedicado (algo como ~/.local/share/agentmemory-npm/) e subir o daemon via systemd user unit pra fugir do problema de pacotes globais sumirem quando o mise troca de versão de Node. Mas o caminho do README serve a maioria dos casos.

Depois de subir o daemon, o passo principal é registrar o servidor MCP no agente que você usa.

Pro Claude Code, edite ~/.mcp.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "/path/to/agentmemory-mcp",
      "env": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}

Verifique com claude mcp list. Deve aparecer agentmemory: ✓ Connected.

Pro Codex CLI, edite ~/.codex/config.toml:

[mcp_servers.agentmemory]
command = "/path/to/agentmemory-mcp"

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "http://localhost:3111"

Pro opencode, edite ~/.config/opencode/opencode.json e adicione na raiz do objeto:

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["/path/to/agentmemory-mcp"],
      "enabled": true,
      "environment": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}

Depois disso, os três agentes compartilham o mesmo servidor de memória. Salvou uma decisão no Claude Code, faz memory_smart_search no Codex e ela aparece.

Pra forçar o agente a consultar memória no início de tarefas não-triviais, vale adicionar uma linha no CLAUDE.md (ou equivalente):

At the start of non-trivial tasks, call `memory_smart_search` with the task
keywords. Use `memory_save` or `memory_lesson_save` when capturing decisions,
patterns, or preferences worth keeping.

Caso contrário o agente usa as tools quando achar que faz sentido, mas vai esquecer em sessões puramente exploratórias.

Vantagem prática: handoff sem fricção

Aqui mora a coisa que mais me convenceu. Lembra do padrão de export-pra-markdown que descrevi antes, pra migrar entre agentes? Com agentmemory, isso fica automático. Salvou uma decisão arquitetural numa sessão de Claude Code (memory_save type=architecture content="usamos cookie store em vez de session store porque X"). Abre o opencode no mesmo projeto. Pergunta sobre persistência de sessão. O opencode chama memory_smart_search, recupera a entrada, e parte daí.

Esquece o “exportar pra markdown, abrir o outro agente, mandar ler”. Os dois agentes lêem do mesmo lugar. Vendor lock perde o sentido nesse setup, porque a fonte da memória é externa a ambos.

Os trade-offs que ficam

Não é mágica. Algumas coisas pra ter na cabeça:

A camada de embedding ideal é uma API paga (Voyage, OpenAI, Cohere). Sem isso o agentmemory usa MiniLM local via @xenova/transformers, que funciona mas é mais lento na primeira ingest e menos acurado em buscas semânticas complexas. Pra quem aceita rodar um modelo local, é solução real. Pra quem quer máxima qualidade de recall, vale a chave de API.

O daemon roda como processo permanente. Precisa de um systemd unit (eu rodo em user mode) ou launchd no macOS. Não é “rode o servidor quando lembrar” — tem que estar sempre up, senão os hooks do plugin perdem eventos.

A consolidação de 4 tiers usa um LLM pra processar. Sem chave de provider configurada, o agentmemory roda em “no-op mode” — ainda indexa observações e busca, mas não comprime nem consolida. Você ainda tem o equivalente da wiki, só que sem o “lint periódico” do Karpathy.

E como toda ferramenta nova, a documentação tem buracos. Algumas coisas pra ficar de olho que não estão no README upstream: o state path real depende de como o daemon é iniciado (relativo ao cwd), a porta 49134 do iii engine bindeia em 0.0.0.0 por default (passa pelo firewall, vale conferir), o import-jsonl não respeita o flag --dry-run apesar de o help global dizer que sim. Vale ler o README do projeto antes, e estar disposto a debugar quando a docs falhar.

Memória é texto. Texto precisa de gestão.

A síntese que eu tiro disso tudo é simples. Memória de agente, no fundo, é texto. Não tem schema proprietário, não tem formato binário, não tem state secreto. Isso é libertador: você não fica preso a um vendor, pode mover entre Claude Code, Codex e opencode na hora que quiser, manualmente ou via uma camada externa como o agentmemory.

Mas texto solto vira lixo rápido. Sem compaction, a janela de contexto enche e o agente fica lento e caro. Com compaction, perde-se memória de longo prazo. Sem disciplina de salvar em arquivos, decisões importantes evaporam na próxima compaction. Sem estrutura nos arquivos, eles viram um amontoado que o agente nem consegue ler eficientemente.

A solução é uma combinação de quatro camadas:

• Compaction resolve o problema de janela de contexto cheia. Os três grandes (Claude Code, Codex, opencode) fazem isso sozinhos.
• Markdown manual em ./.docs/ ou ./docs/ é o fallback de base que sempre funciona, com a desvantagem de exigir disciplina do programador.
• Padrão LLM Wiki (Karpathy) eleva o markdown manual a um workflow estruturado: source / wiki / schema, com ingest / query / lint.
• agentmemory (ou ferramentas similares via MCP) automatiza a wiki, adiciona consolidação em tiers, retrieval híbrida, lifecycle de memória, e como bônus serve os três agentes do mesmo daemon.

A parte mais subestimada disso tudo é o efeito composto. Uma decisão arquitetural salva hoje fica disponível pra todas as sessões futuras, em qualquer agente. Uma pegadinha de biblioteca descoberta na terça-feira não precisa ser re-descoberta no domingo. É o tipo de produtividade que demora algumas semanas pra aparecer (porque você precisa de massa crítica de memórias salvas), mas que muda o jogo quando engata.

Vale testar. Se você usa Claude Code, Codex ou opencode todo dia e nunca configurou nada de memória de longo prazo, comece pelo simples (um ./.docs/ no repo atual). Quando bater a frustração da terceira “explicação que eu já dei”, aí instala o agentmemory.