Modulo 4.5: UserPromptSubmit: injecao por turno

🎯 Quando usar UserPromptSubmit

Use quando o contexto necessario varia por pergunta. Nao faz sentido carregar schema em toda sessao, so quando alguem pergunta sobre DB.

🔄 Casos tipicos

Quando vale o investimento:

•Voce tem dominios distintos (DB, infra, frontend) com docs proprios.
•Long-term tem muitas entradas (100+) e so algumas importam por pergunta.
•Quer economizar tokens evitando carregar tudo sempre.
•Tem busca semantica local pronta e quer aproveitar.

💡 Se nao tem esses casos

SessionStart + PreCompact basta. UserPromptSubmit e sofistificacao, nao essencial.

🔍 Keyword matching no prompt

80% dos casos resolvem com grep simples na pergunta. Sem LLM, sem embeddings.

📐 Router por keyword

#!/usr/bin/env bash
# UserPromptSubmit hook com routing

INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.user_message' | tr '[:upper:]' '[:lower:]')

CONTEXT=""

# DB topics
if echo "$PROMPT" | grep -qE "sql|postgres|banco|query|schema"; then
  CONTEXT="$CONTEXT\n$(cat ~/.memory/docs/schema.md)"
fi

# Deploy topics
if echo "$PROMPT" | grep -qE "deploy|docker|k8s|nginx|infra"; then
  CONTEXT="$CONTEXT\n$(cat ~/.memory/docs/infra.md)"
fi

# API topics
if echo "$PROMPT" | grep -qE "endpoint|api|webhook|rota"; then
  CONTEXT="$CONTEXT\n$(cat ~/.memory/docs/api.md)"
fi

if [[ -n "$CONTEXT" ]]; then
  python3 -c "
import json
print(json.dumps({
  'hookSpecificOutput': {
    'hookEventName': 'UserPromptSubmit',
    'additionalContext': '''$CONTEXT'''
  }
}))
"
else
  echo '{}'
fi

💡 Regex generoso

Inclua sinonimos e variantes. 'banco' e 'database' e 'DB' devem bater. Errar no match perde o valor todo.

🧠 Busca semantica antes do prompt

Para long-term grande (500+ entradas), keyword nao cobre. Ai entra embedding local.

📐 Pipeline semantico

1. Carregar modelo de embedding local (fastembed)
   Custo: ~200ms uma vez por sessao (cached)

2. Encode query do usuario
   Custo: ~30ms

3. Buscar top 3 no indice (sqlite-vec)
   Custo: ~10ms

4. Retornar como additionalContext

Total: ~40ms por turno (excluindo carregamento inicial)
Qualidade: captura 'a decisao sobre pagamentos' mesmo
          sem a palavra 'decisao'.

💡 So se precisar

Nao adicionar antes de sentir falta com keyword. Complexidade adicional, ganho so claro em long-term grande.

📐 Orçamento por turno

Cada turno e injetavel, mas tem cap. Mais que 1000 tokens extras por turno polui.

📊 Token budgets

Minimo util: 200 tokens (1 memoria relevante)
Ideal: 500-800 tokens (2-3 memorias)
Maximo: 1000 tokens
Alem disso: re-estrutura o hook, nao injete tudo

⚠️ Sinais de exagero

Se voce adiciona contexto toda pergunta e Claude parece confuso, provavelmente inflou. Corte para o essencial.

🚫 Quando NAO usar

Hooks por turno tem latencia e complexidade. Nao vale em casos simples.

✓ NAO usar UserPromptSubmit

✓Contexto e o mesmo em 90% das perguntas
✓SessionStart ja carrega o necessario
✓Long-term tem <50 entradas (grep basta)
✓Voce esta comecando — foque em SessionStart + PreCompact

✓ Usar UserPromptSubmit

✗Dominios distintos (DB, infra, tests)
✗Long-term > 200 entradas
✗Economia de tokens importa
✗Time diverso com vocabulario variado

🎓 Exemplo completo: roteador

Script de 30 linhas que serve de base para qualquer adaptacao.

📐 Router pronto para copy

#!/usr/bin/env bash
# ~/.memory/hooks/user_prompt_router.sh

set -e

INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.user_message // ""' | tr '[:upper:]' '[:lower:]')

# Mapa topico → arquivo
declare -A TOPICS=(
  ['sql|postgres|banco|schema']='schema.md'
  ['deploy|docker|k8s|infra']='infra.md'
  ['endpoint|api|webhook']='api.md'
  ['test|pytest|unittest']='testing.md'
  ['auth|token|session']='auth.md'
)

CONTEXT=""
for pattern in "${!TOPICS[@]}"; do
  if echo "$PROMPT" | grep -qE "$pattern"; then
    FILE="$HOME/.memory/docs/${TOPICS[$pattern]}"
    if [[ -f "$FILE" ]]; then
      CONTEXT="$CONTEXT\n$(cat "$FILE")"
    fi
  fi
done

# Cap a 800 tokens (~3200 chars)
CONTEXT="${CONTEXT:0:3200}"

if [[ -n "$CONTEXT" ]]; then
  python3 -c "
import json
print(json.dumps({
  'hookSpecificOutput': {
    'hookEventName': 'UserPromptSubmit',
    'additionalContext': '''$CONTEXT'''
  }
}))
"
else
  echo '{}'
fi

💡 Versione seu mapa

O array TOPICS cresce com o tempo. Versione esse arquivo para nao perder evolucao.

📝 Resumo do Modulo

✓

Dispara a cada mensagem — granularidade maxima.

✓

Keyword match resolve 80% — sem precisar LLM.

✓

Semantica para casos densos — embeddings locais.

✓

Cap de 1000 tokens/turno — acima disso polui.

Proximo:

4.6 — Lab completo: palavra-codigo

← Modulo anterior Proximo Modulo →