Total Recall — Memória Autônoma para Agentes

O que Total Recall — Memória Autônoma para Agentes faz?

A única skill de memória que observa por conta própria.

Sem banco de dados. Sem vetores. Sem salvamentos manuais. Apenas um observador LLM que comprime suas conversas em notas priorizadas, consolida quando elas crescem e recupera qualquer coisa perdida. Cinco camadas de redundância, zero manutenção. ~$0,00/mês (usando modelos gratuitos).

Enquanto outras skills de memória pedem que você se lembre de lembrar, esta apenas presta atenção.

Arquitetura

Camada 1: Observer (cron, a cada 15-30 min)
    ↓ comprime mensagens recentes → observations.md
Camada 2: Reflector (acionado automaticamente quando observations > 8000 palavras)
    ↓ consolida, remove informações obsoletas → redução de 40-60%
Camada 3: Session Recovery (executa em cada /new ou /reset)
    ↓ captura qualquer sessão que o Observer perdeu
Camada 4: Reactive Watcher (daemon inotify, apenas Linux)
    ↓ aciona o Observer após 40+ novas escritas JSONL, cooldown de 5 min
Camada 5: Gancho de pré-compactação (memoryFlush)
    ↓ captura de emergência antes do OpenClaw compactar o contexto

O Que Faz

• Observer lê transcrições de sessão recentes (JSONL), envia para um LLM e anexa observações comprimidas a observations.md com níveis de prioridade (alto, médio, baixo)
• Reflector entra em ação quando as observações crescem demais, consolidando itens relacionados e descartando entradas obsoletas de baixa prioridade
• Session Recovery é executado no início da sessão, verifica se a sessão anterior foi capturada e faz uma observação de emergência se não
• Reactive Watcher monitora o diretório de sessão com inotify para que períodos de alta atividade sejam capturados mais rapidamente que o intervalo do cron
• Gancho de pré-compactação é acionado quando o OpenClaw está prestes a compactar o contexto, garantindo que nada seja perdido

Início Rápido

1. Instale a skill

clawdhub install total-recall

2. Defina sua chave de API

Adicione ao seu .env ou config do OpenClaw:

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. Execute o script de configuração

bash skills/total-recall/scripts/setup.sh

Isso irá:

• Criar a estrutura de diretórios de memória (memory/, logs/, backups)
• No Linux com inotify + systemd: instalar o serviço do watcher reativo
• Imprimir instruções de configuração de cron job e agente para você adicionar manualmente

4. Configure seu agente para carregar observações

Adicione ao contexto do workspace do seu agente (por exemplo, MEMORY.md ou prompt de sistema):

Na inicialização da sessão, leia `memory/observations.md` para contexto entre sessões.

Ou use o memoryFlush.systemPrompt do OpenClaw para injetar uma instrução de inicialização.

Suporte a Plataformas

Plataforma	Observer + Reflector + Recovery	Reactive Watcher
Linux (Debian/Ubuntu/etc.)	Suporte completo	Com inotify-tools
macOS	Suporte completo	Não disponível (apenas cron)

Todos os scripts principais usam bash portátil. Comandos stat, date e md5 são tratados de forma multiplataforma via _compat.sh.

Configuração

Todos os scripts leem variáveis de ambiente com valores padrão sensatos:

Variável	Padrão	Descrição
OPENROUTER_API_KEY	(obrigatório)	Chave de API do OpenRouter para chamadas LLM
MEMORY_DIR	$OPENCLAW_WORKSPACE/memory	Onde o observations.md reside
SESSIONS_DIR	~/.openclaw/agents/main/sessions	Transcrições de sessão do OpenClaw
OBSERVER_MODEL	stepfun/step-3.5-flash:free	Modelo principal para compressão (gratuito)
OBSERVER_FALLBACK_MODEL	nvidia/nemotron-3-nano-30b-a3b:free	Fallback se o principal falhar (gratuito)
OBSERVER_LOOKBACK_MIN	15	Minutos para olhar para trás (durante o dia)
OBSERVER_MORNING_LOOKBACK_MIN	480	Minutos para olhar para trás (antes das 8h)
OBSERVER_LINE_THRESHOLD	40	Linhas antes do acionamento reativo (Linux)
OBSERVER_COOLDOWN_SECS	300	Cooldown entre acionamentos reativos (Linux)
REFLECTOR_WORD_THRESHOLD	8000	Palavras antes do reflector executar
REFLECTOR_MODEL	nvidia/nemotron-3-super-120b-a12b:free	Modelo para consolidar observações (gratuito)
REFLECTOR_FALLBACK_MODEL	openrouter/hunter-alpha	Fallback se o modelo reflector falhar (gratuito)
OPENCLAW_WORKSPACE	~/seu-workspace	Raiz do workspace

Configuração do Provedor LLM

O Total Recall usa qualquer API de conclusão de chat compatível com OpenAI. Troque de provedor configurando variáveis de ambiente:

Variável	Padrão	Descrição
LLM_BASE_URL	https://openrouter.ai/api/v1	Endpoint da API
LLM_API_KEY	recai para OPENROUTER_API_KEY	Chave de API
LLM_MODEL	deepseek/deepseek-v3.2	Modelo a usar

Exemplos de provedores

# OpenRouter (padrão)
export OPENROUTER_API_KEY="sua-chave"

# Ollama (local)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="sua-chave-groq"
export LLM_MODEL="llama-3.3-70b-versatile"

Arquivos Criados

memory/
  observations.md          # O log principal de observações (carregado na inicialização)
  observation-backups/     # Backups do reflector (últimos 10 mantidos)
  .observer-last-run       # Timestamp da última execução do observer
  .observer-last-hash      # Hash de desduplicação das últimas mensagens processadas
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Cron Jobs

O script de configuração cria estes cron jobs do OpenClaw:

Job	Agendamento	Descrição
memory-observer	A cada 15 min	Comprimir conversa recente
memory-reflector	A cada hora	Consolidar se observações estiverem grandes

Reactive Watcher (apenas Linux)

O watcher reativo usa inotifywait para detectar atividade de sessão e acionar o observer mais rápido que o cron sozinho. Requer Linux com inotify-tools instalado.

# Instalar inotify-tools (Debian/Ubuntu)
sudo apt install inotify-tools

# Verificar status do watcher
systemctl --user status total-recall-watcher

# Ver logs
journalctl --user -u total-recall-watcher -f

Custo

Usando os modelos gratuitos padrão via OpenRouter:

• ~$0,00/mês (usando modelos gratuitos) para uso típico (observer + reflector)
• ~15-30 execuções de cron/dia, cada uma processando algumas centenas de tokens
• Todos os modelos padrão são da camada gratuita

Notas sobre Modelos

Os scripts incluem tratamento defensivo para campos .content e .reasoning em respostas da API. Enquanto a maioria dos modelos retorna conteúdo no campo .content padrão, o fallback para .reasoning garante compatibilidade com modelos que podem usar formatos de resposta diferentes.

Como Funciona (Técnico)

Observer

1. Encontra arquivos JSONL de sessão modificados recentemente
2. Filtra sessões de subagente/cron
3. Extrai mensagens de usuário e assistente da janela de retrospectiva
4. Desduplica usando comparação de hash MD5
5. Envia para LLM com o prompt do observer (compressão baseada em prioridade)
6. Anexa resultado a observations.md
7. Se as observações excederem o limite de palavras, aciona o reflector

Reflector

1. Faz backup das observações atuais
2. Envia todo o log para LLM com instruções de consolidação
3. Valida que a saída é mais curta que a entrada (verificação de sanidade)
4. Substitui observações pela versão consolidada
5. Limpa backups antigos (mantém os últimos 10)

Session Recovery

1. Executa em cada /new ou /reset
2. Gera hash de linhas recentes do último arquivo de sessão
3. Compara com o hash armazenado da última execução do observer
4. Se houver divergência: executa o observer em modo de recuperação (retrospectiva de 4 horas)
5. Fallback: extração bruta de mensagens se o observer falhar

Reactive Watcher

1. Usa inotifywait para monitorar o diretório de sessão
2. Conta escritas JSONL apenas para arquivos de sessão principais
3. Após 40+ linhas: aciona o observer (com cooldown de 5 min)
4. Reseta o contador quando execuções de cron/observer externo são detectadas

Personalizando os Prompts

Os prompts de sistema do observer e reflector estão em prompts/:

• prompts/observer-system.txt — controla como as conversas são comprimidas
• prompts/reflector-system.txt — controla como as observações são consolidadas

Edite-os para combinar com a personalidade e prioridades do seu agente.

---

Dream Cycle

O Dream Cycle é um agente noturno opcional que executa após o expediente para consolidar observations.md. Ele arquiva itens obsoletos e adiciona ganchos semânticos para que nada útil seja realmente perdido. O contexto permanece enxuto; tudo permanece encontrável.

O Que Faz

• Classifica cada observação por impacto (crítico / alto / médio / baixo / mínimo) e idade
• Arquiva itens que passaram do limite de relevância
• Adiciona um gancho semântico para cada item arquivado (palavras-chave específicas + referência de arquivo)
• Valida o resultado e reverte automaticamente se algo der errado

Recursos

Recuperação Multi-Gancho — 4-5 frases de busca alternativas por item arquivado. Buscas usando palavras diferentes do original ainda encontram a memória.

Pontuação de Confiança — cada observação recebe uma pontuação de confiança (0.0-1.0) e tipo de fonte (explicit, implicit, inference, weak, uncertain). Itens de alta confiança são preservados por mais tempo; itens de baixa confiança são arquivados mais cedo.

Sistema de Tipo de Memória — 7 tipos com TTLs por tipo: event (14d), fact (90d), preference (180d), goal (365d), habit (365d), rule (nunca), context (30d). Incorporados como comentários HTML de metadados invisíveis em observations.md.

Agrupamento de Observações — clusters de 3+ observações relacionadas são comprimidos em entradas de resumo únicas. As observações de origem são arquivadas; um gancho de agrupamento as substitui. Alcança até 75% de redução de tokens.

Decaimento de Importância — decaimento diário por tipo aplicado às pontuações de importância antes de cada decisão de arquivamento. Itens que decaem abaixo do limite de arquivamento são enfileirados para remoção. Taxas: event (-0.5/dia), fact (-0.1/dia), preference (-0.02/dia), rule/habit/goal (sem decaimento).

Promoção de Padrões — escaneia logs recentes do dream cycle em busca de temas recorrentes (3+ ocorrências em 3+ dias separados). Escreve propostas de promoção em memory/dream-staging/ para revisão humana. Use staging-review.sh para listar, mostrar, aprovar ou rejeitar propostas. O tipo context nunca é promovido automaticamente.

Configuração

1. Execute bash skills/total-recall/scripts/setup.sh — cria diretórios do Dream Cycle automaticamente.

2. Adicione o cron job noturno como uma rodada completa do agente:

   # Dream Cycle — noturno (3h recomendado; ajuste ao seu fuso horário)
   # O dream cycle é executado como uma rodada completa do agente — NÃO como uma chamada bash direta.
   # dream-cycle.sh é um auxiliar de operações de arquivo chamado PELO agente, não o ponto de entrada.
   #
   # 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
   #   && openclaw agent --agent main \
   #   --message "Execute o Total Recall Dream Cycle. Siga as instruções em \
   # $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exatamente. \
   # Use READ_ONLY_MODE=false e DREAM_PHASE=1." \
   #   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'
   

3. Configure seu agente cron usando prompts/dream-cycle-prompt.md como prompt de sistema. Modelos recomendados: Claude Sonnet para o Dreamer (análise + decisões), DeepSeek v3.2 para o Observer (barato, rápido).

4. Comece com READ_ONLY_MODE=true nas primeiras noites. Verifique memory/dream-logs/ após cada execução para verificar o que teria sido arquivado.

5. Mude para READ_ONLY_MODE=false quando estiver satisfeito.

Configuração

Variável	Padrão	Descrição
DREAM_TOKEN_TARGET	8000	Alvo de tokens para observations.md após consolidação
READ_ONLY_MODE	false	Defina true para análise de simulação sem escritas

Arquivos

Arquivo	Descrição
scripts/dream-cycle.sh	Auxiliar shell chamado pelo agente (não um executor independente): preflight, arquivar, atualizar-observations, escrever-log, escrever-métricas, validar, reverter
prompts/dream-cycle-prompt.md	Prompt do agente para a execução noturna do Dream Cycle
dream-cycle/README.md	Referência rápida do Dream Cycle
schemas/observation-format.md	Formato estendido de metadados de observação

Diretórios Criados

memory/
  archive/
    observations/        # Itens arquivados (um arquivo .md por noite)
    chunks/              # Grupos de observações agrupadas
  dream-logs/            # Relatórios de execução noturna
  dream-staging/         # Propostas de promoção de padrões aguardando revisão humana
  .dream-backups/        # Backups de segurança pré-execução
research/
  dream-cycle-metrics/
    daily/               # Métricas JSON por noite

---

Solução de Problemas

Observer não está executando?

• Verifique logs/observer.log para erros
• Confirme se OPENROUTER_API_KEY está definida e é válida
• Confirme se o cron está ativo: crontab -l

Observações não estão sendo carregadas no início da sessão?

• Garanta que as instruções de inicialização do seu agente incluam a leitura de memory/observations.md
• Verifique se MEMORY_DIR aponta para o local correto

Watcher reativo não está acionando (Linux)?

• Execute systemctl --user status total-recall-watcher
• Verifique se inotify-tools está instalado: which inotifywait
• Veja logs do watcher: journalctl --user -u total-recall-watcher -f

Dream Cycle arquivando agressivamente demais?

• Ative READ_ONLY_MODE=true e revise os logs do dream antes de ativar
• Ajuste DREAM_TOKEN_TARGET para cima para arquivar menos por execução

Dream Cycle não está arquivando o suficiente?

• Reduza DREAM_TOKEN_TARGET para acionar uma consolidação mais agressiva

---

Inspirado Por

Este sistema é inspirado em como a memória humana funciona durante o sono — o hipocampo (observer) captura experiências, e durante a consolidação do sono (reflector), memórias importantes são fortalecidas enquanto o ruído é descartado.

Leia mais: Your AI Has an Attention Problem

"Get your ass to Mars." — Bem, coloque a memória do seu agente para funcionar.