🔄 Migration Guide (V2 → V3)

/help--resources/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

cp -r ./data ./data-backup-v2
cp -r ./.ruflo ./.ruflo-backup-v2

npx ruflo@latest migrate status

npx ruflo@latest migrate run --dry-run

npx ruflo@latest migrate run --from v2

npx ruflo@latest migrate verify

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

npx ruflo@latest migrate rollback --list

npx ruflo@latest migrate rollback --to v2

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

🔧 Troubleshooting

📚 Documentation