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 edit:

rUvb083da48cbf7
diff --git a/v3/@claude-flow/memory/src/agentdb-backend.test.ts b/v3/@claude-flow/memory/src/agentdb-backend.test.ts
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
index 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 available
try {
- // @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';
}