tasq/node_modules/agentic-flow/docs/reasoningbank/REASONINGBANK_BACKENDS.md

ReasoningBank Storage Backends

ReasoningBank provides two storage implementations optimized for different environments:

📊 Backend Comparison

Backend	Environment	Storage	Persistence	Performance	Use Case
Node.js	CLI, servers	SQLite	✅ Yes	2-5ms/op	Production, long-term memory
WASM	Browser	IndexedDB	✅ Yes	1-3ms/op	Web apps, client-side
WASM	Node.js	RAM	❌ No	0.04ms/op	Temporary data, fast access

---

🔧 Usage

Node.js Backend (Recommended for CLIs)

Use when: Building CLIs, servers, or any application needing persistent storage.

import { ReasoningBank } from 'agentic-flow/dist/reasoningbank/index.js';

// Initialize with SQLite database
const rb = new ReasoningBank({
  dbPath: '.swarm/memory.db'
});

// Store pattern (persists to disk)
await rb.storePattern({
  task_description: 'Implement authentication',
  task_category: 'auth',
  strategy: 'jwt-tokens',
  success_score: 0.9
});

// Search patterns (queries SQLite database)
const patterns = await rb.searchByCategory('auth', 10);
// Returns: All patterns from database ✅

// Semantic search
const similar = await rb.findSimilar('user login', 'auth', 5);
// Returns: Similar patterns with scores (e.g., 0.54-0.62)

Features:

• ✅ Persistent SQLite storage
• ✅ Automatic embedding generation
• ✅ Fast semantic search (2-5ms)
• ✅ Production-ready
• ✅ Cross-session memory

---

WASM Backend (For Browsers)

Use when: Building web applications that need client-side storage.

import { createReasoningBank } from 'agentic-flow/dist/reasoningbank/wasm-adapter.js';

// Initialize WASM instance (uses IndexedDB in browser)
const rb = await createReasoningBank('my-app-db');

// Store pattern (persists to IndexedDB)
await rb.storePattern({
  task_description: 'Handle form validation',
  task_category: 'ui',
  strategy: 'real-time-validation',
  success_score: 0.95
});

// Semantic search
const similar = await rb.findSimilar('user input validation', 'ui', 5);
// Returns: Similar patterns with scores

Features:

• ✅ Persistent IndexedDB storage (browser)
• ✅ Native performance via WASM
• ✅ Ultra-fast operations (0.04ms in-memory)
• ✅ Browser-optimized
• ⚠️ In-memory only in Node.js (ephemeral)

---

🎯 Backend Selection Guide

Automatic Selection (Recommended)

// Environment-aware import
const ReasoningBankImpl = typeof window !== 'undefined'
  ? await import('agentic-flow/dist/reasoningbank/wasm-adapter.js')
  : await import('agentic-flow/dist/reasoningbank/index.js');

const rb = typeof window !== 'undefined'
  ? await ReasoningBankImpl.createReasoningBank('app-memory')
  : new ReasoningBankImpl.ReasoningBank({ dbPath: '.swarm/memory.db' });

// Now use rb normally - it will work optimally in both environments
const patterns = await rb.searchByCategory('category', 10);

Manual Selection

Choose Node.js backend when:

• Building CLI tools
• Need persistent storage
• Running on servers
• Require SQLite features

Choose WASM backend when:

• Building web apps
• Need client-side storage
• Want maximum browser performance
• Require offline capabilities

---

🔍 Key Differences

Storage Location

Node.js:

.swarm/memory.db (SQLite database on disk)
├── patterns table
├── pattern_embeddings table
└── Full SQL query support

WASM (Browser):

IndexedDB: my-app-db (browser storage)
├── patterns store
├── embeddings store
└── Fast key-value lookups

WASM (Node.js):

RAM only (ephemeral, lost on process exit)
├── In-memory HashMap
└── Fastest access, no persistence

Embedding Generation

Both backends automatically generate embeddings when you store patterns:

// Internal: reasoningbank-core/src/engine.rs
pub fn prepare_pattern(&self, mut pattern: Pattern) -> Result<Pattern> {
    // Auto-generate embedding if not present
    if pattern.embedding.is_none() {
        let embedding = VectorEmbedding::from_text(&pattern.task_description);
        pattern.embedding = Some(embedding.values);
    }
    Ok(pattern)
}

You don't need to manually generate embeddings! They are created automatically from your task description.

---

📦 Package.json Integration

For projects supporting both Node.js and browsers, use conditional exports:

{
  "name": "my-app",
  "exports": {
    "./memory": {
      "node": "./dist/memory-node.js",
      "browser": "./dist/memory-browser.js"
    }
  }
}

memory-node.js:

export { ReasoningBank } from 'agentic-flow/dist/reasoningbank/index.js';

memory-browser.js:

export { createReasoningBank as ReasoningBank } from 'agentic-flow/dist/reasoningbank/wasm-adapter.js';

---

🧪 Validation

Test Node.js Backend

node <<EOF
import { ReasoningBank } from 'agentic-flow/dist/reasoningbank/index.js';

const rb = new ReasoningBank({ dbPath: '.swarm/memory.db' });

// Store
const id = await rb.storePattern({
  task_description: 'Test pattern',
  task_category: 'test',
  strategy: 'validation',
  success_score: 0.95
});

// Search
const patterns = await rb.searchByCategory('test', 10);
console.log(\`Found \${patterns.length} patterns\`);
// Expected: 1 pattern

// Get stats
const stats = await rb.getStats();
console.log(stats);
// Expected: { total_patterns: 1, total_categories: 1 }
EOF

Test WASM Backend (Browser)

// In browser console or webpack bundle
import { createReasoningBank } from 'agentic-flow/dist/reasoningbank/wasm-adapter.js';

const rb = await createReasoningBank('test-db');

// Store
await rb.storePattern({
  task_description: 'Browser test',
  task_category: 'test',
  strategy: 'client-side',
  success_score: 0.9
});

// Search
const patterns = await rb.searchByCategory('test', 10);
console.log(`Found ${patterns.length} patterns`);
// Expected: 1 pattern

// Semantic search
const similar = await rb.findSimilar('test validation', 'test', 5);
console.log(`Similarity: ${similar[0]?.similarity_score}`);
// Expected: score > 0.5

Test WASM Backend (Node.js - In-Memory)

node --experimental-wasm-modules <<EOF
import { createReasoningBank } from 'agentic-flow/dist/reasoningbank/wasm-adapter.js';

const rb = await createReasoningBank('test');

// Store
await rb.storePattern({
  task_description: 'Node WASM test',
  task_category: 'test',
  strategy: 'in-memory',
  success_score: 0.92
});

// Search (same session)
const patterns = await rb.searchByCategory('test', 10);
console.log(\`Found \${patterns.length} patterns\`);
// Expected: 1 pattern (only in current session)

// Stats
const stats = await rb.getStats();
console.log(\`Backend: \${stats.storage_backend}\`);
// Expected: "wasm-memory"
EOF

---

⚠️ Important Notes

WASM in Node.js

When using WASM in Node.js:

• Storage is in-memory only (not persistent)
• Data is lost when process exits
• Useful for temporary/ephemeral data
• Use Node.js backend instead for persistent storage

Node.js Flag Requirement

When importing WASM in Node.js, you need the experimental flag:

node --experimental-wasm-modules your-script.mjs

This is not required for:

• Node.js backend (SQLite)
• WASM in browsers
• Production builds with bundlers (webpack, vite, rollup)

---

🚀 Recommendations

For agentic-flow Package

1. Default to environment-appropriate backend:

   • Node.js → SQLite backend
   • Browser → WASM backend

2. Document WASM limitations in Node.js:

   • In-memory only
   • No cross-session persistence
   • Use Node.js backend for CLIs

3. Provide helper function:

export function getRecommendedBackend(): 'nodejs' | 'wasm' {
  return typeof window === 'undefined' ? 'nodejs' : 'wasm';
}

For Integration Projects

1. Use Node.js backend for:

   • CLI tools (like claude-flow)
   • Server applications
   • Long-running processes
   • Persistent memory requirements

2. Use WASM backend for:

   • Browser applications
   • Client-side AI features
   • Offline-first apps
   • WebAssembly-optimized environments

---

📊 Performance Metrics

Storage Operations

Operation	Node.js	WASM (Browser)	WASM (Node.js)
Store Pattern	2-5ms	1-3ms	0.04ms
Category Search	2-3ms	1-2ms	0.02ms
Semantic Search	3-5ms	2-4ms	0.06ms
Get Stats	1ms	0.5ms	0.01ms

Embedding Generation

Both backends generate embeddings at the same speed:

• 1024-dimensional vectors
• Generated from text via VectorEmbedding::from_text()
• Automatically created on storePattern()

---

🔗 Related Documentation

• ReasoningBank Core
• WASM ESM Fix
• ReasoningBank Investigation
• ReasoningBank Fixes

---

Status: Production Ready ✅ Maintained by: @ruvnet Version: 1.5.12+