Sistema de memória local do OpenClaw: como armazenar memórias de IA em arquivos Markdown

Na semana passada, pedi à IA que analisasse uma proposta de arquitetura. Quando fui procurar no histórico da conversa, descobri que o conteúdo já havia desaparecido. Assistentes de IA ajudam a resolver problemas, mas têm memória curta: quando uma conversa termina, praticamente esquecem tudo o que foi dito. Mais importante ainda: para onde vão esses dados? Ficam armazenados em servidores na nuvem? Quem pode vê-los?

O OpenClaw armazena todas as memórias da IA em arquivos Markdown, diretamente no disco local. Essa abordagem resolve dois problemas: dá memória de longo prazo à IA e evita que os dados sejam enviados para a nuvem.

Este artigo explica o sistema de memória do OpenClaw: a arquitetura em duas camadas, formada por logs temporários e conhecimento persistente; a busca híbrida, que combina palavras-chave com BM25 e busca semântica por vetores; e os mecanismos locais de proteção da privacidade. Você mantém controle total dos dados, pode abri-los e editá-los a qualquer momento no VSCode e usar o Git para versionamento.

Guia econômico para criar seu “lagostim”: o ArkClaw torna os agentes de IA acessíveis de verdade

O OpenClaw, também conhecido como “lagostim”, ficou popular recentemente. Ele é útil, mas sua configuração afasta muita gente. O ArkClaw, da Volcano Engine da ByteDance, reduz drasticamente essa barreira. Sem precisar lidar com servidor nem configurar tokens, você consegue com um clique um “faz-tudo de IA” disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

E o principal: custa pouco. A mensalidade é de apenas 9,9 yuans; usando meu código de convite ZLKUK54M (cadastre-se aqui), sai por apenas 8,9 yuans. Se você programa, também pode entrar diretamente no Coding Plan Pro e usá-lo sem custo adicional.

Por que escolher Markdown: a filosofia file-first

Sinceramente, quando vi pela primeira vez que o OpenClaw armazenava memórias de IA em Markdown, fiquei confuso. Markdown não serve para escrever documentos? Como pode funcionar como banco de dados?

Pensando melhor, porém, esse design é bastante inteligente.

Imagine que todas as memórias da IA estejam no PostgreSQL. Para ver o que ela guardou, seria preciso abrir um cliente de banco de dados e escrever uma consulta SQL — só de pensar já dá trabalho. E com arquivos Markdown? Basta abrir no VSCode e tudo fica visível. Quer alterar alguma coisa? Edite e salve. Quer fazer backup? Copie a pasta. Quer voltar ao estado da semana passada? Um comando do Git resolve.

Os autores do OpenClaw chamam essa filosofia de “file-first”. Em essência, os arquivos Markdown funcionam como a “única fonte da verdade” (Single Source of Truth): todos os dados ficam nos arquivos, enquanto o banco de dados serve apenas para criar índices e acelerar a busca.

Essa ideia segue a mesma linha do padrão NOTES.md recomendado pela Anthropic. A recomendação oficial para desenvolvedores que usam Claude é manter um arquivo NOTES.md no projeto para registrar decisões importantes e informações de contexto do processo de desenvolvimento. Assim, o assistente de IA pode ler o arquivo em cada sessão e manter a continuidade do contexto. O OpenClaw leva esse conceito ao limite: em vez de apenas um arquivo, todo o sistema de memória é baseado em Markdown.

Veja a comparação com abordagens tradicionais:

• Redis/banco de dados em memória: tem bom desempenho, mas perde os dados ao reiniciar e exige persistência adicional
• PostgreSQL/MySQL: oferece muitos recursos, mas é pesado, exige operação e dificulta a visualização direta dos dados
• Banco de dados vetorial, como Pinecone: foi criado para IA, mas normalmente funciona como serviço em nuvem e tira os dados do ambiente local

As vantagens da abordagem com Markdown são claras:

1. Legível por pessoas: você pode abrir os arquivos a qualquer momento e conferir o que a IA guardou
2. Controle total: os dados ficam no seu disco; você decide como fazer backup, excluir ou criptografar
3. Compatível com Git: permite acompanhar as mudanças nas memórias com controle de versão e até colaborar em equipe
4. Sem dependências: não exige serviço de banco de dados, Docker nem serviço em nuvem

É claro que essa abordagem não é perfeita. O maior problema é a eficiência da busca: como encontrar rapidamente o conteúdo relevante em uma enorme quantidade de arquivos de texto? Falaremos disso mais adiante.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Arquitetura de memória em duas camadas: o equilíbrio entre o temporário e o persistente

O sistema de memória do OpenClaw se parece bastante com o cérebro humano. As pessoas têm memória de curto e longo prazo; o OpenClaw também tem duas camadas: logs diários (Daily Logs) e conhecimento organizado (Curated Knowledge).

Os logs temporários funcionam como a memória de curto prazo. O que você fez hoje e o que acabou de dizer ficam em arquivos como memory/YYYY-MM-DD.md. Em 5 de fevereiro de 2026, por exemplo, o OpenClaw cria automaticamente memory/2026-02-05.md e registra todas as atividades em um formato append-only.

O detalhe inteligente é que o OpenClaw carrega automaticamente os logs do dia atual e do dia anterior. Por que dois dias? Isso mantém a continuidade do contexto recente: o que você disse ontem à IA ainda estará disponível hoje. Logs mais antigos não são carregados automaticamente, pois poderiam estourar a janela de contexto.

Já o conhecimento persistente é a memória de longo prazo organizada e fica em um diretório MEMORY dedicado. Esses arquivos contêm informações importantes extraídas manual ou automaticamente, como documentação da arquitetura do projeto, registros de decisões fundamentais e trechos de código usados com frequência.

Imagine esta estrutura:

memory/
├── 2026-02-01.md          # Log antigo, não é carregado automaticamente
├── 2026-02-04.md          # Log de ontem, carregado automaticamente
├── 2026-02-05.md          # Log de hoje, carregado automaticamente
└── MEMORY/
    ├── project-architecture.md   # Conhecimento persistente, consultado quando necessário
    ├── deployment-notes.md
    └── troubleshooting-guide.md

Sempre que a IA é iniciada, ela lê diretamente os arquivos de log dos dois dias mais recentes e insere o conteúdo na janela de contexto. Assim, uma conversa interrompida ontem pode continuar hoje sem ruptura. Para encontrar uma informação registrada há um mês, porém, é preciso usar o sistema de busca no diretório MEMORY.

Essa arquitetura em duas camadas tem um recurso muito prático: o arquivamento automático. Quando muitos arquivos de log se acumulam, o OpenClaw aciona o mecanismo de flush, compactando ou arquivando os logs antigos para evitar que ocupem todo o disco. Informações importantes podem ser extraídas manual ou automaticamente para o armazenamento persistente.

Para ser sincero, esse design me lembra a curva de esquecimento da memória humana. Nem toda lembrança precisa ser guardada para sempre; é natural que a maioria das informações temporárias desapareça. O que realmente importa se consolida na memória de longo prazo.

Busca eficiente: uma solução híbrida com busca vetorial no SQLite

Agora surge a pergunta: se você tiver centenas de arquivos Markdown, como encontrar rapidamente o conteúdo relevante?

Depender apenas de grep ou busca de texto completo não basta. Você pode procurar por “como implantar uma aplicação em contêineres”, enquanto o arquivo diz “criação de imagem Docker e processo de implantação no K8s”. Como as palavras-chave não correspondem, nada aparece. Essa é a limitação da busca puramente textual: ela encontra correspondências literais, mas não entende o significado.

A solução do OpenClaw é a busca híbrida, que combina pesquisa por palavras-chave, usando o algoritmo BM25, e busca semântica por similaridade vetorial.

Como isso funciona na prática?

1. Camada de índice: o SQLite é usado para criar o índice. Sempre que um arquivo Markdown é gravado, o OpenClaw divide o conteúdo em pequenos blocos (chunks) e depois:

   • cria um índice de texto completo com o mecanismo FTS5 (Full-Text Search) do SQLite, permitindo a correspondência rápida de palavras-chave
   • chama uma API de embeddings para transformar o texto em vetores e armazená-los no SQLite

2. Durante a busca: quando você pergunta “como implantar uma aplicação em contêineres”, o sistema:

   • usa a busca BM25 para localizar os blocos que contêm palavras-chave como “implantação” e “contêiner”
   • usa a busca vetorial para encontrar os blocos semanticamente mais relacionados
   • combina as pontuações dos dois resultados e retorna o Top-K

A vantagem é simples: a correspondência por palavras-chave é rápida, e a busca semântica é precisa. Uma complementa a outra, permitindo lidar tanto com consultas exatas quanto com perguntas conceituais mais vagas.

Ao falar de busca vetorial, também é preciso escolher o modelo de embeddings. O OpenClaw oferece três opções:

• Modelo local: funciona totalmente offline e mantém os dados no computador, embora a qualidade possa ser inferior à de uma API
• OpenAI Embedding API: tem bom desempenho, mas depende de um serviço em nuvem e exige uma chave de API
• Gemini Embedding API: é a alternativa do Google e oferece uma cota gratuita maior

O sistema escolhe automaticamente conforme a configuração. Se a privacidade for sua principal preocupação, use um modelo local; se você busca melhor qualidade, pode usar OpenAI ou Gemini.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Eu testei essa busca híbrida e ela realmente é muito mais eficaz do que usar apenas grep. Certa vez, registrei uma nota sobre “configuração de proxy reverso com Nginx”. Mais tarde, perguntei “como configurar balanceamento de carga”, e o sistema encontrou a nota, embora eu não tivesse usado a expressão “balanceamento de carga” nela. Esse é o poder da busca semântica.

Privacidade e segurança: mecanismos de proteção local-first

Quando falamos em armazenamento de dados, a privacidade é inevitável.

Muita gente evita mencionar informações sensíveis ao usar assistentes de IA, como arquitetura interna da empresa, dados de clientes e informações pessoais. Por quê? Porque não sabe se as conversas serão enviadas para a nuvem, usadas para treinar modelos ou vistas por terceiros.

A arquitetura “local-first” do OpenClaw resolve naturalmente esse problema: todos os arquivos de memória ficam no disco local e não são enviados automaticamente para nenhum lugar. Quer fazer backup na nuvem? Sincronize por conta própria com Dropbox ou Git. Quer criptografar? Use VeraCrypt ou FileVault. O controle é totalmente seu.

Essa filosofia segue a ideia atual de “Local-first Software”: a soberania dos dados pertence ao usuário, e o software é apenas uma ferramenta.

Ainda assim, armazenamento local não significa segurança absoluta. O OpenClaw enfrenta alguns desafios:

1. Vazamento de chaves de API: se você registrar acidentalmente uma chave de API em um arquivo de memória e depois sincronizar o arquivo com um repositório público no GitHub, haverá um problema sério
2. Permissões do sistema de arquivos: o OpenClaw precisa ler e gravar no diretório memory; permissões mal configuradas podem ser exploradas por programas maliciosos
3. Skills/plugins maliciosos: o OpenClaw aceita skills de extensão; um plugin malicioso pode roubar dados locais
4. Instâncias expostas: pesquisas de segurança encontraram centenas de instâncias do OpenClaw expostas publicamente e sem autenticação, acessíveis por qualquer pessoa

O quarto item é especialmente preocupante. Cisco e Vectra AI já publicaram alertas de que muitos usuários implantaram o OpenClaw diretamente na internet sem sequer adicionar autenticação básica. Isso permite que invasores leiam todos os arquivos de memória, executem comandos arbitrários e até instalem backdoors.

O que fazer? Estas são algumas boas práticas de segurança:

• Executar em uma sandbox do Docker: use um contêiner para isolar o OpenClaw e limitar os arquivos que ele pode acessar
• Princípio do menor privilégio: conceda apenas as permissões de leitura e gravação necessárias e não execute como root
• Criptografar dados sensíveis: se os arquivos de memória contiverem informações sensíveis, considere a criptografia no nível do sistema de arquivos
• Controlar o acesso: se for necessário expor o serviço na internet, configure autenticação e use um proxy reverso Nginx com basic auth ou OAuth
• Fazer auditorias periódicas: verifique se há arquivos indevidos no diretório memory e skills ou plugins suspeitos na lista de extensões

A DigitalOcean tem um guia bem detalhado para implantação com segurança reforçada que vale a pena consultar.

No fim das contas, o armazenamento local oferece a possibilidade de proteger sua privacidade, mas a segurança real depende de como você configura e usa o sistema. É como receber uma fechadura: você ainda precisa se lembrar de trancar a porta.

Guia prático: como gerenciar e otimizar os dados de memória

Agora que entendemos os princípios, vamos à prática: como gerenciar esses arquivos de memória?

Estrutura dos arquivos

A estrutura padrão do OpenClaw é esta:

memory/
├── 2026-02-05.md          # Log diário
├── MEMORY/                # Base de conhecimento persistente
│   ├── projects/          # Classificação por tema
│   │   ├── project-a.md
│   │   └── project-b.md
│   ├── reference/         # Materiais de referência
│   └── troubleshooting/   # Registros de solução de problemas
└── .memory_index.db       # Arquivo de índice do SQLite

Você pode ajustar essa estrutura conforme suas necessidades. Eu costumo organizar por projeto e tema, por exemplo:

MEMORY/
├── work/
│   ├── backend-api-design.md
│   └── database-migration-notes.md
├── learning/
│   ├── rust-ownership-model.md
│   └── kubernetes-networking.md
└── personal/
    └── recipe-collection.md

Estratégia de manutenção dos dados

1. Limpeza periódica: uma vez por mês, revise os logs antigos, exclua o que não serve mais e mova as informações importantes para o diretório MEMORY
2. Edição manual: como são arquivos Markdown, você pode abri-los e editá-los a qualquer momento. Se a IA registrar algo incorretamente, basta corrigir
3. Controle de versão: adicione o diretório memory ao Git; o histórico de commits mostrará a evolução das memórias
4. Backup: faça cópias periódicas na nuvem ou em um disco externo para se proteger contra falhas no armazenamento

Otimização de desempenho

Se houver arquivos demais, você pode encontrar problemas de desempenho. Algumas recomendações:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

• Controle o tamanho de cada arquivo: recomenda-se manter cada arquivo Markdown abaixo de 1 MB; divida os maiores em vários arquivos
• Configure a janela de contexto de forma adequada: por padrão, são carregados os logs dos dois dias mais recentes. Se o contexto longo estiver reduzindo a velocidade de resposta, carregue apenas o dia atual
• Reconstrua o índice periodicamente: o arquivo de índice do SQLite cresce junto com os dados; exclua .memory_index.db de tempos em tempos para que o sistema o reconstrua
• Defina um limite para compactação preventiva: quando os logs ultrapassarem certa quantidade, como 30 dias, compacte ou arquive automaticamente os arquivos antigos

Uma dica: crie um arquivo INDEX.md dentro do diretório MEMORY e mantenha manualmente um índice que liste os resumos e links de todos os arquivos importantes. Assim, mesmo que o sistema de busca tenha algum problema, você ainda consegue encontrar rapidamente o que precisa.

Sinceramente, gerenciar arquivos de memória é um pouco como organizar um caderno: exige disciplina e a criação de alguns hábitos. Depois que você estabelece seu próprio fluxo, porém, a experiência pode ser muito mais confortável do que depender cegamente de serviços em nuvem. Ter os dados nas próprias mãos traz uma sensação concreta de controle.

Conclusão

Depois de tudo isso, voltamos à pergunta inicial: onde a memória de um assistente de IA deve ficar?

A resposta do OpenClaw é: em arquivos Markdown locais. A abordagem parece um pouco “retrô”, mas resolve dois dos principais problemas do armazenamento em nuvem: privacidade dos dados e controle pelo usuário.

A arquitetura em duas camadas, com logs temporários e conhecimento persistente, imita o funcionamento da memória humana. Ela mantém a continuidade do contexto recente sem estourar a janela de contexto. O sistema de busca híbrida, que combina BM25 e vetores, transforma texto simples em uma base capaz de fazer buscas inteligentes. Já a filosofia file-first permite que desenvolvedores gerenciem a memória da IA com ferramentas conhecidas, como editor de texto, Git e gerenciador de arquivos.

É claro que essa abordagem não é uma solução universal. Ela é mais indicada para quem valoriza privacidade, prefere fluxos de trabalho locais e tem algum conhecimento técnico. Se você precisa sincronizar vários dispositivos, colaborar em equipe ou eliminar completamente a manutenção, um serviço em nuvem pode ser mais adequado.

Para mim, porém, o sistema de memória do OpenClaw traz uma percepção importante: a memória da IA não precisa ficar dentro de uma caixa-preta; ela pode ser transparente, controlável e realmente sua.

Se você também desenvolve aplicações com agentes de IA, vale experimentar uma memória em Markdown. Comece com um arquivo NOTES.md simples e construa seu próprio sistema aos poucos. O que importa não é o nível de sofisticação da tecnologia, mas quem controla os dados.

Para conhecer mais detalhes da implementação do OpenClaw, consulte a documentação oficial e o código-fonte. A comunidade é bastante ativa, e normalmente é possível encontrar respostas para os problemas mais comuns.

E não se esqueça de configurar a segurança. Não deixe que suas memórias virem dados de outras pessoas.