Memória OpenClaw explicada: arquitetura, configuração e por que ela esquece — EasyClaw

A arquitetura completa de memória OpenClaw (3 camadas explicadas)

A memória OpenClaw opera em três camadas distintas, cada uma com diferentes características de persistência e modos de falha.

Ciclo de vida completo da memória:

Write → Embed/Index → Search → Compact → Recover
  ↓          ↓           ↓         ↓         ↓
.md file   sqlite-vec  semantic  summary   MEMORY.md
created    indexes it  query     replaces  re-read at
           on save     returns   context   session start
                       chunks    window

Cada estágio desta cadeia pode falhar de forma independente. A maioria dos problemas de esquecimento remonta exatamente a um estágio interrompido.

Layer 1 — A janela de contexto ativo

Esta é a memória de trabalho do modelo: tudo o que está atualmente carregado na janela de contexto da conversa ativa. Inclui o prompt do sistema, o histórico de conversas e quaisquer pedaços de memória recuperados pela ferramenta de pesquisa.

O que o preenche:

• Prompt do sistema (geralmente grande)
• Trechos de memória recuperados
• Histórico de chamadas de ferramentas
• A conversa gira

Limite prático: suponha que você tenha aproximadamente 60–70% da janela de contexto anunciada do modelo disponível para conversação real após o prompt do sistema e sobrecarga de memória.

Layer 2 – Notas diárias (a janela contínua de dois dias)

As notas diárias são arquivos Markdown somente anexados nomeados no formato YYYY-MM-DD armazenados dentro do diretório memory/. Cargas OpenClaw hoje e ontem arquivos automaticamente no início de cada sessão.

• Fatos sobre o trabalho atual, decisões tomadas e tarefas ativas são anexados aqui
• Eles não foram feitos para serem editados – trate-os como um registro
• Depois de dois dias, eles saem da janela de carregamento automático e só podem ser pesquisados ​​por meio de pesquisa semântica

Layer 3 — Memória durável (MEMORY.md e memory-wiki)

Fatos de longo prazo que devem sobreviver entre sessões — seu nome, contexto do projeto, preferências de codificação, decisões arquitetônicas — pertencem ao MEMORY.md ou ao cofre de plugins estruturado memory-wiki.

O problema da compactação – Por que suas instruções desaparecem no meio da tarefa

A compactação é o modo de falha menos documentado no OpenClaw. A maioria dos artigos cobre o esquecimento pós-sessão. Quase nenhum endereço compactação no meio da tarefa em fluxos de trabalho autônomos de longa duração — onde o agente está executando uma tarefa de várias etapas, a compactação é acionada silenciosamente na etapa 7 de 12 e as instruções comportamentais da etapa 1 desaparecem.

O que a compactação faz:

1. Detecta a janela de contexto se aproximando da capacidade
2. Resume a conversa atual em um bloco condensado
3. Substitui o contexto original pelo resumo
4. Continua a execução

Quando aciona: Não há limite configurável no plugin padrão memory-core. Ele é acionado com base na contagem de tokens, não no estágio da tarefa. Em uma operação autônoma de 2 horas, você pode esperar de 3 a 5 ciclos de compactação.

Como construir uma arquitetura de arquivos resistente à compactação

Fixe instruções comportamentais em MEMORY.md, não na conversa. Qualquer coisa que deva sobreviver a vários ciclos de compactação precisa estar em um arquivo durável que seja relido após cada compactação.

Padrão de fixação recomendado:

## Agent Behavioral Rules (always active)
- Never overwrite files without showing a diff first
- Write tests before implementation (TDD mode: on)
- Use TypeScript strict mode in all new files

## Project Context
- Stack: Node.js 22, Fastify, PostgreSQL 16
- Repo root: /home/user/project
- Active sprint goal: migrate auth to Clerk

Convenções de nomenclatura que sobrevivem à compactação:

• Prefixe seções críticas com ## [PINNED] — o resumidor trata cabeçalhos maiúsculos como de alta prioridade
• Mantenha cada fato fixado em uma linha sempre que possível – parágrafos densos são resumidos, fatos de uma única linha tendem a sobreviver literalmente
• Repita as 3 a 5 regras comportamentais mais críticas em MEMORY.md e na nota diária de hoje - a redundância é a sua proteção de compactação

Configuração de zero para memória em 10 minutos (estrutura de arquivo completa)

Este é o guia de configuração que não existe em nenhum outro lugar. Copie esta estrutura, preencha seu contexto e pronto.

Árvore de diretórios:

memory/
├── MEMORY.md
├── 2026-04-27.md          ← today's daily note (create manually)
└── wiki/                  ← only if using memory-wiki plugin
    ├── index.md
    ├── project-context.md
    └── decisions.md

Iniciante MEMORY.md:

# Persistent Memory

## Identity & Preferences
- Name: [your name]
- Role: [your role]
- Preferred response style: concise, no preamble

## Project: [Project Name]
- Stack: [your stack]
- Key constraints: [e.g., no external APIs, TypeScript only]
- Current focus: [active task or sprint goal]

## Behavioral Rules
- [Rule 1]
- [Rule 2]

## Decisions Made
- [YYYY-MM-DD] Decided to use X because Y

Nota diária inicial (2026-04-27.md):

# 2026-04-27

## Session Goals
- [ ] Task 1
- [ ] Task 2

## Notes

Configuração do slot de plug-in (sintaxe 2026):

{
  "plugins": {
    "slots": {
      "memory": "memory-core"
    }
  }
}

Para desativar totalmente a memória:

{
  "plugins": {
    "slots": {
      "memory": false
    }
  }
}

Etapas de verificação:

1. Execute uma sessão e peça ao agente para se lembrar de algo que você disse em uma sessão anterior
2. Verifique se memory/YYYY-MM-DD.md foi escrito (deve ter novo conteúdo)
3. Pergunte diretamente ao agente: "O que você sabe sobre mim?" - deve extrair de MEMORY.md

Configuring memory-wiki para uma base de conhecimento de produção

Habilite-o trocando o slot do plugin:

{
  "plugins": {
    "slots": {
      "memory": "memory-wiki"
    }
  }
}

memory-wiki gera um cofre estruturado em memory/wiki/. Cada tópico ganha sua própria página. O plugin compila um digest.md que agrega fatos de alta confiança e não contraditos para o agente carregar no início da sessão.

Estrutura prática de cofre para um agente de produção:

memory/wiki/
├── index.md              ← vault table of contents
├── digest.md             ← auto-generated; agent reads this
├── project-context.md    ← stack, goals, constraints
├── decisions.md          ← architectural decisions log
├── team.md               ← stakeholders, contacts
└── domain-knowledge.md   ← business rules, glossary

Semantic Search and Embeddings — SQLite, sqlite-vec e JS Fallback

OpenClaw indexa seus arquivos de memória usando SQLite with the sqlite-vec extension para pesquisa de similaridade vetorial. Quando você ou o agente emitem uma pesquisa de memória, ele incorpora a consulta e recupera os pedaços mais semanticamente relevantes.

Verifique se seu armazenamento de vetores está íntegro:

# Check that the memory index exists
ls memory/.index/

# Reset a corrupted index (safe to run — it rebuilds from .md files)
rm -rf memory/.index/ && openclaw reindex

Se sqlite-vec não estiver disponível (comum no ARM Linux e em algumas configurações do Windows), OpenClaw volta para uma extensão de vetor JS puro. Force o substituto explicitamente:

{
  "memory": {
    "vectorBackend": "js"
  }
}

Segment-Specific Memory Strategies

Solo Developer – sobrecarga mínima, recall máximo

Configuração recomendada: plugin memory-core, MEMORY.md + apenas notas diárias, sem cofre do wiki.

• Mantenha MEMORY.md abaixo de 200 linhas – arquivos mais longos retardam o início da sessão
• Anexe agressivamente às anotações diárias; não tente mantê-los limpos
• Revise e remova MEMORY.md semanalmente – fatos obsoletos degradam a qualidade da pesquisa

Pipeline multiagente – memória compartilhada entre agentes

Quando vários agentes leem e gravam no mesmo diretório memory/, você precisa de regras de propriedade explícitas.

• One agent owns writes to each file — gravações simultâneas no mesmo arquivo .md produzirão conflitos
• Use subdiretórios por agente: memory/agent-a/, memory/agent-b/, com um memory/shared/MEMORY.md compartilhado
• Use o memory-wiki para o cofre compartilhado - sua compilação resumida lida com a atualização de vários gravadores melhor do que arquivos brutos

Long-Running Autonomous Tasks – Horas de execução sobreviventes

Para agentes que executam tarefas medidas em horas:

• Force memory writes at checkpoints — após cada etapa principal da tarefa, instrua o agente a anexar seu estado atual à nota diária de hoje
• Pre-load compaction-resistant context — coloque a especificação completa da tarefa em MEMORY.md antes do início da execução, não apenas na mensagem inicial
• Set explicit continuation markers em notas diárias: <!-- RESUME POINT: completed steps 1-4, next: step 5 --> para que o agente possa se orientar após um ciclo de compactação

Troubleshooting OpenClaw Memory — Diagnosticar qualquer problema de esquecimento em 2 minutos

Siga estas etapas em ordem:

Perguntas frequentes

Veredicto final – A configuração de memória que realmente funciona

Recommended baseline para a maioria dos usuários: Plugin memory-core, diretório memory/ criado antes da primeira sessão, MEMORY.md com regras comportamentais em uma seção fixada claramente identificada, notas diárias anexadas ao longo de cada sessão.

Sua lista de verificação de ação:

• Crie o diretório memory/ na raiz do seu projeto
• Copie o modelo inicial MEMORY.md acima e preencha seu contexto
• Verifique se plugins.slots.memory está definido como "memory-core" (ou o plugin escolhido)
• Adicione suas 3 a 5 regras comportamentais mais críticas em ## [PINNED] em MEMORY.md
• Após sua primeira sessão, confirme que uma nota diária datada foi escrita
• Se a pesquisa semântica parecer errada, execute openclaw reindex para reconstruir o índice vetorial

A arquitetura é sólida quando você a entende. A maioria dos problemas de esquecimento é resolvida em 10 minutos após seguir esta lista de verificação.