🔄 Migration Guide (V2 → V3)

Why Migrate to V3?

┌─────────────────────────────────────────────────────────────┐
│                    V2 → V3 IMPROVEMENTS                     │
├───────────────────────┬─────────────────────────────────────┤
│ Memory Search         │ 150x - 12,500x faster (HNSW)        │
│ Pattern Matching      │ Self-learning (ReasoningBank)       │
│ Security              │ CVE remediation + strict validation │
│ Modular Architecture  │ 18 @claude-flow/* packages          │
│ Agent Coordination    │ 16 specialized agent roles + custom types              │
│ Token Efficiency      │ 32% reduction with optimization     │
└───────────────────────┴─────────────────────────────────────┘

Breaking Changes

Change	V2	V3	Impact
Package Structure	ruflo	@claude-flow/* (scoped)	Update imports
Memory Backend	JSON files	AgentDB + HNSW	Faster search
Hooks System	Basic patterns	ReasoningBank + SONA	Self-learning
Security	Manual validation	Automatic strict mode	More secure
CLI Commands	Flat structure	Nested subcommands	New syntax
Config Format	.ruflo/config.json	claude-flow.config.json	Update path

Step-by-Step Migration

bash
# STEP 1: Backup existing data (CRITICAL)
cp -r ./data ./data-backup-v2
cp -r ./.ruflo ./.ruflo-backup-v2

# STEP 2: Check migration status
npx ruflo@latest migrate status

# STEP 3: Run migration with dry-run first
npx ruflo@latest migrate run --dry-run

# STEP 4: Execute migration
npx ruflo@latest migrate run --from v2

# STEP 5: Verify migration
npx ruflo@latest migrate verify

# STEP 6: Initialize V3 learning
npx ruflo@latest hooks pretrain
npx ruflo@latest doctor --fix

Command Changes Reference

V2 Command	V3 Command	Notes
ruflo start	ruflo mcp start	MCP is explicit
ruflo init	ruflo init wizard	Interactive setup (subcommand, not a flag)
ruflo spawn <type>	ruflo agent spawn -t <type>	Nested under agent
ruflo swarm create	ruflo swarm init --topology mesh	Explicit topology
--pattern-store path	--memory-backend agentdb	Backend selection
hooks record	hooks post-edit --success true	Explicit success flag
memory get <key>	memory retrieve --key <key>	Explicit flag
memory set <key> <value>	memory store --key <key> --value <value>	Explicit flags
neural learn	hooks intelligence --mode learn	Under hooks
config set key value	config set --key key --value value	Explicit flags

Configuration Migration

V2 Config (.ruflo/config.json):

json
{
  "mode": "basic",
  "patternStore": "./patterns",
  "maxAgents": 10
}

V3 Config (claude-flow.config.json):

json
{
  "version": "3.0.0",
  "memory": {
    "type": "hybrid",
    "path": "./data",
    "hnsw": { "m": 16, "ef": 200 }
  },
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 15,
    "strategy": "specialized"
  },
  "security": { "mode": "strict" },
  "neural": { "enabled": true, "sona": true }
}

Import Changes

typescript
// V2 (deprecated)
import { ClaudeFlow, Agent, Memory } from 'ruflo';

// V3 (new)
import { ClaudeFlowClient } from '@claude-flow/cli';
import { AgentDB } from '@claude-flow/memory';
import { ThreatDetector } from '@claude-flow/security';
import { HNSWIndex } from '@claude-flow/embeddings';

Rollback Procedure

If migration fails, you can rollback:

bash
# Check rollback options
npx ruflo@latest migrate rollback --list

# Rollback to V2
npx ruflo@latest migrate rollback --to v2

# Restore backup manually if needed
rm -rf ./data
cp -r ./data-backup-v2 ./data

Post-Migration Checklist

• Verify all agents spawn correctly: npx ruflo@latest agent list
• Check memory search works: npx ruflo@latest memory search -q "test"
• Confirm MCP server starts: npx ruflo@latest mcp start
• Run doctor diagnostics: npx ruflo@latest doctor
• Test a simple swarm: npx ruflo@latest swarm init --topology mesh
• Bootstrap learning: npx ruflo@latest hooks pretrain

Common Migration Issues

Issue	Cause	Solution
MODULE_NOT_FOUND	Old package references	Update imports to @claude-flow/*
Config not found	Path change	Rename to claude-flow.config.json
Memory backend error	Schema change	Run migrate run to convert
Hooks not working	New hook names	Use new hook commands
Agent spawn fails	Type name changes	Check agent list for new types