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 de dois produtos SaaS, escreve tweets, gerencia faturas e se coordena com meu cofundador em diferentes fusos horários. É a coisa mais próxima que tenho de um funcionário júnior.

E por semanas, ele ficava esquecendo coisas.

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

Então parei de construir funcionalidades e passei 5 dias, sempre que tinha um tempo, só consertando a memória. Aqui está tudo o que encontrei, tudo o que quebrei e tudo o que realmente funcionou.

Dia 1: O Agente Esquece Tudo Após Conversas Longas

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

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

O culpado era a compactação. Quando a conversa enche 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 – tudo vai embora.

Isso é proposital. A janela de contexto é finita. Mas o comportamento padrão trata tudo igual, 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 despejo de memória antes da compactação. Isso instrui o agente a gravar o contexto importante no disco antes que o compressor entre em ação.

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 dispara 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 é importante, a compactação roda, e as coisas importantes sobrevivem no disco, mesmo que o resumo de contexto as perca.

O que aprendi:

Compactação não é sua inimiga. Perder informações durante a compactação, sim. A solução é garantir que tudo que vale a pena lembrar seja salvo em um arquivo antes que o compressor toque nele. Se está só na janela de contexto, é temporário. Se está no disco, sobrevive.

Dia 2: A Busca Retorna Lixo

Com os logs diários se acumulando e o MEMORY.md crescendo, eu precisava que o agente realmente encontrasse 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 trechos relevantes. Funciona para consultas amplas, mas sofre com correspondências exatas. Eu buscava um nome de cliente específico e recebia resultados sobre um tópico completamente diferente que por acaso usava linguagem similar.

O que fiz:

Troquei para o QMD como backend de busca de memória. O QMD combina BM25 (correspondência por palavras-chave) com embeddings de vetores e um reranker. Então, quando busco por "falha de pagamento do 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": [
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:

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

Dia 3: O Agente Encontra, Mas Não Usa

Esse foi o dia mais frustrante. Confirmei que a busca estava funcionando – eu conseguia consultar manualmente e obter os resultados certos. 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 buscar. E se a conversa não disparar 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 buscasse quando necessário, eu disse a ele quando buscar:

markdown

Antes de iniciar qualquer tarefa:

• Busque nos logs diários o contexto relacionado
• Verifique LEARNINGS.md em busca de regras sobre esse tipo de tarefa
• Se um cliente for mencionado, busque seu histórico

Também criei 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 git status antes de afirmar que o código foi enviado." Então 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 os dois separadamente.

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

A essa altura, eu já tinha despejo de memória, busca híbrida e 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 despejo de memória só dispara 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 despejo. Todo o resto depois disso estava em risco.

O que fiz:

Configurei a poda de contexto para trabalhar em conjunto 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 despejo de memória, significa que o agente grava coisas importantes no disco cedo, e o contexto antigo é limpo antes de causar estouro.

Também adicionei um protocolo de teste com marcador: após qualquer mudança significativa de configuração, planto um marcador no log diário e testo a recuperação através dos 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 realmente são testados. Conversas curtas raramente atingem a compactação. São as sessões de trabalho profundo de 2 horas onde você perde contexto e não consegue descobrir por quê. Teste seu sistema de memória sob carga, não apenas em conversas rápidas.

Dia 5: O Prompt do Sistema Estava 28% Inchaço

Esse 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 usei. MEMORY.md tinha 200 linhas de wiki da empresa carregadas 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 handover. Nenhuma gravação do contexto atual. Simplesmente perdido.

A causa raiz:

O OpenClaw lê automaticamente esses arquivos em toda 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 por conta própria 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 continha a sequência de inicialização completa. Mas o OpenClaw não carrega BOOT.md automaticamente. Então as instruções ficavam lá, não lidas, não fazendo nada.

O que fiz:

Fiz uma auditoria e limpeza completa:

1. Movi a sequência de inicialização para o topo do AGENTS.md (o único lugar confiável para instruções de inicialização)
2. Excluí BOOT.md (não reconhecido pelo OpenClaw)
3. Excluí BOOTSTRAP.md (arquivo de integração único, já concluído, 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 vira uma regra
7. Adicionei um protocolo de handover: antes de qualquer troca de modelo ou término de sessão, o agente escreve o contexto atual no log diário

A sequência de inicialização agora fica assim:

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: USUÁRIO | APRENDIZADOS | DIÁRIO | MEMÓRIA | PROTOCOLO

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 heartbeat, nunca diretamente durante tarefas)

O protocolo de handover:

markdown

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

Escreva a seção HANDOVER 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 por sessão: 18.280 → 14.627
• 28% mais leve. Mesmo agente. Mesmos modelos. Apenas menos ruído.

O que aprendi:

A verdadeira solução não foi adicionar mais arquivos. Foi remover aqueles que não estavam fazendo nada. Cada token no prompt do sistema é overhead que o agente carrega em cada mensagem. Habilidades não utilizadas, arquivos de memória inchados, arquivos que o sistema nem lê – tudo isso se acumula silenciosamente.

As Regras Que Eu Gostaria de Saber no Dia 1

Depois de 5 dias quebrando e consertando coisas, estas são as regras que eu daria para 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 explícita de leitura no AGENTS.md. Se não estiver na sequência de inicialização, o agente não verá. BOOT.md não é algo 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. Disciplina de escrita importa mais que 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 no 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.

Logs diários são brutos e somente anexo. MEMORY.md é memória de longo prazo curada. Se você deixar o agente despejar qualquer coisa no MEMORY.md, ele incha em uma bagunça de 200 linhas em semanas. Cure o MEMORY.md durante revisões periódicas (heartbeat ou cron), destilando insights de 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.

Todo erro que o agente comete deve se tornar uma regra de uma linha. "Nunca afirme que o código foi enviado sem verificar o git status." "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 handover é a correção para a troca de modelo.

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

8. Execute /context detail regularmente.

Esse comando mostra exatamente o que está consumindo seus tokens. Habilidades que você esqueceu que instalou, arquivos que cresceram sem você perceber, 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 overhead em cada mensagem, para recursos que nunca toquei.

9. Busca híbrida supera busca semântica pura.

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

10. Compactação não é sua inimiga. Contexto não escrito é.

Passei dias lutando contra a compactação antes de perceber que a solução era mais simples: garantir que tudo o que é importante seja salvo em um arquivo antes que a compactação rode. O despejo de memória lida com isso automaticamente. Se está no disco, sobrevive à compactação. Se está apenas na conversa, está em risco.

Minha Configuração Atual

Para referência, aqui está como meu workspace está agora:

workspace/

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

├── SOUL.md (personalidade e comportamento)

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

├── USER.md (informações do dono)

├── 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 por sessão: 14.627 de uma janela de contexto de 200.000 (7,3%). O agente inicializa, lê o que precisa, escreve o que aprende e entrega o contexto antes de trocas de modelo.

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

Estou construindo TweetSmash e LinkedMash – ferramentas de bookmark para redes sociais com meu cofundador. Compartilho o que aprendo sobre executar agentes OpenClaw em produção no X: [@code_rams](https://x.com/code_rams)