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

Checkpoint: File edits

rUvaa3d3c18b5be
diff --git a/v3/@claude-flow/embeddings/README.md b/v3/@claude-flow/embeddings/README.md
index 4f92212f67..d045c058cf 100644
--- a/v3/@claude-flow/embeddings/README.md
+++ b/v3/@claude-flow/embeddings/README.md
@@ -401,6 +401,245 @@ const queryResult = await embeddings.embed('Search query');
const results = await index.search(new Float32Array(queryResult.embedding), 5);
```
+## Document Chunking
+
+Split long documents into overlapping chunks for embedding:
+
+```typescript
+import { chunkText, estimateTokens, reconstructFromChunks } from '@claude-flow/embeddings';
+
+// Chunk by sentence (default)
+const result = chunkText(longDocument, {
+ maxChunkSize: 512,
+ overlap: 50,
+ strategy: 'sentence', // 'character' | 'sentence' | 'paragraph' | 'token'
+ minChunkSize: 100,
+});
+
+console.log('Chunks:', result.totalChunks);
+result.chunks.forEach((chunk, i) => {
+ console.log(`Chunk ${i}: ${chunk.length} chars, ~${chunk.tokenCount} tokens`);
+});
+
+// Estimate tokens
+const tokens = estimateTokens('Hello world'); // ~3 tokens
+
+// Reconstruct (approximate)
+const reconstructed = reconstructFromChunks(result.chunks);
+```
+
+## Normalization
+
+Normalize embeddings for consistent similarity computation:
+
+```typescript
+import {
+ l2Normalize, // Unit vector (Euclidean norm = 1)
+ l1Normalize, // Manhattan norm = 1
+ minMaxNormalize, // Values in [0, 1]
+ zScoreNormalize, // Mean 0, std 1
+ normalize, // Generic with type option
+ l2Norm,
+ isNormalized,
+} from '@claude-flow/embeddings';
+
+const embedding = new Float32Array([3, 4, 0]);
+
+// L2 normalize (most common for cosine similarity)
+const l2 = l2Normalize(embedding); // [0.6, 0.8, 0]
+console.log('L2 norm:', l2Norm(l2)); // 1.0
+
+// Check if already normalized
+console.log(isNormalized(l2)); // true
+console.log(isNormalized(embedding)); // false
+
+// Generic normalize with type
+const normalized = normalize(embedding, { type: 'l2' });
+```
+
+## Hyperbolic Embeddings (PoincarΓ© Ball)
+
+Transform embeddings to hyperbolic space for better hierarchical representation:
+
+```typescript
+import {
+ euclideanToPoincare,
+ poincareToEuclidean,
+ hyperbolicDistance,
+ mobiusAdd,
+ isInPoincareBall,
+ batchEuclideanToPoincare,
+ hyperbolicCentroid,
+} from '@claude-flow/embeddings';
+
+// Convert Euclidean embedding to PoincarΓ© ball
+const euclidean = new Float32Array([0.5, 0.3, 0.2]);
+const poincare = euclideanToPoincare(euclidean);
+
+// Check if point is in the ball
+console.log(isInPoincareBall(poincare)); // true
+
+// Round-trip conversion
+const back = poincareToEuclidean(poincare);
+
+// Hyperbolic distance (geodesic in PoincarΓ© ball)
+const a = euclideanToPoincare(new Float32Array([0.1, 0.2, 0.1]));
+const b = euclideanToPoincare(new Float32Array([0.3, 0.1, 0.2]));
+const dist = hyperbolicDistance(a, b);
+
+// MΓΆbius addition (hyperbolic "plus")
+const sum = mobiusAdd(a, b);
+
+// Batch conversion
+const embeddings = [vec1, vec2, vec3];
+const hyperbolic = batchEuclideanToPoincare(embeddings);
+
+// Hyperbolic centroid (FrΓ©chet mean)
+const centroid = hyperbolicCentroid(hyperbolic);
+```
+
+### Why Hyperbolic?
+
+Hyperbolic space has natural properties for representing hierarchical data:
+- **Exponential growth** - Tree-like structures fit naturally
+- **Better hierarchy** - Parent-child relationships preserved
+- **Lower distortion** - Taxonomies represented with less error
+
+## Neural Substrate Integration
+
+Access agentic-flow's neural features for advanced embedding operations:
+
+```typescript
+import {
+ NeuralEmbeddingService,
+ createNeuralService,
+ isNeuralAvailable,
+ listEmbeddingModels,
+ downloadEmbeddingModel,
+} from '@claude-flow/embeddings';
+
+// Check if neural features are available
+const available = await isNeuralAvailable();
+
+// Create neural service
+const neural = createNeuralService({ dimension: 384 });
+await neural.init();
+
+if (neural.isAvailable()) {
+ // Semantic drift detection
+ await neural.setDriftBaseline('Initial context about the topic');
+ const drift = await neural.detectDrift('New input to check for drift');
+ console.log('Drift:', drift?.trend); // 'stable' | 'drifting' | 'accelerating'
+
+ // Memory with interference detection
+ const stored = await neural.storeMemory('mem-1', 'Important information');
+ console.log('Interference:', stored?.interference);
+
+ // Recall by similarity
+ const memories = await neural.recallMemories('query', 5);
+
+ // Swarm coordination
+ await neural.addSwarmAgent('agent-1', 'researcher');
+ const coordination = await neural.coordinateSwarm('Analyze this task');
+
+ // Coherence checking
+ await neural.calibrateCoherence(['good output 1', 'good output 2']);
+ const coherence = await neural.checkCoherence('Output to check');
+
+ // Health status
+ const health = neural.health();
+ console.log('Memory count:', health?.memoryCount);
+}
+
+// List available ONNX models
+const models = await listEmbeddingModels();
+console.log(models);
+// [{ id: 'all-MiniLM-L6-v2', dimension: 384, size: '23MB', ... }]
+
+// Download model
+const path = await downloadEmbeddingModel('all-MiniLM-L6-v2', '.models');
+```
+
+## Persistent Disk Cache
+
+SQLite-backed persistent cache for embeddings:
+
+```typescript
+import { PersistentEmbeddingCache, isPersistentCacheAvailable } from '@claude-flow/embeddings';
+
+// Check if SQLite is available
+const hasSQLite = await isPersistentCacheAvailable();
+
+// Create persistent cache
+const cache = new PersistentEmbeddingCache({
+ dbPath: './embeddings.db', // SQLite database path
+ maxSize: 10000, // Max entries before LRU eviction
+ ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 day TTL
+});
+
+// Initialize
+await cache.init();
+
+// Store embedding
+await cache.set('my text', new Float32Array([0.1, 0.2, 0.3]));
+
+// Retrieve
+const embedding = await cache.get('my text');
+
+// Get stats
+const stats = await cache.getStats();
+console.log('Cache stats:', {
+ size: stats.totalEntries,
+ hitRate: stats.hitRate,
+ avgLatency: stats.avgLatencyMs,
+});
+
+// Close when done
+await cache.close();
+```
+
+### Enable in Embedding Service
+
+```typescript
+const service = createEmbeddingService({
+ provider: 'openai',
+ apiKey: process.env.OPENAI_API_KEY!,
+ persistentCache: {
+ enabled: true,
+ dbPath: './cache/embeddings.db',
+ maxSize: 50000,
+ ttlMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+ },
+ normalization: 'l2', // Auto-normalize embeddings
+});
+```
+
+## CLI Commands (New)
+
+```bash
+# Document chunking
+claude-flow embeddings chunk document.txt --strategy sentence --max-size 512
+
+# Normalize embedding file
+claude-flow embeddings normalize embeddings.json --type l2 -o normalized.json
+
+# Convert to hyperbolic
+claude-flow embeddings hyperbolic embeddings.json -o poincare.json
+
+# Neural operations
+claude-flow embeddings neural drift --baseline "context" --input "check this"
+claude-flow embeddings neural store --id mem-1 --content "data"
+claude-flow embeddings neural recall "query" --top-k 5
+
+# List/download models
+claude-flow embeddings models list
+claude-flow embeddings models download all-MiniLM-L6-v2
+
+# Cache management
+claude-flow embeddings cache stats
+claude-flow embeddings cache clear --older-than 7d
+```
+
## Related Packages
- [@claude-flow/memory](../memory) - HNSW indexing and vector storage
diff --git a/v3/implementation/adrs/README.md b/v3/implementation/adrs/README.md
index 8ade549b26..73a7fd1118 100644
--- a/v3/implementation/adrs/README.md
+++ b/v3/implementation/adrs/README.md
@@ -250,3 +250,176 @@ claude-flow shell # Enter REPL
> agent spawn coder
> memory search "patterns"
```
+
+---
+
+## agentic-flow vs claude-flow Feature Comparison
+
+### Feature Matrix
+
+| Feature | agentic-flow | claude-flow | Integration Value |
+|---------|--------------|-------------|-------------------|
+| **Core Agent System** | | | |
+| Specialized Agents | 66+ | 15 (hierarchical) | 🟑 |
+| Agent Spawning | βœ… | βœ… | - |
+| Agent Pool/Scaling | βœ… | βœ… | - |
+| **Orchestration** | | | |
+| Swarm Coordination | βœ… | βœ… | - |
+| Hive-Mind Consensus | ❌ | βœ… | - |
+| Federation Hub | βœ… | ❌ | πŸ”΄ High |
+| Ephemeral Agents | βœ… | ❌ | πŸ”΄ High |
+| **Transport** | | | |
+| HTTP/SSE | βœ… | βœ… | - |
+| QUIC (UDP) | βœ… | ❌ | πŸ”΄ High |
+| WebSocket | βœ… | βœ… | - |
+| **AI Providers** | | | |
+| Multi-Provider | βœ… | βœ… | - |
+| Model Optimization | βœ… | ❌ | πŸ”΄ High |
+| Provider Fallback | βœ… | ❌ | πŸ”΄ High |
+| Cost Tracking | βœ… | ❌ | 🟑 Medium |
+| Proxy Server | βœ… | ❌ | 🟑 Medium |
+| **Memory/Learning** | | | |
+| ReasoningBank (WASM) | βœ… | ❌ | πŸ”΄ High |
+| Embeddings CLI | βœ… | βœ… | - |
+| HNSW Indexing | βœ… | βœ… | - |
+| Memory Persistence | βœ… | βœ… | - |
+| **DevOps** | | | |
+| Doctor Command | ❌ | βœ… | - |
+| Shell Completions | ❌ | βœ… | - |
+| Smart Errors | ❌ | βœ… | - |
+| Background Workers | βœ… | βœ… | - |
+| Worker Dispatch | βœ… | ❌ | 🟑 Medium |
+| **Security** | | | |
+| Security Scanning | ❌ | βœ… | - |
+| CVE Detection | ❌ | βœ… | - |
+| Claims/RBAC | ❌ | βœ… | - |
+| **Advanced** | | | |
+| Neural Patterns | ❌ | βœ… | - |
+| Self-Learning Hooks | βœ… | βœ… | - |
+| Deployment Mgmt | ❌ | βœ… | - |
+| Plugin System | ❌ | βœ… | - |
+
+### High-Value Integration Opportunities
+
+#### πŸ”΄ Tier 1: Highest Impact (Unique to agentic-flow)
+
+**1. QUIC Transport (50-70% faster)**
+```bash
+# Integration target:
+claude-flow transport quic --port 4433
+claude-flow swarm start --transport quic # 50-70% faster agent comms
+```
+
+**2. Federation Hub (Ephemeral Agents)**
+```bash
+# Integration target:
+claude-flow federation start --port 9443
+claude-flow federation spawn --tenant acme --lifetime 600
+```
+*Value: Agents die but memories persist β†’ learning across agent generations*
+
+**3. Model Optimization (85% cost savings)**
+```bash
+# Integration target:
+claude-flow agent spawn -t coder --optimize --priority cost
+claude-flow providers optimize --task "Build API" --budget 0.01
+```
+
+**4. Provider Fallback (Enterprise resilience)**
+```bash
+# Integration target:
+claude-flow providers fallback configure --primary anthropic --fallback openrouter,onnx
+```
+
+**5. ReasoningBank (WASM Learning Memory)**
+```bash
+# Integration target:
+claude-flow reasoningbank store "pattern" --reasoning "..."
+claude-flow reasoningbank search "authentication patterns"
+```
+*Value: 10-100x faster reasoning pattern storage vs JSON*
+
+#### 🟑 Tier 2: Medium Impact
+
+| Feature | Description | Complexity |
+|---------|-------------|------------|
+| Proxy Server | Use any model with Claude Code via local proxy | 🟑 Medium |
+| Worker Dispatch | More granular worker control | 🟒 Low |
+| Embeddings Management | Better model management | 🟒 Low |
+
+### Integration Roadmap
+
+#### Phase 1: Quick Wins (1 week) β†’ 9.3 β†’ 9.5
+
+| Feature | Effort | Impact | Source |
+|---------|--------|--------|--------|
+| Model Optimization flags | 🟒 Low | πŸ”΄ High | New command |
+| Provider fallback config | 🟒 Low | πŸ”΄ High | New subcommand |
+| Embeddings download/benchmark | 🟒 Low | 🟑 Med | Enhance existing |
+
+```bash
+# After Phase 1:
+claude-flow agent spawn -t coder --optimize --priority cost
+claude-flow providers fallback configure --primary anthropic --fallback openrouter,onnx
+claude-flow embeddings download all-MiniLM-L6-v2
+```
+
+#### Phase 2: Core Integration (2-3 weeks) β†’ 9.5 β†’ 9.7
+
+| Feature | Effort | Impact | Source |
+|---------|--------|--------|--------|
+| Federation Hub | 🟑 Med | πŸ”΄ High | Port from agentic-flow |
+| Ephemeral agents | 🟑 Med | πŸ”΄ High | Part of federation |
+| Proxy server | 🟑 Med | 🟑 Med | Port from agentic-flow |
+| Worker dispatch triggers | 🟒 Low | 🟑 Med | Enhance daemon |
+
+```bash
+# After Phase 2:
+claude-flow federation start --port 9443
+claude-flow federation spawn --lifetime 300 --task "Quick analysis"
+claude-flow proxy start --provider openrouter
+claude-flow daemon dispatch security-audit
+```
+
+#### Phase 3: Advanced (4-6 weeks) β†’ 9.7 β†’ 9.9
+
+| Feature | Effort | Impact | Source |
+|---------|--------|--------|--------|
+| QUIC Transport | πŸ”΄ High | πŸ”΄ High | Port QUIC module |
+| ReasoningBank (WASM) | πŸ”΄ High | πŸ”΄ High | Port + WASM build |
+| 66 Agent configs | 🟑 Med | 🟑 Med | Copy + adapt |
+
+```bash
+# After Phase 3:
+claude-flow swarm start --transport quic # 50-70% faster
+claude-flow reasoningbank store "pattern" --reasoning "..."
+claude-flow agent spawn -t security-analyst # One of 66 types
+```
+
+### Recommended Integration Approach
+
+**Option A: Dependency Approach (Fastest)**
+```json
+// claude-flow/package.json
+{
+ "dependencies": {
+ "agentic-flow": "^2.0.3"
+ }
+}
+```
+
+**Option B: Port Code (More Control)**
+```bash
+# Copy specific modules:
+- agentic-flow/src/transport/quic.ts β†’ claude-flow/src/transport/
+- agentic-flow/src/federation/ β†’ claude-flow/src/federation/
+- agentic-flow/src/reasoningbank/ β†’ claude-flow/src/reasoningbank/
+```
+
+**Option C: Unified Package (Long-term)**
+```bash
+@claude-flow/core # Shared primitives
+@claude-flow/cli # CLI (current)
+@claude-flow/agents # From agentic-flow's 66 agents
+@claude-flow/transport # QUIC + HTTP + WebSocket
+```