Como o Clawdbot gerencia a memória: uma arquitetura de memória híbrida baseada em Markdown

Resumo:

• O Clawdbot é um assistente de IA local e de código aberto que armazena e gerencia memórias de longo prazo no ambiente local do usuário na forma de arquivos Markdown, sem dependência da nuvem.
• Com um sistema de memória em duas camadas (logs diários e conhecimento de longo prazo) e busca híbrida (vetorial + por palavra-chave), ele permite recuperação eficiente de informações mesmo em contextos de grande escala.
• Para superar os limites da janela de contexto, ele usa as técnicas de 'compaction' e 'pruning', alcançando ao mesmo tempo otimização de custos e manutenção de desempenho.

Resumo detalhado:

1. Visão geral e filosofia de design
   O Clawdbot gerencia todas as memórias como arquivos Markdown dentro do workspace local para devolver a propriedade dos dados ao usuário. Com a transparência (Transparency) como valor central, ele foi projetado para que o usuário possa ler, editar e versionar diretamente os arquivos de memória.

2. Estrutura de memória em duas camadas
   A memória é amplamente dividida em duas camadas:

• Layer 1 (Daily Logs): registra no arquivo memory/YYYY-MM-DD.md os resumos das conversas do dia, decisões tomadas e preferências do usuário.
• Layer 2 (Long-term Knowledge): armazena no arquivo MEMORY.md fatos centrais que precisam persistir ao longo de várias sessões, decisões de projeto e perfis fixos do usuário.

3. Motor de busca híbrido (Hybrid Search)
   O agente usa a ferramenta memory_search para consultar a memória apenas quando necessário:

• Busca semântica (Vector Search): encontra conteúdo semanticamente semelhante por meio de embeddings (usando SQLite-vec).
• Busca por palavra-chave (BM25): usa em paralelo o mecanismo FTS5 para localizar substantivos próprios, datas, IDs etc. com exatidão.
• Cálculo da pontuação final: a precisão foi aumentada com um método ponderado de (0.7 * pontuação vetorial) + (0.3 * pontuação textual).

4. Técnicas de gerenciamento de contexto

• Compaction: ao atingir o limite de contexto, substitui conversas anteriores por um resumo. Em especial, por meio da etapa de 'Memory Flush', informações importantes são salvas permanentemente nos arquivos Markdown antes do resumo, evitando perda de informação.
• Pruning: economiza tokens ao cortar resultados de execução de ferramentas desnecessariamente longos, como saídas de logs em grande volume. Inclui uma lógica de exclusão inteligente que considera o TTL do prompt caching da Anthropic.

5. Stack técnico e fluxo de dados

• Armazenamento: arquivos Markdown locais (Source of Truth) e SQLite (para indexação).
• Workflow: detecção de alterações em arquivos (Chokidar) -> chunking (em unidades de 400 tokens, com sobreposição de 80 tokens) -> embeddings -> armazenamento no SQLite.