Passei 5 dias depurando a memória do meu agente OpenClaw. Aqui está tudo o que aprendi.

O nome do meu agente é Chiti. Ele roda no Telegram, cuida do suporte ao cliente para dois produtos SaaS, escreve tweets, gerencia faturas e coordena com meu cofundador em fusos horários diferentes. É a coisa mais próxima que tenho de um funcionário júnior.

E por semanas, ele continuava esquecendo coisas.

Não de uma forma sutil. Eu passava uma hora configurando um cron job diário, trocava de modelo, e na sessão seguinte o Chiti agia como se nunca tivéssemos conversado. Eu mencionava uma decisão de dois dias atrás e recebia um olhar vazio. Pedia para ele continuar uma tarefa e ele começava do zero.

Então parei de construir funcionalidades e passei 5 dias, sempre que tinha tempo, apenas consertando a memória. Isso é tudo que encontrei, tudo que quebrei e tudo que realmente funcionou.

Dia 1: O Agente Esquece Tudo Depois de Conversas Longas

O primeiro problema era simples de descrever e doloroso de diagnosticar.

Depois de conversas longas, o Chiti começava a perder o contexto anterior. Não gradualmente, simplesmente desaparecia. Coisas que eu disse a ele 20 mensagens atrás tinham sumido. Decisões que tomamos no início da sessão? Nunca aconteceram.

O culpado era a compactação. Quando a conversa preenche a janela de contexto, o OpenClaw comprime mensagens mais antigas em um resumo para abrir espaço para novas. O resumo capta a essência, mas perde detalhes. Nomes, números, decisões exatas — sumiram.

Isso é por design. A janela de contexto é finita. Mas o comportamento padrão trata tudo igualmente, o que significa que sua instrução cuidadosamente elaborada da mensagem #3 recebe o mesmo tratamento que uma conversa casual da mensagem #7.

O que fiz:

Ativei o memory flush antes da compactação. Isso instrui o agente a salvar o contexto importante em disco antes que o compressor seja executado.

1{
2  "compaction": {
3    "memoryFlush": {
4      "enabled": true,
5      "softThresholdTokens": 4000
6    }
7  }
8}

Quando a sessão se aproxima do limite de contexto, o OpenClaw aciona uma rodada silenciosa que lembra o agente de salvar fatos duráveis em memory/YYYY-MM-DD.md antes que a compactação os apague. O agente escreve o que importa, a compactação é executada e o importante sobrevive em disco, mesmo que o resumo de contexto o perca.

O que aprendi:

A compactação não é sua inimiga. Perder informações durante a compactação é. A correção é garantir que qualquer coisa que valha a pena ser lembrada seja gravada em um arquivo antes que o compressor a toque. Se está apenas na janela de contexto, é temporário. Se está em disco, sobrevive.

Dia 2: A Busca Retorna Lixo

Com os logs diários acumulando e o MEMORY.md crescendo, eu precisava que o agente realmente encontrasse as coisas. A busca de memória embutida estava retornando resultados irrelevantes ou perdendo correspondências óbvias.

O problema era o backend de busca. A busca padrão do OpenClaw baseada em SQLite usa embeddings de vetores (similaridade semântica) para encontrar fragmentos relevantes. Funciona para consultas amplas, mas tem dificuldade com correspondências exatas. Eu pesquisava por um nome de cliente específico e recebia resultados sobre um tópico completamente diferente que por acaso usava linguagem semelhante.

O que fiz:

Mudei para o QMD como backend de busca de memória. O QMD combina BM25 (correspondência de palavras-chave) com embeddings de vetores e um reranker. Então, quando pesquiso por "falha de pagamento Charles", ele encontra resultados que contêm essas palavras exatas E resultados que são semanticamente relacionados, depois os reordena por relevância.

Também configurei os caminhos do QMD para incluir minha pasta de aprendizados:

1{
2  "memory": {
3    "qmd": {
4      "paths": "paths": [
5        {
6          "path": "/Users/ramya/clawd",
7          "name": "memory-root",
8          "pattern": "MEMORY.md"
9        },
10        {
11          "path": "/Users/ramya/clawd",
12          "name": "memory-alt",
13          "pattern": "memory_alt.md"
14        },
15        {
16          "path": "/Users/ramya/clawd/memory",
17          "name": "memory-dir",
18          "pattern": "**/*.md"
19        },
20        {
21          "path": "/Users/ramya/clawd/learnings",
22          "name": "learnings",
23          "pattern": "**/*.md"
24        }
25      ]
26    }
27  }
28}

O que aprendi:

A busca puramente semântica parece boa na teoria, mas falha com nomes próprios, números específicos e frases exatas. A busca híbrida (palavras-chave + vetores + reranking) é significativamente melhor para a memória de agentes no mundo real. Se seu agente não consegue encontrar algo que você sabe que está em seus arquivos, o backend de busca é provavelmente o gargalo, não os arquivos em si.

Dia 3: O Agente Encontra Mas Não Usa

Este foi o dia mais frustrante. Confirmei que a busca estava funcionando, conseguia consultar manualmente e obter os resultados corretos. Mas durante conversas reais, o Chiti não recuperava o contexto relevante, mesmo quando ele claramente existia na memória.

O problema era que a recuperação não é automática. O agente precisa decidir pesquisar. E se a conversa não acionar os sinais certos, ele não vai procurar as coisas.

O que fiz:

Adicionei instruções explícitas de recuperação na sequência de inicialização. Em vez de esperar que o agente pesquisasse quando necessário, eu disse a ele quando pesquisar:

markdown

Antes de iniciar qualquer tarefa:

• Pesquise os logs diários por contexto relacionado
• Verifique LEARNINGS.md por regras sobre este tipo de tarefa
• Se um cliente for mencionado, pesquise seu histórico

Também construí um teste de recuperação. Eu plantava um marcador específico no log diário — algo como "MARCADOR: 2026-02-20 — Lembre-se de sempre verificar o status do git antes de afirmar que o código foi enviado." Então eu esperava, iniciava uma nova sessão e perguntava: "Qual foi o marcador de ontem?" Se o agente encontrasse, a recuperação estava funcionando. Se não, algo estava quebrado.

O que aprendi:

Há uma diferença entre "a informação existe" e "o agente usa a informação". Você precisa de ambos. A infraestrutura de busca cuida da primeira parte. As instruções de inicialização e os hábitos de recuperação cuidam da segunda. Teste ambos separadamente.

Dia 4: Tornando-o Seguro para Compactação

A essa altura, eu já tinha o memory flush, a busca híbrida e as instruções de recuperação. Mas continuava perdendo contexto em um cenário específico: sessões muito longas onde a compactação era executada várias vezes.

O problema era que o memory flush só é acionado uma vez por ciclo de compactação. Se a sessão fosse longa o suficiente para duas ou três compactações, apenas a primeira recebia o tratamento de flush. Tudo depois disso estava em risco.

O que fiz:

Configurei a poda de contexto para trabalhar junto com a compactação:

1{
2  "contextPruning": {
3    "mode": "cache-ttl",
4    "ttl": "6h",
5    "keepLastAssistants": 3
6  }
7}

Isso poda agressivamente o contexto antigo após 6 horas, mantendo as últimas 3 respostas do assistente. Combinado com o memory flush, isso significa que o agente escreve coisas importantes em disco cedo, e o contexto antigo é limpo antes de causar estouro.

Também adicionei um protocolo de teste de MARCADOR: após qualquer mudança de configuração significativa, eu planto um marcador no log diário e testo a recuperação entre os limites de compactação. Se o marcador sobreviver, a mudança funcionou. Se não, algo quebrou.

O que aprendi:

Sessões longas são onde os sistemas de memória são realmente testados. Conversas curtas raramente atingem a compactação. São as sessões de trabalho profundas de 2 horas onde você perde o contexto e não consegue descobrir o porquê. Teste seu sistema de memória sob carga, não apenas em conversas rápidas.

Dia 5: O Prompt do Sistema Estava 28% Inflado

Este foi o dia em que tudo se encaixou. Executei /context detail e fiquei olhando para os números.

Meu agente estava carregando 11.887 tokens de prompt do sistema antes mesmo de ler minha mensagem. 51 habilidades, 20 das quais eu nunca tinha usado. O MEMORY.md era um wiki da empresa de 200 linhas carregado em todas as sessões. E eu tinha duas sequências de inicialização concorrentes — uma no BOOT.md (que o OpenClaw nem reconhece) e outra enterrada 200 linhas dentro do AGENTS.md.

Pior de tudo, toda vez que eu trocava de modelo, o Chiti esquecia tudo. Nenhum protocolo de entrega. Nenhuma gravação do contexto atual. Simplesmente sumia.

A causa raiz:

O OpenClaw lê automaticamente estes arquivos em cada nova sessão: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md.

Todo o resto — LEARNINGS.md, logs diários, docs, arquivos de referência — o agente precisa lê-los usando ferramentas. Se a instrução para ler esses arquivos não estiver em um dos arquivos carregados automaticamente (especificamente AGENTS.md), o agente nunca os verá.

Meu BOOT.md tinha a sequência de inicialização completa. Mas o OpenClaw não carrega BOOT.md automaticamente. Então, as instruções apenas ficavam lá, não lidas, sem fazer nada.

O que fiz:

Fiz uma auditoria e limpeza completa:

1. Mudei a sequência de inicialização para o topo do AGENTS.md (o único lugar confiável para instruções de inicialização)
2. Deletei BOOT.md (não reconhecido pelo OpenClaw)
3. Deletei BOOTSTRAP.md (arquivo de integração único, já concluído, estava desperdiçando 361 tokens a cada sessão)
4. Reduzi MEMORY.md de 200 linhas para 90, movendo documentos de referência para uma pasta docs/
5. Removi 20 habilidades de marketing não utilizadas que estavam consumindo 3.000 tokens por sessão
6. Adicionei disciplina de escrita: toda tarefa registra seu resultado, todo erro se torna uma regra
7. Adicionei um protocolo de entrega: antes de qualquer troca de modelo ou fim de sessão, o agente escreve o contexto atual no log diário

A sequência de inicialização agora se parece com isso:

markdown

Antes de fazer QUALQUER COISA:

1. Leia USER.md
2. Leia learnings/LEARNINGS.md
3. Leia memory/YYYY-MM-DD.md (hoje + ontem)
4. Leia MEMORY.md (apenas na sessão principal, nunca em grupos)
5. Leia PROTOCOL_COST_EFFICIENCY.md
6. Imprima: CARREGADO: USER | LEARNINGS | DAILY | MEMORY | PROTOCOL

A disciplina de escrita:

markdown

Após cada tarefa:

1. Registre decisão + resultado → memory/YYYY-MM-DD.md
2. Se erro → anexe a learnings/LEARNINGS.md
3. Se contexto significativo → atualize MEMORY.md (apenas durante revisões de heartbeat, nunca diretamente durante tarefas)

O protocolo de entrega:

markdown

Antes do fim da sessão ou troca de modelo:

Escreva a seção ENTREGA em memory/YYYY-MM-DD.md:

• O que foi discutido
• O que foi decidido
• Tarefas pendentes com detalhes exatos
• Próximos passos restantes

Resultados:

• Prompt do sistema: 11.887 → 8.529 tokens
• Habilidades: 51 → 32
• Tokens da sessão: 18.280 → 14.627
• 28% mais leve. Mesmo agente. Mesmos modelos. Apenas menos ruído.

O que aprendi:

A verdadeira correção não foi adicionar mais arquivos. Foi remover aqueles que não estavam fazendo nada. Cada token no prompt do sistema é uma sobrecarga que o agente carrega em cada mensagem. Habilidades não utilizadas, arquivos de memória inchados, arquivos que o sistema nem lê — todos se acumulam silenciosamente.

As Regras que Eu Gostaria de Saber no Dia 1

Depois de 5 dias quebrando coisas e consertando-as, estas são as regras que eu daria a qualquer um configurando a memória do OpenClaw:

1. Apenas estes arquivos são carregados automaticamente: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md.

Todo o resto precisa de uma instrução de leitura explícita em AGENTS.md. Se não estiver na sequência de inicialização, o agente não o verá. BOOT.md não é uma coisa real no OpenClaw. Eu tive um por semanas. Não fez nada.

2. A sequência de inicialização vai no topo do AGENTS.md.

Não no meio. Não no final. Bem no topo. Os arquivos carregados automaticamente são injetados no prompt do sistema, então as instruções de inicialização precisam ser a primeira coisa que o agente processa.

3. A disciplina de escrita é mais importante que a disciplina de leitura.

A maioria das pessoas configura arquivos para o agente ler, mas nunca impõe a gravação de volta. Se o agente não registra decisões, resultados e erros em disco, essas coisas existem apenas na janela de contexto. E a janela de contexto é compactada. A gravação de volta é como o contexto temporário se torna memória permanente.

4. Nunca escreva diretamente no MEMORY.md durante as tarefas.

Os logs diários são brutos e apenas anexados. O MEMORY.md é uma memória de longo prazo curada. Se você permitir que o agente despeje qualquer coisa no MEMORY.md, ele incha em uma bagunça de 200 linhas em poucas semanas. Cuide do MEMORY.md durante revisões periódicas (heartbeat ou cron) destilando insights dos logs diários recentes. Aprendi isso com um colega usuário do OpenClaw que pegou seu agente fazendo exatamente isso — inchando o MEMORY.md com ruído não curado até que se tornasse inútil.

5. LEARNINGS.md é o arquivo mais subestimado.

Cada erro que o agente comete deve se tornar uma regra de uma linha. "Nunca afirme que o código foi enviado sem verificar o status do git." "Não leia o MEMORY.md completo em chats de grupo." "Sempre confirme o fuso horário do usuário antes de agendar." Essas regras se acumulam. Depois de algumas semanas, seu agente tem um manual de operações pessoal construído a partir de suas próprias falhas.

6. Teste a recuperação, não apenas o armazenamento.

Armazenar informações e recuperá-las são problemas diferentes. Já tive arquivos indexados e pesquisáveis, mas nunca acessados porque o agente não sabia que deveria procurá-los. Plante marcadores, teste entre sessões, teste entre trocas de modelo. Se o agente não consegue encontrar o que você armazenou ontem, o armazenamento não importa.

7. O protocolo de entrega é a correção para a troca de modelo.

Os agentes do OpenClaw perdem todo o contexto quando você troca de modelo. O novo modelo começa com uma janela de contexto limpa — ele só vê os arquivos carregados automaticamente. Sem um protocolo de entrega que despeje o estado atual no log diário antes da troca, o novo modelo não tem ideia do que estava acontecendo. Este foi meu maior ponto de dor por semanas.

8. Execute /context detail regularmente.

Este comando mostra exatamente o que está consumindo seus tokens. Habilidades que você esqueceu que instalou, arquivos que cresceram sem você notar, ferramentas que você nunca usa. Encontrei 20 habilidades não utilizadas queimando 3.000 tokens por sessão. Isso são 3.000 tokens de sobrecarga em cada mensagem, para funcionalidades que eu nunca tinha tocado.

9. A busca híbrida supera a busca puramente semântica.

BM25 (palavras-chave) + vetores (significado) + reranking dá resultados significativamente melhores do que apenas vetores. Nomes de clientes, números específicos, frases exatas — a busca semântica perde isso. A busca por palavras-chave captura. Use ambos.

10. A compactação não é a inimiga. O contexto não escrito é.

Passei dias lutando contra a compactação antes de perceber que a correção era mais simples: garantir que qualquer coisa importante seja gravada em um arquivo antes que a compactação seja executada. O memory flush lida com isso automaticamente. Se está em disco, sobrevive à compactação. Se está apenas na conversa, está em risco.

Minha Configuração Atual

Para referência, aqui está como meu espaço de trabalho se parece agora:

workspace/

├── AGENTS.md (sequência de inicialização + disciplina de escrita + protocolo de entrega)

├── SOUL.md (personalidade e comportamento)

├── IDENTITY.md (nome, função)

├── USER.md (informações do proprietário)

├── TOOLS.md (diretrizes de uso de ferramentas)

├── HEARTBEAT.md (comportamento de check-in autônomo)

├── MEMORY.md (memória de longo prazo curada, ~90 linhas)

├── PROTOCOL_COST_EFFICIENCY.md

├── learnings/

│ └── LEARNINGS.md (regras de erros)

├── memory/ (logs diários: YYYY-MM-DD.md)

├── docs/ (documentos de referência movidos para fora do MEMORY.md)

│ ├── tweetsmash-arch.md

│ ├── knowledge-transfer.md

│ ├── infrastructure.md

│ └── group-chat-rules.md

└── skills/ (32 habilidades, de 51)

Prompt do sistema: 8.529 tokens. Tokens da sessão: 14.627 de 200.000 da janela de contexto (7,3%). O agente inicializa, lê o que precisa, escreve o que aprende e entrega o contexto antes das trocas de modelo.

Levei 5 dias para chegar aqui. A maior parte foi desaprender a suposição de que mais arquivos é igual a melhor memória. Não é. Disciplina é. Meu experimento ainda continua.

Estou construindo o TweetSmash e o LinkedMash — ferramentas de bookmark para mídias sociais com meu cofundador. Compartilho o que aprendo sobre executar agentes OpenClaw em produção no X: @code_rams