Como funciona a memória no OpenCode? Entenda o que a ferramenta guarda e por quê

Você abre o OpenCode, trabalha uma hora numa feature, e do nada bate a dúvida: o que essa ferramenta realmente lembra?

É uma pergunta boa, e a resposta engana muita gente

Quando a gente fala de memória no OpenCode, na verdade estamos falando de duas coisas bem diferentes que costumam ser jogadas no mesmo balde

Uma é o que o agente lembra de propósito entre sessões, as instruções fixas do seu projeto

A outra é como ele lida com uma conversa que ficou longa demais e ameaça estourar a janela de contexto

São mecanismos separados, com arquivos e comandos próprios. Bora destrinchar os dois

O que ‘memória’ significa no OpenCode

Antes de sair configurando qualquer coisa, vale entender o mapa

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Existem dois conceitos aqui, e confundir eles é a raiz de metade da frustração de quem acha que o OpenCode ‘esquece’ as coisas

O primeiro é a memória intencional entre sessões: aquilo que você quer que o agente sempre saiba sobre o projeto, não importa quantas vezes você feche e abra a ferramenta. Isso vive nos arquivos AGENTS.md

O segundo é o gerenciamento de contexto dentro de uma sessão: o que acontece quando a conversa cresce tanto que não cabe mais inteira na janela do modelo. Isso é a compactação (compaction)

Um é sobre lembrar de propósito

O outro é sobre não perder o fio da meada numa conversa gigante

Entendendo essa divisão, o resto do post fica fácil. Se liga

AGENTS.md: as instruções que o OpenCode sempre carrega

Se você conhece o jeito que outras ferramentas de IA usam um arquivo de regras, o AGENTS.md é bem semelhante

É um arquivo de instruções persistentes que entra no contexto do modelo pra personalizar o comportamento do agente naquele projeto

E ele existe em dois lugares, cada um com um propósito

O AGENTS.md na raiz do projeto guarda as regras específicas daquele repositório: convenções de código, comandos de build, estrutura de pastas, o que for do time

Como ele fica junto do projeto, todo mundo que clona o repo herda essas regras. É a memória compartilhada do time

Já o ~/.config/opencode/AGENTS.md é o arquivo global, aplicado em todas as suas sessões, em qualquer projeto

Esse aqui é pessoal: ele não é commitado no Git nem compartilhado com o time. Por isso a recomendação é usar ele pras suas preferências pessoais, aquele jeitão que você gosta de trabalhar e que não faz sentido impor pros outros

Os dois se combinam: o global vale pra tudo, o do projeto entra por cima com o que é específico dali

Quer a documentação oficial na fonte? Está no OpenCode docs de rules

Como criar o AGENTS.md com o comando /init

Você não precisa escrever esse arquivo na unha. O OpenCode tem um comando pra isso

1. Rode /init dentro do OpenCode, na raiz do projeto

/init

Ele vai escanear os arquivos importantes do repositório, montar comandos de build, lint e test, mapear a estrutura, e pode até te fazer perguntas direcionadas pra entender melhor o projeto

2. Deixe ele fazer as perguntas e responda o que ele pedir

Quanto mais contexto ele coletar agora, menos você vai ter que corrigir depois. O resultado é um AGENTS.md já com a cara do seu repo

3. Se já existe um AGENTS.md, rode /init sem medo

O erro comum aqui é achar que o /init vai apagar o trabalho anterior e escrever tudo do zero. Não é isso: quando o arquivo já existe, ele melhora no lugar em vez de substituir. Então rodar de novo depois de mudanças grandes no projeto é seguro e até recomendado

Compactação: como o OpenCode não estoura o contexto em conversas longas

Agora o segundo pilar. E esse aqui é o que salva as conversas longas

Todo modelo tem uma janela de contexto, um limite de quanto texto ele consegue segurar de uma vez. Numa sessão comprida, cheia de código e idas e vindas, você chega nesse teto

A solução do OpenCode se chama compactação (compaction), e ela já vem ativada por padrão

O que ela faz: substitui a parte mais antiga da sessão por um checkpoint. Esse checkpoint é um resumo estruturado, mais uma cauda serializada do contexto recente

Traduzindo: ele pega o começão da conversa (que já rendeu o que tinha que render), condensa num resumo, e mantém intacto o pedaço recente que ainda está quente. Com isso, libera espaço na janela

Um ponto importante pra não gerar susto: a compactação é lossy, ou seja, ela perde parte do detalhe fino ao resumir

Mas ela não apaga as mensagens duráveis anteriores da sessão. O contexto ativo encolhe, o histórico durável continua guardado

Em projetos maiores isso é o que segura a barra: você consegue tocar uma sessão longa sem que o agente colapse por falta de espaço

Como forçar a compactação manualmente (/compact e /summarize)

A compactação roda sozinha, mas às vezes você quer disparar na hora que achar melhor. Dá pra fazer isso

1. Use o comando /compact

/compact

Existe um alias que faz a mesma coisa, o /summarize. Use o que for mais natural pra você

2. Ou use o keybind session_compact

O padrão é <leader>c. Vale lembrar que keybind pode variar conforme a config de cada um, então se o seu estiver diferente, confira suas configurações

3. Saiba o que entra no resumo antes de disparar

O resumo gerado pela compactação registra objetivo, detalhes importantes, trabalho concluído e ativo, bloqueios, próximos passos e arquivos relevantes

Ele usa o modelo selecionado da sessão, com as ferramentas desativadas, e tem um teto de 4096 tokens de saída

Quando vale a pena disparar você mesmo? Quando você acabou uma etapa grande e quer ‘fechar o capítulo’ antes de partir pra próxima, garantindo que o resumo pegue o estado num ponto limpo em vez de no meio de uma bagunça

Memória persistente entre sessões: os plugins da comunidade

Depois de tudo isso, cabe um esclarecimento honesto

Memória durável e automática entre sessões TOTALMENTE diferentes não é um recurso oficial nativo do OpenCode. O que é oficial é o AGENTS.md (instruções persistentes) e a compactação (gestão de contexto dentro da sessão)

Quando você quer ir além disso, entram os plugins da comunidade. Existem alguns:

• opencode-agent-memory, do joshuadavidthomas, inspirado no Letta
• opencode-mem, do tickernelz, que usa um banco vetorial local
• Supermemory, que oferece um plugin pro OpenCode

Todos são de terceiros, não recursos oficiais. Então antes de adotar, vale olhar cada um com calma

Quando faz sentido considerar? Quando o AGENTS.md mais a compactação não dão conta do seu fluxo, e você precisa mesmo de uma camada de memória que atravesse sessões independentes de forma automática

Conclusão

No fim, a memória no OpenCode se apoia em dois pilares, e agora eles não se confundem mais na sua cabeça

O AGENTS.md é a memória intencional: o que o agente sempre carrega sobre o projeto (na raiz, pro time) e sobre você (no global, pessoal e não versionado)

A compactação é a gestão de contexto: o que segura as conversas longas sem estourar a janela, resumindo o antigo e mantendo o histórico durável

O próximo passo prático é simples: roda /init no seu projeto pra gerar o AGENTS.md, e define suas regras globais no ~/.config/opencode/AGENTS.md

Começa por aí e já sente a diferença 🙂 até o próximo post!