github.com/brainfish-ai/ReasonDB @v0.5.10

<img src="https://github.com/brainfish-ai/ReasonDB/raw/v0.5.10/assets/logo.svg" alt="ReasonDB" width="140" />

AI-Native Document Intelligence

The database that understands your documents.


Built for AI agents that need to reason, not just retrieve.











<a href="https://github.com/reasondb/reasondb/releases"><img src="https://img.shields.io/github/v/release/reasondb/reasondb?color=6C5CE7&include_prereleases&label=version&sort=semver&style=flat-square" alt="Version"></a>
&nbsp;
<a href="https://github.com/reasondb/reasondb"><img src="https://img.shields.io/badge/built_with-Rust-dca282.svg?style=flat-square" alt="Built with Rust"></a>
&nbsp;
<a href="https://github.com/reasondb/reasondb/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/reasondb/reasondb/ci.yml?style=flat-square&branch=main&label=CI" alt="CI"></a>
&nbsp;
<a href="https://github.com/reasondb/reasondb/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-ReasonDB_v1.0-00bfff.svg?style=flat-square" alt="License"></a>







<a href="https://hub.docker.com/r/brainfishai/reasondb"><img src="https://img.shields.io/docker/pulls/brainfishai/reasondb?label=docker%20pulls&style=flat-square" alt="Docker Pulls"></a>
&nbsp;
<a href="https://github.com/reasondb/reasondb"><img src="https://img.shields.io/github/stars/reasondb/reasondb?color=FFD700&style=flat-square&label=stars" alt="GitHub Stars"></a>
&nbsp;
<a href="https://github.com/reasondb/reasondb"><img src="https://img.shields.io/github/downloads/reasondb/reasondb/total?color=8259dd&label=downloads&style=flat-square" alt="Downloads"></a>







<a href="https://reason-db.devdoc.sh">Docs</a>
&nbsp;&bull;&nbsp;
<a href="https://reason-db.devdoc.sh/documentation/page/quickstart">Quick Start</a>
&nbsp;&bull;&nbsp;
<a href="https://reason-db.devdoc.sh/api-reference/introduction">API Reference</a>







<sub>&#9888;&#65039; <strong>Alpha Release</strong> &mdash; ReasonDB is under active development. APIs and features may change. We'd love your <a href="https://github.com/reasondb/reasondb/issues">feedback</a>!</sub>

What is ReasonDB?

ReasonDB is an AI-native document database built in Rust, designed to go beyond simple retrieval. While traditional databases and vector stores treat documents as data to be indexed, ReasonDB treats them as knowledge to be understood - preserving document structure, enabling LLM-guided traversal, and extracting precise answers with full context.

ReasonDB introduces Hierarchical Reasoning Retrieval (HRR), a fundamentally new architecture where the LLM doesn't just consume retrieved content - it actively navigates your document structure to find exactly what it needs, like a human expert scanning summaries, drilling into relevant sections, and synthesizing answers.

ReasonDB is not another vector database. It's a reasoning engine that preserves document hierarchy, enabling AI to traverse your knowledge the way a domain expert would.

Key features of ReasonDB include:

• Hierarchical Reasoning Retrieval: LLM-guided tree traversal with parallel beam search - AI navigates document structure instead of relying on similarity matching
• RQL Query Language: SQL-like syntax with built-in SEARCH (BM25) and REASON (LLM) clauses in a single query
• Plugin Architecture: Extensible extraction pipeline - PDF, Office, images, audio, and URLs out of the box via MarkItDown
• Multi-Provider LLM Support: Anthropic, OpenAI, Gemini, Cohere, Vertex AI, AWS Bedrock, and more — switch providers without code changes
• Production Ready: ACID-compliant storage, API key auth, rate limiting, async parallel traversal - all in a single Rust binary

Contents

• What is ReasonDB?
• The Problem
• Benchmark
• Insurance Policy Analyser — Live Demo
• How It Works
• Quick Start
• Interactive Tutorials
• Query with RQL
• Plugin Architecture
• Use Cases
• Tech Stack
• Documentation
• Community
• Contributing
• License

The Problem

AI agents today are limited by their databases:

The result? AI agents that hallucinate, miss critical context, or drown in irrelevant chunks.

ReasonDB solves this by letting the LLM reason through your documents - not just search them.

Benchmark

Results on a real-world insurance document corpus (4 policy documents, ~1,900 nodes, 12 queries across 6 complexity tiers). Full benchmark script: tutorials/data/insurance/benchmark.py.

Retrieval quality vs. typical RAG

"Typical RAG" = chunked-retrieval pipelines (LlamaIndex / LangChain defaults) on the same corpus. ReasonDB uses BM25 candidate selection + LLM-guided hierarchical tree traversal instead of flat similarity matching.

Per-category breakdown

Cross-section reference retrieval

ReasonDB detects and follows intra-document cross-references during ingestion (LLM-extracted during summarization) and surfaces the referenced sections alongside primary results. This closes the "answer is split across two clauses" gap that defeats flat-chunk retrieval.

Insurance Policy Analyser — Live Demo

The benchmark above is powered by this tutorial app. It queries four insurance policy documents using REASON and shows the full traversal trace — which nodes the LLM visited, why it selected them, and how it synthesized the final answer.

Full tutorial source: tutorials/06-insurance/

How It Works

%%{init: {'theme': 'dark'}}%%
flowchart TD
    subgraph Ingestion["Ingestion Pipeline (Plugin-Driven)"]
        A["Documents / URLs"] -->|Extractor Plugin| B["Markdown"]
        B -->|Post-Processor Plugin| C["Cleaned Markdown"]
        C -->|Chunker| D["Semantic Chunks"]
        P["Pre-chunked JSON"] -->|"bypasses extract + chunk"| D
        D --> E["Build Hierarchical Tree"]
        E -->|Bottom-up| F["LLM Summarizes Each Node"]
    end

    subgraph Search["Search & Reasoning"]
        G["Natural Language Query"] --> G1["BM25 Candidates + Title Boost"]
        G1 --> G2["Recursive Tree-Grep Pre-Filter"]
        G2 --> H["LLM Ranks by Summaries + Match Signals"]
        H -->|Selects relevant branches| I["Traverse Tree"]
        I -->|Parallel beam search| J["Drill Into Leaf Nodes"]
    end

    subgraph Result["Response"]
        J --> K["Extract Answer"]
        K --> L["Confidence Score + Reasoning Path"]
    end

    Ingestion --> Search

1. Extract - Extractor plugins convert documents and URLs to Markdown (built-in: MarkItDown)
2. Chunk - Content is split into semantic chunks with heading detection — or bypass entirely with pre-chunked JSON via /ingest/chunks
3. Build Tree - Chunks are organized into a hierarchical tree structure, preserving per-chunk metadata (page numbers, line ranges, custom attributes)
4. Summarize - LLM generates summaries for each node (bottom-up); pre-supplied summaries are used as-is
5. Search - 4-phase pipeline: BM25 candidate selection → recursive tree-grep filtering → LLM summary ranking → parallel beam-search traversal
6. Return - Relevant content with extracted answers, confidence scores, and the full reasoning path

Quick Start

Get from zero to intelligent document search in under 5 minutes.

Download pre-built binaries

Grab the latest release for your platform:

ReasonDB Client: A desktop app is also available for macOS (.dmg) and Windows (.msi).

macOS: "ReasonDB.app" Not Opened

Since ReasonDB is in alpha, the desktop app is not yet signed with an Apple Developer certificate. macOS Gatekeeper will block it on first launch. To open it:

1. Right-click (or Control-click) on ReasonDB.app and select Open
2. Click Open in the confirmation dialog

Or remove the quarantine attribute from the terminal:

xattr -cr /Applications/ReasonDB.app

You can also go to System Settings → Privacy & Security, scroll down, and click Open Anyway next to the ReasonDB message.

Install with Homebrew (macOS / Linux)

brew tap brainfish-ai/reasondb-tap
brew install reasondb

Install with one line (macOS / Linux)

No Homebrew? Download and install directly:

# macOS Apple Silicon
curl -L https://github.com/brainfish-ai/reasondb/releases/latest/download/reasondb-$(curl -s https://api.github.com/repos/brainfish-ai/reasondb/releases/latest | grep tag_name | cut -d'"' -f4)-aarch64-apple-darwin.tar.gz | tar -xz && sudo mv reasondb /usr/local/bin/

# Linux x86_64
curl -L https://github.com/brainfish-ai/reasondb/releases/latest/download/reasondb-$(curl -s https://api.github.com/repos/brainfish-ai/reasondb/releases/latest | grep tag_name | cut -d'"' -f4)-x86_64-unknown-linux-gnu.tar.gz | tar -xz && sudo mv reasondb /usr/local/bin/

Install from source

git clone https://github.com/reasondb/reasondb.git && cd reasondb
cargo build --release

To also set up the desktop app and tutorials, install JS dependencies from the repo root:

yarn install          # installs apps/, packages/, and tutorials/ in one step
yarn build:packages   # builds the shared @reasondb/rql-editor package

Configure your LLM provider

reasondb config init

Start the server

reasondb serve

Server starts at http://localhost:4444 with Swagger UI at http://localhost:4444/swagger-ui/

Run using Docker

docker run --rm --pull always --name reasondb -p 4444:4444 \
  -e REASONDB_LLM_PROVIDER=openai \
  -e REASONDB_LLM_API_KEY=sk-... \
  brainfishai/reasondb:latest serve

Or use the Makefile for local development:

make docker-up        # Build and start
make docker-up-d      # Start in background
make docker-logs      # View logs
make docker-down      # Stop containers
make docker-down-v    # Stop and remove data volume
make docker-ps        # Check health status

ReasonDB Client (Desktop App)

The repo uses a Yarn workspace — a single yarn install at the root installs all JS dependencies across apps/, packages/, and tutorials/.

# One-time setup from repo root
yarn install
yarn build:packages   # build the shared @reasondb/rql-editor package

# Run the desktop app
make client-app          # dev mode (Tauri + Vite)
make client-app-build    # production build

# Or use yarn workspace commands directly
yarn workspace reasondb-client dev         # Vite web dev server only
yarn workspace reasondb-client tauri dev   # full Tauri desktop app (dev)
yarn workspace reasondb-client build       # production build

Interactive Tutorials

Six hands-on tutoria