Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs: add lightweight modular installation strategy for v3

Claude076e59cb9a9f
diff --git a/docs/v3/AGENTIC-FLOW-INTEGRATION-ANALYSIS.md b/docs/v3/AGENTIC-FLOW-INTEGRATION-ANALYSIS.md
index 13b603dfe5..7e4e676e0f 100644
--- a/docs/v3/AGENTIC-FLOW-INTEGRATION-ANALYSIS.md
+++ b/docs/v3/AGENTIC-FLOW-INTEGRATION-ANALYSIS.md
@@ -1140,6 +1140,365 @@ Nightly β†’ FlashAttention Consolidation + A/B Experiments + Transfer Learning
---
+## 16. Lightweight Installation Strategy
+
+### 16.1 Design Principles
+
+1. **Minimal Core** - Install only essential runtime (~2MB)
+2. **Lazy Loading** - Load features on first use
+3. **Platform Detection** - Auto-select optimal backend
+4. **Progressive Enhancement** - Add capabilities as needed
+
+### 16.2 Core Package (Required)
+
+```bash
+# Minimal install - works on all platforms
+npm install claude-flow@3 --save
+# ~2MB, no native dependencies, pure JavaScript
+```
+
+**Core includes**:
+- CLI interface
+- Basic swarm coordination
+- In-memory storage
+- JavaScript-only runtime
+
+### 16.3 Modular Components (Optional)
+
+```bash
+# Install components as needed
+npx claude-flow install <component>
+
+# Available components:
+npx claude-flow install learning # RL + trajectory tracking
+npx claude-flow install memory # Persistent memory (SQLite/WASM)
+npx claude-flow install attention # Flash/MoE attention mechanisms
+npx claude-flow install transport # QUIC transport layer
+npx claude-flow install neural # Neural pattern training
+npx claude-flow install gnn # GNN query enhancement
+```
+
+### 16.4 Platform-Specific Installation
+
+#### Linux (Fastest)
+```bash
+npm install claude-flow@3
+npx claude-flow install native # NAPI bindings (50-200x faster)
+# Total: ~15MB with native bindings
+```
+
+#### macOS (Apple Silicon + Intel)
+```bash
+npm install claude-flow@3
+npx claude-flow install native # Universal binary
+# Fallback: WASM if Rosetta issues
+```
+
+#### Windows
+```bash
+npm install claude-flow@3
+npx claude-flow install wasm # WASM backend (recommended)
+# Note: NAPI optional but requires build tools
+```
+
+### 16.5 Component Dependency Graph
+
+```
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ CORE (Required) β”‚
+β”‚ CLI, Swarm Basics, In-Memory, JS Runtime (~2MB) β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+ β”‚ β”‚ β”‚
+ β–Ό β–Ό β–Ό
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ memory β”‚ β”‚ learning β”‚ β”‚ attention β”‚
+β”‚ SQLite/WASM β”‚ β”‚ RL + SONA β”‚ β”‚ Flash/MoE β”‚
+β”‚ (~3MB) β”‚ β”‚ (~2MB) β”‚ β”‚ (~1MB) β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚ β”‚ β”‚
+ β”‚ β–Ό β”‚
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+ └───────────▢│ neural β”‚β—€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚ Pattern Train β”‚
+ β”‚ (~2MB) β”‚
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β–Ό
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+ β”‚ gnn β”‚
+ β”‚ Query Refine β”‚
+ β”‚ (~4MB) β”‚
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+### 16.6 Runtime Detection & Fallback
+
+```typescript
+// Automatic runtime selection (zero config)
+const runtimeChain = [
+ 'napi', // Native bindings (fastest)
+ 'wasm', // WebAssembly (portable)
+ 'js' // Pure JavaScript (universal)
+];
+
+// Platform detection
+const platform = {
+ linux: { preferred: 'napi', fallback: 'wasm' },
+ darwin: { preferred: 'napi', fallback: 'wasm' },
+ win32: { preferred: 'wasm', fallback: 'js' } // WASM default on Windows
+};
+```
+
+### 16.7 Feature Flags
+
+```typescript
+// .claude-flow/config.json
+{
+ "core": {
+ "runtime": "auto", // auto | napi | wasm | js
+ "lazyLoad": true, // Load components on first use
+ "maxMemoryMB": 512 // Memory limit for caching
+ },
+ "components": {
+ "memory": "enabled", // enabled | disabled | lazy
+ "learning": "lazy", // Loads when first RL session starts
+ "attention": "lazy",
+ "transport": "disabled", // Explicitly disabled
+ "neural": "lazy",
+ "gnn": "disabled"
+ }
+}
+```
+
+### 16.8 Installation Size Comparison
+
+| Configuration | Size | Platforms | Performance |
+|---------------|------|-----------|-------------|
+| Core Only | ~2MB | All | Baseline |
+| + Memory | ~5MB | All | Persistent storage |
+| + Learning | ~7MB | All | RL capabilities |
+| + Attention | ~8MB | All | Better consensus |
+| Full (JS) | ~15MB | All | Complete features |
+| Full (NAPI) | ~25MB | Linux/Mac | Maximum speed |
+
+### 16.9 Quick Start by Use Case
+
+```bash
+# Minimal CLI usage
+npm install -g claude-flow@3
+
+# Basic swarm coordination
+npm install claude-flow@3
+
+# With persistent memory
+npm install claude-flow@3 && npx claude-flow install memory
+
+# Full learning system
+npm install claude-flow@3 && npx claude-flow install learning memory
+
+# Maximum performance (Linux/Mac)
+npm install claude-flow@3 && npx claude-flow install --all --native
+```
+
+---
+
+## 17. Testing Strategy
+
+### 17.1 Test Pyramid
+
+```
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+ β”‚ E2E (5%) β”‚ Cross-platform smoke tests
+ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+ β”‚Integration β”‚ Component interactions
+ β”‚ (15%) β”‚
+ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+ β”‚ Unit β”‚ Individual functions
+ β”‚ (80%) β”‚
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+### 17.2 Platform Test Matrix
+
+| Test Suite | Linux | macOS Intel | macOS ARM | Windows |
+|------------|-------|-------------|-----------|---------|
+| Core | βœ“ | βœ“ | βœ“ | βœ“ |
+| NAPI bindings | βœ“ | βœ“ | βœ“ | Optional |
+| WASM fallback | βœ“ | βœ“ | βœ“ | βœ“ |
+| Memory (SQLite) | βœ“ | βœ“ | βœ“ | βœ“ |
+| Learning (RL) | βœ“ | βœ“ | βœ“ | βœ“ |
+
+### 17.3 Benchmark Suite
+
+```bash
+# Run performance benchmarks
+npx claude-flow benchmark
+
+# Specific component benchmarks
+npx claude-flow benchmark memory --iterations 1000
+npx claude-flow benchmark learning --episodes 100
+npx claude-flow benchmark attention --batch-size 32
+
+# Compare runtimes
+npx claude-flow benchmark --runtime napi
+npx claude-flow benchmark --runtime wasm
+npx claude-flow benchmark --runtime js
+```
+
+### 17.4 Regression Detection
+
+```typescript
+// Performance thresholds (fail if exceeded)
+const thresholds = {
+ 'memory.store': { p95: 10, unit: 'ms' },
+ 'memory.search': { p95: 50, unit: 'ms' },
+ 'learning.predict': { p95: 5, unit: 'ms' },
+ 'attention.forward': { p95: 2, unit: 'ms' },
+ 'startup.cold': { max: 500, unit: 'ms' },
+ 'startup.warm': { max: 100, unit: 'ms' }
+};
+```
+
+---
+
+## 18. Error Handling & Recovery
+
+### 18.1 Graceful Degradation Chain
+
+```
+NAPI fails β†’ WASM fallback β†’ JS fallback β†’ Error with guidance
+ β”‚ β”‚ β”‚
+ β–Ό β–Ό β–Ό
+ Log warning Log warning Log error
+ Continue Continue Suggest fix
+```
+
+### 18.2 Component Failure Isolation
+
+```typescript
+// Each component fails independently
+class ComponentManager {
+ async loadComponent(name: string): Promise<Component> {
+ try {
+ return await this.loadNative(name);
+ } catch (e) {
+ console.warn(`Native ${name} unavailable, using WASM`);
+ try {
+ return await this.loadWasm(name);
+ } catch (e) {
+ console.warn(`WASM ${name} unavailable, using JS`);
+ return await this.loadJs(name);
+ }
+ }
+ }
+}
+```
+
+### 18.3 Learning Recovery
+
+```typescript
+// Automatic checkpoint and recovery
+const learningConfig = {
+ checkpointInterval: 100, // Save every 100 episodes
+ maxRetries: 3, // Retry failed operations
+ rollbackOnCorruption: true, // Auto-rollback if DB corrupted
+ isolateFailures: true // One session failure doesn't affect others
+};
+```
+
+---
+
+## 19. Monitoring & Observability
+
+### 19.1 Built-in Metrics
+
+```bash
+# View real-time metrics
+npx claude-flow metrics
+
+# Export metrics for external systems
+npx claude-flow metrics --format prometheus
+npx claude-flow metrics --format json > metrics.json
+```
+
+### 19.2 Key Metrics
+
+| Metric | Description | Alert Threshold |
+|--------|-------------|-----------------|
+| `cf_startup_ms` | Cold start time | > 1000ms |
+| `cf_memory_mb` | Memory usage | > 80% of limit |
+| `cf_component_load_ms` | Component load time | > 500ms |
+| `cf_learning_episodes` | Total episodes | - |
+| `cf_learning_success_rate` | Success percentage | < 50% |
+| `cf_storage_bytes` | Disk usage | > 1GB |
+
+### 19.3 Logging Levels
+
+```typescript
+// .claude-flow/config.json
+{
+ "logging": {
+ "level": "info", // error | warn | info | debug | trace
+ "file": ".claude-flow/logs/claude-flow.log",
+ "maxSize": "10MB",
+ "maxFiles": 5,
+ "components": {
+ "memory": "warn", // Per-component overrides
+ "learning": "debug"
+ }
+ }
+}
+```
+
+---
+
+## 20. Security Considerations
+
+### 20.1 Dependency Audit
+
+```bash
+# Audit before install
+npm audit claude-flow@3
+
+# Verify checksums
+npx claude-flow verify --checksums
+```
+
+### 20.2 Data Privacy
+
+| Data Type | Storage | Encryption | Retention |
+|-----------|---------|------------|-----------|
+| Patterns | Local SQLite | Optional | Configurable |
+| Trajectories | Local SQLite | Optional | 90 days default |
+| Episodes | Local SQLite | Optional | 90 days default |
+| Metrics | Local JSON | No | 30 days default |
+
+### 20.3 MCP Tool Access Control
+
+```typescript
+// .claude-flow/config.json
+{
+ "security": {
+ "mcpToolAllowlist": [
+ "swarm_*",
+ "memory_*",
+ "learning_*"
+ ],
+ "mcpToolDenylist": [
+ "admin_*"
+ ],
+ "requireConfirmation": [
+ "learning_transfer",
+ "memory_delete"
+ ]
+ }
+}
+```
+
+---
+
*Deep review completed: 2026-01-03*
*agentic-flow version analyzed: 2.0.1-alpha.50*
*agentdb version analyzed: 2.0.0-alpha.3.1*
diff --git a/docs/v3/LEARNING-OPTIMIZED-PLAN.md b/docs/v3/LEARNING-OPTIMIZED-PLAN.md
index 5e35363213..e9570fc84c 100644
--- a/docs/v3/LEARNING-OPTIMIZED-PLAN.md
+++ b/docs/v3/LEARNING-OPTIMIZED-PLAN.md
@@ -676,6 +676,223 @@ export const memoryOptimizations = {
---
+## 9. Modular Learning Installation
+
+### 9.1 Learning Component Tiers
+
+```bash
+# Tier 1: Basic Learning (Minimal)
+npx claude-flow install learning:basic
+# Includes: Pattern storage, skill lookup, basic RL (Q-Learning, SARSA)
+# Size: ~1MB | Platforms: All
+
+# Tier 2: Standard Learning (Recommended)
+npx claude-flow install learning
+# Includes: Tier 1 + 5 more RL algorithms, reflexion memory, trajectory tracking
+# Size: ~2MB | Platforms: All
+
+# Tier 3: Advanced Learning (Full)
+npx claude-flow install learning:advanced
+# Includes: Tier 2 + causal graphs, nightly learner, FlashAttention
+# Size: ~4MB | Platforms: All (NAPI for FlashAttention speedup)
+```
+
+### 9.2 Learning Feature Matrix
+
+| Feature | Basic | Standard | Advanced |
+|---------|-------|----------|----------|
+| Pattern Storage | βœ“ | βœ“ | βœ“ |
+| Skill Library | βœ“ | βœ“ | βœ“ |
+| Q-Learning | βœ“ | βœ“ | βœ“ |
+| SARSA | βœ“ | βœ“ | βœ“ |
+| DQN | - | βœ“ | βœ“ |
+| PPO | - | βœ“ | βœ“ |
+| Actor-Critic | - | βœ“ | βœ“ |
+| Decision Transformer | - | βœ“ | βœ“ |
+| MCTS | - | βœ“ | βœ“ |
+| Reflexion Memory | - | βœ“ | βœ“ |
+| Trajectory Tracking | - | βœ“ | βœ“ |
+| Causal Memory Graph | - | - | βœ“ |
+| Nightly Learner | - | - | βœ“ |
+| FlashAttention | - | - | βœ“ |
+| A/B Experiments | - | - | βœ“ |
+| Transfer Learning | - | - | βœ“ |
+
+### 9.3 Platform-Optimized Learning
+
+```bash
+# Linux: Maximum performance
+npx claude-flow install learning:advanced --native
+# Uses NAPI for FlashAttention (4x faster, 75% less memory)
+
+# macOS: Universal binary
+npx claude-flow install learning:advanced
+# Auto-detects ARM vs Intel, uses native when possible
+
+# Windows: WASM-optimized
+npx claude-flow install learning:advanced --wasm
+# Full features via WebAssembly, no build tools required
+```
+
+### 9.4 Lazy Loading Configuration
+
+```typescript
+// .claude-flow/config.json
+{
+ "learning": {
+ "tier": "standard", // basic | standard | advanced
+ "lazyLoad": {
+ "algorithms": true, // Load RL algorithms on first use
+ "causal": true, // Load causal graph when queried
+ "nightly": true // Load nightly learner at scheduled time
+ },
+ "preload": [
+ "pattern_storage", // Always preload for fast pattern lookup
+ "skill_library" // Always preload for skill suggestions
+ ]
+ }
+}
+```
+
+### 9.5 Memory-Constrained Environments
+
+```typescript
+// Lightweight mode for constrained environments
+{
+ "learning": {
+ "tier": "basic",
+ "memoryLimit": "128MB",
+ "episodeBuffer": 100, // Smaller buffer
+ "maxPatterns": 1000, // Limit stored patterns
+ "pruneOnLimit": true, // Auto-prune old patterns
+ "disableEmbeddings": false // Keep embeddings for search
+ }
+}
+```
+
+---
+
+## 10. Quick Start Recipes
+
+### 10.1 Minimal Learning Setup
+
+```bash
+# Install core + basic learning
+npm install claude-flow@3
+npx claude-flow install learning:basic
+
+# Start using immediately
+npx claude-flow learning start --algorithm q-learning
+```
+
+### 10.2 Recommended Learning Setup
+
+```bash
+# Install with persistent memory
+npm install claude-flow@3
+npx claude-flow install memory learning
+
+# Initialize with sensible defaults
+npx claude-flow init --learning
+```
+
+### 10.3 Production Learning Setup
+
+```bash
+# Full installation with native bindings
+npm install claude-flow@3
+npx claude-flow install --all --native
+
+# Configure for production
+cat > .claude-flow/config.json << 'EOF'
+{
+ "learning": {
+ "tier": "advanced",
+ "nightly": {
+ "enabled": true,
+ "schedule": "0 2 * * *"
+ }
+ },
+ "monitoring": {
+ "enabled": true,
+ "exportMetrics": true
+ }
+}
+EOF
+```
+
+### 10.4 CI/CD Learning Setup
+
+```bash
+# Minimal for CI (no native deps)
+npm install claude-flow@3
+npx claude-flow install learning:basic --wasm
+
+# Run tests with learning
+npx claude-flow test --with-learning
+```
+
+---
+
+## 11. Upgrade Paths
+
+### 11.1 Tier Upgrades
+
+```bash
+# Upgrade from basic to standard
+npx claude-flow install learning --upgrade
+
+# Upgrade from standard to advanced
+npx claude-flow install learning:advanced --upgrade
+
+# Downgrade (preserves data)
+npx claude-flow install learning:basic --downgrade
+```
+
+### 11.2 Data Migration
+
+```bash
+# Export learning data before major upgrade
+npx claude-flow learning export --output learning-backup.json
+
+# Import after upgrade
+npx claude-flow learning import --input learning-backup.json
+
+# Verify data integrity
+npx claude-flow learning verify
+```
+
+---
+
+## 12. Troubleshooting
+
+### 12.1 Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Slow startup | Too many preloaded features | Enable lazy loading |
+| High memory | Large episode buffer | Reduce `episodeBuffer` |
+| NAPI errors | Missing build tools | Use `--wasm` flag |
+| Windows failures | Native dep issues | Use `--wasm` explicitly |
+
+### 12.2 Diagnostic Commands
+
+```bash
+# Check learning system status
+npx claude-flow learning status
+
+# View component load times
+npx claude-flow learning diagnostics
+
+# Test RL algorithms
+npx claude-flow learning test --algorithm ppo
+
+# Verify installation
+npx claude-flow verify --component learning
+```
+
+---
+
*Optimized Learning Plan - v3.0*
*Generated: 2026-01-03*