claude-flow 2.7.0-alpha.7 → 2.7.0-alpha.9

package/docs/PERFORMANCE-METRICS-GUIDE.md

@@ -0,0 +1,259 @@
+# Performance Metrics Enhancement Guide
+
+## Overview
+
+The `performance.json` file has been enhanced with comprehensive metrics for tracking memory operations, mode usage, and ReasoningBank-specific performance.
+
+## Enhanced Structure
+
+### Session Information
+```json
+{
+  "startTime": 1234567890,
+  "sessionId": "session-1234567890",
+  "lastActivity": 1234567890,
+  "sessionDuration": 12345
+}
+```
+Tracks when the session started, unique session ID, last activity timestamp, and total session duration in milliseconds.
+
+### Memory Mode Tracking
+```json
+{
+  "memoryMode": {
+    "reasoningbankOperations": 45,
+    "basicOperations": 12,
+    "autoModeSelections": 50,
+    "modeOverrides": 7,
+    "currentMode": "auto"
+  }
+}
+```
+Tracks which memory mode (ReasoningBank vs Basic/JSON) is being used, how often AUTO MODE selects each, and manual overrides.
+
+### Operation Type Breakdown
+```json
+{
+  "operations": {
+    "store": { "count": 20, "totalDuration": 1234, "errors": 0 },
+    "retrieve": { "count": 45, "totalDuration": 2345, "errors": 1 },
+    "query": { "count": 30, "totalDuration": 15000, "errors": 0 },
+    "list": { "count": 10, "totalDuration": 500, "errors": 0 },
+    "delete": { "count": 3, "totalDuration": 200, "errors": 0 },
+    "search": { "count": 25, "totalDuration": 12000, "errors": 0 },
+    "init": { "count": 1, "totalDuration": 500, "errors": 0 }
+  }
+}
+```
+Detailed breakdown of each operation type with count, total duration, and error count.
+
+### Performance Statistics
+```json
+{
+  "performance": {
+    "avgOperationDuration": 450.5,
+    "minOperationDuration": 10,
+    "maxOperationDuration": 5000,
+    "slowOperations": 3,
+    "fastOperations": 100,
+    "totalOperationTime": 45050
+  }
+}
+```
+- `avgOperationDuration`: Average time per operation (ms)
+- `minOperationDuration`: Fastest operation time (ms)
+- `maxOperationDuration`: Slowest operation time (ms)
+- `slowOperations`: Count of operations > 5000ms
+- `fastOperations`: Count of operations < 100ms
+- `totalOperationTime`: Cumulative time for all operations (ms)
+
+### Storage Statistics
+```json
+{
+  "storage": {
+    "totalEntries": 150,
+    "reasoningbankEntries": 120,
+    "basicEntries": 30,
+    "databaseSize": 2048000,
+    "lastBackup": 1234567890,
+    "growthRate": 12.5
+  }
+}
+```
+- `totalEntries`: Total memory entries across all modes
+- `reasoningbankEntries`: Entries in ReasoningBank database
+- `basicEntries`: Entries in JSON storage
+- `databaseSize`: Database file size in bytes
+- `lastBackup`: Timestamp of last backup
+- `growthRate`: Entries per hour growth rate
+
+### Error Tracking
+```json
+{
+  "errors": {
+    "total": 5,
+    "byType": {
+      "timeout": 2,
+      "connection": 1,
+      "validation": 2
+    },
+    "byOperation": {
+      "query": 3,
+      "store": 2
+    },
+    "recent": [
+      {
+        "operation": "query",
+        "type": "timeout",
+        "timestamp": 1234567890,
+        "mode": "reasoningbank"
+      }
+    ]
+  }
+}
+```
+Comprehensive error tracking by type, operation, and recent error history.
+
+### ReasoningBank Specific Metrics
+```json
+{
+  "reasoningbank": {
+    "semanticSearches": 45,
+    "sqlFallbacks": 12,
+    "embeddingGenerated": 40,
+    "consolidations": 3,
+    "avgQueryTime": 450.5,
+    "cacheHits": 25,
+    "cacheMisses": 20
+  }
+}
+```
+- `semanticSearches`: Number of semantic vector searches
+- `sqlFallbacks`: Number of SQL fallback queries (when semantic returns empty)
+- `embeddingGenerated`: Number of text embeddings created
+- `consolidations`: Number of memory consolidation runs
+- `avgQueryTime`: Average query execution time (ms)
+- `cacheHits`: Successful cache retrievals
+- `cacheMisses`: Cache misses requiring computation
+
+## Usage Examples
+
+### Tracking Memory Operations
+
+```javascript
+import { trackMemoryOperation } from './performance-metrics.js';
+
+// Track a successful query
+const startTime = Date.now();
+const result = await queryMemory('search term');
+const duration = Date.now() - startTime;
+
+await trackMemoryOperation('query', 'reasoningbank', duration, true);
+
+// Track a failed operation with error
+try {
+  await storeMemory(data);
+} catch (error) {
+  const duration = Date.now() - startTime;
+  await trackMemoryOperation('store', 'basic', duration, false, 'validation_error');
+}
+```
+
+### Tracking Mode Selection
+
+```javascript
+import { trackModeSelection } from './performance-metrics.js';
+
+// AUTO MODE selection
+const mode = await detectMemoryMode();
+await trackModeSelection(mode, true); // true = automatic selection
+
+// Manual override
+if (flags.reasoningbank) {
+  await trackModeSelection('reasoningbank', false); // false = manual override
+}
+```
+
+### Tracking ReasoningBank Operations
+
+```javascript
+import { trackReasoningBankOperation } from './performance-metrics.js';
+
+// Track semantic search
+const startTime = Date.now();
+const results = await semanticSearch(query);
+const duration = Date.now() - startTime;
+
+if (results.length === 0) {
+  // Semantic search returned empty, using SQL fallback
+  await trackReasoningBankOperation('sql_fallback', duration);
+} else {
+  await trackReasoningBankOperation('semantic_search', duration);
+}
+
+// Track cache hits/misses
+if (cacheHit) {
+  await trackReasoningBankOperation('cache_hit', 0);
+} else {
+  await trackReasoningBankOperation('cache_miss', duration);
+}
+```
+
+### Getting Performance Summary
+
+```javascript
+import { getMemoryPerformanceSummary } from './performance-metrics.js';
+
+const summary = await getMemoryPerformanceSummary();
+
+console.log('Session:', summary.session);
+console.log('Mode Usage:', summary.mode);
+console.log('Operations:', summary.operations);
+console.log('Performance:', summary.performance);
+console.log('Storage:', summary.storage);
+console.log('ReasoningBank:', summary.reasoningbank);
+console.log('Errors:', summary.errors);
+```
+
+The summary includes calculated metrics like:
+- Error rate percentage
+- SQL fallback rate (percentage of semantic searches that fell back to SQL)
+- Cache hit rate (percentage of successful cache retrievals)
+
+## Integration Points
+
+These tracking functions should be integrated into:
+
+1. **Memory Command** (`src/cli/simple-commands/memory.js`)
+   - Track all store, retrieve, query, list, delete operations
+   - Track mode detection and selection
+
+2. **ReasoningBank Adapter** (`src/reasoningbank/reasoningbank-adapter.js`)
+   - Track semantic searches
+   - Track SQL fallbacks
+   - Track embedding generation
+   - Track cache hits/misses
+
+3. **Session Hooks** (hooks system)
+   - Initialize metrics at session start
+   - Export metrics at session end
+   - Update storage stats periodically
+
+## Benefits
+
+1. **Visibility**: Understand how AUTO MODE performs in real-world usage
+2. **Performance Tuning**: Identify slow operations and bottlenecks
+3. **Error Analysis**: Track error patterns and frequency
+4. **Mode Optimization**: See which mode performs better for different workloads
+5. **Resource Planning**: Monitor growth rates and storage usage
+6. **Cache Effectiveness**: Measure cache hit rates for optimization
+
+## Future Enhancements
+
+Potential additions:
+- Query pattern analysis (most common queries)
+- Operation frequency heatmaps
+- Performance degradation alerts
+- Automatic recommendation system
+- Export to time-series database for long-term analysis
+- Real-time dashboards

package/docs/integrations/agentic-flow/AGENTIC_FLOW_SECURITY_TEST_REPORT.md

@@ -29,8 +29,8 @@
 
 **Features:**
 - Comprehensive API key pattern matching
-  - Anthropic keys: `sk-ant-...`
-  - OpenRouter keys: `sk-or-...`
+  - Anthropic keys: `$ANTHROPIC_API_KEY`
+  - OpenRouter keys: `$OPENROUTER_API_KEY`
   - Google/Gemini keys: `AIza...`
   - Bearer tokens
   - Environment variables
@@ -41,7 +41,7 @@
 
 **Test Results:**
 ```
-✅ API keys redacted in text (sk-ant-a...[REDACTED])
+✅ API keys redacted in text ($ANTHROPIC_API_KEY)
 ✅ Environment variables sanitized
 ✅ Objects with sensitive fields protected
 ✅ Validation detects unredacted keys
@@ -96,8 +96,8 @@ grep -E "^[A-Z_]+=" .env | cut -d'=' -f1
 npx tsx test-redaction.ts
 
 # Results
-✅ Anthropic API Key: sk-ant-a...[REDACTED]
-✅ OpenRouter API Key: sk-or-v1...[REDACTED]
+✅ Anthropic API Key: $ANTHROPIC_API_KEY
+✅ OpenRouter API Key: $OPENROUTER_API_KEY
 ✅ Environment Variables: ANTHROPI...[REDACTED]
 ✅ Object Redaction: { apiKey: [REDACTED], model: "claude-3-sonnet" }
 ✅ Validation: Detects unredacted keys
@@ -203,8 +203,8 @@ npx agentic-flow agent list
 
 **Present in `.env`:**
 ```
-ANTHROPIC_API_KEY=sk-an...[REDACTED]
-OPENROUTER_API_KEY=sk-or...[REDACTED]
+ANTHROPIC_API_KEY=***REDACTED***
+OPENROUTER_API_KEY=***REDACTED***
 GOOGLE_GEMINI_API_KEY=AIza...[REDACTED]
 HUGGINGFACE_API_KEY=hf_...[REDACTED]
 PERPLEXITY_API_KEY=pplx...[REDACTED]

package/docs/integrations/reasoningbank/MIGRATION-v1.5.13.md

@@ -0,0 +1,189 @@
+# ReasoningBank Migration Guide: v1.5.12 → v1.5.13
+
+## Overview
+
+Claude-Flow has been updated to use **agentic-flow@1.5.13** with the **Node.js backend** for ReasoningBank, replacing the previous WASM adapter approach.
+
+## Key Changes
+
+### Backend Migration: WASM → Node.js SQLite
+
+**Before (v1.5.12 - WASM)**:
+- Ephemeral in-memory storage (Node.js) or IndexedDB (browser)
+- Direct WASM module imports
+- Ultra-fast but non-persistent
+
+**After (v1.5.13 - Node.js)**:
+- **Persistent SQLite database** at `.swarm/memory.db`
+- Full embedding support for semantic search
+- Memory consolidation and trajectory tracking
+- Recommended backend for Node.js environments
+
+### API Compatibility
+
+✅ **No breaking changes to external API** - All claude-flow memory functions remain the same:
+- `storeMemory(key, value, options)`
+- `queryMemories(searchQuery, options)`
+- `listMemories(options)`
+- `getStatus()`
+- `initializeReasoningBank()`
+
+### Internal Implementation Changes
+
+**Storage**:
+```javascript
+// Old (WASM)
+pattern = { task_description, task_category, strategy, success_score }
+await wasm.storePattern(pattern)
+
+// New (Node.js)
+memory = { type: 'reasoning_memory', pattern_data: { title, content, domain } }
+ReasoningBank.db.upsertMemory(memory)
+await ReasoningBank.computeEmbedding(content) // Generate embeddings
+```
+
+**Retrieval**:
+```javascript
+// Old (WASM)
+results = await wasm.findSimilar(query, category, limit)
+
+// New (Node.js)
+results = await ReasoningBank.retrieveMemories(query, {
+  domain, agent, k: limit, minConfidence
+})
+```
+
+## Database Schema
+
+**Location**: `.swarm/memory.db`
+
+**Tables**:
+- `patterns` - Reasoning memories with confidence scores
+- `pattern_embeddings` - Vector embeddings for semantic search
+- `pattern_links` - Memory relationships and contradictions
+- `task_trajectories` - Task execution history
+- `matts_runs` - MaTTS algorithm runs
+- `consolidation_runs` - Memory consolidation history
+
+## Migration Steps
+
+### Automatic Migration
+
+When you upgrade to v2.7.0-alpha.7+, ReasoningBank will automatically:
+
+1. Initialize Node.js backend on first use
+2. Create SQLite database at `.swarm/memory.db`
+3. Run database migrations (create tables)
+4. Generate embeddings for new memories
+
+**No manual migration needed!** Old WASM data was ephemeral and not persisted.
+
+### Environment Variables
+
+```bash
+# Optional: Custom database path
+export CLAUDE_FLOW_DB_PATH="/path/to/memory.db"
+
+# Optional: Disable ReasoningBank
+export REASONINGBANK_ENABLED=false
+```
+
+## Feature Comparison
+
+| Feature | WASM (v1.5.12) | Node.js (v1.5.13) |
+|---------|----------------|-------------------|
+| **Storage** | Ephemeral (in-memory) | Persistent (SQLite) |
+| **Semantic Search** | Basic similarity | Embeddings + MMR ranking |
+| **Domain Filtering** | Category-based | Full JSON query support |
+| **Memory Consolidation** | ❌ Not available | ✅ Built-in |
+| **Trajectory Tracking** | ❌ Not available | ✅ Full history |
+| **Cross-session Memory** | ❌ Lost on restart | ✅ Persistent |
+| **Performance** | 0.04ms/op (WASM) | 1-2ms/op (SQLite + embeddings) |
+| **Database Size** | ~0 MB (memory) | Grows with data (~41MB for 100 patterns) |
+
+## Performance
+
+**Benchmarks** (100 memories, semantic search):
+
+```
+Storage:     1-2ms per memory (includes embedding generation)
+Query:       1-3ms per semantic search query
+Cached:      <1ms for cached queries
+List:        <1ms for database queries
+```
+
+**Memory Usage**:
+- SQLite database: ~400KB per memory (with embedding)
+- RAM: Minimal (SQLite handles paging)
+
+## Verification
+
+Test your ReasoningBank integration:
+
+```bash
+# Run comprehensive test
+node tests/test-semantic-search.mjs
+
+# Expected output:
+# ✅ Initialized successfully
+# ✅ Stored 5 test memories
+# ✅ Semantic search returning results
+# ✅ Query caching working
+```
+
+## Troubleshooting
+
+### Issue: "Database not found"
+```bash
+# Ensure initialization ran
+npx claude-flow@alpha memory status
+
+# Manually initialize if needed
+npx claude-flow@alpha memory init
+```
+
+### Issue: "No results from semantic search"
+```bash
+# Check embeddings are being generated
+# Look for warnings: "[ReasoningBank] Failed to generate embedding"
+
+# Verify database has embeddings:
+sqlite3 .swarm/memory.db "SELECT COUNT(*) FROM pattern_embeddings;"
+```
+
+### Issue: "Embeddings not generating"
+```bash
+# Ensure API key is set (if using Claude embeddings)
+export ANTHROPIC_API_KEY="your-key"
+
+# Or configure alternative embedding provider in .reasoningbank.json
+```
+
+## Benefits of Node.js Backend
+
+✅ **Persistent Memory** - Survives process restarts
+✅ **Semantic Search** - True embedding-based similarity
+✅ **Memory Consolidation** - Deduplicate and prune old memories
+✅ **Trajectory Tracking** - Full task execution history
+✅ **Production-Ready** - Battle-tested SQLite backend
+
+## Rollback (Not Recommended)
+
+If you need to temporarily rollback to v1.5.12:
+
+```bash
+npm install agentic-flow@1.5.12 --legacy-peer-deps
+```
+
+**Note**: This will lose Node.js backend features and return to ephemeral storage.
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/ruvnet/claude-code-flow/issues
+- Documentation: `/docs/integrations/reasoningbank/`
+- Test Suite: `/tests/test-semantic-search.mjs`
+
+---
+
+**Migration completed**: Claude-Flow v2.7.0-alpha.7 with agentic-flow@1.5.13 Node.js backend ✅