ruvnet--ruflo/v3/@claude-flow/neural

@claude-flow/neural

Self-Optimizing Neural Architecture (SONA) for Claude Flow V3 — adaptive learning, trajectory tracking, pattern reuse, and 7 RL algorithms in a single package.

What this is

A self-contained learning module that records agent execution trajectories, distills them into reusable patterns, retrieves matches for new tasks, and adapts via SONA + LoRA + EWC++. Designed to be the substrate that the Claude Flow CLI's intelligence layer composes onto — the package owns the algorithms, the CLI owns the orchestration.

Install

npm install @claude-flow/neural

Note (2026-05-16): @claude-flow/neural@3.0.0-alpha.9+ pins @ruvector/sona to the exact known-good 0.1.5 because @ruvector/sona@0.1.6 shipped as an empty publish (README + package.json only — no index.js, no native bins). Prior alpha.8 used "latest" and broke on every fresh install. The pin will stay until @ruvector/sona@0.1.7+ ships with content.

Standalone use (without the Ruflo CLI)

// route a task across 8 specialized experts (MoE) — no other deps
import { getMoERouter } from '@claude-flow/neural';

const router = getMoERouter();
await router.initialize();

const decision = await router.route(
  new Float32Array(384).fill(0.1),   // task embedding
  { task: 'optimize-query', complexity: 0.7 },
);
console.log(decision.expert, decision.confidence);
// → 'performance', 0.83  (or whichever expert wins)

Quick start (recommended)

NeuralLearningSystem is the high-level entry point — it wires SONAManager, ReasoningBank, and PatternLearner together so callers don't have to:

import { createNeuralLearningSystem } from '@claude-flow/neural';

const sys = createNeuralLearningSystem('balanced');
await sys.initialize();

// Track a task
const id = sys.beginTask('Refactor auth middleware', 'code');

// Record steps as the agent works (Float32Array embeddings)
sys.recordStep(id, 'analyzed-imports', 0.8, embedding1);
sys.recordStep(id, 'extracted-helpers',  0.9, embedding2);

// Complete — fires distillation + pattern extraction automatically
await sys.completeTask(id, /* qualityScore */ 0.85);

// Retrieve relevant memories for the next similar task
const memories = await sys.retrieveMemories(queryEmbedding, /* k */ 3);
const patterns = await sys.findPatterns(queryEmbedding, 3);

// Periodic learning sweep (consolidation + EWC)
await sys.triggerLearning();

console.log(sys.getStats());
// → { sona: NeuralStats, reasoningBank: { ... }, patternLearner: { ... } }

Lower-level API: SONA Manager

For callers that want to manage trajectories and patterns directly:

import { createSONAManager, type Trajectory } from '@claude-flow/neural';

const sona = createSONAManager('balanced');
await sona.initialize();

// domain ∈ 'code' | 'creative' | 'reasoning' | 'chat' | 'math' | 'general'
const trajectoryId = sona.beginTrajectory('code-review-task', 'code');

sona.recordStep(trajectoryId, 'analyze-code',     0.8, stateEmbedding);
sona.recordStep(trajectoryId, 'generate-feedback', 0.9, nextStateEmbedding);

const trajectory: Trajectory = sona.completeTrajectory(trajectoryId, 0.85);

// Query patterns
const matches = await sona.findSimilarPatterns(contextEmbedding, /* k */ 3);

// Trigger consolidation manually
await sona.triggerLearning('manual');
sona.consolidateEWC();

Learning modes

Mode	Adaptation	Quality	Memory	Use case
real-time	<0.5ms	70%+	25 MB	Production, low-latency
balanced (default)	<18ms	75%+	50 MB	General purpose
research	<100ms	95%+	100 MB	Deep exploration
edge	<1ms	80%+	5 MB	Resource-constrained
batch	<50ms	85%+	75 MB	High-throughput

await sys.setMode('research'); // or directly: await sona.setMode('research')

ReasoningBank + PatternLearner (separately accessible)

NeuralLearningSystem composes them; you can also use them standalone:

import {
  createReasoningBank,
  createPatternLearner,
  createSONALearningEngine,
} from '@claude-flow/neural';

const bank = createReasoningBank();
await bank.storeTrajectory(trajectory);
await bank.judge(trajectory);
const distilled = await bank.distill(trajectory);

const learner = createPatternLearner();
learner.extractPattern(trajectory, distilled);
const matches = await learner.findMatches(queryEmbedding, 5);

const engine = createSONALearningEngine();
const adapted = await engine.adapt(input, /* domain */ 'code');

RL algorithms (7 included)

Imports use the Algorithm suffix where applicable:

import {
  PPOAlgorithm,         createPPO,         DEFAULT_PPO_CONFIG,
  A2CAlgorithm,         createA2C,         DEFAULT_A2C_CONFIG,
  DQNAlgorithm,         createDQN,         DEFAULT_DQN_CONFIG,
  QLearning,            createQLearning,   DEFAULT_QLEARNING_CONFIG,
  SARSAAlgorithm,       createSARSA,       DEFAULT_SARSA_CONFIG,
  DecisionTransformer,  createDecisionTransformer, DEFAULT_DT_CONFIG,
  CuriosityModule,      createCuriosity,   DEFAULT_CURIOSITY_CONFIG,
} from '@claude-flow/neural';

const ppo = createPPO({ learningRate: 0.0003, epsilon: 0.2, valueCoef: 0.5 });
const dqn = createDQN({ learningRate: 0.001, gamma: 0.99, epsilon: 0.1, targetUpdateFreq: 100 });

// Generic factory — pick algorithm by name
import { createAlgorithm, getDefaultConfig } from '@claude-flow/neural';
const algo = createAlgorithm('ppo', getDefaultConfig('ppo'));

LoRA configuration

const config = sona.getLoRAConfig();
// { rank: 4, alpha: 8, dropout: 0.05, targetModules: ['q_proj','v_proj','k_proj','o_proj'], microLoRA: false }

const weights = sona.initializeLoRAWeights('code-generation');

EWC++ (Elastic Weight Consolidation)

Prevents catastrophic forgetting when adapting to new domains:

const config = sona.getEWCConfig();
// { lambda: 2000, decay: 0.9, fisherSamples: 100, minFisher: 1e-8, online: true }

// After learning a new task, consolidate before moving on
sona.consolidateEWC();

Event system

sys.addEventListener((event) => {
  switch (event.type) {
    case 'trajectory_started':  console.log(`Started: ${event.trajectoryId}`); break;
    case 'trajectory_completed': console.log(`Quality: ${event.qualityScore}`); break;
    case 'pattern_matched':     console.log(`Pattern ${event.patternId} matched`); break;
    case 'learning_triggered':  console.log(`Learning: ${event.reason}`); break;
    case 'mode_changed':        console.log(`${event.fromMode} → ${event.toMode}`); break;
  }
});

Performance targets

Metric	Target	Typical
Adaptation latency	<0.05 ms	0.02 ms
Pattern retrieval	<1 ms	0.5 ms
Learning step	<10 ms	5 ms
Quality improvement	+55%	+40–60%
Memory overhead	<50 MB	25–75 MB

TypeScript types

import type {
  // Core
  SONAMode, SONAModeConfig, ModeOptimizations,
  Trajectory, TrajectoryStep, TrajectoryVerdict, DistilledMemory,
  Pattern, PatternMatch, PatternEvolution,

  // RL
  RLAlgorithm, RLConfig,
  PPOConfig, DQNConfig, A2CConfig, QLearningConfig, SARSAConfig,
  DecisionTransformerConfig, CuriosityConfig,

  // Neural
  LoRAConfig, LoRAWeights, EWCConfig, EWCState,
  NeuralStats, NeuralEvent, NeuralEventListener,
} from '@claude-flow/neural';

Integration with @claude-flow/cli

The CLI's intelligence layer (hooks_intelligence_*, neural_* MCP tools, /intelligence dashboard) is the primary consumer. Phase 1 of the convergence (#1773) adds a thin bridge in cli/src/memory/neural-package-bridge.ts that lazy-loads NeuralLearningSystem so cli's intelligence handlers can call into the package surface alongside the existing local implementation. Future phases migrate cli's LocalSonaCoordinator and LocalReasoningBank to wrap this package's SONALearningEngine and ReasoningBankAdapter.

If you're building a Ruflo plugin that wants neural learning, depend on @claude-flow/neural directly rather than reaching into cli internals.

Dependencies

• @claude-flow/memory — vector memory for patterns
• @ruvector/sona — SONA learning engine

Related packages

• @claude-flow/memory — memory backend
• @claude-flow/cli — primary consumer + MCP tool surface
• @claude-flow/cli-core — lite path (no neural; for plugin scripts)

License

MIT