Memória Hierárquica de Agentes (HAM)

Sistema de memória com escopo que oferece aos agentes de codificação de IA um "guia" para cada diretório, em vez de reler todo o seu projeto a cada prompt. O arquivo CLAUDE.md raiz contém o contexto global (200 tokens), os arquivos CLAUDE.md de subdiretório contêm contexto com escopo (250 tokens cada), e uma camada .memory/ armazena decisões, padrões e uma caixa de entrada para inferências não confirmadas.

Quando Usar Esta Habilidade

• Use quando quiser reduzir os custos de tokens de entrada em sessões do Claude Code
• Use quando seu projeto tiver 3+ diretórios e o agente continuar relendo os mesmos arquivos
• Use quando quiser contexto com escopo de diretório em vez de um único CLAUDE.md monolítico
• Use quando quiser um painel para visualizar a economia de tokens, o histórico da sessão e a saúde do contexto
• Use ao configurar um novo projeto e desejar memória de agente estruturada desde o primeiro dia

Como Funciona

Etapa 1: Configuração ("go ham")

Detecta automaticamente a plataforma e a maturidade do seu projeto, em seguida, gera a estrutura de memória:

project/
├── CLAUDE.md              # Root context (~200 tokens)
├── .memory/
│   ├── decisions.md       # Architecture Decision Records
│   ├── patterns.md        # Reusable patterns
│   ├── inbox.md           # Inferred items awaiting confirmation
│   └── audit-log.md       # Audit history
└── src/
    ├── api/CLAUDE.md      # Scoped context for api/
    ├── components/CLAUDE.md
    └── lib/CLAUDE.md

Etapa 2: Roteamento de Contexto

O CLAUDE.md raiz inclui uma seção de roteamento que informa ao agente exatamente qual subcontexto carregar:

## Context Routing

→ api: src/api/CLAUDE.md
→ components: src/components/CLAUDE.md
→ lib: src/lib/CLAUDE.md

O agente lê o arquivo raiz e, em seguida, carrega imediatamente o contexto relevante do subdiretório — sem adivinhações.

Etapa 3: Painel ("ham dashboard")

Inicia um painel web em localhost:7777 que visualiza:

• Economia de tokens (sessões com HAM ativado vs. desativado)
• Tendências diárias de tokens e custos
• Detalhamento da sessão por diretório
• Saúde dos arquivos de contexto (cobertura de CLAUDE.md ausente/desatualizada/herdada)
• Conformidade de roteamento (com que frequência o agente segue o mapa de roteamento)
• Estimativas de carbono/energia

Comandos

Exemplos

Exemplo 1: Configuração inicial

User: go ham

Agent: HAM setup complete. Created 8 files.
  - CLAUDE.md (root)
  - .memory/decisions.md
  - .memory/patterns.md
  - .memory/inbox.md
  - src/api/CLAUDE.md
  - src/components/CLAUDE.md
  - src/lib/CLAUDE.md
  - src/utils/CLAUDE.md

Baseline captured in .memory/baseline.json
Run "HAM savings" to see your token and cost savings.

Exemplo 2: Verificando a economia

User: ham savings

Agent:
  Before HAM: ~7,500 tokens/prompt
  After HAM:    ~450 tokens/prompt
  Savings:    7,050 tokens (94%)

  Monthly projection (1,500 prompts):
    Sonnet: ~$31.73 saved
    Opus:   ~$158.63 saved

Melhores Práticas

• Mantenha o CLAUDE.md raiz com menos de 60 linhas / 250 tokens
• Mantenha os arquivos CLAUDE.md de subdiretório com menos de 75 linhas cada
• Execute ham audit a cada 2 semanas para identificar arquivos de contexto desatualizados ou ausentes
• Use ham route após adicionar novos diretórios para manter o roteamento atualizado
• Revise .memory/inbox.md periodicamente — confirme ou rejeite itens inferidos

Limitações

• As estimativas de tokens usam a aproximação de ~4 caracteres = 1 token, não um tokenizador real
• As comparações de economia de linha de base são estimativas baseadas no comportamento típico do agente
• O painel requer Node.js 18+ e lê dados da sessão de arquivos JSONL em ~/.claude/projects/
• A detecção de roteamento de contexto depende da ordem de leitura do CLAUDE.md em arquivos JSONL de sessão
• Não atualiza automaticamente o conteúdo do CLAUDE.md de subdiretório — você os mantém manualmente ou via ham audit
• As estimativas de carbono usam médias da rede regional, não dados de energia em tempo real

Habilidades Relacionadas

• agent-memory-systems — padrões gerais de arquitetura de memória de agente
• agent-memory-mcp — integração de memória baseada em MCP