flowchart TB
    subgraph USER["👤 User Layer"]
        U[User]
    end

    subgraph ENTRY["🚪 Entry Layer"]
        CLI[CLI / MCP Server]
        AID[AIDefence Security]
    end

    subgraph ROUTING["🧭 Routing Layer"]
        QL[Q-Learning Router]
        MOE[MoE - 8 Experts]
        SK[Skills - 130+]
        HK[Hooks - 27]
    end

    subgraph SWARM["🐝 Swarm Coordination"]
        TOPO[Topologies<br/>mesh/hier/ring/star]
        CONS[Consensus<br/>Raft/BFT/Gossip]
        CLM[Claims<br/>Human-Agent Coord]
    end

    subgraph AGENTS["🤖 100+ Agents"]
        AG1[coder]
        AG2[tester]
        AG3[reviewer]
        AG4[architect]
        AG5[security]
        AG6[...]
    end

    subgraph RESOURCES["📦 Resources"]
        MEM[(Memory<br/>AgentDB)]
        PROV[Providers<br/>Claude/GPT/Gemini/Ollama]
        WORK[Workers - 12<br/>ultralearn/audit/optimize]
    end

    subgraph RUVECTOR["🧠 RuVector Intelligence Layer"]
        direction TB
        subgraph ROW1[" "]
            SONA[SONA<br/>Self-Optimize<br/>&lt;0.05ms]
            EWC[EWC++<br/>No Forgetting]
            FLASH[Flash Attention<br/>2.49-7.47x]
        end
        subgraph ROW2[" "]
            HNSW[HNSW<br/>HNSW-indexed]
            RB[ReasoningBank<br/>Pattern Store]
            HYP[Hyperbolic<br/>Poincaré]
        end
        subgraph ROW3[" "]
            LORA[LoRA/Micro<br/>low-rank adaptation]
            QUANT[Int8 Quant<br/>3.92x memory]
            RL[9 RL Algos<br/>Q/SARSA/PPO/DQN]
        end
    end

    subgraph LEARNING["🔄 Learning Loop"]
        L1[RETRIEVE] --> L2[JUDGE] --> L3[DISTILL] --> L4[CONSOLIDATE] --> L5[ROUTE]
    end

    U --> CLI
    CLI --> AID
    AID --> QL & MOE & SK & HK
    QL & MOE & SK & HK --> TOPO & CONS & CLM
    TOPO & CONS & CLM --> AG1 & AG2 & AG3 & AG4 & AG5 & AG6
    AG1 & AG2 & AG3 & AG4 & AG5 & AG6 --> MEM & PROV & WORK
    MEM --> SONA & EWC & FLASH
    SONA & EWC & FLASH --> HNSW & RB & HYP
    HNSW & RB & HYP --> LORA & QUANT & RL
    LORA & QUANT & RL --> L1
    L5 -.->|loops back| QL

    style RUVECTOR fill:#1a1a2e,stroke:#e94560,stroke-width:2px
    style LEARNING fill:#0f3460,stroke:#e94560,stroke-width:2px
    style USER fill:#16213e,stroke:#0f3460
    style ENTRY fill:#1a1a2e,stroke:#0f3460
    style ROUTING fill:#1a1a2e,stroke:#0f3460
    style SWARM fill:#1a1a2e,stroke:#0f3460
    style AGENTS fill:#1a1a2e,stroke:#0f3460
    style RESOURCES fill:#1a1a2e,stroke:#0f3460

RuVector Components (included with Ruflo):

# Use RuVector via Ruflo
npx ruflo@latest hooks intelligence --status

Every request flows through four layers: from your CLI or Claude Code interface, through intelligent routing, to specialized agents, and finally to LLM providers for reasoning.

Agents organize into swarms led by queens that coordinate work, prevent drift, and reach consensus on decisions—even when some agents fail.

Hive Mind Capabilities:

• 🐝 Queen Types: Strategic (planning), Tactical (execution), Adaptive (optimization)
• 👷 8 Worker Types: Researcher, Coder, Analyst, Tester, Architect, Reviewer, Optimizer, Documenter
• 🗳️ 3 Consensus Algorithms: Majority, Weighted (Queen 3x), Byzantine (f < n/3)
• 🧠 Collective Memory: Shared knowledge, LRU cache, SQLite persistence with WAL
• ⚡ Performance: Fast batch spawning with parallel agent coordination

The system stores successful patterns in vector memory, builds a knowledge graph for structural understanding, learns from outcomes via neural networks, and adapts routing based on what works best.

Skip expensive LLM calls for simple tasks using WebAssembly transforms, and compress tokens to reduce API costs by 30-50%.

Background daemons handle security audits, performance optimization, and session persistence automatically while you work.

Smart routing skips expensive LLM calls when possible. Simple edits use WASM (free), medium tasks use cheaper models. This can extend your Claude Code usage by 250% or save significantly on direct API costs.

Agent Booster uses WebAssembly to handle simple code transformations without calling the LLM at all. When the hooks system detects a simple task, it routes directly to Agent Booster for instant results.

Supported Transform Intents:

Hook Signals:

When you see these in hook output, the system is telling you how to optimize:

# Agent Booster available - skip LLM entirely
[AGENT_BOOSTER_AVAILABLE] Intent: var-to-const
→ Use Edit tool directly, instant (regex-based, no LLM call) than LLM

# Model recommendation for Task tool
[TASK_MODEL_RECOMMENDATION] Use model="haiku"
→ Pass model="haiku" to Task tool for cost savings

Performance:

The Token Optimizer integrates agentic-flow optimizations to reduce API costs by compressing context and caching results.

Savings Breakdown:

Usage:

import { getTokenOptimizer } from '@claude-flow/integration';
const optimizer = await getTokenOptimizer();

// Get compact context (32% fewer tokens)
const ctx = await optimizer.getCompactContext("auth patterns");

// Optimized edit (instant (regex-based, no LLM call) for simple transforms)
await optimizer.optimizedEdit(file, oldStr, newStr, "typescript");

// Optimal config for swarm (100% success rate)
const config = optimizer.getOptimalConfig(agentCount);

Complex swarms can drift from their original goals. Ruflo V3 includes anti-drift defaults that prevent agents from going off-task.

Recommended Configuration:

// Anti-drift defaults (ALWAYS use for coding tasks)
swarm_init({
  topology: "hierarchical",  // Single coordinator enforces alignment
  maxAgents: 8,              // Smaller team = less drift surface
  strategy: "specialized"    // Clear roles reduce ambiguity
})

Why This Prevents Drift:

Additional Anti-Drift Measures:

• Frequent checkpoints via post-task hooks
• Shared memory namespace for all agents
• Short task cycles with verification gates
• Hierarchical coordinator reviews all outputs

Task → Agent Routing (Anti-Drift):

Examples:

# Minimal global install (fastest)
curl ... | bash -s -- --global --minimal

# With MCP auto-setup
curl ... | bash -s -- --global --setup-mcp

# Full setup with diagnostics
curl ... | bash -s -- --full

Speed:

Ruflo supports both Claude Code and OpenAI Codex CLI via the @claude-flow/codex package, following the Agentics Foundation standard.

Quick Start for Codex

# Initialize for Codex CLI (creates AGENTS.md instead of CLAUDE.md)
npx ruflo@latest init --codex

# Full Codex setup with all 137+ skills
npx ruflo@latest init --codex --full

# Initialize for both platforms (dual mode)
npx ruflo@latest init --dual

Platform Comparison

Key Concept: Execution Model

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE-FLOW = ORCHESTRATOR (tracks state, stores memory)       │
│  CODEX = EXECUTOR (writes code, runs commands, implements)      │
└─────────────────────────────────────────────────────────────────┘

Codex does the work. Claude-flow coordinates and learns.

Dual-Mode Integration (Claude Code + Codex)

Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE CODE (interactive)  ←→  CODEX WORKERS (headless)        │
│  - Main conversation         - Parallel background execution    │
│  - Complex reasoning         - Bulk code generation            │
│  - Architecture decisions    - Test execution                   │
│  - Final integration         - File processing                  │
└─────────────────────────────────────────────────────────────────┘

# Spawn parallel Codex workers from Claude Code
claude -p "Analyze src/auth/ for security issues" --session-id "task-1" &
claude -p "Write unit tests for src/api/" --session-id "task-2" &
claude -p "Optimize database queries in src/db/" --session-id "task-3" &
wait  # Wait for all to complete

Dual-Mode CLI Commands (NEW)

# List collaboration templates
npx @claude-flow/codex dual templates

# Run feature development swarm (architect → coder → tester → reviewer)
npx @claude-flow/codex dual run --template feature --task "Add user auth"

# Run security audit swarm (scanner → analyzer → fixer)
npx @claude-flow/codex dual run --template security --task "src/auth/"

# Run refactoring swarm (analyzer → planner → refactorer → validator)
npx @claude-flow/codex dual run --template refactor --task "src/legacy/"

Pre-Built Collaboration Templates

MCP Integration for Codex

When you run init --codex, the MCP server is automatically registered:

# Verify MCP is registered
codex mcp list

# If not present, add manually:
codex mcp add ruflo -- npx ruflo mcp start

Self-Learning Workflow

1. LEARN:   memory_search(query="task keywords") → Find similar patterns
2. COORD:   swarm_init(topology="hierarchical") → Set up coordination
3. EXECUTE: YOU write code, run commands       → Codex does real work
4. REMEMBER: memory_store(key, value, namespace="patterns") → Save for future

The Intelligence Loop (ADR-050) automates this cycle through hooks. Each session automatically:

• Builds a knowledge graph from memory entries (PageRank + Jaccard similarity)
• Injects ranked context into every route decision
• Tracks edit patterns and generates new insights
• Boosts confidence for useful patterns, decays unused ones
• Saves snapshots so you can track improvement with node .claude/helpers/hook-handler.cjs stats

MCP Tools for Learning

137+ Skills Available

Vector Search Details

• Embedding Dimensions: 384
• Search Algorithm: HNSW (sub-millisecond)
• Similarity Scoring: 0-1 (higher = better)
  • Score > 0.7: Strong match, use pattern
  • Score 0.5-0.7: Partial match, adapt
  • Score < 0.5: Weak match, create new

Ruflo v3 introduces self-learning neural capabilities that no other agent orchestration framework offers. While competitors require manual agent configuration and static routing, Ruflo learns from every task execution, prevents catastrophic forgetting of successful patterns, and intelligently routes work to specialized experts.

🧠 Neural & Learning

💾 Memory & Embeddings

🐝 Swarm & Coordination

🔧 Developer Experience

🛡️ Security & Platform

_{Comparison updated February 2026. Feature availability based on public documentation.}

What makes Ruflo different from other agent frameworks? These 10 capabilities work together to create a system that learns from experience, runs efficiently on any hardware, and keeps working even when things go wrong.

Not every task needs the most powerful (and expensive) model. Ruflo analyzes each request and automatically routes it to the cheapest handler that can do the job well. Simple code transforms skip the LLM entirely using WebAssembly. Medium tasks use faster, cheaper models. Only complex architecture decisions use Opus.

Cost & Usage Benefits:

Routing Tiers:

Routing: Q-learning with epsilon-greedy exploration, sub-millisecond decision latency

Complex projects fail when implementation drifts from the original plan. Ruflo solves this with a spec-first approach: define your architecture through ADRs (Architecture Decision Records), organize code into DDD bounded contexts, and let the system enforce compliance as agents work. The result is implementations that match specifications — even across multi-agent swarms working in parallel.

How It Prevents Drift:

Specification Features:

DDD Bounded Contexts:

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│    Core     │  │   Memory    │  │  Security   │
│  Agents,    │  │  AgentDB,   │  │  AIDefence, │
│  Swarms,    │  │  HNSW,      │  │  Validation │
│  Tasks      │  │  Cache      │  │  CVE Fixes  │
└─────────────┘  └─────────────┘  └─────────────┘
┌─────────────┐  ┌─────────────┐
│ Integration │  │Coordination │
│ agentic-    │  │  Consensus, │
│ flow,MCP    │  │  Hive-Mind  │
└─────────────┘  └─────────────┘

Key ADRs:

• ADR-001: agentic-flow@alpha as foundation (eliminates 10,000+ duplicate lines)
• ADR-006: Unified Memory Service with AgentDB
• ADR-008: Vitest testing framework (10x faster than Jest)
• ADR-009: Hybrid Memory Backend (SQLite + HNSW)
• ADR-026: Intelligent 3-tier model routing
• ADR-048: Auto Memory Bridge (Claude Code ↔ AgentDB bidirectional sync)
• ADR-049: Self-Learning Memory with GNN (LearningBridge, MemoryGraph, AgentMemoryScope)

flowchart TB
    subgraph User["👤 User Layer"]
        CC[Claude Code]
        CLI[CLI Commands]
    end

    subgraph Orchestration["🎯 Orchestration Layer"]
        MCP[MCP Server]
        Router[Intelligent Router]
        Hooks[Self-Learning Hooks]
    end

    subgraph Agents["🤖 Agent Layer"]
        Queen[Queen Coordinator]
        Workers[100+ Specialized Agents]
        Swarm[Swarm Manager]
    end

    subgraph Intelligence["🧠 Intelligence Layer"]
        SONA[SONA Learning]
        MoE[Mixture of Experts]
        HNSW[HNSW Vector Search]
    end

    subgraph Providers["☁️ Provider Layer"]
        Anthropic[Anthropic]
        OpenAI[OpenAI]
        Google[Google]
        Ollama[Ollama]
    end

    CC --> MCP
    CLI --> MCP
    MCP --> Router
    Router --> Hooks
    Hooks --> Queen
    Queen --> Workers
    Queen --> Swarm
    Workers --> Intelligence
    Intelligence --> Providers

sequenceDiagram
    participant U as User
    participant R as Router
    participant H as Hooks
    participant A as Agent Pool
    participant M as Memory
    participant P as Provider

    U->>R: Submit Task
    R->>H: pre-task hook
    H->>H: Analyze complexity

    alt Simple Task
        H->>A: Agent Booster (WASM)
        A-->>U: Result (<1ms)
    else Medium Task
        H->>A: Spawn Haiku Agent
        A->>M: Check patterns
        M-->>A: Cached context
        A->>P: LLM Call
        P-->>A: Response
        A->>H: post-task hook
        H->>M: Store patterns
        A-->>U: Result
    else Complex Task
        H->>A: Spawn Swarm
        A->>A: Coordinate agents
        A->>P: Multiple LLM calls
        P-->>A: Responses
        A->>H: post-task hook
        A-->>U: Result
    end

flowchart LR
    subgraph Input["📥 Input"]
        Query[Query/Pattern]
        Insight[New Insight]
    end

    subgraph Processing["⚙️ Processing"]
        Embed[ONNX Embeddings]
        Normalize[Normalization]
        Learn[LearningBridge<br/>SONA + ReasoningBank]
    end

    subgraph Storage["💾 Storage"]
        HNSW[(HNSW Index<br/>150x faster)]
        SQLite[(SQLite Cache)]
        AgentDB[(AgentDB)]
        Graph[MemoryGraph<br/>PageRank + Communities]
    end

    subgraph Retrieval["🔍 Retrieval"]
        Vector[Vector Search]
        Semantic[Semantic Match]
        Rank[Graph-Aware Ranking]
        Results[Top-K Results]
    end

    Query --> Embed
    Embed --> Normalize
    Normalize --> HNSW
    Normalize --> SQLite
    Insight --> Learn
    Learn --> AgentDB
    AgentDB --> Graph
    HNSW --> Vector
    SQLite --> Vector
    AgentDB --> Semantic
    Vector --> Rank
    Semantic --> Rank
    Graph --> Rank
    Rank --> Results

Self-Learning Memory (ADR-049):

Ruflo V3 integrates AgentDB v3 (3.0.0-alpha.10) providing 20+ memory controllers accessible via MCP tools and the CLI.

Core Memory:

Intelligence:

Causal & Explainable:

Security & Integrity:

Optimization:

MCP Tool Examples:

# Store to hierarchical memory
agentdb_hierarchical-store --key "auth-pattern" --value "JWT refresh" --tier "semantic"

# Recall from memory tiers
agentdb_hierarchical-recall --query "authentication" --topK 5

# Run memory consolidation
agentdb_consolidate

# Batch insert
agentdb_batch --operation insert --entries '[{"key":"k1","value":"v1"}]'

# Synthesize context
agentdb_context-synthesize --query "error handling patterns"

# Semantic routing
agentdb_semantic-route --input "fix auth bug in login"

Hierarchical Memory Tiers:

┌─────────────────────────────────────────────┐
│  Working Memory                             │  ← Active context, fast access
│  Size-based eviction (1MB limit)            │
├─────────────────────────────────────────────┤
│  Episodic Memory                            │  ← Recent patterns, moderate retention
│  Importance × retention score ranking       │
├─────────────────────────────────────────────┤
│  Semantic Memory                            │  ← Consolidated knowledge, persistent
│  Promoted from episodic via consolidation   │
└─────────────────────────────────────────────┘

flowchart TB
    subgraph Hierarchical["👑 Hierarchical (Default)"]
        Q1[Queen] --> W1[Worker 1]
        Q1 --> W2[Worker 2]
        Q1 --> W3[Worker 3]
    end

    subgraph Mesh["🕸️ Mesh"]
        M1[Agent] <--> M2[Agent]
        M2 <--> M3[Agent]
        M3 <--> M1[Agent]
    end

    subgraph Ring["💍 Ring"]
        R1[Agent] --> R2[Agent]
        R2 --> R3[Agent]
        R3 --> R1
    end

    subgraph Star["⭐ Star"]
        S1[Hub] --> S2[Agent]
        S1 --> S3[Agent]
        S1 --> S4[Agent]
    end

flowchart TB
    subgraph Input["📥 Input Validation"]
        Req[Request] --> Scan[AIDefence Scan]
        Scan --> PII[PII Detection]
        Scan --> Inject[Injection Check]
        Scan --> Jailbreak[Jailbreak Detection]
    end

    subgraph Decision["⚖️ Decision"]
        PII --> Risk{Risk Level}
        Inject --> Risk
        Jailbreak --> Risk
    end

    subgraph Action["🎬 Action"]
        Risk -->|Safe| Allow[✅ Allow]
        Risk -->|Warning| Sanitize[🧹 Sanitize]
        Risk -->|Threat| Block[⛔ Block]
    end

    subgraph Learn["📚 Learning"]
        Allow --> Log[Log Pattern]
        Sanitize --> Log
        Block --> Log
        Log --> Update[Update Model]
    end

Ruflo runs as an MCP (Model Context Protocol) server, allowing you to connect it to any MCP-compatible AI client. This means you can use Ruflo's 100+ agents, swarm coordination, and self-learning capabilities from Claude Desktop, VS Code, Cursor, Windsurf, ChatGPT, and more.

Quick Add Command

# Start Ruflo MCP server in any environment
npx ruflo@latest mcp start

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

# Add via CLI (recommended)
claude mcp add ruflo -- npx ruflo@latest mcp start

# Or add with environment variables
claude mcp add ruflo \
  --env ANTHROPIC_API_KEY=sk-ant-... \
  -- npx ruflo@latest mcp start

# Verify installation
claude mcp list

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

# Start with HTTP transport
npx ruflo@latest mcp start --transport http --port 3000

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// MCP definitions are natively supported in the Gen AI SDK
const mcpConfig = {
  servers: [{
    name: 'ruflo',
    command: 'npx',
    args: ['ruflo@latest', 'mcp', 'start']
  }]
};

{
  "name": "ruflo",
  "command": "npx",
  "args": ["ruflo@latest", "mcp", "start"]
}

Environment Variables

All configurations support these environment variables:

MCP Tool Groups

Control which MCP tools are loaded to reduce latency and token usage:

# Enable specific tool groups
export CLAUDE_FLOW_TOOL_GROUPS=implement,test,fix,memory

# Or use a preset mode
export CLAUDE_FLOW_TOOL_MODE=develop

Available Groups: create, issue, branch, implement, test, fix, optimize, monitor, security, memory, all, minimal

Preset Modes:

Precedence: CLI args (--tools=X) > Environment vars > Config file > Default (all)

Security Best Practices

⚠️ Never hardcode API keys in config files checked into version control.

# Use environment variables instead
export ANTHROPIC_API_KEY="sk-ant-..."

# Or use a .env file (add to .gitignore)
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Overview

@claude-flow/guidance turns CLAUDE.md into a runtime governance system with enforcement gates, cryptographic proofs, and feedback loops. Agents that normally drift after 30 minutes can now operate for days — rules are enforced mechanically at every step, not remembered by the model.

7-phase pipeline: Compile → Retrieve → Enforce → Trust → Prove → Defend → Evolve

Install

npm install @claude-flow/guidance@alpha

Quick Usage

import {
  createCompiler,
  createRetriever,
  createGates,
  createLedger,
  createProofChain,
} from '@claude-flow/guidance';

// Compile CLAUDE.md into a policy bundle
const compiler = createCompiler();
const bundle = await compiler.compile(claudeMdText);

// Retrieve task-relevant rules
const retriever = createRetriever();
await retriever.loadBundle(bundle);
const { shards, policyText } = await retriever.retrieve({
  taskDescription: 'Fix authentication bug in login flow',
});

// Enforce gates on tool calls
const gates = createGates(bundle);
const result = gates.evaluate({ tool: 'bash', args: { command: 'rm -rf /' } });
// result.blocked === true

// Audit with proof chain
const chain = createProofChain({ signingKey: process.env.PROOF_KEY! });
const envelope = chain.seal(runEvent);
chain.verify(envelope); // true — tamper-evident

Key Modules

Stats

• 1,331 tests across 26 test files
• 27 subpath exports for tree-shaking
• WASM kernel for security-critical hot paths (gates, proof, scoring)
• 25 ADRs documenting every architectural decision

Documentation

• Architecture Overview
• Getting Started
• Enforcement Gates Tutorial
• Proof Audit Trail
• Multi-Agent Security
• API Quick Reference
• Full README

Comprehensive feature set for enterprise-grade AI agent orchestration.

npx ruflo hive-mind init                    # Initialize hive mind
npx ruflo hive-mind spawn "Build API"       # Spawn with objective
npx ruflo hive-mind spawn "..." --queen-type strategic --consensus byzantine
npx ruflo hive-mind status                  # Check status
npx ruflo hive-mind metrics                 # Performance metrics
npx ruflo hive-mind memory                  # Collective memory stats
npx ruflo hive-mind sessions                # List active sessions

# Automatically enabled with ruflo init
npx ruflo@latest init

# Or manually add to .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

// Create a team
TeamCreate({ team_name: "feature-dev", description: "Building feature" })

// Create shared tasks
TaskCreate({ subject: "Design API", description: "..." })
TaskCreate({ subject: "Implement endpoints", description: "..." })

// Spawn teammates (parallel background work)
Task({ prompt: "Work on task #1...", subagent_type: "architect",
       team_name: "feature-dev", name: "architect", run_in_background: true })
Task({ prompt: "Work on task #2...", subagent_type: "coder",
       team_name: "feature-dev", name: "developer", run_in_background: true })

// Message teammates
SendMessage({ type: "message", recipient: "developer",
              content: "Prioritize auth", summary: "Priority update" })

// Cleanup when done
SendMessage({ type: "shutdown_request", recipient: "developer" })
TeamDelete()

# Handle idle teammate
npx ruflo@latest hooks teammate-idle --auto-assign true

# Handle task completion
npx ruflo@latest hooks task-completed --task-id <id> --train-patterns

# Install Quality Engineering plugin
npm install @claude-flow/plugin-agentic-qe

# Install AI Interpretability plugin
npm install @claude-flow/plugin-prime-radiant

# Install Gas Town Bridge plugin (WASM-accelerated orchestration)
npx ruflo@latest plugins install -n @claude-flow/plugin-gastown-bridge

# Install domain-specific plugins
npm install @claude-flow/plugin-healthcare-clinical
npm install @claude-flow/plugin-financial-risk
npm install @claude-flow/plugin-legal-contracts

# Install development intelligence plugins
npm install @claude-flow/plugin-code-intelligence
npm install @claude-flow/plugin-test-intelligence
npm install @claude-flow/plugin-perf-optimizer

# Install advanced AI/reasoning plugins
npm install @claude-flow/plugin-neural-coordination
npm install @claude-flow/plugin-cognitive-kernel
npm install @claude-flow/plugin-quantum-optimizer
npm install @claude-flow/plugin-hyperbolic-reasoning

# List all installed plugins
npx ruflo plugins list --installed

import { createRuVectorBridge } from '@claude-flow/plugins';

const bridge = createRuVectorBridge({
  host: 'localhost',
  port: 5432,
  database: 'vectors',
  user: 'postgres',
  password: 'secret',
  pool: { min: 2, max: 10 },
  ssl: true
});

// Enable the plugin
await registry.register(bridge);
await registry.loadAll();

import { createHyperbolicSpace } from '@claude-flow/plugins';

const space = createHyperbolicSpace('poincare', { curvature: -1.0 });

// Embed hierarchical data (trees, taxonomies)
const embedding = await space.embed(vector);
const distance = await space.distance(v1, v2);  // Geodesic distance
const midpoint = await space.geodesicMidpoint(v1, v2);

import { createSelfLearningSystem } from '@claude-flow/plugins';

const learning = createSelfLearningSystem(bridge);

// Automatic optimization
await learning.startLearningLoop();  // Runs in background

// Manual optimization
const suggestions = await learning.queryOptimizer.analyze(query);
await learning.indexTuner.tune('my_index');

npx ruflo@latest worker dispatch --trigger audit --context "./src"
npx ruflo@latest worker status

# Initialize ONNX embeddings with hyperbolic config
ruflo embeddings init

# Use larger model for higher quality
ruflo embeddings init --model all-mpnet-base-v2

# Semantic search
ruflo embeddings search -q "authentication patterns"

# Initialize RuVector in PostgreSQL
ruflo ruvector init --database mydb --user admin

# Check connection and schema status
ruflo ruvector status --verbose

# Run pending migrations
ruflo ruvector migrate --up

# Performance benchmark
ruflo ruvector benchmark --iterations 1000

# Optimize indices and vacuum
ruflo ruvector optimize --analyze

# Backup vector data
ruflo ruvector backup --output ./backup.sql

npx ruflo hive-mind init                                    # Initialize
npx ruflo hive-mind spawn "Build API" --queen-type tactical # Spawn swarm
npx ruflo hive-mind spawn "Research AI" --consensus byzantine --claude
npx ruflo hive-mind status                                  # Check status

▊ Ruflo V3 ● ruvnet  │  ⎇ main  │  Opus 4.6  | ●42% ctx  | $0.15
🏗️ DDD [●●●●○] 4/5  ⚡ HNSW 150x  🤖 ◉ [12/8]  👥 3  🟢 CVE 3/3  💾 512MB  🧠 15%  📦 AgentDB ●1.2K vectors

{
  "statusLine": {
    "type": "command",
    "command": "node .claude/helpers/statusline.cjs"
  }
}

npx ruflo@latest init --update --settings

{
  "model": { "display_name": "Opus 4.6" },
  "context_window": { "used_percentage": 42, "remaining_percentage": 58 },
  "cost": { "total_cost_usd": 0.15, "total_duration_ms": 45000 },
  "workspace": { "current_dir": "/path/to/project" },
  "session_id": "abc-123"
}

# Start daemon (auto-runs on SessionStart hooks)
npx ruflo@latest daemon start

# Check status with worker history
npx ruflo@latest daemon status

# Manually trigger a worker
npx ruflo@latest daemon trigger map

# Enable/disable workers
npx ruflo@latest daemon enable map audit optimize

# Stop daemon
npx ruflo@latest daemon stop

+-- Worker Daemon ---+
| Status: ● RUNNING  |
| PID: 12345         |
| Workers Enabled: 5 |
| Max Concurrent: 3  |
+--------------------+

Worker Status
+-------------+----+----------+------+---------+----------+----------+
| Worker      | On | Status   | Runs | Success | Last Run | Next Run |
+-------------+----+----------+------+---------+----------+----------+
| map         | ✓  | idle     | 12   | 100%    | 2m ago   | in 3m    |
| audit       | ✓  | idle     | 6    | 100%    | 5m ago   | in 5m    |
| optimize    | ✓  | running  | 4    | 100%    | now      | -        |
| consolidate | ✓  | idle     | 2    | 100%    | 15m ago  | in 15m   |
| testgaps    | ✓  | idle     | 3    | 100%    | 8m ago   | in 12m   |
+-------------+----+----------+------+---------+----------+----------+

# Start all daemons
.claude/helpers/daemon-manager.sh start 3 5

# Check daemon status
.claude/helpers/daemon-manager.sh status

# Stop all daemons
.claude/helpers/daemon-manager.sh stop

# Start worker manager
.claude/helpers/worker-manager.sh start 60

# Force run all workers immediately
.claude/helpers/worker-manager.sh force

# Check worker status
.claude/helpers/worker-manager.sh status

# Initialize project with wizard
npx ruflo@latest init --wizard

# Start daemon with background workers
npx ruflo@latest daemon start

# Spawn an agent with specific type
npx ruflo@latest agent spawn -t coder --name my-coder

# Initialize swarm with V3 mode
npx ruflo@latest swarm init --v3-mode

# Search memory (HNSW-indexed, 150x faster)
npx ruflo@latest memory search -q "authentication patterns"

# Run security scan
npx ruflo@latest security scan --depth full

# Performance benchmark
npx ruflo@latest performance benchmark --suite all

# Run full diagnostics
npx ruflo@latest doctor

# Run diagnostics with auto-fix
npx ruflo@latest doctor --fix

# Check specific component
npx ruflo@latest doctor --component memory

# Verbose output
npx ruflo@latest doctor --verbose

🩺 Ruflo Doctor v3.5

✅ Node.js      20.11.0 (required: 20+)
✅ npm          10.2.4 (required: 9+)
✅ Git          2.43.0
✅ Config       Valid claude-flow.config.json
✅ Daemon       Running (PID: 12345)
✅ Memory       SQLite healthy, 1.2MB
⚠️ API Keys    ANTHROPIC_API_KEY set, OPENAI_API_KEY missing
✅ MCP Server   Responsive (45ms latency)
✅ Disk Space   2.4GB available

Summary: 9/10 checks passed

# Initialize embeddings system
npx ruflo@latest embeddings init

# Generate embedding for text
npx ruflo@latest embeddings embed "authentication patterns"

# Batch embed multiple texts
npx ruflo@latest embeddings batch --file texts.txt

# Search with semantic similarity
npx ruflo@latest embeddings search "login flow" --top-k 5

import { createEmbeddingServiceAsync } from '@claude-flow/embeddings';

const service = await createEmbeddingServiceAsync({
  model: 'all-MiniLM-L6-v2',
  hyperbolic: true,  // Enable Poincaré ball embeddings
  cacheSize: 256
});

// Generate embedding
const embedding = await service.embed("authentication flow");

// Search similar patterns
const results = await service.search("login", { topK: 5 });

👨‍💻 Development & Code Quality

🔒 Security & Compliance

🐝 Multi-Agent Swarms

📊 Performance & Optimization

🔄 GitHub & DevOps

📋 Spec-Driven Development

🧠 Learning & Intelligence

The Problem

Claude Code has a finite context window (~200K tokens). When full, it compacts — summarizing the conversation and discarding details like exact file paths, tool outputs, decision reasoning, and code snippets. This creates a "context cliff" where Claude loses the ability to reference earlier work.

The Solution: Context Autopilot (ADR-051)

Ruflo intercepts the compaction lifecycle with three hooks that make context loss invisible:

Every Prompt                    Context Full                    After Compact
     │                              │                              │
     ▼                              ▼                              ▼
UserPromptSubmit              PreCompact                     SessionStart
     │                              │                              │
 Archive turns              Archive + BLOCK              Restore from archive
 to SQLite                  auto-compaction               via additionalContext
 (incremental)              (exit code 2)                (importance-ranked)
     │                              │                              │
     ▼                              ▼                              ▼
 Track tokens              Manual /compact               Seamless continuation
 Report % used             still allowed                 with full history

How Memory is Optimized

Optimization Thresholds

Real-Time Statusline

The statusline shows live context metrics read from autopilot-state.json:

🛡️  45% 89.2K ⊘  🧠 86%
│    │   │     │    │   │
│    │   │     │    │   └─ Intelligence score (learning.json + patterns + archive)
│    │   │     │    └──── Intelligence indicator
│    │   │     └───────── No prune cycles (⊘) or prune count (⟳N)
│    │   └─────────────── Token count (actual API usage)
│    └─────────────────── Context percentage used
└──────────────────────── Autopilot active (shield icon)

Storage Tiers

Configuration

# Context Autopilot (all have sensible defaults)
CLAUDE_FLOW_CONTEXT_AUTOPILOT=true        # Enable/disable autopilot (default: true)
CLAUDE_FLOW_CONTEXT_WINDOW=200000         # Context window size in tokens
CLAUDE_FLOW_AUTOPILOT_WARN=0.70           # Warning threshold (70%)
CLAUDE_FLOW_AUTOPILOT_PRUNE=0.85          # Optimization threshold (85%)
CLAUDE_FLOW_COMPACT_RESTORE_BUDGET=4000   # Max chars restored after compaction
CLAUDE_FLOW_RETENTION_DAYS=30             # Auto-prune never-accessed entries
CLAUDE_FLOW_AUTO_OPTIMIZE=true            # Importance ranking + pruning + sync

Commands

# Check archive status and autopilot state
node .claude/helpers/context-persistence-hook.mjs status

# Manual compact (archives first, then allows Claude Code to compress)
# Use /compact in Claude Code — autopilot allows manual, blocks auto

# Query archive directly
sqlite3 .claude-flow/data/transcript-archive.db \
  "SELECT COUNT(*), SUM(LENGTH(content)) FROM transcript_entries;"

Architecture Reference

• ADR-051: Infinite Context via Compaction-to-Memory Bridge
• ADR-052: Statusline Observability System
• Implementation: .claude/helpers/context-persistence-hook.mjs (~1560 lines)
• Settings: .claude/settings.json (PreCompact, SessionStart, UserPromptSubmit hooks)

Why RVF?

Previous versions shipped sql.js (18MB WASM blob) for persistent storage. This caused slow cold starts, large installs, and compatibility issues on ARM/Alpine. RVF eliminates all of that:

How it works

RVF files use a simple binary layout: a 4-byte magic header (RVF\0), a JSON metadata section, then packed entries. Each module has its own format variant:

Storage auto-selection

You don't need to pick a backend. The DatabaseProvider tries each option in order and uses the first one available:

RVF (pure TypeScript) → better-sqlite3 (native) → sql.js (WASM) → JSON (fallback)

RVF is always available since it has zero dependencies, so it wins by default. If you have better-sqlite3 installed (e.g., for advanced queries), it gets priority.

Vector search with HnswLite

RVF includes HnswLite — a pure TypeScript implementation of the HNSW (Hierarchical Navigable Small World) algorithm for fast nearest-neighbor search. It's used automatically when storing entries with embeddings.

import { RvfBackend } from '@claude-flow/memory';

const backend = new RvfBackend({ databasePath: './memory.rvf' });
await backend.initialize();

// Store entries — embeddings are indexed automatically
await backend.store({ id: '1', key: 'auth-pattern', content: '...', embedding: vector });

// Search by similarity
const results = await backend.search({ embedding: queryVector, limit: 10 });

Supports cosine, dot product, and Euclidean distance metrics. For large datasets (100K+ entries), install hnswlib-node for the native implementation — the backend switches automatically.

Migrating from older formats

The RvfMigrator converts between JSON files, SQLite databases, and RVF:

import { RvfMigrator } from '@claude-flow/memory';

// Auto-detect format and migrate
await RvfMigrator.autoMigrate('./old-memory.db', './memory.rvf');

// Or be explicit
await RvfMigrator.fromJsonFile('./backup.json', './memory.rvf');
await RvfMigrator.fromSqlite('./legacy.db', './memory.rvf');

// Export back to JSON for inspection
await RvfMigrator.toJsonFile('./memory.rvf', './export.json');

Format detection works by reading the first few bytes of the file — no file extension guessing.

Crash safety

All write operations use atomic writes: data goes to a temporary file first, then a single rename() call swaps it into place. If the process crashes mid-write, the old file stays intact.

• Memory backend: file.rvf.tmp → file.rvf
• Embedding cache: file.rvec.tmp.{random} → file.rvec
• Event log: Append-only (no overwrite needed)

SONA learning persistence

The PersistentSonaCoordinator stores learning patterns and trajectories in RVF format, so agents retain knowledge across sessions:

import { PersistentSonaCoordinator } from '@claude-flow/memory';

const sona = new PersistentSonaCoordinator({
  storePath: './data/sona-learning.rvls',
});
await sona.initialize();

// Patterns survive restarts
const similar = sona.findSimilarPatterns(embedding, 5);
sona.storePattern('routing', embedding);
await sona.shutdown(); // persists to disk

Security

RVF validates inputs at every boundary:

• Path validation — null bytes and traversal attempts are rejected
• Header validation — corrupted files are detected before parsing
• Payload limits — event log entries cap at 100MB to prevent memory exhaustion
• Dimension validation — embedding dimensions must be between 1 and 10,000
• Concurrent write protection — a lock flag prevents overlapping disk flushes

Configuration

# Environment variables
CLAUDE_FLOW_MEMORY_BACKEND=hybrid   # auto-selects RVF
CLAUDE_FLOW_MEMORY_PATH=./data/memory

# Or via CLI
ruflo memory init --force
ruflo config set memory.backend hybrid

What Are Hooks?

Hooks intercept operations (file edits, commands, tasks) and learn from outcomes. Unlike static automation, hooks improve over time by tracking what works and applying those patterns to future tasks.

How Hooks Learn (4-Step Pipeline)

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  RETRIEVE   │───▶│    JUDGE    │───▶│   DISTILL   │───▶│ CONSOLIDATE │
│             │    │             │    │             │    │             │
│ Find similar│    │ Was it      │    │ Extract key │    │ Prevent     │
│ past patterns│   │ successful? │    │ learnings   │    │ forgetting  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     HNSW              Verdict            LoRA              EWC++
   150x faster        success/fail      compression       memory lock

Hook Signals (ADR-026 Model Routing)

When hooks run, they emit signals that guide routing decisions. Watch for these in hook output:

Agent Booster Intents (handled without LLM):

• var-to-const - Convert var/let to const
• add-types - Add TypeScript type annotations
• add-error-handling - Wrap in try/catch
• async-await - Convert promises to async/await
• add-logging - Add console.log statements
• remove-console - Strip console.* calls

Example Hook Output:

$ npx ruflo@latest hooks pre-task --description "convert var to const in utils.ts"

[AGENT_BOOSTER_AVAILABLE] Intent: var-to-const
Recommendation: Use Edit tool directly
Performance: <1ms (instant (regex-based, no LLM call) than LLM)
Cost: $0

Intelligence Loop (ADR-050)

The intelligence loop wires PageRank-ranked memory into the hook system. Every session builds a knowledge graph that improves over time:

SessionStart:
  session-restore  → intelligence.init()
    → Read MEMORY.md / auto-memory-store.json
    → Build graph (nodes + similarity/temporal edges)
    → Compute PageRank
    → "[INTELLIGENCE] Loaded 13 patterns, 12 edges"

UserPrompt:
  route            → intelligence.getContext(prompt)
    → Jaccard-match prompt against pre-ranked entries
    → Inject top-5 patterns into Claude's context:

    [INTELLIGENCE] Relevant patterns for this task:
      * (0.95) HNSW gives HNSW-indexed search [rank #1, 12x accessed]
      * (0.88) London School TDD preferred [rank #3, 8x accessed]

PostEdit:
  post-edit        → intelligence.recordEdit(file)
    → Append to pending-insights.jsonl (<2ms)

SessionEnd:
  session-end      → intelligence.consolidate()
    → Process pending insights (3+ edits → new entry)
    → Confidence boost for accessed patterns (+0.03)
    → Confidence decay for unused patterns (-0.005/day)
    → Recompute PageRank, rebuild edges
    → Save snapshot for trend tracking

Measuring improvement:

# Human-readable diagnostics
node .claude/helpers/hook-handler.cjs stats

# JSON output for scripting
node .claude/helpers/hook-handler.cjs stats --json

# Or via intelligence.cjs directly
node .claude/helpers/intelligence.cjs stats

The stats command shows:

Example output:

+--------------------------------------------------------------+
|  Intelligence Diagnostics (ADR-050)                          |
+--------------------------------------------------------------+

  Graph
    Nodes:    9
    Edges:    8 (7 temporal, 1 similar)
    Density:  22.2%

  Confidence
    Min:      0.490    Max:  0.600
    Mean:     0.556    Median: 0.580

  Access
    Total accesses:     11
    Patterns used:      6/9
    Never accessed:     3

  Top Patterns (by composite score)
    #1  HNSW gives HNSW-indexed search
         conf=0.600  pr=0.2099  score=0.3659  accessed=2x
    #2  London School TDD preferred
         conf=0.600  pr=0.1995  score=0.3597  accessed=2x

  Last Delta (5m ago)
    Confidence: +0.0300
    Accesses:   +6

  Trend (3 snapshots)
    Confidence drift:  +0.0422
    Direction:         IMPROVING
+--------------------------------------------------------------+

All 27 Hooks by Category

🔧 Tool Lifecycle Hooks (6 hooks)

# Example: Edit with pattern learning
npx ruflo@latest hooks pre-edit ./src/auth.ts
npx ruflo@latest hooks post-edit ./src/auth.ts --success true --train-patterns

🧠 Intelligence & Routing Hooks (8 hooks)

# Route a task with explanation
npx ruflo@latest hooks route "refactor authentication to use JWT" --include-explanation

# Bootstrap intelligence from your codebase
npx ruflo@latest hooks pretrain --depth deep --model-type moe

📅 Session Management Hooks (4 hooks)

# Start session with auto-daemon
npx ruflo@latest hooks session-start --session-id "feature-auth" --start-daemon

# End session and export learnings
npx ruflo@latest hooks session-end --export-metrics --persist-patterns

🤖 Intelligence System Hooks (9 hooks)

# Start trajectory for complex task
npx ruflo@latest hooks intelligence trajectory-start --task "implement OAuth2"

# Record successful action
npx ruflo@latest hooks intelligence trajectory-step --action "created token service" --quality 0.9

# End trajectory and trigger learning
npx ruflo@latest hooks intelligence trajectory-end --success true

# View intelligence diagnostics and improvement trends (ADR-050)
node .claude/helpers/hook-handler.cjs stats
node .claude/helpers/intelligence.cjs stats --json

12 Background Workers (Auto-Triggered)

Workers run automatically based on context, or dispatch manually.

# List all workers
npx ruflo@latest hooks worker list

# Manually dispatch security audit
npx ruflo@latest hooks worker dispatch --trigger audit --context "./src/auth"

# Check worker status
npx ruflo@latest hooks worker status

Model Routing Hooks (3 hooks)

Automatically selects haiku/sonnet/opus based on task complexity.

# Get model recommendation
npx ruflo@latest hooks model-route --task "fix typo in README"
# → Recommends: haiku (simple task, low complexity)

npx ruflo@latest hooks model-route --task "design distributed consensus system"
# → Recommends: opus (complex architecture, high reasoning)

Progress Tracking

Quick Reference

# ══════════════════════════════════════════════════════════════════
# MOST COMMON HOOKS
# ══════════════════════════════════════════════════════════════════

# Route task to best agent (with intelligence context injection)
npx ruflo@latest hooks route "<task>" --include-explanation

# Start/end session with learning
npx ruflo@latest hooks session-start --start-daemon
npx ruflo@latest hooks session-end --persist-patterns

# View what the system has learned
npx ruflo@latest hooks metrics
npx ruflo@latest hooks intelligence stats

# Intelligence diagnostics — see if intelligence is improving
node .claude/helpers/hook-handler.cjs stats          # Human-readable
node .claude/helpers/hook-handler.cjs stats --json   # JSON for scripting
node .claude/helpers/intelligence.cjs stats           # Direct access

# Bootstrap on new project
npx ruflo@latest hooks pretrain --depth deep

# Dispatch background worker
npx ruflo@latest hooks worker dispatch --trigger audit

Share learned patterns across projects, teams, and the community via the decentralized pattern marketplace.

What You Can Share

Export Commands

# Export learned patterns to file
npx ruflo@latest memory export --format json --output ./patterns.json

# Export specific namespace
npx ruflo@latest memory export --namespace "security" --output ./security-patterns.json

# Export with embeddings (larger file, faster import)
npx ruflo@latest memory export --include-embeddings --output ./full-export.json

# Export agent configurations
npx ruflo@latest config export --scope project --output ./agent-configs.json

# Export session state
npx ruflo@latest session export --session-id "my-session" --output ./session.json

Import Commands

# Import patterns from file
npx ruflo@latest memory import --input ./patterns.json

# Import and merge with existing (don't overwrite)
npx ruflo@latest memory import --input ./patterns.json --merge

# Import from another project
npx ruflo@latest hooks transfer --source-path ../other-project

# Import agent configurations
npx ruflo@latest config import --input ./agent-configs.json --scope project

# Restore session
npx ruflo@latest session restore --session-id "my-session"

Pattern Store (IPFS Marketplace)

Decentralized pattern marketplace for sharing and discovering community patterns.

# Search for authentication patterns
npx ruflo@latest transfer-store search --query "authentication" --min-rating 4.0

# Download a pattern
npx ruflo@latest transfer-store download --id "auth-jwt-patterns-v2" --verify

# Publish your patterns
npx ruflo@latest transfer-store publish --input ./my-patterns.json --category "security"

Plugin Store

Discover and install community plugins from the live IPFS registry with 19 official plugins and live ratings via Cloud Function.

# List plugins with live ratings from Cloud Function
npx ruflo@latest plugins list

# Filter by type
npx ruflo@latest plugins list --type integration

# Rate a plugin
npx ruflo@latest plugins rate --name @claude-flow/embeddings --rating 5

# Search for MCP tool plugins
npx ruflo@latest transfer plugin-search --type "mcp-tool" --verified

# Get plugin info
npx ruflo@latest transfer plugin-info --name "semantic-code-search"

# List official plugins
npx ruflo@latest transfer plugin-official

Live IPFS Plugin Registry

The official plugin registry is hosted on IPFS with Ed25519 signature verification:

# Fetch live registry directly
curl -s "https://gateway.pinata.cloud/ipfs/bafkreiahw4ufxwycbwwswt7rgbx6hkgnvg3rophhocatgec4bu5e7tzk2a"

IPFS Integration

Patterns and models are distributed via IPFS for decentralization and integrity.

# Resolve IPNS name to CID
npx ruflo@latest transfer ipfs-resolve --name "/ipns/patterns.ruflo.io"

# Detect PII before publishing
npx ruflo@latest transfer detect-pii --content "$(cat ./patterns.json)"

Model & Learning Pattern Import/Export

Share trained neural patterns and learning models via IPFS.

# Export a learning pattern to IPFS
curl -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -d '{
    "pinataContent": {
      "type": "learning-pattern",
      "name": "my-patterns",
      "patterns": [...]
    },
    "pinataMetadata": {"name": "ruflo-learning-pattern"}
  }'

# Import a pattern from IPFS CID
curl -s "https://gateway.pinata.cloud/ipfs/QmYourCIDHere"

# Via Cloud Function (when deployed)
curl "https://publish-registry-xxx.cloudfunctions.net?action=export-model" -d @model.json
curl "https://publish-registry-xxx.cloudfunctions.net?action=import-model&cid=QmXxx"

Supported Model Types

Pre-trained Model Registry

Import pre-defined rule-based patterns for common tasks. 40 patterns across 8 categories (trigger-action rules, not ML-trained models).

Registry CID: QmNr1yYMKi7YBaL8JSztQyuB5ZUaTdRMLxJC1pBpGbjsTc

# Browse available models
curl -s "https://gateway.pinata.cloud/ipfs/QmNr1yYMKi7YBaL8JSztQyuB5ZUaTdRMLxJC1pBpGbjsTc" | jq '.models[].name'

# Import all models
npx ruflo@latest transfer import --cid QmNr1yYMKi7YBaL8JSztQyuB5ZUaTdRMLxJC1pBpGbjsTc

# Import specific category
npx ruflo@latest neural import --model security-review-patterns --source ipfs

# Use patterns in routing
npx ruflo@latest hooks route --task "review authentication code" --use-patterns

Benefits vs Fresh Install

Pre-Built Pattern Packs

# Install a pattern pack
npx ruflo@latest transfer-store download --id "security-essentials" --apply

RuVector WASM Neural Training

Real WASM-accelerated neural training using @ruvector/learning-wasm and @ruvector/attention packages for state-of-the-art performance.

# List available pre-trained models from IPFS registry
npx ruflo@latest neural list

# List models by category
npx ruflo@latest neural list --category security

# Train with WASM acceleration
npx ruflo@latest neural train -p coordination -e 100 --wasm --flash --contrastive

# Train security patterns
npx ruflo@latest neural train -p security --wasm --contrastive

# Benchmark WASM performance
npx ruflo@latest neural benchmark -d 256 -i 1000

# Import pre-trained models
npx ruflo@latest neural import --cid QmNr1yYMKi7YBaL8JSztQyuB5ZUaTdRMLxJC1pBpGbjsTc

# Export trained patterns to IPFS
npx ruflo@latest neural export --ipfs --sign

Benchmark Results

+---------------------+---------------+-------------+
| Mechanism           | Avg Time (ms) | Ops/sec     |
+---------------------+---------------+-------------+
| DotProduct          | 0.1063        | 9,410       |
| FlashAttention      | 0.1096        | 9,127       |
| MultiHead (4 heads) | 0.1661        | 6,020       |
| MicroLoRA           | 0.0026        | 383,901     |
+---------------------+---------------+-------------+
MicroLoRA Target (<100μs): ✓ PASS (2.60μs actual)

Training Options

The .claude/helpers/ directory contains 30+ automation scripts for development, monitoring, learning, and swarm coordination. These scripts integrate with hooks and can be called directly or via the V3 master tool.

Quick Start

# Master V3 tool - access all helpers
.claude/helpers/v3.sh help              # Show all commands
.claude/helpers/v3.sh status            # Quick development status
.claude/helpers/v3.sh update domain 3   # Update metrics

# Quick setup
.claude/helpers/quick-start.sh          # Initialize development environment
.claude/helpers/setup-mcp.sh            # Configure MCP servers

Helper Categories

📊 Progress & Metrics

🤖 Daemon & Worker Management

🧠 Learning & Intelligence

🐝 Swarm Coordination

🔒 Security & Compliance

💾 Checkpoints & Git

🎯 Guidance & Hooks

Example Workflows

Start Development Session:

# Initialize everything
.claude/helpers/v3.sh init
.claude/helpers/daemon-manager.sh start 3 5
.claude/helpers/worker-manager.sh start 60

# Check status
.claude/helpers/v3.sh full-status

Swarm Development:

# Start swarm monitoring
.claude/helpers/swarm-monitor.sh --watch &

# Initialize swarm hooks
.claude/helpers/swarm-hooks.sh init

# Monitor agent communication
.claude/helpers/swarm-comms.sh listen

Learning & Pattern Management:

# Start learning service
node .claude/helpers/learning-service.mjs &

# Consolidate patterns after session
.claude/helpers/pattern-consolidator.sh

# Optimize learned patterns
.claude/helpers/learning-optimizer.sh --aggressive

Configuration

Helpers are configured in .claude/settings.json:

{
  "helpers": {
    "directory": ".claude/helpers",
    "enabled": true,
    "v3ProgressUpdater": ".claude/helpers/update-v3-progress.sh",
    "autoStart": ["daemon-manager.sh", "worker-manager.sh"]
  }
}

Skills are reusable workflows that combine agents, hooks, and patterns into ready-to-use solutions. Think of them as "recipes" for common development tasks.

How Skills Work

┌──────────────────────────────────────────────────────────────────┐
│                         SKILL EXECUTION                          │
├──────────────────────────────────────────────────────────────────┤
│  You: "Run /github-code-review"                                  │
│           ↓                                                      │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐            │
│  │ Load Skill  │──▶│ Spawn Agents│──▶│ Execute     │            │
│  │ Definition  │   │ (5 agents)  │   │ Workflow    │            │
│  └─────────────┘   └─────────────┘   └─────────────┘            │
│           │                                  │                   │
│           └──── Learns from outcome ─────────┘                   │
└──────────────────────────────────────────────────────────────────┘

All 42 Skills by Category

# Example: Initialize vector search
/agentdb-vector-search

# Example: Review current PR
/github-code-review

# Example: Deploy swarm to cloud
/flow-nexus-swarm

# Example: Enable adaptive learning
/reasoningbank-intelligence

# Example: Apply security hardening
/v3-security-overhaul

# Example: Start pair programming session
/pair-programming

# Example: Run benchmarks
/worker-benchmarks

Running Skills

# In Claude Code - just use the slash command
/github-code-review
/pair-programming --mode tdd
/v3-security-overhaul

# Via CLI
npx ruflo@latest skill run github-code-review
npx ruflo@latest skill list
npx ruflo@latest skill info sparc-methodology

Creating Custom Skills

Use the skill-builder skill to create your own:

/skill-builder

Skills are defined in YAML with:

• Frontmatter: Name, description, agents needed
• Workflow: Steps to execute
• Learning: How to improve from outcomes

The Claims system manages who is working on what — whether human or agent. It prevents conflicts, enables handoffs, and balances work across your team.

Why Use Claims?

How Claims Work

┌─────────────────────────────────────────────────────────────────────┐
│                        CLAIMS LIFECYCLE                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────┐    ┌──────────┐    ┌──────────┐    ┌─────────────┐   │
│  │ UNCLAIMED│───▶│ CLAIMED  │───▶│ STEALABLE│───▶│ HANDED OFF  │   │
│  │         │    │          │    │          │    │             │   │
│  │ Open for│    │ Agent or │    │ Stuck or │    │ New owner   │   │
│  │ claiming│    │ human    │    │ abandoned│    │ continues   │   │
│  └─────────┘    └──────────┘    └──────────┘    └─────────────┘   │
│       │              │                │               │            │
│       └──────────────┴────────────────┴───────────────┘            │
│                           COMPLETED                                 │
└─────────────────────────────────────────────────────────────────────┘

Claims Commands

Visual Board View

npx ruflo@latest issues board

┌──────────────────────────────────────────────────────────────────────┐
│                        CLAIMS BOARD                                  │
├───────────────┬───────────────┬───────────────┬─────────────────────┤
│   UNCLAIMED   │    ACTIVE     │   STEALABLE   │     COMPLETED       │
├───────────────┼───────────────┼───────────────┼─────────────────────┤
│ #127 Add auth │ #123 Fix bug  │ #120 Refactor │ #119 Update docs    │
│ #128 Tests    │   (coder-1)   │   (stale 2h)  │ #118 Security fix   │
│               │ #124 API work │               │ #117 Performance    │
│               │   (reviewer)  │               │                     │
└───────────────┴───────────────┴───────────────┴─────────────────────┘

Handoff Workflow

When you need to pass work to someone else:

# 1. Request handoff with context
npx ruflo@latest issues handoff #123 \
  --to security-architect \
  --reason "Needs security review" \
  --progress 80

# 2. Target accepts handoff
npx ruflo@latest issues accept #123 --as security-architect

# 3. Work continues with full context

Load Balancing

# View current load
npx ruflo@latest issues load

# Output:
# Agent          | Claims | Load  | Status
# ---------------+--------+-------+--------
# coder-1        | 3      | 85%   | 🔴 Overloaded
# coder-2        | 1      | 25%   | 🟢 Available
# reviewer       | 2      | 50%   | 🟡 Normal
# security-arch  | 0      | 0%    | 🟢 Available

# Auto-rebalance
npx ruflo@latest issues rebalance

MCP Tools

The Route system uses Q-Learning to automatically assign tasks to the best agent based on learned performance patterns.

How Routing Works

┌─────────────────────────────────────────────────────────────────────┐
│                     INTELLIGENT ROUTING                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Task: "Fix authentication bug"                                     │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Analyze Task    │ ← Complexity, domain, keywords                 │
│  └────────┬────────┘                                                │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Q-Learning      │ ← Historical success rates per agent           │
│  │ Lookup          │                                                │
│  └────────┬────────┘                                                │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Recommend:      │                                                │
│  │ security-arch   │ → 94% confidence (auth domain expert)          │
│  └─────────────────┘                                                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Route Commands

Example: Route a Task

npx ruflo@latest route task "refactor authentication to use JWT"

# Output:
# ╔══════════════════════════════════════════════════════════════╗
# ║                    ROUTING RECOMMENDATION                     ║
# ╠══════════════════════════════════════════════════════════════╣
# ║ Task: "refactor authentication to use JWT"                    ║
# ║                                                                ║
# ║ Recommended Agent: security-architect                         ║
# ║ Confidence: 94%                                                ║
# ║                                                                ║
# ║ Why this agent?                                                ║
# ║ • Domain match: authentication, security                       ║
# ║ • Historical success: 12/13 similar tasks (92%)                ║
# ║ • Expertise: JWT, OAuth, session management                    ║
# ║                                                                ║
# ║ Alternative agents:                                            ║
# ║ • coder (78% confidence) - general implementation              ║
# ║ • backend-dev (71% confidence) - API expertise                 ║
# ╚══════════════════════════════════════════════════════════════╝

Coverage-Aware Routing

Routes tasks to agents based on test coverage gaps:

npx ruflo@latest route coverage

# Finds untested code and routes to tester agent:
# • src/auth/jwt.ts - 23% coverage → tester
# • src/api/users.ts - 45% coverage → tester
# • src/utils/crypto.ts - 0% coverage → security-architect + tester

Routing Hooks

# Route via hooks (preferred)
npx ruflo@latest hooks route "implement caching layer" --include-explanation

# Record outcome for learning
npx ruflo@latest hooks post-task --task-id "task-123" --success true --agent coder

How Q-Learning Improves Over Time

The system remembers what works and applies it to future similar tasks.

Use Ruflo packages directly in your TypeScript/JavaScript applications.

Installation

# Install specific packages
npm install @claude-flow/cli @claude-flow/memory @claude-flow/swarm

# Or install everything
npm install ruflo@latest

Quick Examples

import { AgentDB } from '@claude-flow/memory';

// Initialize with HNSW indexing (150x faster)
const db = new AgentDB({
  path: './data/memory',
  hnsw: { m: 16, efConstruction: 200 }
});

// Store patterns with embeddings
await db.store('auth-pattern', {
  content: 'JWT authentication flow',
  domain: 'security',
  embedding: await db.embed('JWT authentication flow')
});

// Semantic search
const results = await db.search('how to authenticate users', {
  topK: 5,
  minSimilarity: 0.7
});

console.log(results);
// [{ key: 'auth-pattern', similarity: 0.92, content: '...' }]

# Initialize memory database
npx ruflo@latest memory init --force

# Store patterns
npx ruflo@latest memory store --key "pattern-auth" --value "JWT authentication with refresh tokens"
npx ruflo@latest memory store --key "pattern-cache" --value "Redis caching for API responses"

# Build HNSW index for HNSW-indexed search
npx ruflo@latest memory search --query "authentication" --build-hnsw

# Semantic search (uses HNSW if built)
npx ruflo@latest memory search --query "how to cache data" --limit 5

# List and manage entries
npx ruflo@latest memory list --namespace patterns
npx ruflo@latest memory stats

import { createSwarm } from '@claude-flow/swarm';

// Create a hierarchical swarm
const swarm = await createSwarm({
  topology: 'hierarchical',
  maxAgents: 8,
  strategy: 'specialized'
});

// Spawn agents
await swarm.spawn('coder', { name: 'coder-1' });
await swarm.spawn('tester', { name: 'tester-1' });
await swarm.spawn('reviewer', { name: 'reviewer-1' });

// Coordinate a task
const result = await swarm.orchestrate({
  task: 'Implement user authentication',
  strategy: 'adaptive'
});

// Shutdown
await swarm.shutdown({ graceful: true });

import { isSafe, checkThreats, createAIDefence } from '@claude-flow/aidefence';

// Quick safety check
if (!isSafe(userInput)) {
  throw new Error('Potentially malicious input detected');
}

// Detailed threat analysis
const result = checkThreats(userInput);
if (!result.safe) {
  console.log('Threats:', result.threats);
  console.log('PII found:', result.piiFound);
}

// With learning enabled
const aidefence = createAIDefence({ enableLearning: true });
const analysis = await aidefence.detect(userInput);

// Provide feedback for learning
await aidefence.learnFromDetection(userInput, analysis, {
  wasAccurate: true,
  userVerdict: 'Confirmed threat'
});

import { createEmbeddingService, cosineSimilarity } from '@claude-flow/embeddings';

// Auto-selects best provider (agentic-flow ONNX preferred)
const embeddings = await createEmbeddingService({
  provider: 'auto',        // agentic-flow → transformers → mock
  autoInstall: true,       // Auto-install agentic-flow if missing
  dimensions: 384,
  cache: { enabled: true, maxSize: 10000 }
});

// Generate embeddings
const result = await embeddings.embed('authentication patterns');
console.log(`Generated in ${result.latencyMs}ms`);

// Batch processing with cache stats
const batch = await embeddings.embedBatch([
  'user login flow',
  'password reset',
  'session management'
]);
console.log(`Cache hits: ${batch.cacheStats?.hits}`);

// Compare similarity
const similarity = cosineSimilarity(batch.embeddings[0], batch.embeddings[1]);
// 0.94 (high similarity)

import { chunkText, estimateTokens } from '@claude-flow/embeddings';

const result = chunkText(longDocument, {
  maxChunkSize: 512,
  overlap: 50,
  strategy: 'sentence',  // 'character' | 'sentence' | 'paragraph' | 'token'
  minChunkSize: 100,
});

console.log(`Created ${result.totalChunks} chunks`);
result.chunks.forEach((chunk, i) => {
  console.log(`Chunk ${i}: ${chunk.length} chars, ~${chunk.tokenCount} tokens`);
});

import { l2Normalize, l1Normalize, minMaxNormalize, zScoreNormalize } from '@claude-flow/embeddings';

// L2 normalize (unit vector - most common for cosine similarity)
const l2 = l2Normalize(embedding);  // [0.6, 0.8, 0]

// Other normalizations
const l1 = l1Normalize(embedding);       // Manhattan norm = 1
const minMax = minMaxNormalize(embedding); // Values in [0, 1]
const zScore = zScoreNormalize(embedding); // Mean 0, std 1

import {
  euclideanToPoincare,
  hyperbolicDistance,
  hyperbolicCentroid,
  mobiusAdd,
} from '@claude-flow/embeddings';

// Convert to hyperbolic space (better for tree-like structures)
const poincare = euclideanToPoincare(embedding);

// Hyperbolic distance (geodesic in Poincaré ball)
const dist = hyperbolicDistance(embedding1, embedding2);

// Hyperbolic centroid (Fréchet mean)
const centroid = hyperbolicCentroid([embed1, embed2, embed3]);

// Why hyperbolic? Better for:
// - Parent-child relationships (class inheritance)
// - Directory hierarchies
// - Taxonomy structures
// - Lower distortion for tree-like data

import { createNeuralService, isNeuralAvailable } from '@claude-flow/embeddings';

// Check availability
const available = await isNeuralAvailable();

// Create neural service
const neural = createNeuralService({ dimension: 384 });
await neural.init();

if (neural.isAvailable()) {
  // Semantic drift detection (catches context drift)
  await neural.setDriftBaseline('Initial context');
  const drift = await neural.detectDrift('New input to check');
  console.log('Drift:', drift?.trend);  // 'stable' | 'drifting' | 'accelerating'

  // Memory with interference detection
  const stored = await neural.storeMemory('mem-1', 'Important pattern');
  console.log('Interference:', stored?.interference);

  // Recall by similarity
  const memories = await neural.recallMemories('query', 5);

  // Coherence calibration (fine-tune quality detection)
  await neural.calibrateCoherence(['good output 1', 'good output 2']);
  const coherence = await neural.checkCoherence('Output to verify');

  // Swarm coordination via embeddings
  await neural.addSwarmAgent('agent-1', 'researcher');
  const coordination = await neural.coordinateSwarm('Complex task');
}

import { PersistentEmbeddingCache } from '@claude-flow/embeddings';

const cache = new PersistentEmbeddingCache({
  dbPath: './embeddings.db',
  maxSize: 10000,
  ttlMs: 7 * 24 * 60 * 60 * 1000,  // 7 days
});

await cache.init();
await cache.set('my text', new Float32Array([0.1, 0.2, 0.3]));
const embedding = await cache.get('my text');

const stats = await cache.getStats();
console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);

# Generate embedding
ruflo embeddings embed "Your text here"

# Batch embed from file
ruflo embeddings batch documents.txt -o embeddings.json

# Similarity search
ruflo embeddings search "query" --index ./vectors

# Document chunking
ruflo embeddings chunk document.txt --strategy sentence --max-size 512

# Normalize embeddings
ruflo embeddings normalize embeddings.json --type l2 -o normalized.json

# Convert to hyperbolic
ruflo embeddings hyperbolic embeddings.json -o poincare.json

# Neural operations
ruflo embeddings neural drift --baseline "context" --input "check"
ruflo embeddings neural store --id mem-1 --content "data"
ruflo embeddings neural recall "query" --top-k 5

# Model management
ruflo embeddings models list
ruflo embeddings models download all-MiniLM-L6-v2

# Cache management
ruflo embeddings cache stats
ruflo embeddings cache clear --older-than 7d

import { HooksService } from '@claude-flow/hooks';

const hooks = new HooksService({
  enableLearning: true,
  reasoningBank: true
});

// Route task to optimal agent
const routing = await hooks.route('implement caching layer');
console.log(`Recommended: ${routing.agent} (${routing.confidence}%)`);

// Record task outcome
await hooks.postTask({
  taskId: 'task-123',
  success: true,
  quality: 0.95,
  agent: routing.agent
});

// Start trajectory for RL learning
const trajectory = await hooks.startTrajectory('complex-feature');
await hooks.recordStep(trajectory, { action: 'created service', reward: 0.8 });
await hooks.endTrajectory(trajectory, { success: true });

Package Reference

Ruflo v3 is built on top of agentic-flow, a production-ready AI agent orchestration platform. This deep integration provides instant (regex-based, no LLM call) code transformations, learning memory, and geometric intelligence.

Quick Start

# Install globally
npm install -g agentic-flow

# Or run directly with npx
npx agentic-flow --help

# Start MCP server
npx agentic-flow mcp start

# Add to Claude Code
claude mcp add agentic-flow -- npx agentic-flow mcp start

Core Components

# Single file edit
npx agentic-flow agent-booster edit \
  --file src/api.ts \
  --instructions "Add error handling" \
  --code 'try { ... } catch (error) { ... }'

# Batch rename across codebase
npx agentic-flow agent-booster batch-rename \
  --pattern "getUserData" \
  --replacement "fetchUserProfile" \
  --glob "src/**/*.ts"

# Parse LLM markdown output
npx agentic-flow agent-booster parse-md response.md

import { ReasoningBank } from 'agentic-flow/reasoningbank';

const bank = new ReasoningBank();

// Record successful outcome
await bank.recordOutcome({
  task: 'implement authentication',
  outcome: 'JWT with refresh tokens',
  success: true,
  context: { framework: 'express' }
});

// Retrieve similar patterns for new task
const patterns = await bank.retrieveSimilar('add user login', { k: 5 });
// Returns past successful auth implementations

// Judge and distill learnings
await bank.judge(trajectoryId, 'success');
await bank.distill();  // Extract key patterns
await bank.consolidate();  // Prevent forgetting (EWC++)

import { getOptimizedEmbedder, cosineSimilarity } from 'agentic-flow/embeddings';

const embedder = getOptimizedEmbedder();
await embedder.init();

// Generate embedding (3ms local vs 230ms Transformers.js)
const vector = await embedder.embed('authentication patterns');

// Batch processing
const vectors = await embedder.embedBatch([
  'user login flow',
  'password reset',
  'session management'
]);

// Calculate similarity
const similarity = cosineSimilarity(vectors[0], vectors[1]);

import { getOptimizedEmbedder, cosineSimilarity } from 'agentic-flow/embeddings';

const embedder = getOptimizedEmbedder();
let baseline: Float32Array;

// Set baseline context
baseline = await embedder.embed('User asking about API authentication');

// Check for drift
const current = await embedder.embed(userMessage);
const drift = 1 - cosineSimilarity(baseline, current);

if (drift > 0.15) {
  console.log('Semantic drift detected - escalate');
}

// Agents coordinate via embedding positions, not messages
const agentPosition = await embedder.embed(agentRole);
const taskPosition = await embedder.embed(currentTask);

// Geometric alignment for task routing
const alignment = cosineSimilarity(agentPosition, taskPosition);

// Detect model degradation/poisoning via embedding drift
await monitor.calibrate(knownGoodOutputs);
const result = await monitor.check(newOutput);
if (result.anomalyScore > 1.5) {
  console.log('WARNING: Output drifting from baseline');
}

import { ModelRouter } from 'agentic-flow/router';

const router = new ModelRouter();

// Automatic routing based on task complexity
const result = await router.route({
  task: 'Add console.log to function',
  preferCost: true
});
// Returns: { model: 'haiku', reason: 'simple task, low complexity' }

const result2 = await router.route({
  task: 'Design distributed caching architecture'
});
// Returns: { model: 'opus', reason: 'complex architecture, high reasoning' }

# Agent Booster
npx agentic-flow agent-booster edit --file <file> --instructions "<instr>" --code '<code>'
npx agentic-flow agent-booster batch --config batch-edits.json
npx agentic-flow agent-booster batch-rename --pattern <old> --replacement <new> --glob "**/*.ts"
npx agentic-flow agent-booster parse-md response.md

# ReasoningBank
npx agentic-flow reasoningbank retrieve "query" --k 5
npx agentic-flow reasoningbank record --task "task" --outcome "outcome" --success
npx agentic-flow reasoningbank distill
npx agentic-flow reasoningbank consolidate

# Embeddings
npx agentic-flow embeddings embed "text"
npx agentic-flow embeddings batch documents.txt -o vectors.json
npx agentic-flow embeddings search "query" --index ./vectors

# Model Router
npx agentic-flow router route "task description"
npx agentic-flow router stats

# MCP Server
npx agentic-flow mcp start
npx agentic-flow mcp stdio

# Start MCP server
npx agentic-flow mcp start

# Add to Claude Code
claude mcp add agentic-flow -- npx agentic-flow mcp start

Integration with Ruflo

Ruflo automatically leverages agentic-flow for:

// Ruflo automatically uses agentic-flow optimizations
import { getTokenOptimizer } from '@claude-flow/integration';

const optimizer = await getTokenOptimizer();

// Uses ReasoningBank (32% fewer tokens)
const ctx = await optimizer.getCompactContext('auth patterns');

// Uses Agent Booster (instant (regex-based, no LLM call) edits)
await optimizer.optimizedEdit(file, old, new, 'typescript');

// Uses Model Router (optimal model selection)
const config = optimizer.getOptimalConfig(agentCount);

Agentic-Jujutsu is self-learning version control designed for multiple AI agents working simultaneously without conflicts. Built on Jujutsu, it provides faster performance than Git with automatic conflict resolution.

Quick Start

# Install globally (zero dependencies - jj binary embedded!)
npm install -g agentic-jujutsu

# Or run directly with npx
npx agentic-jujutsu --help

# Analyze repository for AI agent compatibility
npx agentic-jujutsu analyze

# Start MCP server for AI agents
npx agentic-jujutsu mcp-server

# Compare performance with Git
npx agentic-jujutsu compare-git

Why Agentic-Jujutsu?

Core Capabilities

const { JjWrapper } = require('agentic-jujutsu');

const jj = new JjWrapper();

// Start learning trajectory
const trajectoryId = jj.startTrajectory('Deploy to production');

// Perform operations (automatically tracked)
await jj.branchCreate('release/v1.0');
await jj.newCommit('Release v1.0');

// Record operations to trajectory
jj.addToTrajectory();

// Finalize with success score (0.0-1.0) and critique
jj.finalizeTrajectory(0.95, 'Deployment successful, no issues');

// Later: Get AI-powered suggestions for similar tasks
const suggestion = JSON.parse(jj.getSuggestion('Deploy to staging'));
console.log('AI Recommendation:', suggestion.reasoning);
console.log('Confidence:', (suggestion.confidence * 100).toFixed(1) + '%');