Arquitetura de memória de três camadas para contexto persistente do agente OpenClaw

Arquitetura de memória para contexto persistente do agente

Um desenvolvedor executando uma operação multiagente do OpenClaw para imóveis enfrentou perda persistente de contexto, onde os agentes começavam cada sessão do zero, exigindo reexplicação do trabalho anterior. Isso levou a custos comerciais concretos, incluindo agentes tratando leads quentes como estranhos e perdendo prazos devido à falta de estado.

A solução é uma arquitetura de memória de 3 camadas construída sobre a infraestrutura existente de espaço de trabalho e memória do OpenClaw. A informação flui para baixo através das camadas e nunca é duplicada entre elas.

Camada 1: Cérebro (arquivos do espaço de trabalho)

O OpenClaw injeta um conjunto fixo de arquivos do espaço de trabalho como contexto do projeto em cada turno automaticamente. Esses sete arquivos formam o sistema operacional do agente:

• SOUL.md: personalidade, voz, valores
• AGENTS.md: função, regras, faixa de atuação
• MEMORY.md: o que está ativo agora (uma linha por item, tempo presente)
• USER.md: como o usuário pensa e o que ele precisa
• TOOLS.md: comandos específicos da máquina e soluções alternativas
• IDENTITY.md: nome, função, referência rápida
• HEARTBEAT.md: tarefas permanentes para verificações recorrentes

O desenvolvedor estabeleceu uma regra de orçamento: enquanto o OpenClaw permite até 20.000 caracteres por arquivo, eles visam 500-1.000 tokens por arquivo, mantendo o total da L1 abaixo de 7.000 tokens. Isso garante que os agentes realmente leiam tudo em vez de apenas folhear arquivos inchados. Um comando trim impõe esse limite.

Regra de estabilidade: apenas o usuário ou um ponto de verificação atualiza os arquivos L1. Os agentes não alteram aleatoriamente suas próprias regras, com a exceção de que MEMORY.md pode ser atualizado para refletir o estado atual.

Camada 2: Memória (busca semântica)

Esta é a recuperação de longo prazo usando a ferramenta integrada memory_search do OpenClaw, que busca semanticamente em MEMORY.md e tudo dentro do diretório memory/. Quando um agente é questionado sobre trabalho anterior, decisões ou contexto, ele pesquisa automaticamente a L2.

Dois tipos de arquivos residem aqui:

• Notas diárias: memory/YYYY-MM-DD.md (convenção do OpenClaw) contendo histórico da sessão, decisões tomadas, trabalho concluído e correções
• Arquivos de migalhas: memory/[nome-do-tópico].md (adição do desenvolvedor) contendo fatos curados organizados por situação, com máximo de 4KB por arquivo, um fato por linha

Cada fato-chave nos arquivos de migalhas inclui um ponteiro para L3: → Mergulho profundo: reference/nome-do-arquivo.md. Isso cria uma ponte entre L2 e L3 para que os agentes não precisem carregar documentos de referência completos apenas para lembrar um fato relevante.

Insight crítico: a precisão da L2 depende inteiramente do que é escrito nela. Se um agente realiza uma ação e não a captura antes de prosseguir, o arquivo de estado começa a retornar informações desatualizadas.

Camada 3: Referência (sob demanda)

Esta é inteiramente uma adição do desenvolvedor, não uma convenção do OpenClaw. Um diretório reference/ contém contexto profundo: SOPs, frameworks, playbooks e pesquisa.

Os agentes acessam a L3 sob demanda quando uma tarefa específica requer profundidade. Ela não é pesquisada pelo memory_search por design, para evitar queimar contexto carregando coisas que raramente importam.

O fluxo completo: L1 (sempre carregada) → busca L2 (memória) → abre L3 (referência) sob demanda.