🔒 O que e sincrono
Hook sincrono bloqueia Claude ate retornar. Todo hook que retorna additionalContext e sincrono por natureza.
⏳ Caracteristicas de sync
Por que bloqueia:
- •Claude precisa do additionalContext ANTES de gerar proxima resposta.
- •Nao faz sentido gerar resposta e depois corrigir com contexto.
- •Latencia e percebida pelo usuario como 'Claude lento'.
- •Orçamento de latencia deve ser rigoroso: <100ms ideal, <300ms aceitavel.
🏎️ O que e assincrono
Hook assincrono dispara processo em background e retorna imediato. Claude nao espera.
🚀 Quando usar async
Casos tipicos:
- •SessionEnd: resumir sessao via Gemini (10+ segundos). Nao trava proxima sessao.
- •PostCompact: logar metricas de compactacao. Observacao pura.
- •Indexacao: rebuild de embedding de memoria. Pesado mas nao urgente.
- •Notificacoes externas: Slack, email, webhook. Cada um com seu timeout.
🛠️ Padrao: nohup + desacoplamento
O padrao classico para tornar qualquer hook assincrono: dispare em background e retorne imediatamente.
📐 Hook sync que dispara async
#!/usr/bin/env bash
# Hook sincrono que roda trabalho pesado em background
set -e
# Dispara trabalho pesado em background
nohup python3 ~/.memory/jobs/heavy_summarizer.py \
> /tmp/summarizer.log 2>&1 &
# Retorna imediato (sync)
echo '{}'💡 Timeout externo tambem
Dentro do heavy_summarizer.py, use timeout 60 para nao deixar pendurado se API cair.
📏 Orçamento de latencia
Regra dura: <100ms para sync. Acima disso, sensacao de lag. Acima de 2s, usuario acha que travou.
📊 Tabela de percepcao
- <100ms: imperceptivel. Usuario nao nota.
- 100-300ms: perceptivel mas aceitavel. Tolerado se ganho claro.
- 300ms-1s: sensivel. Usuario comeca a estranhar.
- 1-3s: lag. Pergunta se quebrou.
- >3s: inaceitavel. Comando vira 'travado'.
💡 Medicao
Adicione time no inicio e fim do hook. Log da duracao por execucao.
🔄 Lock e concorrencia
Duas sessoes abertas simultaneamente podem escrever no mesmo arquivo. Race condition corrompe memoria.
🔒 Solucoes de locking
Em ordem de simplicidade:
- •flock:
flock ~/.memory/context.md.lock command. Uma linha. - •Atomic write: escrever em temp + mv. POSIX garante atomicidade do rename.
- •Append-only: nunca sobrescrever. Novos eventos sempre no fim.
- •SQLite: ja trata locking internamente. Use quando escalar.
📐 Escolhendo sync/async por hook
Regra pratica para decidir no dia-a-dia:
✓ Sincrono (precisa do output)
- ✓SessionStart (precisa injetar contexto)
- ✓PreCompact (precisa antes do squeeze)
- ✓UserPromptSubmit (precisa antes da resposta)
- ✓PreToolUse para gates (bloquear ou nao)
✗ Asincrono (nao precisa esperar)
- ✗SessionEnd (proxima sessao nao depende)
- ✗PostToolUse (observacao pura)
- ✗PostCompact (metricas nao urgentes)
- ✗Stop em tarefas pesadas de analise
📝 Resumo do Modulo
Proximo:
3.6 — Depuracao e logging de hooks