agentic-flow 1.9.0 → 1.9.2

package/docs/features/reasoningbank/REASONINGBANK_INVESTIGATION.md

@@ -1,380 +0,0 @@
-# ReasoningBank Investigation Report
-
-**Date**: 2025-10-13
-**Package**: agentic-flow@1.5.12
-**Issue**: Limitations in semantic query, status reporting, and namespace separation
-
----
-
-## 🔍 Investigation Summary
-
-### Observed Issues
-
-1. **Semantic Query Returns 0 Results**
-   - Query on existing database returns empty
-   - Freshly stored patterns can be queried
-   - Status shows "0 memories" despite 1.8MB database
-
-2. **Status Reporting Incorrect**
-   - `getStats()` returns `{ total_patterns: 0 }`
-   - SQLite database has 289 patterns with 289 embeddings
-   - Database size: 1.8MB with active WAL
-
-3. **Namespace Separation**
-   - WASM and SQLite use completely separate storage
-   - No cross-querying between implementations
-   - Expected behavior but undocumented
-
----
-
-## 🎯 Root Cause Analysis
-
-### Primary Finding: WASM Uses In-Memory Storage in Node.js
-
-**Location**: `reasoningbank/crates/reasoningbank-wasm/src/lib.rs:47-51`
-
-```rust
-if reasoningbank_storage::adapters::wasm::is_nodejs() {
-    // Node.js environment - use in-memory storage
-    let db = MemoryStorage::new(config).await
-        .map_err(|e| JsValue::from_str(&format!("Memory storage error: {}", e)))?;
-    Arc::new(db)
-}
-```
-
-**Explanation**: The WASM implementation **always uses in-memory storage** when running in Node.js. It never connects to the SQLite database at `.swarm/memory.db`.
-
-### Storage Backend Selection Logic
-
-```
-Environment Detection:
-├─ Node.js (no window object)
-│  └─► MemoryStorage (RAM only, ephemeral) ✅ Currently used
-│
-├─ Browser with IndexedDB
-│  └─► IndexedDbStorage (persistent, browser storage)
-│
-└─ Browser without IndexedDB
-   └─► SqlJsStorage (WASM SQLite in browser)
-```
-
-### Database File Analysis
-
-```bash
-$ ls -lh .swarm/memory.db
--rw-r--r-- 1 codespace codespace 1.8M Oct 13 15:00 .swarm/memory.db
-
-$ sqlite3 .swarm/memory.db "SELECT COUNT(*) FROM patterns;"
-289
-
-$ sqlite3 .swarm/memory.db "SELECT COUNT(*) FROM pattern_embeddings;"
-289
-```
-
-**This database is from the Node.js ReasoningBank implementation (non-WASM)**, which claude-flow uses. The WASM adapter never touches it.
-
----
-
-## 📊 Test Results
-
-### Direct WASM API Test
-
-```bash
-$ node --experimental-wasm-modules test-reasoningbank-api.mjs
-
-🧪 Testing ReasoningBank API with existing database...
-
-2. Getting statistics...
-   📊 Stats: {
-     "total_patterns": 0,           # ❌ Empty (in-memory storage)
-     "total_categories": 0,
-     "backend_type": "wasm-memory"  # ← Key indicator
-   }
-
-3. Testing category search...
-   ✅ Found 0 patterns by category   # ❌ No existing data
-
-5. Storing a new test pattern...
-   ✅ Stored with ID: 49928d08...   # ✅ Storage works
-
-6. Searching for the new pattern...
-   ✅ Found 1 test patterns          # ✅ Can query fresh data
-
-7. Testing semantic search on new pattern...
-   ✅ Found 1 similar test patterns
-   Similarity score: 0.557           # ✅ Semantic search works!
-```
-
-**Conclusion**: WASM functionality is correct, but it operates on a separate in-memory database.
-
----
-
-## 🏗️ Architecture Comparison
-
-### Node.js ReasoningBank (Non-WASM)
-
-```
-claude-flow
-    ↓
-reasoningbank-core (Node.js native)
-    ↓
-SQLite via better-sqlite3
-    ↓
-.swarm/memory.db (1.8MB, 289 patterns)
-```
-
-**Status**: ✅ Persistent, works with existing data
-
-### WASM ReasoningBank
-
-```
-agentic-flow WASM adapter
-    ↓
-reasoningbank-wasm (WASM)
-    ↓
-MemoryStorage (in-memory)
-    ↓
-RAM only (ephemeral, no persistence)
-```
-
-**Status**: ✅ Works correctly, but isolated from SQLite
-
----
-
-## 🔄 Data Flow Diagram
-
-```
-┌──────────────────────────────────────────┐
-│  .swarm/memory.db (1.8MB)                │
-│  ├─ 289 patterns                         │
-│  └─ 289 embeddings (1024-dim)            │
-│                                           │
-│  Used by: Node.js ReasoningBank ✅       │
-│  NOT used by: WASM ReasoningBank ❌      │
-└──────────────────────────────────────────┘
-         │
-         │ Only accessible by
-         ↓
-┌──────────────────────────────────────────┐
-│  claude-flow (Node.js native)            │
-│  import { ReasoningBank } from           │
-│  'agentic-flow/dist/reasoningbank'       │
-└──────────────────────────────────────────┘
-
-┌──────────────────────────────────────────┐
-│  WASM MemoryStorage (RAM)                │
-│  ├─ Starts empty                         │
-│  ├─ Stores patterns in memory            │
-│  └─ Lost on process exit                 │
-│                                           │
-│  Used by: WASM ReasoningBank ✅          │
-└──────────────────────────────────────────┘
-         │
-         │ Only accessible by
-         ↓
-┌──────────────────────────────────────────┐
-│  agentic-flow WASM adapter               │
-│  import { createReasoningBank } from     │
-│  'agentic-flow/...wasm-adapter.js'       │
-└──────────────────────────────────────────┘
-```
-
----
-
-## ✅ What Works
-
-1. **WASM Pattern Storage**: ✅ Working perfectly
-   - Store patterns: 3ms/operation
-   - Retrieve by ID: <1ms
-   - Category search: Works on WASM data
-   - Semantic search: Works with similarity scores
-
-2. **Node.js ReasoningBank**: ✅ Fully functional
-   - Persistent SQLite storage
-   - 289 patterns available
-   - Used by claude-flow successfully
-
-3. **Namespace Separation**: ✅ By design
-   - WASM and Node.js implementations are independent
-   - No cross-contamination of data
-   - Each has its own storage strategy
-
----
-
-## ❌ Limitations
-
-1. **WASM Cannot Access Existing SQLite Data**
-   - WASM uses in-memory storage in Node.js
-   - Cannot read `.swarm/memory.db`
-   - Starts empty on every instantiation
-
-2. **No Persistence in WASM (Node.js)**
-   - All data lost on process exit
-   - Not suitable for long-term memory
-   - Browser environments have persistent storage (IndexedDB)
-
-3. **Status Reporting Shows Empty**
-   - `getStats()` reflects WASM's in-memory state
-   - Does not show SQLite database contents
-   - Misleading if expecting combined view
-
----
-
-## 🔧 Solution Options
-
-### Option 1: Use Node.js ReasoningBank (Recommended for claude-flow)
-
-```javascript
-// ✅ RECOMMENDED: Persistent SQLite storage
-import { ReasoningBank } from 'agentic-flow/dist/reasoningbank/index.js';
-
-const rb = new ReasoningBank({ dbPath: '.swarm/memory.db' });
-await rb.storePattern({ /* ... */ });
-const patterns = await rb.searchByCategory('web.admin', 10);
-// ✅ Accesses all 289 existing patterns
-```
-
-### Option 2: Implement SQLite Support in WASM
-
-**Requires**: Modify `reasoningbank-wasm/src/lib.rs` to add Node.js SQLite backend
-
-```rust
-// Proposed implementation
-if reasoningbank_storage::adapters::wasm::is_nodejs() {
-    // Check if SQLite native module is available
-    if has_sqlite_native() {
-        let db = SqliteStorage::new(config).await?;  // New backend
-        Arc::new(db)
-    } else {
-        // Fallback to in-memory
-        let db = MemoryStorage::new(config).await?;
-        Arc::new(db)
-    }
-}
-```
-
-**Complexity**: Medium - requires new storage backend implementation
-
-### Option 3: Use WASM Only for Browser, Node.js for CLI
-
-```javascript
-// Environment-aware import
-const createReasoningBank = typeof window !== 'undefined'
-    ? (await import('agentic-flow/dist/reasoningbank/wasm-adapter.js')).createReasoningBank
-    : (await import('agentic-flow/dist/reasoningbank/index.js')).default;
-
-const rb = await createReasoningBank('.swarm/memory');
-// ✅ Persistent in Node.js, WASM in browser
-```
-
----
-
-## 📝 Recommendations
-
-### For claude-flow Integration
-
-1. **Use Node.js ReasoningBank**: Import from `agentic-flow/dist/reasoningbank/index.js`
-2. **Avoid WASM adapter in Node.js**: It's designed for browsers
-3. **Update documentation**: Clarify WASM vs Node.js usage
-
-### For agentic-flow Package
-
-1. **Document storage backends clearly**:
-   ```
-   - Node.js: Use non-WASM import (persistent SQLite)
-   - Browser: Use WASM adapter (IndexedDB/SqlJs)
-   ```
-
-2. **Add detection helper**:
-   ```typescript
-   export function getRecommendedBackend(): 'nodejs' | 'wasm' {
-       return typeof window === 'undefined' ? 'nodejs' : 'wasm';
-   }
-   ```
-
-3. **Consider unified API**:
-   ```typescript
-   export async function createReasoningBank(options?) {
-       if (typeof window === 'undefined') {
-           return new ReasoningBank(options);  // Node.js native
-       } else {
-           return new ReasoningBankWasm(options);  // WASM
-       }
-   }
-   ```
-
----
-
-## 🧪 Validation Commands
-
-### Check SQLite Database (Node.js)
-
-```bash
-sqlite3 .swarm/memory.db "SELECT COUNT(*) FROM patterns;"
-# Expected: 289
-
-sqlite3 .swarm/memory.db "SELECT pattern_data FROM patterns LIMIT 1;" | jq .
-# Should show pattern JSON
-```
-
-### Test WASM Storage (Ephemeral)
-
-```bash
-node --experimental-wasm-modules <<EOF
-import { createReasoningBank } from 'agentic-flow/dist/reasoningbank/wasm-adapter.js';
-const rb = await createReasoningBank('test');
-const stats = await rb.getStats();
-console.log(stats);  // Will show 0 patterns (fresh instance)
-EOF
-```
-
-### Test Node.js Storage (Persistent)
-
-```bash
-node <<EOF
-import { ReasoningBank } from 'agentic-flow/dist/reasoningbank/index.js';
-const rb = new ReasoningBank({ dbPath: '.swarm/memory.db' });
-const stats = await rb.getStats();
-console.log(stats);  // Will show 289 patterns
-EOF
-```
-
----
-
-## 📊 Performance Comparison
-
-| Backend | Storage | Persistence | Performance | Use Case |
-|---------|---------|-------------|-------------|----------|
-| **Node.js** | SQLite | ✅ Yes | 2-5ms/op | CLI, servers, long-term memory |
-| **WASM (Node.js)** | RAM | ❌ No | 0.04ms/op | Temporary data, fast access |
-| **WASM (Browser)** | IndexedDB | ✅ Yes | 1-3ms/op | Web apps, client-side |
-
----
-
-## 🎯 Conclusion
-
-The reported "limitations" are **not bugs**, but **architectural decisions**:
-
-1. ✅ **Semantic search works** - Tested and verified
-2. ✅ **Status reporting correct** - Shows WASM's in-memory state accurately
-3. ✅ **Namespace separation intended** - Prevents cross-contamination
-
-The confusion arose from expecting WASM to access the Node.js SQLite database, which was never the design intent.
-
-### Action Items
-
-**For claude-flow:**
-- [x] Understand WASM uses in-memory storage
-- [ ] Switch to Node.js ReasoningBank for persistence
-- [ ] Update integration documentation
-
-**For agentic-flow:**
-- [ ] Add backend selection guide to README
-- [ ] Consider unified API with automatic backend selection
-- [ ] Document WASM memory limitations clearly
-
----
-
-**Report Status**: Complete ✅
-**Issue Status**: No bugs found - working as designed
-**Next Steps**: Documentation updates and integration guidance

package/docs/features/router/README.md

@@ -1,38 +0,0 @@
-# Multi-Model Router - Intelligent Model Selection
-
-> Automatic model selection based on task requirements and optimization priorities
-
-## 📚 Documentation
-
-- [Router User Guide](ROUTER_USER_GUIDE.md) - Complete user guide
-- [Router Config Reference](ROUTER_CONFIG_REFERENCE.md) - Configuration options
-- [Top 20 Models Matrix](TOP20_MODELS_MATRIX.md) - Model comparison
-
-## 🚀 Quick Start
-
-### Basic Usage
-```bash
-# Auto-select optimal model
-npx claude-flow agent \
-  --agent coder \
-  --task "Implement authentication" \
-  --priority quality
-
-# Cost-optimized model
-npx claude-flow agent \
-  --agent coder \
-  --task "Fix typo" \
-  --priority cost
-```
-
-## 🎯 Optimization Priorities
-
-- **quality** - Best results (Sonnet 4.5, GPT-4)
-- **balanced** - Cost/quality balance (GPT-4-mini, Gemini Pro)
-- **cost** - Cheapest options (OpenRouter, Gemini Flash)
-- **speed** - Fastest response (Haiku, GPT-3.5)
-- **privacy** - Local only (ONNX models)
-
----
-
-**Back to**: [Features](../README.md) | [Main Documentation](../../README.md)