🌱 Fundamentos de Ruflo

Tarefas complexas que exigem múltiplas perspectivas (arquitetura, código, testes, segurança) acabam serializadas e gargaladas em um único agente.

Entender o problema é o primeiro passo. Sem isso, você não vê o valor de coordenar agentes especializados.

Sequenciamento, perda de contexto entre tarefas, ausência de memória persistente, sem cross-validation.

Ruflo é um framework de orquestração que coordena enxames de agentes especializados (architect, coder, tester, reviewer) com memória compartilhada e consenso distribuído.

Múltiplos agentes paralelos resolvem mais rápido, com cross-validation embutida e aprendizado contínuo.

Topologia, consenso, memória semântica, named agents, SendMessage, hooks de aprendizado.

SONA aprende com cada execução em <0.05ms. AgentDB+HNSW dá busca 150x-12.500x mais rápida. Federation conecta agentes de máquinas diferentes em zero-trust.

São features únicas do Ruflo. Saber o que existe é o que te faz escolher Ruflo em vez de soluções genéricas.

Self-Optimizing Neural Architecture, HNSW vector index, mTLS+ed25519, EWC++ anti-forgetting.

Use Ruflo para tarefas multi-arquivo (3+), features novas, refatorações cross-module, mudanças de schema, reviews de segurança e otimizações de performance.

Ruflo é overkill para edits simples. Saber quando usar economiza tempo e foco do agente.

Complexity detection, swarm vs solo, anti-drift, topologia hierarchical para 6-8 agentes.

Ruflo distribui responsabilidades em 27 pacotes (cli, mcp, swarm, memory, hooks, security, etc.), 60+ tipos de agentes e 33 plugins nativos no marketplace IPFS.

Saber o que está disponível evita reinventar a roda. Você instala plugin em vez de codar do zero.

Monorepo, separação de responsabilidades, plugin marketplace, IPFS/Pinata distribution.

Comando único: npx claude-flow@v3alpha init --wizard. Em 5 min você tem swarm rodando, memória ativa e hooks instalados.

Sentir o produto na mão é o melhor jeito de entender. Teoria sem prática esquece.

CLI wizard, daemon, MCP server, doctor health check, primeiros comandos.

Ruflo se organiza em 4 camadas: Interface (CLI/MCP), Orquestração (swarm/hooks), Inteligência (neural/memory) e Infraestrutura (security/guidance).

Saber em qual camada cada problema vive te faz debugar mais rápido e estender com confiança.

Domain-Driven Design, bounded contexts, monorepo, separation of concerns.

@claude-flow/cli (entry point), @claude-flow/mcp (servidor MCP), @claude-flow/swarm (orquestração), @claude-flow/memory (AgentDB+HNSW), @claude-flow/hooks (lifecycle + 12 workers).

São os 5 pacotes que você usa todos os dias. Entender cada um abre o caminho para o resto.

Entry point, MCP transport (stdio/http/ws), topology, vector index, lifecycle hooks.

@claude-flow/security (validação, CVE), @claude-flow/guidance (control plane de policies), @claude-flow/neural (SONA), @claude-flow/embeddings (ONNX 75x).

Estes pacotes potencializam o core. Você raramente importa direto, mas eles são chamados o tempo todo.

Zod validation, WASM kernel, SONA adaptation, ONNX runtime, vector embeddings.

Comando CLI vira request MCP, que inicializa swarm, que spawna agentes via Task tool, que executam e gravam memória, que dispara hooks de aprendizado.

Saber o caminho do dado é essencial para debugar, otimizar e estender o sistema.

Request lifecycle, MCP protocol, Task tool, agent spawn, post-task hook.

Claude Code adiciona Ruflo via claude mcp add ruflo. Daí Claude Code chama tools do Ruflo (314 disponíveis) por MCP, recebe resultados, age.

Sem MCP, Claude Code não vê Ruflo. Configurar certo destrava todo o ecossistema.

MCP server, stdio transport, tools/resources/prompts, Claude Code integration.

Diagrama mental do projeto: pontos de entrada, fluxos típicos e dependências entre pacotes. Claude Code → MCP → CLI → Swarm → Memory + Hooks.

Modelo mental claro acelera tudo. Você para de adivinhar onde editar quando algo quebra.

Entry points, data flow, dependency graph, mental model.

Um agente é um especialista IA com prompt e role definidos (architect, coder, tester, etc.). Roda via Task tool, pode rodar em background, comunica via SendMessage.

Agentes são a unidade básica de trabalho. Saber escolher o tipo certo aumenta a qualidade e reduz custo.

subagent_type, named agents, prompt isolation, run_in_background, lifecycle.

Categorias: Core (coder, reviewer, tester, planner, researcher), Especializados (security, memory, performance), Coordenação (hierarchical-coord, mesh-coord), GitHub (pr-manager, release-manager), SPARC, Testing.

Tipo errado = resultado ruim. Ex: usar coder para review é pedir para passar bug.

Especialização, coordenação, distribuição de responsabilidades, anti-drift via roles.

Uma rainha (coordinator) controla os workers diretamente. 6-8 agentes max. Strategy "specialized" para clareza de roles.

É a topologia padrão para coding swarms. Previne drift e mantém foco.

Centralized control, anti-drift, specialized strategy, raft consensus.

Todos os agentes podem falar com todos. Mais flexível, mais propenso a drift. Bom para pesquisa exploratória.

Em fases criativas, mesh dá mais caminhos. Evite para coding sério.

Peer-to-peer, distributed decision-making, byzantine consensus, gossip protocol.

Hierarchical-mesh combina rainha + comms peer. Adaptive muda topologia conforme carga e tipo de tarefa.

Para 10+ agentes ou cargas variáveis, hybrid/adaptive são as escolhas certas.

Hybrid topology, dynamic reconfiguration, load-aware routing.

Coding 6-8 agentes: hierarchical. Pesquisa/criação: mesh. 10+ agentes: hybrid. Carga variável: adaptive.

Decisão errada custa retrabalho. Esta heurística cobre 90% dos casos.

Heuristic selection, anti-drift, scalability tradeoffs.

Embeddings transformam texto em vetores 384-dim. Buscas semânticas (significado) em vez de keyword match. "auth" encontra "login", "credentials", "session".

Memória semântica é o que faz agentes lembrarem padrões e reusarem soluções.

Vector embeddings, semantic search, dimensions, similarity (cosine).

Vector database baseado em sql.js (SQLite via WASM). Roda em qualquer plataforma sem compilação nativa. Persiste em disco.

É a fundação da memória do Ruflo. Sem AgentDB, não tem persistência cross-session.

sql.js, WASM, vector_indexes table, persistent storage, namespaces.

Hierarchical Navigable Small World. Estrutura de grafo que aproxima nearest-neighbor em logarítmico em vez de linear.

Em grandes bases (10k+ itens), busca linear mata performance. HNSW resolve.

Approximate nearest neighbor (ANN), graph traversal, recall vs latency tradeoff.

Buckets lógicos: patterns, tasks, solutions, feedback, claude-memories.

Sem namespaces, busca retorna lixo. Separar por contexto melhora qualidade.

Logical separation, scope, multi-tenant memory, search filtering.

Modelo all-MiniLM-L6-v2 rodando em ONNX runtime. 384 dimensões, <5ms latência por embedding. Local, sem API call.

Embeddings locais economizam tempo e custo. ONNX dá performance sem dor.

ONNX runtime, sentence transformers, dimensionality, local inference.

RuVector Format: formato binário comprimido para salvar/restaurar memória entre sessões. Migração e backup simples.

Memória que sobrevive a restart. Sem RVF, agentes "esquecem" tudo a cada sessão.

Serialization, compression, RvfBackend, RvfMigrator, snapshot.

npx claude-flow@v3alpha init --wizard cria estrutura, instala hooks, configura MCP, gera CLAUDE.md.

É o ponto de partida. Init bem feito economiza horas depois.

Wizard, presets, skills config, hooks bootstrap, CLAUDE.md generation.

8 subcomandos: spawn (criar), list (listar), status (estado), stop (parar), metrics (performance), pool (compartilhamento), health (saúde), logs.

Controla ciclo de vida dos agentes. Saber listar e ver logs salva debug.

Lifecycle, agent pool, health checks, metrics export.

swarm init --topology hierarchical --max-agents 8 configura coordenação. swarm status mostra estado.

Swarm é a unidade de coordenação. Iniciar certo determina sucesso.

Topology config, max agents, strategy, consensus type, monitoring.

11 subcomandos. Principais: store --key X --value Y --namespace patterns e search --query "auth" --namespace patterns.

Operar memória manualmente é essencial para debug e ajustes.

Key-value, namespaces, semantic search, batch import/export.

doctor --fix verifica Node 20+, npm 9+, git, config, daemon, memory DB, API keys, MCP servers, disco, TypeScript.

Primeiro comando quando algo dá errado. Detecta 10+ problemas comuns.

Health checks, auto-fix, dependency validation, environment scan.

daemon start roda os 12 background workers (audit, optimize, ultralearn, etc.) em segundo plano.

Sem daemon, hooks de aprendizado não disparam. Daemon é o motor de auto-melhoria.

Background process, worker pool, trigger queue, async execution.

Hooks são funções executadas automaticamente em pontos específicos: antes/depois de edit, command, task, session. Configurados em settings.json.

Hooks injetam comportamento sem mudar código. Habilitam aprendizado, validação e logging automáticos.

Event-driven, lifecycle, settings.json, harness execution, automation.

6 hooks core: pre-edit, post-edit, pre-command, post-command, pre-task, post-task. Disparam antes/depois de cada operação.

São os hooks mais usados. post-edit treina padrões. post-task armazena trajetórias de sucesso.

Pre/post pattern, hook handlers, train-patterns, train-neural flags.

session-start importa memórias do projeto. session-end exporta métricas. session-restore continua de onde parou.

Mantém continuidade entre sessões. Importa contexto automaticamente.

Session ID, context import, metrics export, state persistence.

ultralearn, optimize, consolidate, predict, audit (crítico), map, preload, deepdive, document, refactor, benchmark, testgaps. Cada um com prioridade.

Workers fazem o trabalho de fundo enquanto você codifica. Auto-melhoria gratuita.

Worker priority, dispatch trigger, async tasks, background daemon.

Memórias do Claude Code (~/.claude/projects/.../memory/*.md) são importadas no AgentDB com embeddings 384-dim, busca semântica unificada.

Você ganha busca semântica nas memórias do Claude sem mudar nada do seu fluxo.

memory_import_claude, unified search, source attribution, ONNX embeddings.

SONA registra trajetórias (estado, ação, recompensa) após cada task e adapta routing futuro em <0.05ms.

É a base do auto-aprendizado. Quanto mais você usa, melhor fica.

Trajectory storage, online learning, RETRIEVE→JUDGE→DISTILL→CONSOLIDATE pipeline.