Como o Clawdbot (MoltBot) lembra de tudo

Clawdbot é um assistente de IA open-source com mais de 32 mil estrelas no GitHub. Diferente do ChatGPT ou Claude, ele roda local. Integra com Discord, WhatsApp, Telegram.

Mas o que chamou minha atenção foi outra coisa: o sistema de memória.

Retenção de contexto 24/7. Lembra de conversas anteriores e constrói em cima delas. Indefinidamente.

E o mais importante: tudo fica na sua máquina. Você é dono do contexto. Das habilidades. Da memória.

O que o modelo vê em cada requisição

Antes de entender memória, precisa entender o que chega pro modelo.

[0] System Prompt (instruções fixas + condicionais)
[1] Contexto do Projeto (arquivos bootstrap: AGENTS.md, SOUL.md)
[2] Histórico da Conversa (mensagens, tool calls, resumos)
[3] Mensagem Atual

O contexto do projeto inclui arquivos Markdown editáveis pelo usuário. Esses arquivos são injetados em toda requisição.

Ficam no workspace do agente junto com os arquivos de memória. Configuração transparente. Editável.

Contexto vs Memória

Essa distinção é fundamental.

Contexto é tudo que o modelo vê numa única requisição.

Contexto = System Prompt + Histórico + Resultados de Tools + Anexos

Contexto é:

• –Efêmero — existe só pra essa requisição
• –Limitado — restrito pela janela do modelo (200K tokens, 1M tokens)
• –Caro — cada token custa latência e dinheiro

Memória é o que fica gravado em disco.

Memória = MEMORY.md + memory/*.md + Transcrições de Sessão

Memória é:

• –Persistente — sobrevive reinicializações, dias, meses
• –Ilimitada — pode crescer infinitamente
• –Barata — zero custo de API pra armazenar
• –Pesquisável — indexada pra busca semântica

As ferramentas de memória

O agente acessa memória através de duas ferramentas.

memory_search: busca semântica em todos os arquivos de memória.

Passo obrigatório antes de responder perguntas sobre trabalho anterior, decisões, datas, pessoas, preferências ou tarefas.

Retorna trechos relevantes com score de similaridade, caminho do arquivo e linhas específicas.

memory_get: lê conteúdo específico após encontrar via busca.

Recebe caminho do arquivo e range de linhas. Retorna o texto completo daquele trecho.

Escrevendo na memória

Não existe ferramenta memory_write dedicada.

O agente escreve na memória usando as mesmas ferramentas que usa pra qualquer arquivo: write e edit.

Memória é só Markdown.

Você pode editar manualmente. Abrir no editor, corrigir algo, salvar. Os arquivos são re-indexados automaticamente.

A decisão de onde escrever é guiada por prompt no AGENTS.md. Escrita automática também acontece durante flush pré-compactação e no fim de sessões.

Armazenamento: duas camadas

A memória vive no workspace do agente (por padrão: ~/clawd/).

~/clawd/
├── MEMORY.md              - Camada 2: conhecimento curado
└── memory/
    ├── 2026-01-26.md      - Camada 1: notas de hoje
    ├── 2026-01-25.md      - notas de ontem
    └── ...

Camada 1: logs diários (memory/YYYY-MM-DD.md)

Notas append-only que o agente escreve durante o dia.

# 2026-01-26

## 10:30 - Discussão de API
Discutimos REST vs GraphQL. Decisão: usar REST por simplicidade.
Endpoints principais: /users, /auth, /projects.

## 14:15 - Deploy
Deploy da v2.3.0 em produção. Sem problemas.

## 16:00 - Preferência do usuário
Usuário mencionou que prefere TypeScript a JavaScript.

Camada 2: memória de longo prazo (MEMORY.md)

Conhecimento curado e persistente. Eventos significativos, decisões, lições aprendidas.

# Memória de Longo Prazo

## Preferências do Usuário
- Prefere TypeScript a JavaScript
- Gosta de explicações concisas
- Trabalhando no projeto "Acme Dashboard"

## Decisões Importantes
- 2026-01-15: Escolheu PostgreSQL pro banco
- 2026-01-20: Adotou REST ao invés de GraphQL
- 2026-01-26: Usando Tailwind CSS pra estilização

Como o agente sabe quando ler memória

O arquivo AGENTS.md contém instruções:

## Toda Sessão

Antes de qualquer coisa:
1. Leia SOUL.md — isso é quem você é
2. Leia USER.md — isso é quem você está ajudando
3. Leia memory/YYYY-MM-DD.md (hoje e ontem) pra contexto recente
4. Se na SESSÃO PRINCIPAL, leia também MEMORY.md

Não peça permissão, só faça.

Como a memória é indexada

Quando você salva um arquivo de memória:

1. 1.File watcher detecta mudança — Chokidar monitora MEMORY.md + memory/**/*.md. Debounce de 1.5s pra agrupar escritas rápidas.
2. 2.Chunking — Divide em pedaços de ~400 tokens com 80 tokens de overlap. O overlap garante que fatos que cruzam fronteiras de chunk sejam capturados nos dois.
3. 3.Embedding — Cada chunk vira um vetor via OpenAI/Gemini/modelo local. “Discutimos REST vs GraphQL” → [0.12, -0.34, 0.56, ...] (1536 dimensões)
4. 4.Armazenamento — SQLite com extensões:chunks: id, path, start_line, end_line, text, hashchunks_vec: embeddings via sqlite-vecchunks_fts: busca full-text via FTS5embedding_cache: evita re-embedding

sqlite-vec permite busca de similaridade vetorial direto no SQLite. FTS5 é o motor de busca full-text nativo. Juntos, rodam busca híbrida num único arquivo de banco leve.

Como a busca funciona

Duas estratégias em paralelo:

Busca vetorial (semântica): encontra conteúdo com significado similar.

Busca BM25 (keyword): encontra conteúdo com tokens exatos.

Resultados combinados com peso:

scoreF inal = (0.7 × scoreVetorial) + (0.3 × scoreTexto)

Por que 70/30?

Similaridade semântica é o sinal principal pra recall de memória. Mas BM25 pega termos exatos que vetores podem perder: nomes, IDs, datas.

Resultados abaixo do threshold mínimo (padrão 0.35) são filtrados.

Isso garante bons resultados seja buscando por conceitos (”aquela parada do banco”) ou por específicos (”POSTGRES_URL”).

Memória multi-agente

Clawdbot suporta múltiplos agentes, cada um com isolamento completo de memória.

~/.clawdbot/memory/              # Diretório de estado (índices)
├── main.sqlite                  # Índice vetorial do agente "main"
└── work.sqlite                  # Índice vetorial do agente "work"

~/clawd/                         # Workspace do agente "main"
├── MEMORY.md
└── memory/

~/clawd-work/                    # Workspace do agente "work"
├── MEMORY.md
└── memory/

Arquivos Markdown (fonte da verdade) ficam em cada workspace. Índices SQLite (dados derivados) ficam no diretório de estado.

Cada agente tem workspace e índice próprios. O gerenciador de memória é indexado por agentId + workspaceDir. Sem busca cross-agent por padrão.

Agentes podem ler memória uns dos outros? Não por padrão. O workspace é sandbox soft (diretório de trabalho padrão), não fronteira rígida. Um agente poderia acessar outro workspace via caminhos absolutos, a menos que sandboxing estrito esteja habilitado.

Útil pra separar contextos: agente “pessoal” pro WhatsApp e agente “trabalho” pro Slack.

Compactação

Todo modelo tem limite de janela de contexto. Claude: 200K tokens. GPT-5.1: 1M.

Conversas longas eventualmente batem nesse limite.

Quando isso acontece, o Clawdbot usa compactação: resume conversa antiga num parágrafo denso, mantendo mensagens recentes intactas.

Antes da compactação:

• –Contexto: 180.000 / 200.000 tokens
• –150 turnos de conversa

Depois da compactação:

• –Contexto: 45.000 / 200.000 tokens
• –Resumo dos turnos 1-140 + turnos 141-150 intactos

Compactação pode ser automática (quando se aproxima do limite) ou manual (comando /compact).

Diferente de outras otimizações, compactação persiste em disco. O resumo é gravado no arquivo JSONL da transcrição da sessão. Sessões futuras começam com histórico compactado.

O memory flush

Compactação baseada em LLM é processo lossy. Informação importante pode ser resumida e potencialmente perdida.

Pra contornar isso, existe o flush de memória pré-compactação.

Contexto se aproximando do limite
         ↓
Turno silencioso de memory flush
Sistema: "Flush de memória pré-compactação. Grave memórias 
         duráveis agora (use memory/YYYY-MM-DD.md).
         Se não tiver nada pra gravar, responda NO_REPLY."
         ↓
Agente revisa conversa pra informação importante
Escreve decisões/fatos chave nos arquivos de memória
→ NO_REPLY (usuário não vê nada)
         ↓
Compactação prossegue com segurança
Informação importante já está em disc

o

O flush é configurável no arquivo clawdbot.yaml.

Pruning

Resultados de ferramentas podem ser enormes. Um único comando exec pode gerar 50.000 caracteres de logs.

Pruning corta esses outputs antigos sem reescrever o histórico. É processo lossy — outputs antigos não são recuperáveis.

Cache-TTL Pruning

Anthropic cacheia prefixos de prompt por até 5 minutos pra reduzir latência e custo em chamadas repetidas. Tokens cacheados custam ~90% menos.

Se a sessão fica idle além do TTL, a próxima requisição perde o cache e precisa re-cachear todo o histórico a preço cheio.

Cache-TTL pruning resolve isso: detecta quando o cache expirou e corta resultados de ferramentas antigos antes da próxima requisição. Prompt menor pra re-cachear = custo menor.

Ciclo de vida da sessão

Sessões não duram pra sempre. Reset acontece baseado em regras configuráveis. Comportamento padrão: reset diário.

Hook de memória de sessão

Quando você roda /new pra iniciar sessão nova, o hook pode salvar contexto automaticamente:

1. 1.Extrai últimas 15 mensagens da sessão que está terminando
2. 2.Gera slug descritivo via LLM
3. 3.Salva em ~/clawd/memory/2026-01-26-api-design.md

Sessão nova começa. Contexto anterior agora é pesquisável via memory_search.

Por que funciona

O sistema de memória do Clawdbot funciona porque abraça princípios simples:

Transparência sobre caixas pretas. Memória é Markdown puro. Você pode ler, editar, versionar no Git. Sem bancos de dados opacos ou formatos proprietários.

Busca sobre injeção. Ao invés de encher o contexto com tudo, o agente busca o que é relevante. Mantém contexto focado e custos baixos.

Persistência sobre sessão. Informação importante sobrevive em arquivos no disco, não só no histórico de conversa. Compactação não pode destruir o que já foi salvo.

Híbrido sobre puro. Busca vetorial sozinha perde matches exatos. Busca keyword sozinha perde semântica. Híbrido entrega os dois.

A memória das IAs que usamos hoje mora em servidores de terceiros. O Clawdbot mostra que existe alternativa: memória local, transparente, pesquisável, sua.

Mas essa é outra conversa, e merece um artigo próprio.

Fontes

• –Clawdbot Documentação - Docs oficiais cobrindo instalação, configuração e todas as funcionalidades
• –GitHub Repositório - Source code, issues, and community contributions