ReasoningBank Core Memory Integration

🎯 Overview

Integrate ReasoningBank as an optional enhanced mode for claude-flow memory while maintaining full backward compatibility with existing installations.

📊 Current State

Two Separate Systems

Core Memory (claude-flow memory)

Basic key-value storage
File-based (JSON): ./memory/memory-store.json
Commands: store, query, stats, export, import, clear, list
No AI/learning capabilities
Always available, no dependencies

ReasoningBank (claude-flow agent memory)

AI-powered learning memory
Database-based (SQLite): .swarm/memory.db
Commands: init, status, list, demo, test, benchmark
Learns from task execution patterns
Requires initialization and API keys

🚀 Proposed Integration

Unified Interface

bash

# Basic mode (current behavior - backward compatible)
claude-flow memory store api_key "sk-ant-xxx" --redact
claude-flow memory query research

# Enhanced mode (NEW - opt-in via flag)
claude-flow memory store api_key "sk-ant-xxx" --reasoningbank
claude-flow memory query research --reasoningbank
claude-flow memory status --reasoningbank

# Short form
claude-flow memory store api_key "sk-ant-xxx" --rb
claude-flow memory query research --rb

Auto-Detection

bash

# Automatically detect which mode is appropriate
claude-flow memory query research --auto

# Check if ReasoningBank is available
claude-flow memory detect

🏗️ Architecture

Command Flow

┌─────────────────────────────────────────┐
│  claude-flow memory <cmd> [--rb|--auto] │
└────────────────┬────────────────────────┘
                 │
        ┌────────▼─────────┐
        │  Parse Flags     │
        └────────┬─────────┘
                 │
     ┌───────────▼────────────┐
     │  Mode Detection        │
     │  • No flag → Basic     │
     │  • --rb → ReasoningBank│
     │  • --auto → Detect     │
     └───────────┬────────────┘
                 │
        ┌────────▼─────────┐
        │  Execute Command │
        └──────────────────┘

Feature Matrix

Command	Basic Mode	ReasoningBank Mode	Notes
`store`	JSON file	SQLite + embeddings	RB learns patterns
`query`	Exact/fuzzy match	Semantic search	RB uses embeddings
`stats`	File stats	AI metrics (confidence, usage)	RB shows learning stats
`export`	JSON export	JSON + embeddings	RB includes vectors
`import`	JSON import	JSON + rebuild vectors	RB regenerates embeddings
`clear`	Delete entries	Archive + clean	RB preserves learning
`list`	List keys	List with confidence scores	RB shows quality metrics

New Commands

bash

# Initialize ReasoningBank (one-time setup)
claude-flow memory init --reasoningbank

# Check ReasoningBank status
claude-flow memory status --reasoningbank

# Show which mode is active
claude-flow memory mode

# Detect ReasoningBank availability
claude-flow memory detect

# Migrate basic → ReasoningBank
claude-flow memory migrate --to reasoningbank

# Consolidate/optimize ReasoningBank
claude-flow memory consolidate --reasoningbank

🔄 Backward Compatibility

Guaranteed Compatibility

Existing commands work unchanged

bash

# These continue to work exactly as before
claude-flow memory store key value
claude-flow memory query search

No breaking changes
- Default behavior unchanged (uses basic mode)
- Existing JSON files untouched
- No forced migration
Opt-in enhancement
- Users must explicitly use --reasoningbank or --rb
- Or run memory init --reasoningbank first
- Then optionally set default mode

Migration Path

bash

# Step 1: Check current memory
claude-flow memory stats
# Shows: 150 entries in basic mode

# Step 2: Initialize ReasoningBank
claude-flow memory init --reasoningbank
# Creates .swarm/memory.db

# Step 3: (Optional) Migrate existing data
claude-flow memory migrate --to reasoningbank
# Imports all 150 entries + generates embeddings

# Step 4: Use ReasoningBank mode
claude-flow memory query api --reasoningbank
# Now uses semantic search with AI

📝 Implementation Plan

Phase 1: Core Integration (Week 1)

File: src/cli/simple-commands/memory.js

Add mode detection:

javascript

export async function memoryCommand(subArgs, flags) {
  const memorySubcommand = subArgs[0];

  // NEW: Detect mode
  const mode = detectMemoryMode(flags);
  // Returns: 'basic' | 'reasoningbank' | 'auto'

  if (mode === 'reasoningbank') {
    // Delegate to ReasoningBank implementation
    return await reasoningBankMemoryCommand(subArgs, flags);
  }

  // Existing basic implementation continues...
}

Phase 2: Auto-Detection (Week 1)

Add intelligent detection:

javascript

async function detectMemoryMode(flags) {
  // Explicit flag takes precedence
  if (flags.reasoningbank || flags.rb) {
    return 'reasoningbank';
  }

  // Auto mode: check if ReasoningBank is initialized
  if (flags.auto) {
    const rbAvailable = await isReasoningBankInitialized();
    return rbAvailable ? 'reasoningbank' : 'basic';
  }

  // Default: basic mode (backward compatible)
  return 'basic';
}

Phase 3: Enhanced Commands (Week 2)

Add ReasoningBank-specific features:

javascript

// New commands available only in ReasoningBank mode
case 'init':
  if (mode === 'reasoningbank') {
    await initializeReasoningBank();
  }
  break;

case 'status':
  if (mode === 'reasoningbank') {
    await showReasoningBankStatus();
  } else {
    await showBasicMemoryStats();
  }
  break;

Phase 4: Migration Tools (Week 2)

Add migration utilities:

javascript

case 'migrate':
  await migrateMemoryData(flags.to); // 'reasoningbank' or 'basic'
  break;

case 'detect':
  await detectAndShowAvailableModes();
  break;

🎯 User Experience

First-Time User

bash

# Install and use basic memory immediately
$ claude-flow memory store project "Started new API project"
✅ Stored: project

$ claude-flow memory query project
✅ Found 1 result:
   project: Started new API project

# Later: Discover ReasoningBank
$ claude-flow memory detect
ℹ️  Memory Modes Available:
   ✅ Basic Mode (active)
   ⚠️  ReasoningBank (not initialized)

💡 To enable AI-powered memory:
   claude-flow memory init --reasoningbank

Existing User (Backward Compatible)

bash

# Existing installation - everything works unchanged
$ claude-flow memory stats
📊 Memory Statistics:
   Total entries: 247
   Namespaces: 5
   Size: 45.2 KB
   Mode: Basic

# Opt-in to ReasoningBank
$ claude-flow memory init --reasoningbank
🧠 Initializing ReasoningBank...
✅ Created: .swarm/memory.db
✅ ReasoningBank ready!

# Migrate existing data (optional)
$ claude-flow memory migrate --to reasoningbank
📦 Migrating 247 entries...
⏳ Generating embeddings... (this may take a moment)
✅ Migrated successfully!

# Now use either mode
$ claude-flow memory query api
# Uses basic mode (default)

$ claude-flow memory query api --reasoningbank
# Uses ReasoningBank with semantic search

Power User

bash

# Set default mode via config
$ claude-flow config set memory.default_mode reasoningbank
✅ Default memory mode: ReasoningBank

# Now all commands use ReasoningBank by default
$ claude-flow memory query performance
# Automatically uses ReasoningBank

# Override to use basic mode
$ claude-flow memory query performance --basic
# Forces basic mode

🔐 Security & Privacy

Data Separation

Basic mode: ./memory/memory-store.json
ReasoningBank: .swarm/memory.db
Both support --redact flag
ReasoningBank embeddings never expose raw API keys

Privacy Controls

bash

# Redact sensitive data in both modes
claude-flow memory store api "sk-ant-xxx" --redact

# ReasoningBank with privacy-first local embeddings
claude-flow memory init --reasoningbank --local-embeddings
# Uses ONNX local models, no data sent to external APIs

📊 Performance Comparison

Metric	Basic Mode	ReasoningBank	Improvement
Query Speed	2ms	15ms	-6.5x slower
Query Accuracy	60%	88%	+46% better
Learning	No	Yes	∞ better
Memory Usage	1MB	50MB	-49x more
Setup Time	0s	30s	-30s longer

Recommendation: Use basic mode for simple key-value storage, ReasoningBank for AI-powered learning and semantic search.

🧪 Testing Strategy

Backward Compatibility Tests

bash

# Test 1: Existing commands work unchanged
claude-flow memory store test "value"
claude-flow memory query test

# Test 2: No forced migration
claude-flow memory stats
# Should show basic mode by default

# Test 3: Opt-in works
claude-flow memory query test --reasoningbank
# Should fail gracefully if not initialized

Integration Tests

bash

# Test 4: ReasoningBank initialization
claude-flow memory init --reasoningbank
claude-flow memory status --reasoningbank

# Test 5: Migration
claude-flow memory migrate --to reasoningbank
claude-flow memory stats --reasoningbank

# Test 6: Mode detection
claude-flow memory detect

📚 Documentation Updates

Help Text Updates

bash

$ claude-flow memory --help

Memory Management

USAGE:
  claude-flow memory <command> [options]

MODES:
  Basic Mode (default)     Simple key-value storage in JSON file
  ReasoningBank Mode       AI-powered learning with semantic search

FLAGS:
  --reasoningbank, --rb    Use ReasoningBank mode (AI-powered)
  --auto                   Auto-detect best mode
  --basic                  Force basic mode
  --redact                 Enable API key redaction

COMMANDS:
  store <key> <value>      Store a key-value pair
  query <search>           Search for entries
  stats                    Show memory statistics
  export [filename]        Export memory to file
  import <filename>        Import memory from file
  clear --namespace <ns>   Clear a namespace
  list                     List all namespaces

  # ReasoningBank Commands (require --reasoningbank)
  init --reasoningbank     Initialize ReasoningBank system
  status --reasoningbank   Show ReasoningBank statistics
  consolidate --rb         Optimize ReasoningBank database

  # Mode Management
  detect                   Show available memory modes
  migrate --to <mode>      Migrate between basic/reasoningbank
  mode                     Show current default mode

EXAMPLES:
  # Basic mode (always works)
  memory store api_key "sk-ant-xxx" --redact
  memory query research

  # ReasoningBank mode (requires init)
  memory init --reasoningbank
  memory store api_key "sk-ant-xxx" --reasoningbank
  memory query research --reasoningbank

  # Auto-detect (uses best available)
  memory query research --auto

🚦 Rollout Plan

Version 2.6.1 (Current)

✅ ReasoningBank available via agent memory commands
✅ Core memory works independently

Version 2.7.0 (Next - This Integration)

🎯 Add --reasoningbank flag to memory command
🎯 Add mode detection and auto-selection
🎯 Add migration tools
🎯 Update help and documentation
🎯 Maintain full backward compatibility

Version 2.8.0 (Future)

🔮 Add hybrid mode (both simultaneously)
🔮 Add sync between basic ↔ ReasoningBank
🔮 Add cloud ReasoningBank sync

✅ Benefits

For Users

Smooth upgrade path: No forced changes
Choose your mode: Basic for simple, ReasoningBank for AI
Gradual migration: Try ReasoningBank without losing existing data
Performance options: Fast basic vs. smart ReasoningBank

For Development

Zero breaking changes: Existing code continues to work
Feature flag pattern: Easy to enable/disable
Independent testing: Test each mode separately
Clean architecture: Clear separation of concerns

🔌 MCP Tools Integration

Current MCP Tools

Existing (mcp__claude-flow__memory_usage)

javascript

// Current implementation - basic mode only
mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config",
  value: "some data"
})

Enhanced MCP Tools

Option 1: Add Mode Parameter

javascript

// Backward compatible - defaults to basic mode
mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config",
  value: "some data",
  mode: "basic"  // NEW: optional, defaults to "basic"
})

// Opt-in to ReasoningBank
mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config",
  value: "some data",
  mode: "reasoningbank"  // NEW: use AI-powered mode
})

// Auto-detect best mode
mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config",
  value: "some data",
  mode: "auto"  // NEW: intelligent selection
})

Option 2: Separate MCP Tools (Recommended)

Keep backward compatibility and add new tools:

javascript

// Existing tool - unchanged (basic mode)
mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config",
  value: "some data"
})

// NEW tool - ReasoningBank
mcp__claude-flow__reasoningbank_memory({
  action: "store",
  key: "api_config",
  value: "some data",
  domain: "api",           // NEW: semantic domain
  confidence: 0.8          // NEW: learning confidence
})

// NEW tool - semantic query
mcp__claude-flow__reasoningbank_query({
  query: "how to configure API",
  k: 3,                    // Top-k results
  min_confidence: 0.7      // Minimum confidence threshold
})

MCP Tool Schema Updates

Enhanced memory_usage tool:

json

{
  "name": "mcp__claude-flow__memory_usage",
  "description": "Store/retrieve memory with optional ReasoningBank mode",
  "parameters": {
    "action": {
      "type": "string",
      "enum": ["store", "retrieve", "list", "delete", "search"]
    },
    "key": { "type": "string" },
    "value": { "type": "string" },
    "namespace": { "type": "string" },
    "mode": {
      "type": "string",
      "enum": ["basic", "reasoningbank", "auto"],
      "default": "basic",
      "description": "Memory mode: basic (JSON), reasoningbank (AI), auto (detect)"
    },
    "ttl": { "type": "number" }
  }
}

NEW ReasoningBank-specific tools:

json

{
  "name": "mcp__claude-flow__reasoningbank_store",
  "description": "Store memory with AI learning (ReasoningBank)",
  "parameters": {
    "key": { "type": "string" },
    "value": { "type": "string" },
    "domain": {
      "type": "string",
      "description": "Semantic domain (e.g., 'api', 'security', 'performance')"
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Confidence score for this memory"
    },
    "metadata": {
      "type": "object",
      "description": "Additional metadata for learning"
    }
  }
}

MCP Usage Examples

Claude Desktop with ReasoningBank:

typescript

// In Claude Desktop conversation
"Store the API configuration I just learned"

// Claude Code MCP call (auto-detects mode):
await mcp__claude-flow__memory_usage({
  action: "store",
  key: "api_config_pattern",
  value: "Always use environment variables for API keys",
  mode: "auto"  // Will use ReasoningBank if initialized
})

// Later, in a new conversation:
"What did I learn about API configuration?"

// Claude Code MCP call:
await mcp__claude-flow__reasoningbank_query({
  query: "API configuration best practices",
  k: 3
})

// Returns semantic matches with confidence scores:
// 1. [0.92] Always use environment variables for API keys
// 2. [0.85] API keys should be in .env files
// 3. [0.78] Never commit API keys to git

MCP Integration Benefits

Zero Breaking Changes: Existing MCP calls work unchanged
Opt-In Enhancement: Add mode parameter to enable ReasoningBank
Intelligent Defaults: mode: "auto" detects best available
Specialized Tools: New tools for ReasoningBank-specific features
Cross-Session Learning: MCP tools persist across Claude Desktop sessions

MCP Tool Migration Path

typescript

// Phase 1: Current (v2.6.x)
mcp__claude-flow__memory_usage({ action: "store", ... })
// Always uses basic mode

// Phase 2: Enhanced (v2.7.0)
mcp__claude-flow__memory_usage({
  action: "store",
  mode: "auto",  // NEW parameter (optional)
  ...
})
// Auto-detects ReasoningBank if available

// Phase 3: Specialized (v2.7.0)
mcp__claude-flow__reasoningbank_store({
  key: "pattern",
  value: "learned behavior",
  domain: "coding",
  confidence: 0.9
})
// ReasoningBank-specific tool with full features

🎉 Summary

This integration adds ReasoningBank as an optional enhancement to core memory:

✅ Backward Compatible: Existing installations work unchanged ✅ Opt-In: Users choose when to enable ReasoningBank ✅ Auto-Detect: Intelligent mode selection with --auto ✅ Migration Tools: Easy upgrade path from basic to ReasoningBank ✅ Flexible: Use basic, ReasoningBank, or both based on needs ✅ Documented: Clear help text showing both modes ✅ MCP Integrated: Claude Desktop can use both memory modes seamlessly

Result: Best of both worlds - simple JSON storage OR AI-powered learning memory! 🚀