🧠 ReasoningBank

Adaptive self-learning reasoning system with embedded storage and QUIC neural bus

ReasoningBank is a high-performance, self-learning AI reasoning system that learns from experience and improves over time. It combines pattern recognition, adaptive strategy optimization, and distributed neural communication to build smarter AI agents.

---

🎯 What is ReasoningBank?

For Non-Technical Users:

Think of ReasoningBank as a "memory and learning system" for AI. Just like humans learn from experience and get better at tasks over time, ReasoningBank helps AI systems:

• Remember what worked and what didn't in past tasks
• Learn from successful strategies and avoid repeating mistakes
• Adapt by automatically choosing the best approach for new challenges
• Share knowledge efficiently across distributed AI agents

It's like giving your AI a notebook, a teacher, and a communication system all in one.

For Technical Users:

ReasoningBank is a Rust-based adaptive learning framework that provides:

• Pattern Storage: Embedded SQLite with WAL mode, connection pooling, and optimized queries
• Adaptive Learning: Cosine similarity-based pattern matching, strategy scoring, and confidence-weighted recommendations
• Neural Bus: QUIC-based communication protocol with Ed25519-signed intent-capped actions, stream multiplexing, and gossip protocols
• Async-First Design: Actor pattern for thread-safe async operations with message-passing architecture
• MCP Integration: Full Model Context Protocol server with tools and resources for AI agent coordination

---

✨ Features

🎓 Core Learning Capabilities

• Pattern Recognition: Stores and retrieves task patterns with vector embeddings
• Similarity Matching: Cosine and Euclidean distance algorithms for finding relevant experiences
• Strategy Optimization: Automatically identifies and recommends successful strategies
• Success Tracking: Confidence-weighted success rates and outcome analysis
• Adaptive Recommendations: Context-aware strategy suggestions based on task characteristics

💾 High-Performance Storage

• Embedded SQLite: Zero-configuration, file-based or in-memory storage
• Connection Pooling: Efficient multi-threaded access with Parking Lot synchronization
• Write-Ahead Logging (WAL): Concurrent reads during writes for maximum throughput
• Optimized Queries: Indexed searches, prepared statements, and efficient similarity calculations
• Migration System: Automatic schema versioning and upgrades

🚀 QUIC Neural Bus

• 0-RTT Connections: Sub-millisecond connection establishment
• Stream Multiplexing: Parallel data streams without head-of-line blocking
• Intent-Capped Actions: Ed25519-signed authorization with spend caps and scope restrictions
• Reasoning Streams: Separate channels for tokens, traces, rubrics, and verification
• Gossip Protocol: Decentralized knowledge sharing across agent networks
• Snapshot Streaming: Efficient large-state transfer with chunking

🔧 Developer Experience

• Async/Await Support: Full Tokio integration with spawn_blocking for sync operations
• Actor Pattern: Thread-safe message passing eliminates Send/Sync issues
• Type-Safe API: Strongly-typed interfaces with comprehensive error handling
• MCP Tools: Ready-to-use server with pattern storage, retrieval, analysis, and optimization tools
• Extensive Tests: 60+ unit and integration tests with 90%+ coverage
• Performance Benchmarks: Criterion-based benchmarking for storage, learning, and neural bus operations

---

📦 Installation

Add ReasoningBank to your Cargo.toml:

[dependencies]
reasoningbank-core = "0.1.0"          # Core reasoning engine
reasoningbank-storage = "0.1.0"       # SQLite storage layer
reasoningbank-learning = "0.1.0"      # Adaptive learning system
reasoningbank-network = "0.1.0"       # QUIC neural bus
reasoningbank-mcp = "0.1.0"          # MCP server integration

Requirements

• Rust: 1.70 or later
• OS: Linux, macOS, Windows (SQLite bundled for all platforms)
• Features: tokio async runtime, rusqlite with bundled SQLite

---

🚀 Quick Start

Basic Pattern Storage and Learning

use reasoningbank_core::{Pattern, TaskOutcome, ReasoningEngine, EngineConfig};
use reasoningbank_learning::{AdaptiveLearner, LearningConfig};
use reasoningbank_storage::{SqliteStorage, StorageConfig};
use std::path::PathBuf;

fn main() -> anyhow::Result<()> {
    // Initialize storage
    let storage_config = StorageConfig {
        database_path: PathBuf::from("reasoningbank.db"),
        max_connections: 10,
        enable_wal: true,
        cache_size_kb: 8192,
    };
    let storage = SqliteStorage::new(storage_config)?;

    // Create reasoning engine and learner
    let engine = ReasoningEngine::new(EngineConfig::default());
    let mut learner = AdaptiveLearner::new(
        engine,
        storage,
        LearningConfig::default(),
    );

    // Store a successful task pattern
    let pattern = Pattern::new(
        "Implement REST API endpoint".to_string(),
        "backend_development".to_string(),
        "test_driven_development".to_string(),
    ).with_outcome(TaskOutcome::success(0.95));

    let insight = learner.learn_from_task(&pattern)?;
    println!("Learning insight: {:?}", insight);

    // Get recommendations for a new task
    let applied = learner.apply_learning(
        "Build a new API endpoint",
        "backend_development",
    )?;

    println!("Recommended strategy: {}", applied.recommended_strategy);
    println!("Confidence: {:.2}%", applied.confidence * 100.0);

    Ok(())
}

---

📚 Documentation

Architecture Overview

ReasoningBank uses a modular architecture with six primary crates:

• reasoningbank-core: Core reasoning engine with pattern matching
• reasoningbank-storage: SQLite storage layer with connection pooling
• reasoningbank-learning: Adaptive learning system with similarity matching
• reasoningbank-network: QUIC neural bus with intent verification
• reasoningbank-mcp: MCP server with tools and resources
• reasoningbank-wasm: WASM bindings (placeholder for future web support)

Performance

Based on Criterion benchmarks:

• Storage: ~200-300 µs per pattern storage, ~50-100 µs per lookup
• Learning: ~2.6 ms per learning operation, ~4.7 ms per recommendation
• Neural Bus: ~5-10 µs per frame encode/decode (1KB payload)

---

🧪 Testing

# Run all tests
cargo test --all-features

# Run benchmarks
cargo bench

# Generate benchmark HTML reports
cargo bench -- --save-baseline baseline-v1

Test Coverage: 60+ tests across all crates with 90%+ coverage

---

🤝 Contributing

Contributions are welcome! Please:

• Write tests for new features
• Run cargo fmt and cargo clippy before committing
• Update documentation for API changes
• Add benchmarks for performance-critical code

---

📄 License

Dual-licensed under MIT or Apache-2.0 at your option.

---

🙏 Acknowledgments

Built with Rust, SQLite, Quinn, Tokio, and Criterion.

---

_{Built with ❤️ by the ReasoningBank contributors}