🌊 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 edit:
rUvb083da48cbf7
diff --git a/v3/@claude-flow/memory/src/agentdb-backend.test.ts b/v3/@claude-flow/memory/src/agentdb-backend.test.tsnew file mode 100644index 0000000000..181d5c9e6b--- /dev/null+++ b/v3/@claude-flow/memory/src/agentdb-backend.test.ts@@ -0,0 +1,338 @@+/**+ * AgentDB Backend Tests+ *+ * Tests for [email protected] integration with V3 memory system+ */++import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { AgentDBBackend } from './agentdb-backend.js';+import { createDefaultEntry } from './types.js';++describe('AgentDBBackend', () => {+ let backend: AgentDBBackend;++ beforeEach(async () => {+ backend = new AgentDBBackend({+ dbPath: ':memory:',+ namespace: 'test',+ vectorDimension: 384,+ });+ await backend.initialize();+ });++ afterEach(async () => {+ await backend.shutdown();+ });++ describe('Initialization', () => {+ it('should initialize successfully', async () => {+ expect(backend).toBeDefined();+ });++ it('should handle missing agentdb gracefully', async () => {+ const fallbackBackend = new AgentDBBackend();+ await fallbackBackend.initialize();++ // Should still work with in-memory fallback+ expect(fallbackBackend).toBeDefined();++ await fallbackBackend.shutdown();+ });+ });++ describe('Basic CRUD Operations', () => {+ it('should store and retrieve entries', async () => {+ const entry = createDefaultEntry({+ key: 'test-key',+ content: 'Test content',+ type: 'episodic',+ });++ await backend.store(entry);++ const retrieved = await backend.get(entry.id);+ expect(retrieved).toBeDefined();+ expect(retrieved?.content).toBe('Test content');+ });++ it('should get entry by key', async () => {+ const entry = createDefaultEntry({+ key: 'unique-key',+ content: 'Unique content',+ namespace: 'test',+ });++ await backend.store(entry);++ const retrieved = await backend.getByKey('test', 'unique-key');+ expect(retrieved).toBeDefined();+ expect(retrieved?.content).toBe('Unique content');+ });++ it('should update entries', async () => {+ const entry = createDefaultEntry({+ key: 'update-test',+ content: 'Original content',+ });++ await backend.store(entry);++ const updated = await backend.update(entry.id, {+ content: 'Updated content',+ });++ expect(updated?.content).toBe('Updated content');+ expect(updated?.version).toBe(entry.version + 1);+ });++ it('should delete entries', async () => {+ const entry = createDefaultEntry({+ key: 'delete-test',+ content: 'To be deleted',+ });++ await backend.store(entry);++ const deleted = await backend.delete(entry.id);+ expect(deleted).toBe(true);++ const retrieved = await backend.get(entry.id);+ expect(retrieved).toBeNull();+ });+ });++ describe('Query Operations', () => {+ beforeEach(async () => {+ // Insert test data+ await backend.store(+ createDefaultEntry({+ key: 'entry-1',+ content: 'First entry',+ namespace: 'test',+ tags: ['tag1', 'tag2'],+ })+ );++ await backend.store(+ createDefaultEntry({+ key: 'entry-2',+ content: 'Second entry',+ namespace: 'test',+ tags: ['tag2', 'tag3'],+ })+ );++ await backend.store(+ createDefaultEntry({+ key: 'entry-3',+ content: 'Third entry',+ namespace: 'other',+ tags: ['tag1'],+ })+ );+ });++ it('should query by namespace', async () => {+ const results = await backend.query({+ type: 'hybrid',+ namespace: 'test',+ limit: 10,+ });++ expect(results.length).toBe(2);+ });++ it('should query by exact key', async () => {+ const results = await backend.query({+ type: 'exact',+ namespace: 'test',+ key: 'entry-1',+ limit: 10,+ });++ expect(results.length).toBe(1);+ expect(results[0].content).toBe('First entry');+ });++ it('should query by prefix', async () => {+ const results = await backend.query({+ type: 'prefix',+ keyPrefix: 'entry-',+ limit: 10,+ });++ expect(results.length).toBeGreaterThanOrEqual(2);+ });++ it('should query by tags', async () => {+ const results = await backend.query({+ type: 'tag',+ tags: ['tag2'],+ limit: 10,+ });++ expect(results.length).toBe(2);+ });+ });++ describe('Vector Search', () => {+ it('should perform brute-force search when agentdb unavailable', async () => {+ const entry = createDefaultEntry({+ key: 'vector-test',+ content: 'Vector content',+ });++ // Create a fake embedding+ entry.embedding = new Float32Array([0.1, 0.2, 0.3, 0.4]);++ await backend.store(entry);++ const queryEmbedding = new Float32Array([0.1, 0.2, 0.3, 0.4]);++ const results = await backend.search(queryEmbedding, { k: 5 });++ expect(results.length).toBeGreaterThan(0);+ expect(results[0].entry.id).toBe(entry.id);+ });++ it('should handle semantic queries', async () => {+ const entry = createDefaultEntry({+ key: 'semantic-test',+ content: 'Semantic content',+ });++ entry.embedding = new Float32Array([0.5, 0.5, 0.5, 0.5]);++ await backend.store(entry);++ const results = await backend.query({+ type: 'semantic',+ embedding: new Float32Array([0.5, 0.5, 0.5, 0.5]),+ limit: 5,+ });++ expect(results.length).toBeGreaterThan(0);+ });+ });++ describe('Bulk Operations', () => {+ it('should bulk insert entries', async () => {+ const entries = [+ createDefaultEntry({ key: 'bulk-1', content: 'Bulk 1' }),+ createDefaultEntry({ key: 'bulk-2', content: 'Bulk 2' }),+ createDefaultEntry({ key: 'bulk-3', content: 'Bulk 3' }),+ ];++ await backend.bulkInsert(entries);++ const count = await backend.count();+ expect(count).toBeGreaterThanOrEqual(3);+ });++ it('should bulk delete entries', async () => {+ const entries = [+ createDefaultEntry({ key: 'delete-1', content: 'Delete 1' }),+ createDefaultEntry({ key: 'delete-2', content: 'Delete 2' }),+ ];++ await backend.bulkInsert(entries);++ const ids = entries.map((e) => e.id);+ const deleted = await backend.bulkDelete(ids);++ expect(deleted).toBe(2);+ });+ });++ describe('Statistics and Health', () => {+ it('should provide backend statistics', async () => {+ await backend.store(+ createDefaultEntry({ key: 'stats-test', content: 'Stats content' })+ );++ const stats = await backend.getStats();++ expect(stats.totalEntries).toBeGreaterThan(0);+ expect(stats.avgQueryTime).toBeGreaterThanOrEqual(0);+ expect(stats.memoryUsage).toBeGreaterThan(0);+ });++ it('should perform health checks', async () => {+ const health = await backend.healthCheck();++ expect(health.status).toBeDefined();+ expect(['healthy', 'degraded', 'unhealthy']).toContain(health.status);+ expect(health.components).toBeDefined();+ expect(health.components.storage).toBeDefined();+ expect(health.components.index).toBeDefined();+ expect(health.components.cache).toBeDefined();+ });+ });++ describe('Namespace Operations', () => {+ beforeEach(async () => {+ await backend.store(+ createDefaultEntry({+ key: 'ns1-entry',+ content: 'NS1',+ namespace: 'namespace1',+ })+ );++ await backend.store(+ createDefaultEntry({+ key: 'ns2-entry',+ content: 'NS2',+ namespace: 'namespace2',+ })+ );+ });++ it('should list namespaces', async () => {+ const namespaces = await backend.listNamespaces();++ expect(namespaces).toContain('namespace1');+ expect(namespaces).toContain('namespace2');+ });++ it('should count entries by namespace', async () => {+ const count = await backend.count('namespace1');+ expect(count).toBe(1);+ });++ it('should clear namespace', async () => {+ const cleared = await backend.clearNamespace('namespace1');+ expect(cleared).toBe(1);++ const count = await backend.count('namespace1');+ expect(count).toBe(0);+ });+ });++ describe('Graceful Degradation', () => {+ it('should work without agentdb package', async () => {+ const fallbackBackend = new AgentDBBackend({+ dbPath: ':memory:',+ });++ await fallbackBackend.initialize();++ const entry = createDefaultEntry({+ key: 'fallback-test',+ content: 'Fallback content',+ });++ await fallbackBackend.store(entry);+ const retrieved = await fallbackBackend.get(entry.id);++ expect(retrieved).toBeDefined();+ expect(retrieved?.content).toBe('Fallback content');++ await fallbackBackend.shutdown();+ });++ it('should indicate availability status', () => {+ expect(typeof backend.isAvailable()).toBe('boolean');+ });+ });+});diff --git a/v3/@claude-flow/performance/ATTENTION.md b/v3/@claude-flow/performance/ATTENTION.mdnew file mode 100644index 0000000000..bce1cee263--- /dev/null+++ b/v3/@claude-flow/performance/ATTENTION.md@@ -0,0 +1,277 @@+# Flash Attention Integration++Integration of `@ruvector/attention` Flash Attention capabilities into the V3 performance module.++## Overview++This module provides high-performance attention mechanisms optimized for V3's 2.49x-7.47x speedup targets. Flash Attention reduces memory usage by ~50% while achieving significant performance improvements through block-wise computation.++## Features++- **Flash Attention Optimizer**: Memory-efficient attention with automatic runtime selection (NAPI/WASM/JS)+- **Comprehensive Benchmarking**: Validate performance against V3 targets+- **Memory Profiling**: Track memory usage and reduction metrics+- **Performance Metrics**: Continuous tracking of speedup and efficiency++## Installation++The `@ruvector/attention` package is already installed as a dependency:++```bash+npm install @ruvector/attention@latest+```++## Quick Start++### Basic Usage++```typescript+import { createFlashAttentionOptimizer } from '@claude-flow/performance';++// Create optimizer+const optimizer = createFlashAttentionOptimizer(512, 64);++// Prepare input+const input = {+ query: new Float32Array(512).fill(1.0),+ keys: Array.from({ length: 100 }, () => new Float32Array(512).fill(1.0)),+ values: Array.from({ length: 100 }, () => new Float32Array(512).fill(1.0)),+};++// Run optimized attention+const output = await optimizer.optimize(input);+console.log(`Execution time: ${output.executionTimeMs}ms`);+console.log(`Runtime: ${output.runtime}`); // 'napi', 'wasm', or 'js'+```++### Performance Benchmarking++```typescript+import { quickBenchmark } from '@claude-flow/performance';++// Quick benchmark+const result = await quickBenchmark(512);+console.log(`Speedup: ${result.speedup.toFixed(2)}x`);+console.log(`Meets target: ${result.meetsTarget ? 'YES' : 'NO'}`);+```++### V3 Target Validation++```typescript+import { quickValidation } from '@claude-flow/performance';++// Validate V3 performance targets (2.49x-7.47x)+const isValid = await quickValidation();+// Prints detailed validation report+```++### Comprehensive Benchmark Suite++```typescript+import { runAndDisplaySuite } from '@claude-flow/performance';++// Run full benchmark suite across multiple dimensions+const suite = await runAndDisplaySuite();+// Prints detailed report with all benchmarks+```++## API Reference++### FlashAttentionOptimizer++Main class for optimizing attention computations.++#### Constructor++```typescript+new FlashAttentionOptimizer(dim?: number, blockSize?: number)+```++- `dim`: Vector dimension (default: 512)+- `blockSize`: Flash Attention block size (default: 64)++#### Methods++##### optimize(input: AttentionInput): Promise<AttentionOutput>++Optimize attention computation using Flash Attention.++```typescript+const output = await optimizer.optimize({+ query: Float32Array,+ keys: Float32Array[],+ values: Float32Array[],+});+```++##### benchmark(): Promise<BenchmarkResult>++Run comprehensive benchmark comparing Flash Attention vs baseline.++```typescript+const result = await optimizer.benchmark();+console.log(result.speedup); // e.g., 4.23x+```++##### getSpeedup(): number++Get current average speedup from accumulated metrics.++```typescript+const speedup = optimizer.getSpeedup();+```++##### getMetrics(): PerformanceMetrics++Get detailed performance metrics.++```typescript+const metrics = optimizer.getMetrics();+console.log(metrics.averageSpeedup);+console.log(metrics.peakSpeedup);+console.log(metrics.successRate);+```++### AttentionBenchmarkRunner++Comprehensive benchmark suite runner.++#### Methods++##### runComprehensiveSuite(): Promise<SuiteResult>++Run benchmarks across multiple dimensions (128, 256, 512, 768, 1024).++```typescript+const runner = new AttentionBenchmarkRunner();+const suite = await runner.runComprehensiveSuite();+```++##### runComparison(dim, numKeys, iterations): Promise<ComparisonBenchmark>++Run single benchmark comparing Flash vs baseline.++```typescript+const result = await runner.runComparison(512, 100, 1000);+```++##### runMemoryProfile(dimensions): Promise<MemoryProfile[]>++Profile memory usage across different dimensions.++```typescript+const profiles = await runner.runMemoryProfile([256, 512, 1024]);+```++##### validateV3Targets(): Promise<ValidationResult>++Validate against V3 performance targets (2.49x-7.47x).++```typescript+const validation = await runner.validateV3Targets();+console.log(validation.meetsMinimum); // true if ≥2.49x+```++## Performance Targets++The V3 module targets the following Flash Attention performance improvements:++- **Minimum Speedup**: 2.49x+- **Maximum Speedup**: 7.47x+- **Memory Reduction**: ~50%+- **Target Use Cases**:+ - Small (128D): Mobile/edge devices+ - Medium (256D): Standard applications+ - Large (512D): High-performance scenarios+ - XL (768D): Transformer models+ - XXL (1024D): Large language models++## Examples++See `/src/examples/flash-attention-demo.ts` for comprehensive examples:++```bash+# Run all examples+npx tsx v3/@claude-flow/performance/src/examples/flash-attention-demo.ts+```++## Technical Details++### Runtime Selection++The optimizer automatically selects the best available runtime:++1. **NAPI** (Native): Best performance, requires native bindings+2. **WebAssembly**: Good performance, works in browser and Node.js+3. **JavaScript**: Fallback, pure JS implementation++### Memory Efficiency++Flash Attention achieves memory efficiency through:++- Block-wise computation (default block size: 64)+- Reduced intermediate storage+- Optimized memory access patterns++### Benchmark Methodology++Benchmarks measure:++- **Average execution time** over multiple iterations+- **Operations per second**+- **Memory usage** before/after operations+- **Speedup ratio** vs baseline attention++## Integration with V3 Metrics Dashboard++Performance metrics are automatically exported for the V3 metrics dashboard:++```typescript+import { FlashAttentionOptimizer } from '@claude-flow/performance';++const optimizer = new FlashAttentionOptimizer();+// ... run operations ...++// Export metrics for dashboard+const metrics = optimizer.getMetrics();+// Can be integrated with hooks metrics system+```++## Troubleshooting++### Low Speedup (<2.49x)++- Increase `dim` parameter (larger dimensions benefit more)+- Increase `numKeys` (more keys = more benefit)+- Check if NAPI runtime is available (native bindings)+- Ensure sufficient memory for optimal performance++### Memory Usage++- Reduce `blockSize` for lower memory footprint+- Use smaller dimensions for memory-constrained environments+- Monitor with `getMetrics().totalMemorySavedBytes`++### Platform Compatibility++The package includes native bindings for:++- Windows (x64, ARM64)+- macOS (x64, ARM64)+- Linux (x64, ARM64)++Falls back to WebAssembly or JavaScript if native bindings unavailable.++## Contributing++When adding new attention mechanisms or optimizations:++1. Add implementation to `attention-integration.ts`+2. Add benchmarks to `attention-benchmarks.ts`+3. Update exports in `index.ts`+4. Add examples to `examples/flash-attention-demo.ts`+5. Update this README++## License++MIT OR Apache-2.0 (follows @ruvector/attention license)diff --git a/v3/@claude-flow/performance/src/attention-integration.ts b/v3/@claude-flow/performance/src/attention-integration.tsindex 7891cefdf5..92357fa9aa 100644--- a/v3/@claude-flow/performance/src/attention-integration.ts+++ b/v3/@claude-flow/performance/src/attention-integration.ts@@ -240,8 +240,7 @@ export class FlashAttentionOptimizer {private detectRuntime(): 'napi' | 'wasm' | 'js' {// Check if NAPI bindings are availabletry {- // @ts-expect-error - Checking for NAPI runtime- if (process.versions.napi) {+ if (typeof process !== 'undefined' && process.versions && 'napi' in process.versions) {return 'napi';}} catch {@@ -249,7 +248,7 @@ export class FlashAttentionOptimizer {}// Check for WebAssembly support- if (typeof WebAssembly !== 'undefined') {+ if (typeof globalThis !== 'undefined' && 'WebAssembly' in globalThis) {return 'wasm';}