A maioria dos Agentes de IA mantém sua memória dentro das janelas de conversa, e quando estas são fechadas, a memória desaparece. O OpenClaw escolheu um caminho diferente: tratar o sistema de arquivos como o cérebro do Agente.

1. O Problema Inicial: Por que os Agentes de IA "esquecem"?

Quem já usou um Agente de IA já passou por essa experiência:

Você conversou com ele por duas horas ontem, explicando o contexto do projeto, as escolhas técnicas e suas preferências. Ao abrir uma nova conversa hoje, ele se comporta como um estranho que não sabe nada. Você precisa repetir tudo novamente.

Isso não é porque a IA seja insuficientemente inteligente, mas sim por causa da falta de um design adequado para a memória.

Na abordagem tradicional, a memória do Agente reside no contexto da janela, que é volátil e limitada. Quando ultrapassa o limite de tamanho, o conteúdo antigo é truncado. Cada nova conversa reinicia tudo.

A solução proposta pelo OpenClaw é simples e direta:

Os arquivos não se apagam. Escreva a memória em arquivos.

2. Arquivo como SO: A Filosofia Central do OpenClaw

O princípio fundamental do OpenClaw é tratar o sistema de arqiuvos como o sistema operacional do Agente.

Neste modelo, tudo é um arquivo:

Componente	Arquivo	Função
Personalidade do Agente	SOUL.md	Define tom, personalidade e limites do papel
Políticas de Comportamento	policy.md	Estabelece limites de ações do Agente
Memória Persistente	MEMORY.md	Armazena conhecimento essencial entre sessões
Registro Diário	memory/YYYY-MM-DD.md	Registros diários, apenas adição
Documentação de Ferramentas	TOOLS.md	Notas e configurações de ferramentas mantidas pelo usuário
Tarefas Automáticas	HEARTBEAT.md	Lista de tarefas executadas periodicamente

Não é banco de dados, nem armazenamento vetorial, nem serviço na nuvem. São apenas arquivos Markdown em seu sistema local, rastreáveis pelo Git, editáveis em qualquer editor de texto, e legíveis por humanos.

Esta abordagem oferece uma vantagem rara: transparência. Não há necessidade de especular sobre o que o Agente "lembrará" — basta abrir a pasta para ver.

3. Modelo de Memória em Três Camadas

A memória do OpenClaw não é uma estrutura plana de pares chave-valor, mas sim uma arquitetura em três níveis, correspondendo às três dimensões da memória humana:

┌─────────────────────────────────┐
│    Memória de Trabalho (Working Memory)   │  ← Contexto atual, volátil
│   Prompt do sistema + histórico + resultados   │
└────────────────┬────────────────┘
                 │ Compactação automática ao exceder limite
                 ▼
┌─────────────────────────────────┐
│    Memória Curta (Compaction)       │  ← Resumo compactado, mantém essencial
│   Resumo do histórico da sessão atual         │
└────────────────┬────────────────┘
                 │ Escrita manual de informações importantes
                 ▼
┌─────────────────────────────────┐
│    Memória Longa (Arquivos de Memória)  │  ← Persistente, nunca se apaga
│  MEMORY.md + memory/ano-mes-dia.md   │
└─────────────────────────────────┘

Memória de Trabalho: presente no contexto atual, mais recente, mas volátil.

Memória Curta (Compaction): quando o contexto está quase cheio, o sistema compacta o histórico antigo em um resumo, preservando pontos-chave e liberando espaço. É o mecanismo de limpeza da mesa de trabalho do Agente.

Memória Longa (Arquivos de Memória): apenas o conteúdo escrito em arquivos sobrevive entre sessões. Essa é a inovação central do OpenClaw e a origem do conceito de "arquivo como verdade".

O único nível persistente de memória é o arquivo. O que não está no arquivo, não foi realmente lembrado.

4. Dois Tipos de Arquivo-Chave: MEMORY.md vs Log Diário

MEMORY.md —— Base de Conhecimento Persistente

MEMORY.md é o "centro de memória persistente" do Agente, contendo conhecimento essencial que deve ser mantido permanentemente:

# Preferências do Usuário
- Estilo de blog técnico: informal, com dados, com frase impactante no fim
- Preferência de linguagem: Python > Go > TypeScript
- Não gosta de usar emojis, considera não profissional

# Acordos do Projeto
- Todos os arquivos de blog ficam em /Users/xxx/WorkBuddy/Claw/
- Formato de nomeação: tema-kebab-case.md
- Tarefa automática diária: gerar artigo todos os dias às 8h, foco em IA Agent

# Registros de Decisões Importantes
- 2026-03-01: Escolha do FastAPI como framework backend, por familiaridade da equipe
- 2026-03-08: Implementação de mecanismo de código secreto: primeiro informar código antes de executar tarefa

Características do MEMORY.md:

• Carregado apenas em sessões privadas, evitando vazamento para contextos em grupo
• Atualizações em vez de adições, mantendo a simplicidade
• Conteúdo estruturado, seções por tópico facilitam a navegação

memory/YYYY-MM-DD.md —— Registro Diário de Atividades

O registro diário é um registro aditivo que registra as atividades do dia:

# Registro de 2026-03-14

## Tarefa: Escrever post sobre Vibe Coding Survival Guide
- Artigo de referência: https://juejin.cn/post/7615229750572236809
- Tema: Relatório prático de 443 projetos / 84 bilhões de tokens
- Arquivo: /Users/xxx/WorkBuddy/Claw/vibe-coding-survival-guide.md

## Tarefa: Publicar artigo em três plataformas
- Editor CSDN aberto, aguardando permissão
- Abas de tags do Juejin e Zhihu prontas

Características do registro diário:

• Lido automaticamente ao iniciar a sessão, inclui conteúdo de hoje e ontem para manter continuidade
• Somente adição, sem modificação, preservando histórico completo
• Registros acima de 30 dias devem ser resumidos em MEMORY.md e excluídos para evitar acúmulo

5. Motor de Busca: Fazer os Arquivos "Viverem"

Ter arquivos não é suficiente. Como encontrar rapidamente o conteúdo relevante quando há muitos?

O OpenClaw implementa um sistema híbrido de busca, exposto ao Agente por meio de duas funções:

memory_search —— Busca Semântica

Consulta: "Qual estilo de código o usuário prefere?"
→ Retorna: linha 12 em MEMORY.md, similaridade 0.94
→ Trecho: "Preferência de linguagem: Python > Go > TypeScript"

memory_search utiliza busca híbrida:

• 70% busca textual completa via SQLite FTS5, precisão em palavras-chave
• 30% busca vetorial semântica usando modelos de embedding

Combinação ponderada com modelo de decaimento temporal (conteúdo recente tem maior peso) e MMR para diversidade (evita repetição), retornando os trechos mais relevantes.

memory_get —— Leitura Exata

memory_get("MEMORY.md", line=1, count=50)
→ Retorna as primeiras 50 linhas de MEMORY.md

Quando você sabe exatamente onde está a informação, use memory_get para leitura direta e eficiente.

6. Resiliência do Sistema: Cadeia de Degradiação em Quatro Níveis

Um detalhe importante no sistema de memória do OpenClaw é a cadeia de degradação em quatro níveis.

A ordem de prioridade dos modelos de embedding é:

Modelo Local (Ollama/LM Studio)
    ↓ Se indisponível
OpenAI text-embedding-3
    ↓ Se indisponível
Gemini / Voyage / Mistral
    ↓ Se todos falharem
Busca textual SQLite FTS5 (apenas palavras-chave)

Mesmo com todos os serviços de embedding offline, o sistema ainda pode funcionar com busca por palavras-chave, garantindo que o sistema de memória nunca falhe completamente por dependências externas.

Essa é uma abordagem engenhosa: não assumir que serviços externos estarão sempre disponíveis, preservando funcionalidades essenciais mesmo em condições adversas.

7. Guia Prático: Como Utilizar Este Sistema

Estratégias de Gravação

Coisas para lembrar entre sessões → MEMORY.md (atualize conteúdo existente)
Atividades do dia → memory/YYYY-MM-DD.md (adicionar apenas)
Configurações de ferramentas → TOOLS.md
Preferências do usuário → Seção "Preferências do Usuário" em MEMORY.md
Decisões técnicas importantes → Seção "Registros de Decisões" em MEMORY.md

Regra dourada: Se desejar reutilizar algo na próxima sessão, escreva no arquivo.

Dicas de Otimização de Busca

1. Habilite busca híbrida: Configure memorySearch.enabled: true no arquivo de configuração
2. Defina decaimento temporal: halfLifeDays: 30 para dar prioridade à memória recente
3. Resuma logs mensalmente: Extraia o essencial de memory/YYYY-MM-DD.md para MEMORY.md
4. Use estruturação: Seções com títulos Markdown ajudam a segmentar melhor o conteúdo vetorial

Considerações de Segurança

Como o Agente tem permissão para gravar arquivos, é necessário prevenir ataques de injeção de memória — instruções maliciosas podem tentar modificar MEMORY.md.

Sugestões:

• Não armazene senhas ou chaves em arquivos de trabalho; use variáveis de ambiente
• Revise regularmente o conteúdo de MEMORY.md para detectar alterações aômalas
• Mantenha MEMORY.md como privado, evitando exposição em contextos públicos ou em grupo

8. Por Que "Arquivo como Verdade" é uma Boa Resposta

Voltando ao problema inicial: onde a memória de um Agente de IA deveria residir?

Banco de dados? Intransparência, difícil de migrar. Serviço na nuvem? Risco à privacidade, dependência de rede. Base vetorial? Retorno misterioso, difícil de depurar.

A resposta do OpenClaw é: arquivos de texto puro.

• Legibilidade: humanos podem ler, editar diretamente
• Rastreabilidade: controle de versão com Git
• Portabilidade: copiar pasta copia toda a memória
• Depurabilidade: quando o resultado da busca é duvidoso, abra o arquivo

Não é tecnologia avançada — é uma resistência à complexidade desnecessária.

O melhor sistema é frequentemente o mais simples.

Os arquivos não esquecem, não falham, estão sempre lá.

Arquivo como verdade (File are the source of truth) — essa frase é o lema do sistema de memória do OpenClaw, e a diferença fundamental entre ele e outros frameworks de Agente de IA.

Referências

• Documentação oficial do OpenClaw · Sistema de Memória
• Prática em Sistemas de Memória de Agentes de IA: Melhores práticas do OpenClaw
• Análise profunda do sistema de memória do OpenClaw: Como um Agente "lembra de você"
• Guia completo do arquivo MEMORY.md do OpenClaw