Por Que Agentes de IA Precisam de 4 Camadas de Memória (Não Apenas Uma)
Neto Pompeu with Koda —
Por Que Agentes de IA Precisam de 4 Camadas de Memória (Não Apenas Uma)
E como construímos uma solução 100% local e sem custo
---
O Problema Que Ninguém Fala
Seu agente de IA esquece tudo.
Cada conversa, cada decisão, cada lição aprendida com dificuldade — desaparece assim que o contexto é compactado. Você paga R$1.000/mês por um agente que não consegue lembrar o que você disse ontem.
Eu sei porque vivi isso. Eu gerencio um estúdio de desenvolvimento web na French Guiana com 3 agentes de IA trabalhando comigo diariamente. Quando o Lossless Claw da Martian Engineering foi lançado, foi um divisor de águas — finalmente, uma compactação que preserva o contexto. Mas eu continuava esbarrando no mesmo problema: compactação preserva texto, não conhecimento.
Um agente pode lembrar que você discutiu um bug. Mas será que ele pode conectar esse bug à correção que você aplicou duas semanas depois? Será que ele consegue detectar quando uma nova informação contradiz algo que ele já "sabe"? Conseguirá encontrar aquele fato relevante enterrado em 3.000 linhas do histórico da conversa?
Não. Não com uma única camada de memória.
---
Por Que Uma Fonte de Memória Não Basta
Suponha que você pesquise por "problemas de implantação." Eis o que cada tipo de memória encontra:
| Tipo de Memória | O Que Encontra | O Que Perde | |-----------------|----------------|-------------| | Armazenamento de Fatos | "Falha na implantação no Vercel quando variáveis de ambiente estão ausentes" | Não encontra se palavras diferentes forem usadas | | Vetores de Embeddings | Trechos semanticamente similares sobre problemas de implantação | Perde termos técnicos exatos | | Busca em Texto Completo (FTS) | Correspondência exata à palavra-chave "implantação" | Perde "deploy", "push para produção", "liberar" | | Grafo de Conhecimento | "Vercel → depende de → variáveis de ambiente → causou → falha na implantação" | Requer extração estruturada primeiro |
Cada fonte é cega onde as outras enxergam. A resposta não é uma fonte melhor — são todas as quatro, em paralelo.
---
A Arquitetura: 4 Camadas, Uma Consulta
É assim que funciona quando você faz uma pergunta ao Agent Memory Tools:
``` Sua pergunta │ ▼ ┌─────────────────────────────┐ │ unified_recall │ │ (fan-out, ~2 segundos) │ ├─────────┬──────┬──────┬─────┤ │ Fatos │Vetores│ BM25 │Grafo│ │ Store │Embed │ FTS │ │ ├─────────┴──────┴──────┴─────┤ │ Mesclar → Pontuar → Reordenar │ │ (ponderado + remoção duplicados) │ ├─────────────────────────────┤ │ Síntese LLM │ │ (resposta fundamentada, ~3s)│ └─────────────────────────────┘ ```
Camada 1: Armazenamento de Fatos — fatos estruturados com categorias (conhecimento, erro, linha do tempo, preferência, ferramenta). Cada fato tem um índice de confiança e detecção de contradição. Quando você armazena "Next.js 15 usa Turbopack por padrão" e depois "Next.js 15 usa Webpack por padrão," o sistema detecta.
Camada 2: Vetores de Embeddings — busca semântica via nomic-embed-text-v2-moe rodando localmente pelo Ollama. 768 dimensões, custo zero de API. Encontra conteúdo relevante mesmo com palavras completamente diferentes.
Camada 3: BM25 em Texto Completo — busca clássica por palavras-chave. Quando você precisa de termos técnicos exatos, nomes de funções ou códigos de erro, é isso que encontra. Complementa perfeitamente a busca por vetores.
Camada 4: Grafo de Conhecimento — entidades e relações extraídas automaticamente. "App Bureau → usa → backend Convex → implantado no → Vercel." Permite raciocínio multi-hop: "O que afeta a performance do Bureau?" atravessa o grafo para encontrar problemas conectados em várias conversas.
---
O Ingrediente Secreto: Detecção de Contradição
É isso que separa um sistema de memória de um simples motor de busca.
Cada novo fato armazenado é checado contra fatos já existentes na mesma categoria:
- Remoção de duplicados por hash de conteúdo (combinações exatas)
- Similaridade por palavras-chave (índice de Jaccard)
- Distância de Levenshtein (para fatos curtos)
- Verificação semântica de contradição via LLM
Ao detectar contradição, você pode escolher: substituir o fato antigo, manter ambos ou rejeitar o novo. Sem mais corrupção silenciosa do conhecimento.
Exemplo real do nosso sistema em produção: um agente armazenou "Contrato de Pierre foi renovado" enquanto o armazenamento já tinha "Contrato de Pierre não foi renovado." Foi detectado na hora. Sem isso, o agente poderia dar respostas erradas com confiança, dependendo de qual fato recuperasse primeiro.
---
Custo Zero. Zero Nuvem. Zero Desculpas.
Aqui está a divisão completa dos custos:
| Componente | Custo | |------------|-------| | Ollama (gemma3:4b) | R$0 — roda com 8GB RAM | | Embeddings (nomic-embed-text-v2-moe) | R$0 — roda localmente | | Armazenamento de fatos | R$0 — arquivo JSON local | | Grafo de conhecimento | R$0 — arquivo JSON local | | Busca BM25 | R$0 — índice local | | Total | R$0/mês |
Compare isso com Mem0 Pro por R$1.200/mês para memória em grafo, ou os preços empresariais do Supermemory para hospedagem própria.
O único requisito: uma máquina que rode Ollama com modelo de 8GB. Isso é um Mac Mini de USD 500 ou qualquer laptop razoável dos últimos 3 anos.
---
Como Funciona Na Prática
Sou desenvolvedor web. Não crio ferramentas de IA para viver. Construí isso porque meus agentes precisavam.
Nossa rotina diária é assim:
Auto-ingestão: Toda vez que um arquivo markdown muda no workspace, auto_ingest.py extrai fatos, verifica contradições, atualiza embeddings e reconstrói o grafo de conhecimento. Sem intervenção manual.
Recall unificado: Quando um agente precisa de contexto, roda unified_recall.py. Quatro fontes consultadas em paralelo, resultados mesclados por pontuação ponderada, reordenados por um LLM, sintetizados em resposta fundamentada. Tempo total: ~3 segundos.
Raciocínio multi-hop: "Como a pipeline de deploy afeta o módulo CRM?" O sistema encadeia buscas: pipeline de deploy → Vercel → webhook do GitHub → app Bureau → módulo CRM. Responde perguntas que cruzam múltiplos documentos e conversas.
Decaimento temporal: fatos recentes pontuam mais. Erros são protegidos do decaimento (você nunca quer esquecer um bug crítico). Fatos de conhecimento têm pontuação estável. Isso imita como a memória humana funciona — recente é mais relevante, mas lições aprendidas persistem.
---
Começando
```bash
Instale via ClawHub (para usuários OpenClaw)
npx clawhub install primo-studio/agent-memory-tools
Ou clone diretamente
git clone https://github.com/Primo-Studio/agent-memory-tools cd agent-memory-tools
Baixe os modelos
ollama pull gemma3:4b ollama pull nomic-embed-text-v2-moe
Verifique a configuração
python3 scripts/selftest.py
Teste
python3 scripts/unified_recall.py "O que aconteceu na semana passada?" ```
É isso. Sem chaves de API, sem contas na nuvem, sem inferno de configuração.
---
O Que Vem a Seguir
Esta é a versão 1.0. Eis o que está por vir:
- Backend SQLite para o grafo de conhecimento (atualmente JSON, funciona bem até ~200 entidades)
- Compartilhamento de memória entre agentes (vários agentes lendo/escrevendo no mesmo armazenamento de fatos)
- Benchmark contra Mem0 e Supermemory no dataset LoCoMo
- Plugin OpenClaw para gatilhos automáticos de recall/captura (como o plugin do Mem0, porém local)
---
Por Que Código Aberto
Eu poderia ter vendido. O mercado de ferramentas de memória para agentes está explodindo — USD 8,5 bilhões em gastos com IA agente só neste ano.
Mas aqui está a questão: a memória deve ser local. O conhecimento do seu agente sobre seu código, seus clientes, suas decisões — isso não deve ficar no servidor de outra pessoa. E não deveria custar R$1.200/mês.
Então, tornamos open source. Licença MIT-0. Pegue, faça fork, melhore, venda se quiser. Só dê aos seus agentes uma memória de verdade.
---
→ ClawHub: https://clawhub.ai/primo-studio/agent-memory-tools → GitHub: https://github.com/Primo-Studio/agent-memory-tools
Construído pelo Primo Studio da French Guiana 🇬🇫 — uma pequena equipe de devs com grandes agentes.