π 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
Checkpoint: File edits
rUvaa3d3c18b5be
diff --git a/v3/@claude-flow/embeddings/README.md b/v3/@claude-flow/embeddings/README.mdindex 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 storagediff --git a/v3/implementation/adrs/README.md b/v3/implementation/adrs/README.mdindex 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+```