🧠 Estado e Persistência: Memória entre Sessões

✓ O que PERSISTE entre sessões

• ✓Arquivos no filesystem — qualquer arquivo que o Claude escreve persiste
• ✓CLAUDE.md — instruções lidas no início de cada sessão
• ✓settings.json — hooks e comandos registrados
• ✓Arquivos de estado — YAML/JSON escritos pelos hooks

📊 Estrutura recomendada de estado

Todo arquivo de estado deve ter pelo menos:

• •version: número inteiro para migração de schema futuro
• •updated_at: timestamp ISO 8601 da última escrita
• •hook: nome do hook responsável pelo arquivo
• •data: o estado de negócio em si

🔄 Implementação de CAS em shell

#!/bin/bash
# Padrão CAS para atualização segura de estado

STATE_FILE=".claude/state/hook-state.yaml"
MAX_RETRIES=3
RETRY_DELAY=0.1

for i in $(seq 1 $MAX_RETRIES); do
  # 1. Lê o estado atual
  CURRENT_VERSION=$(yq '.version' "$STATE_FILE" 2>/dev/null || echo "0")

  # 2. Calcula o novo estado
  NEW_VERSION=$((CURRENT_VERSION + 1))
  NOVO_CONTEUDO="version: $NEW_VERSION
updated_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
runs: $(yq '.runs // 0' "$STATE_FILE" | awk '{print $1+1}')"

  # 3. Escreve no temporário
  TMPFILE=$(mktemp ".claude/state/state.XXXXXX.yaml")
  echo "$NOVO_CONTEUDO" > "$TMPFILE"

  # 4. Verifica se a versão ainda é a mesma (CAS)
  CURRENT_AT_WRITE=$(yq '.version' "$STATE_FILE" 2>/dev/null || echo "0")

  if [ "$CURRENT_AT_WRITE" = "$CURRENT_VERSION" ]; then
    # Versão não mudou: pode escrever
    mv "$TMPFILE" "$STATE_FILE"
    exit 0
  else
    # Conflito: outra instância atualizou. Retenta.
    rm -f "$TMPFILE"
    sleep $RETRY_DELAY
  fi
done

echo "CAS falhou após $MAX_RETRIES tentativas" >&2
exit 0  # fail-open

🔐 Implementação de lockfile

#!/bin/bash
# Lockfile com cleanup automático

LOCK_DIR=".claude/state/hook.lock"
MAX_WAIT=5  # segundos

# Cleanup no EXIT (mesmo em caso de erro)
cleanup() {
  rmdir "$LOCK_DIR" 2>/dev/null || true
}
trap cleanup EXIT

# Tenta adquirir o lock (mkdir é atômico)
WAITED=0
while ! mkdir "$LOCK_DIR" 2>/dev/null; do
  # Verifica lock stale (mais de 30s)
  if [ -d "$LOCK_DIR" ]; then
    LOCK_AGE=$(( $(date +%s) - $(stat -c %Y "$LOCK_DIR" 2>/dev/null || echo 0) ))
    if [ "$LOCK_AGE" -gt 30 ]; then
      rmdir "$LOCK_DIR" 2>/dev/null || true
      continue
    fi
  fi

  if [ "$WAITED" -ge "$MAX_WAIT" ]; then
    echo "Lock timeout após ${MAX_WAIT}s — fail-open" >&2
    exit 0  # fail-open
  fi
  sleep 0.5
  WAITED=$((WAITED + 1))
done

# --- Seção crítica (execução exclusiva) ---
echo $$ > "$LOCK_DIR/pid"
# ... operação crítica aqui ...
# --- Fim da seção crítica ---

# cleanup() remove o lock automaticamente via trap EXIT

💻 Padrões de leitura

#!/bin/bash
STATE_FILE=".claude/state/hook-state.yaml"

# --- Leitura com yq (YAML) ---
VERSION=$(yq '.version // 0' "$STATE_FILE" 2>/dev/null || echo "0")
LAST_RUN=$(yq '.last_run // ""' "$STATE_FILE" 2>/dev/null || echo "")

# --- Leitura com jq (JSON) ---
JSON_FILE=".claude/state/hook-state.json"
RUNS=$(jq -r '.stats.total_runs // 0' "$JSON_FILE" 2>/dev/null || echo "0")

# --- Fallback com grep (sem dependências) ---
# Funciona para YAML e JSON simples
VERSION_GREP=$(grep -m1 '"version"' "$JSON_FILE" 2>/dev/null | grep -o '[0-9]*' || echo "0")

# --- Verificação de existência antes de ler ---
if [ ! -f "$STATE_FILE" ]; then
  echo "Estado não encontrado — usando defaults"
  VERSION=0
  LAST_RUN=""
fi

# --- Validação de tipo ---
if ! [[ "$VERSION" =~ ^[0-9]+$ ]]; then
  echo "Versão inválida no estado: '$VERSION' — usando 0" >&2
  VERSION=0
fi