π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdindex 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.mdindex 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**Packages: [email protected], [email protected]**Generated: 2026-01-03*