🧠 Por que filesystem é a metáfora certa
Memória de agente não é uma lista plana de fatos. É um sistema com hierarquia, paths de acesso, permissões e expiração — exatamente como um sistema de arquivos. A metáfora não é poética: é funcional. Organizar memória como filesystem resolve os problemas que "lista de fatos" não resolve.
🗂️ Propriedades que filesystem oferece
- •Hierarquia — /global, /projeto, /sessao. Diferentes níveis de persistência e escopo.
- •Paths de acesso — o agente sabe exatamente onde buscar: /memoria/clientes/marco.md.
- •ACL (permissões) — quem pode ler, quem pode escrever, quem pode deletar cada memória.
- •TTL — arquivo expira em X dias. Sistema operacional limpa automaticamente.
- •Namespace — memórias de projetos diferentes não se contaminam.
💡 Onde isso aparece hoje
Claude Code já implementa memória como filesystem: ~/.claude/CLAUDE.md (global), projeto/CLAUDE.md (projeto), subpasta/CLAUDE.md (local). É literalmente um filesystem hierárquico.
🪣 Letta/MemGPT — RAM vs Disco
O trabalho de Charles Packer e equipe da UC Berkeley (MemGPT, 2023 → Letta, 2024) é a implementação acadêmica mais rigorosa de memória estruturada para agentes. A ideia central: agentes precisam de memória em camadas, assim como computadores têm RAM e disco.
🏗️ As 3 camadas do MemGPT
🟢 Core Memory (RAM = in-context)
Sempre presente na janela de contexto. Informação crítica que o agente precisa a cada turno: identidade, regras, contexto atual da tarefa.
Equivalente: CLAUDE.md ativo na sessão. Tamanho: pequeno (~2-5K tokens).
🟡 Archival Memory (Disco = indexado)
Memória persistente e indexada. O agente busca nela via query quando precisa. Pode crescer indefinidamente — não fica na janela de contexto.
Equivalente: Silver Platters, wikis, documentos. O agente faz "archival_memory_search('campanha Black Friday')".
🔵 Recall Memory (Cache = histórico)
Log das conversas anteriores. O agente busca o que foi dito/decidido antes, sem manter tudo na janela.
Equivalente: histórico de sessões indexado. Consulta: "o que combinamos sobre entrega semana passada?"
📒 Claude Code — memória em 3 níveis
O Claude Code implementa memória hierárquica via sistema de arquivos nativo: três níveis de CLAUDE.md com cascata de herança. Global → projeto → local. Cada nível sobrescreve (ou complementa) o anterior para o escopo em que está.
📁 A hierarquia de CLAUDE.md
~/.claude/CLAUDE.md # Global: preferências do usuário,
# estilo de comunicação, ferramentas padrão.
# Vale para TODOS os projetos.
/projetos/meu-projeto/CLAUDE.md # Projeto: stack, arquitetura,
# convenções de código, personas.
# Vale para este projeto.
/projetos/meu-projeto/frontend/CLAUDE.md # Local: regras específicas
# do módulo frontend.
# Sobrescreve projeto para esta pasta.
📊 O que colocar em cada nível
- Global (~/.claude/CLAUDE.md) — tom de comunicação, idioma, ferramentas preferidas, regras que nunca mudam.
- Projeto (projeto/CLAUDE.md) — arquitetura, stack, nomes de personas, onde ficam os platters, convenções do time.
- Local (subpasta/CLAUDE.md) — regras específicas do módulo: "este código usa TypeScript strict, nunca any", "testes ficam em /__tests__".
📖 Karpathy LLM Wiki — memória que se enriquece
Andrej Karpathy propôs que agentes deveriam manter uma wiki Markdown incremental — não um snapshot, mas um grafo de conhecimento que cresce a cada nova observação. Entidades, contradições, sínteses e cross-links. É o futuro da memória de longa duração.
📖 Estrutura da LLM Wiki
wiki/
pessoas/
cliente-marcos-antunes.md # Histórico, preferências, decisões
fornecedor-xyz.md
projetos/
campanha-black-friday.md # Timeline, aprendizados, cross-links
projeto-alpha.md
conceitos/
politica-desconto.md # Regra da empresa + exceções registradas
contradictions.md # Log de conflitos e como foram resolvidos
💡 Como o agente escreve na wiki
Após cada sessão relevante, o agente executa um hook de "memory synthesis":
- Identifica entidades novas mencionadas na sessão.
- Verifica se já existem páginas para essas entidades.
- Atualiza ou cria páginas com as novas informações.
- Registra contradições com informação anterior em contradictions.md.
- Adiciona cross-links entre páginas relacionadas.
🔍 Vector Stores e RAG
Quando a memória cresce além de centenas de arquivos, busca por palavra-chave não basta. Vector stores armazenam embeddings — representações numéricas do significado — e permitem busca semântica: "o que falamos sobre desconto de fidelidade?" retorna documentos relevantes mesmo sem as palavras exatas.
🔍 Quando usar RAG
- •Memória < 100 arquivos — filesystem hierárquico com grep suficiente. Sem necessidade de vector store.
- •100-10K arquivos — hybrid search: FTS5 (texto) + embeddings para queries semânticas.
- •10K+ arquivos — RAG completo necessário. Ferramentas: pgvector, Chroma, Qdrant, Pinecone.
📊 RAG na prática para cada persona
- Marco — carteira de 500 clientes: RAG para buscar historial de compra por semântica.
- Sally — base jurisprudencial com 10K decisões: RAG essencial para busca por conceito jurídico.
- Sana — literatura médica interna + casos clínicos: RAG para busca por diagnóstico diferencial.
⏳ TTL, Escopo e ACLs
Memória sem política de expiração e controle de acesso vira poluição. O agente confia em dado obsoleto, vaza informação entre projetos ou sobrescreve memória crítica acidentalmente. TTL, escopo e ACL são a governança da memória.
⚙️ As 3 dimensões de governança
⏰ TTL (Time to Live)
Cada item de memória tem validade declarada. Após expirar, o item é marcado como stale ou deletado.
# No frontmatter do arquivo de memória --- ttl: 30d # Expira em 30 dias created: 2026-05-01 owner: agente-cmo ---
🗂️ Escopo (Namespace)
Memória de um projeto não vaza para outro. Escopo garante isolamento.
memoria/ global/ # Todos os projetos projeto-a/ # Isolado: apenas projeto A projeto-b/ # Isolado: apenas projeto B
🔐 ACL (Access Control)
Quem lê, quem escreve, quem deleta cada memória. Especialmente crítico para dados sensíveis (médicos, jurídicos, financeiros).
# Permissions read: [agente-cmo, orquestrador] write: [agente-cmo] delete: [admin]
✓ Memória bem governada
- ✓TTL declarado em cada arquivo
- ✓Namespace por projeto/cliente
- ✓ACL explícita para dados sensíveis
- ✓Curador humano revisa memória mensal
✗ Memória como swamp
- ✗Sem TTL — tudo fica para sempre
- ✗Namespace único — projetos se contaminam
- ✗Sem controle de quem escreveu o quê
- ✗Dados médicos/jurídicos sem isolamento
📋 Resumo do Módulo
Próxima Trilha:
Trilha 4 — Trabalhadores: Orquestradores, especialistas, hierarquias e delegação de tarefas