🪝 Anatomia de um hook
Um hook em Ruflo é um interceptor de eventos no lifecycle de tools, sessões e tasks. Sua estrutura mínima: name, description, handler async e lifecycle stage. Registra-se no HookRegistry.
🔧Anatomia básica
interface Hook {
name: string;
description: string;
lifecycle: 'pre-edit' | 'post-edit' | 'pre-task' | ...;
handler: (ctx: HookContext) => Promise<HookResult>;
}📊Categorias disponíveis
- Core (6) — pre/post edit, command, task
- Session (4) — start, end, restore, notify
- Intelligence (5) — route, explain, pretrain, build-agents, transfer
- Agent Teams (2) — teammate-idle, task-completed
🛠️ Implementando custom hook
Do scaffold ao registro: vamos criar um hook que loga toda edição em arquivos sensíveis (auth, payment, etc).
🛠️Exemplo TypeScript
export const sensitiveFileGuard: Hook = {
name: 'sensitive-file-guard',
description: 'Audita edits em arquivos sensíveis',
lifecycle: 'pre-edit',
handler: async (ctx) => {
const sensitivePatterns = [/auth/, /payment/, /token/];
if (sensitivePatterns.some(p => p.test(ctx.filePath))) {
await audit.log({ action: 'edit', file: ctx.filePath });
}
return { proceed: true };
}
};💡Registro
Registre via HookRegistry.register(sensitiveFileGuard). O hook passa a ser executado a cada pre-edit. Para desabilitar temporariamente, HookRegistry.disable('sensitive-file-guard').
🛤️ Trajetórias
Trajetórias são sequências de (state, action, reward, outcome). São a matéria-prima do ReasoningBank — o que permite o agente aprender com sua própria experiência.
State
Snapshot do contexto
Arquivo, função, dependências relevantes, prompt do usuário, histórico recente.
Action
Decisão tomada
Qual tool foi chamada, parâmetros usados, qual abordagem foi escolhida (e qual rejeitada).
Reward & Outcome
Feedback
Testes passaram? Build verde? User aprovou? O reward é numérico, o outcome qualitativo.
🔄 RETRIEVE — busca via HNSW
A primeira fase do ReasoningBank é recuperar padrões relevantes. Usa HNSW (Hierarchical Navigable Small Worlds) para buscar top-K vizinhos mais próximos em milissegundos, mesmo entre milhões de embeddings.
🔄Como funciona
- •Embedding do contexto atual via ONNX MiniLM (384 dim)
- •HNSW search retorna top-K (default: 5) mais similares
- •Filtragem por verdict (success/failure) e recência
- •150x-12.500x mais rápido que busca linear
📊Numeros reais
- 1k embeddings → ~150x speedup vs linear
- 100k embeddings → ~5.000x speedup
- 1M embeddings → ~12.500x speedup
⚖️ JUDGE & DISTILL
Após RETRIEVE, o pipeline JULGA os padrões recuperados (success/failure/partial) e DESTILA learnings em uma representação mais compacta via LoRA.
✓ JUDGE — verdicts
- ✓success — testes verdes, user aprovou
- ✓failure — testes falharam, rollback
- ✓partial — funcionou em alguns casos
- ✓uncertain — sem signal claro
✗ Sem JUDGE
- ✗Aprende padrões ruins junto com os bons
- ✗Repete erros sistematicamente
- ✗Memória vira lixo
- ✗Confiança decresce com uso
🎚️DISTILL via LoRA
Após JUDGE, padrões aprovados viram training data para um adaptador LoRA. Em poucos minutos, o expert correspondente aprende o novo comportamento sem retraining completo.
🧠 CONSOLIDATE
Etapa final: consolidar o aprendizado sem destruir conhecimento prévio. EWC++ entra aqui — calcula importância dos pesos antigos e protege os críticos durante o update.
🧠O ciclo completo do RB
- RETRIEVE — HNSW busca top-K padrões
- JUDGE — verdicts classificam o que aprender
- DISTILL — LoRA extrai learnings em adaptador leve
- CONSOLIDATE — EWC++ aplica sem catastrophic forgetting
- PERSIST — AgentDB armazena para próxima sessão
💡Resultado prático
Após semanas de uso, seu Ruflo conhece seus padrões pessoais: estilo de testes preferido, convenções de naming, quais bibliotecas você gosta. Isso vem do ciclo RETRIEVE → JUDGE → DISTILL → CONSOLIDATE rodando em background.
📋Resumo do Módulo
Próximo Módulo:
3.4 - Plugin Development: scaffold ao publish em IPFS