Architecture

🏗️ Deep dive into ReasonKit’s Biomimetic Architecture.

ReasonKit follows a biological design paradigm, splitting cognition into three distinct, specialized systems: the Brain (Logic), the Eyes (Sensing), and the Hippocampus (Memory). This separation allows for specialized performance optimization in each domain.

Biomimetic Architecture Overview

The system is composed of three primary modular components:

The Brain (reasonkit-core): Pure Rust. High-performance logic, orchestration, and critical path reasoning.
The Eyes (reasonkit-web): Python. The Sensing Layer. Handles “messy” inputs, web searching, MCP server integration, and multimodal data ingestion.
The Hippocampus (reasonkit-mem): Rust/Vector DB. The Semantic Memory. Manages long-term storage, retrieval, and context integration.

High-Level System Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     USER / CLI / API                            │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │                   │
                    │   reasonkit-core  │  <-- THE BRAIN (Rust)
                    │  (Orchestrator)   │
                    │                   │
                    └────┬─────────┬────┘
                         │         │
           ┌─────────────▼┐       ┌▼──────────────┐
           │              │       │               │
           │ reasonkit-web│       │ reasonkit-mem │
           │  (The Eyes)  │       │ (Hippocampus) │
           │   [Python]   │       │    [Rust]     │
           │              │       │               │
           └─────┬────────┘       └───────┬───────┘
                 │                        │
       ┌─────────▼─────────┐      ┌───────▼────────┐
       │   World / Web /   │      │  Vector Store  │
       │   MCP Servers     │      │   (Qdrant)     │
       └───────────────────┘      └────────────────┘

1. The Brain: `reasonkit-core`

This is the central nervous system. It is written in Rust for maximum reliability, type safety, and speed. It never communicates directly with the messy outside world (HTML, PDFs, APIs) without going through the “Eyes”, and it offloads storage complexity to “Memory”.

Core Components

CLI / Entry Point (`src/main.rs`)

The entry point parses arguments, loads configuration, and spins up the async runtime.

// Simplified structure
fn main() -> Result<()> {
    let args = Args::parse();
    let config = Config::load(&args)?;

    let runtime = Runtime::new()?;
    runtime.block_on(async {
        // The Brain orchestrates the request
        let result = orchestrator::run(&args.input, &config).await?;
        output::render(&result, &config.output_format)?;
        Ok(())
    })
}

Orchestrator (`src/thinktool/executor.rs`)

Coordinates the ThinkTool execution pipeline. It decides which tools to run based on the selected Reasoning Profile.

#![allow(unused)]
fn main() {
pub struct Executor {
    registry: Registry,
    profile: Profile,
    provider: Box<dyn LlmProvider>,
}

impl Executor {
    pub async fn run(&self, input: &str) -> Result<Analysis> {
        let tools = self.profile.tools();
        // ... execute tools in sequence or parallel ...
        self.synthesize(input, results).await
    }
}
}

ThinkTool Registry

Manages the available cognitive modules (ThinkTools).

#![allow(unused)]
fn main() {
pub fn new() -> Self {
    let mut tools = HashMap::new();
    tools.insert("gigathink".to_string(), Box::new(GigaThink::new()));
    tools.insert("laserlogic".to_string(), Box::new(LaserLogic::new()));
    tools.insert("bedrock".to_string(), Box::new(BedRock::new()));
    // ...
    Self { tools }
}
}

2. The Eyes: `reasonkit-web`

The Sensing Layer. Written in Python to leverage its rich ecosystem of data processing libraries (BeautifulSoup, Pandas, PyPDF2, etc.) and the Model Context Protocol (MCP).

Role: Ingests “messy” data from the real world.
Communication: Exposes an MCP (Model Context Protocol) server or local socket that reasonkit-core connects to.
Capabilities:
- Web scraping and cleaning.
- PDF / Doc / Image parsing.
- API integration (via MCP).

This layer acts as a Sanitizer. It takes raw, unstructured input and converts it into clean, structured text that the Brain can reason about safely.

3. The Hippocampus: `reasonkit-mem`

The Semantic Memory. Dedicated to efficient storage and retrieval.

Role: Long-term memory and context management.
Tech Stack: Qdrant (Vector DB) + Tantivy (Keyword Search).
Architecture:
- Short-term: In-memory context window management.
- Long-term: Vector embeddings for semantic search.
Interface: Provides a high-speed Rust API for reasonkit-core to query past interactions, documents, and learned facts.

Data Flow Example

User Input: “Analyze the latest stock trends for Company X based on this PDF.”
The Brain (core): Receives request. Identifies need for external data.
The Eyes (web): Brain delegates “Read PDF” task to reasonkit-web.
- web reads file, extracts text, performs OCR if needed.
- Returns clean text to Brain.
The Hippocampus (mem): Brain queries reasonkit-mem for “historical trends of Company X”.
- mem returns relevant past context.
Synthesis: Brain runs LaserLogic and GigaThink on the combined data (New PDF info + Historical Memory).
Output: Final structured analysis returned to user.

Supporting Modules

Processing Module (`src/processing/`)

Text processing utilities for document normalization and chunking.

#![allow(unused)]
fn main() {
use reasonkit::processing::{normalize_text, NormalizationOptions, ProcessingPipeline};

// Normalize text for indexing
let opts = NormalizationOptions::for_indexing();
let clean = normalize_text("  raw   text  ", &opts);

// Token estimation (~4 chars/token)
let tokens = estimate_tokens(text);

// Extract sentences and paragraphs
let sentences = extract_sentences(text);
let paragraphs = split_paragraphs(text);
}

Verification Module (`src/verification/`)

Cryptographic citation anchoring with ProofLedger.

#![allow(unused)]
fn main() {
use reasonkit::verification::ProofLedger;

let ledger = ProofLedger::new("proofledger.db")?;
let hash = ledger.anchor(claim, source_url, metadata)?;
ledger.verify(&hash)?;
}

Uses SQLite with SHA-256 hashing for immutable audit trails.

Telemetry Module (`src/telemetry/`)

Privacy-first telemetry with GDPR compliance.

#![allow(unused)]
fn main() {
use reasonkit::telemetry::{TelemetryConfig, PrivacyConfig};

let config = TelemetryConfig {
    enabled: false,           // Opt-in by default
    privacy: PrivacyConfig::strict(),
    community_contribution: false,
    retention_days: 90,
    // ...
};
}

Features:

Opt-in by default — No data collection without consent
PII stripping — Automatically removes sensitive information
Differential privacy — Optional noise addition for aggregates
Local-only storage — Data stays on your machine

Benchmark System (`src/bin/bench.rs`)

Reproducible reasoning evaluation.

# Built-in benchmarks
rk bench arc-c          # 10 ARC-Challenge science problems

# Custom benchmarks
REASONKIT_CUSTOM_BENCHMARK=./problems.json rk bench custom

Benchmark JSON format:

[
  {
    "id": "custom-001",
    "question": "What is 2 + 2?",
    "expected": "4",
    "category": "math",
    "difficulty": 1
  }
]

Results include per-category and per-difficulty accuracy metrics.

Extension Points

Adding a New ThinkTool (Brain)

Implement the ThinkTool trait in Rust.
Register it in the Registry.

#![allow(unused)]
fn main() {
#[async_trait]
impl ThinkTool for MyTool {
    fn name(&self) -> &str { "MyTool" }
    fn alias(&self) -> &str { "mt" }
    async fn execute(&self, input: &str, provider: &dyn LlmProvider) -> Result<ToolResult> {
        // Logic here
    }
}
}

Adding a New Sense (Eyes)

Add a new Python module in reasonkit-web.
Expose it via the MCP interface.

Adding Memory Capabilities (Hippocampus)

Extend the schema in reasonkit-mem.
Update the embedding strategy.

Integration Patterns — Embedding ReasonKit
LLM Providers — Provider details
Contributing — Contributing guide

Keyboard shortcuts

ReasonKit Documentation