agentic-flow

🚀 Agentic-Flow v2 — the Agentic Meta-Harness

Freeze the model, evolve the harness. Agentic-Flow is an open agentic meta-harness: a runtime whose product is the harness around a model, not the model. It routes each query to the cost-optimal model, evolves its own harness and autonomously repairs code, then orchestrates 66 self-learning agents, 213 MCP tools, and multi-agent swarms on top.

The four pillars of the meta-harness

Why a meta-harness? The measured lever in modern agentic systems is the harness, not a bigger model: a cheap model in a well-built, self-improving harness matches a frontier model at a fraction of the cost (see the DRACO/Darwin findings). Agentic-Flow is the open runtime that operates that harness.

⚡ Quick Start (60 seconds)

# 1. Initialize your project
npx agentic-flow init

# 2. Bootstrap intelligence from your codebase
npx agentic-flow hooks pretrain

# 3. Start Claude Code with self-learning hooks
claude

Step 1 in an empty directory prints (agentic-flow 3.5.3, abridged):

✅ Created CLAUDE.md

📁 Created structure:
   .claude/
   ├── settings.json      # Claude Code settings (hooks, agents, skills, statusline)
   ├── statusline.sh      # Custom statusline (model, tokens, cost, swarm status)
   ├── agents/            # 80+ agent definitions (coder, tester, reviewer, etc.)
   ├── commands/          # 100+ slash commands (swarm, github, sparc, etc.)
   ├── skills/            # Custom skills and workflows
   └── helpers/           # Helper utilities
   CLAUDE.md              # Project instructions
   .agents/skills/        # Codex skills (same integrations guidance)

🚀 Next steps:
   1. Start the MCP server:
      npx agentic-flow@3.5.3 mcp start

On a Raspberry Pi 4 (no ARMv8.3 RCPC) native @ruvector/attention loads when its linux-arm64 binary is 2.3.1 or later (built without RCPC); an older binary is skipped in favour of the JS fallback. Set AGENTIC_FLOW_NATIVE_ATTENTION=0|1 to override.

That's it! Your project now has:

• 🧠 Self-learning hooks that improve agent routing over time
• 🤖 80+ specialized agents (coder, tester, reviewer, architect, etc.)
• ⚡ Background workers triggered by keywords (ultralearn, optimize, audit)
• 📊 213 MCP tools for swarm coordination

Common Commands

# Route a task to the optimal agent
npx agentic-flow hooks route "implement user authentication"

# View learning metrics
npx agentic-flow hooks metrics

# Dispatch background workers
npx agentic-flow workers dispatch "ultralearn how caching works"

# Run MCP server for Claude Code
npx agentic-flow mcp start

Use in Code

import { AgenticFlow } from "agentic-flow";

const flow = new AgenticFlow();
await flow.initialize();

// Route task to best agent
const result = await flow.route("Fix the login bug");
console.log(`Best agent: ${result.agent} (${result.confidence}% confidence)`);

Programmatic orchestration API (library-safe)

Build systems, IDEs, and CI can drive orchestration in-process without spawning the CLI or MCP. Import from the orchestration subpath (side-effect-free; no CLI, no servers).

Generic client (recommended for build agents — stable input/output: task description, memory seed, paths, provenance):

import { createOrchestrationClient } from "agentic-flow/orchestration";

const client = createOrchestrationClient({ config: { backend: "safe-exec" } });
const { runId } = await client.startRun({
  taskDescription: "Your task",
  acceptanceCriteria: ["Tests pass"],
  allowedPaths: ["src/"],
  provenance: { runId: "build-1", cardId: "card-42" },
});
const status = await client.getStatus(runId);

Low-level API: createOrchestrator, orchestrateTask, getRunStatus, cancelRun — see Orchestration API & Memory Plane. Do not use the default entry (import 'agentic-flow') for library use; it runs the CLI and starts servers.

🎉 What's New in v2

SONA: Self-Optimizing Neural Architecture 🧠

Agentic-Flow v2 now includes SONA (@ruvector/sona) for sub-millisecond adaptive learning:

• 🎓 +55% Quality Improvement: Research profile with LoRA fine-tuning
• ⚡ <1ms Learning Overhead: Sub-millisecond pattern learning and retrieval
• 🔄 Continual Learning: EWC++ prevents catastrophic forgetting
• 💡 Pattern Discovery: 300x faster pattern retrieval (150ms → 0.5ms)
• 💰 60% Cost Savings: LLM router with intelligent model selection
• 🚀 2211 ops/sec: Production throughput with SIMD optimization

Complete AgentDB@alpha Integration 🧠

Agentic-Flow v2 now includes ALL advanced vector/graph, GNN, and attention capabilities from AgentDB@alpha v2.0.0-alpha.2.11:

• ⚡ Flash Attention: 2.49x-7.47x speedup, 50-75% memory reduction
• 🎯 GNN Query Refinement: +12.4% recall improvement
• 🔧 5 Attention Mechanisms: Flash, Multi-Head, Linear, Hyperbolic, MoE
• 🕸️ GraphRoPE: Topology-aware position embeddings
• 🤝 Attention-Based Coordination: Smarter multi-agent consensus

Performance Grade: A+ (100% Pass Rate)

Cost-Optimal Model Routing (ADR-073) 💰

Route each query to the cheapest model predicted to clear a quality bar, learned from your own eval logs — the productized DRACO finding, powered by @metaharness/router (dependency-free k-NN / kernel-ridge, optional native FastGRNN via the already-bundled @ruvector/tiny-dancer). This is additive to the existing config-rule routing — it selects a model by predicted cost-quality rather than a provider by static rule, and degrades gracefully to best-predicted on a cold start.

import { ModelRouter } from "agentic-flow";
import { CostOptimalRouter } from "agentic-flow/router/cost-optimal";

// Build from your eval logs: rows of (query embedding → quality each model achieved)
const router = CostOptimalRouter.fromDataset(
  rows,
  {
    "anthropic/claude-haiku-4.5": 1, // $/Mtok
    "anthropic/claude-sonnet-4.5": 3,
    "anthropic/claude-opus-4": 15,
  },
  { qualityBar: 0.8 },
);

const model = new ModelRouter();
model.enableCostOptimalRouting({ router, embed: yourEmbedder });
// chat() now routes each query to the cheapest model predicted to clear 0.8.

Measured (node benchmarks/cost-optimal-router-benchmark.mjs, 3-tier lineup, 1000-query held-out test, bar=0.8):

→ 28.5% cheaper than always-opus while holding 98.1% of queries at/above the bar. Routing decision latency: p50 73µs · p99 125µs.

Autonomous Repair — Darwin Mode (ADR-074) 🔧

Freeze the model, evolve the harness: @metaharness/darwin mutates one policy surface at a time (planner / context / reviewer / retry / tool / memory / score), tests each in a shell-free, env-scrubbed sandbox, and keeps only what measurably improves under a frozen scorer + safety gate. Exposed as a typed repair() wrapper and the agentic-flow-repair CLI:

# Test-Driven Repair: the repo's own tests gate every promotion
npx --package=agentic-flow -- agentic-flow-repair ./my-repo --generations 3
# Deterministic, Docker-free smoke run
npx --package=agentic-flow -- agentic-flow-repair ./my-repo --mock

agentic-flow-repair is a binary provided by the agentic-flow package. Keep --package=agentic-flow before the command so npx selects that package instead of inferring a package name from the binary.

import { repair } from "agentic-flow/repair";
const result = await repair({ repoRoot: "./my-repo", generations: 3 }); // sandbox 'real'
// → { improved, winnerId, winnerLineage, baselineScore, winnerScore, deltaOverBaseline }

The sandbox is consistent with the repo's CWE-78 hardening (test command run via execFile, never a shell; only PATH + identifying vars reach a variant). The headline SWE-bench-Lite TDR product (≈68.3% with-test, ~$0.01–0.08/instance) additionally needs the official swebench Docker harness — see ADR-074.

📖 Table of Contents

• Quick Start
• What's New
• Key Features
• Performance Benchmarks
• Project Initialization
• Self-Learning Hooks
• Background Workers
• Installation
• API Reference
• Architecture
• Contributing

🔥 Key Features

🎓 SONA: Self-Optimizing Neural Architecture

Adaptive Learning (<1ms Overhead)

• Sub-millisecond pattern learning and retrieval
• 300x faster than traditional approaches (150ms → 0.5ms)
• Real-time adaptation during task execution
• No performance degradation

LoRA Fine-Tuning (99% Parameter Reduction)

• Rank-2 Micro-LoRA: 2211 ops/sec
• Rank-16 Base-LoRA: +55% quality improvement
• 10-100x faster training than full fine-tuning
• Minimal memory footprint (<5MB for edge devices)

Continual Learning (EWC++)

• No catastrophic forgetting
• Learn new tasks while preserving old knowledge
• EWC lambda 2000-2500 for optimal memory preservation
• Cross-agent pattern sharing