black-rainbow-labs / inillucent

v2.8.1 2026-10-17 09:58 UTC

Requires

• php: >=8.1
• ext-json: *

Suggests

• ext-ffi: Lets a future in-process binding load the C ABI directly. The CLI wrapper needs nothing beyond ext-json.

MIT

• Black Rainbow Labs

• database
• sql
• search
• sqlite
• vector
• mcp
• embedding
• rag

Published on Packagist.org on 2026-10-17 09:58 UTC

README

A fast embedded database for AI agents.

Inillucent is an embedded SQL database written in Rust. It speaks SQLite's SQL, and it has vector search and keyword search built in. Everything lives in one file.

inillucent.com  ·  Documentation  ·  Install  ·  Client libraries

Features

• SQLite's SQL dialect. 402 of 416 probed SQL cases give SQLite's exact answer. A PostgreSQL dialect is on the roadmap.
• A storage engine written from scratch in Rust.
• Faster than SQLite on 110 of the 116 workloads its benchmark times, and 499% faster overall in a graded run of release 2.5.4. Reads by key are 3,304% faster.¹
• 297% faster than SQLite through the Connection API on 48 common and edge case workloads, using 66% less processor time.²
• 74% faster than SQLite when called the way programs call it: 418% faster from Node, 135% from Python and 49% through scripts piped into the shell.³
• 174% faster than PostgreSQL with pgvector for semantic search.⁴
• 302% better than PostgreSQL full text search at finding identifiers.⁴
• A command line and an MCP server with the same commands.
• A write ahead log and crash recovery, tested by cutting the power at every step of a commit.
• Vector columns, HNSW indexes and an embedding model that runs inside your process.
• One database file that several processes can use at the same time.
• Encryption at rest with XChaCha20-Poly1305, for the database file, its log and its journals.

Documentation

The full guide is at inillucent.com/docs. The pages in this repository are listed in docs/README.md. Good places to start:

Page	What it covers
Product overview	what Inillucent is and who it is for
Getting started	installing, the four programs, your first database
Glossary	the database and search terms the pages use
SQL support	what runs, and where it differs from SQLite
Vector search	vector columns, HNSW indexes, keyword search and hybrid ranking
Embeddings	running the embedding model inside your process
Migrating	moving in from SQLite, PostgreSQL or MySQL
Encryption at rest	keys, what is encrypted, and what it costs
Performance	speed, processor time and memory against SQLite
Retrieval quality	search quality and speed against PostgreSQL with pgvector
AGENTS.md	the starting point for an AI agent that uses or changes this repository

Install

Windows

irm https://inillucent.com/downloads/install.ps1 | iex

macOS and Linux

curl -fsSL https://inillucent.com/downloads/install.sh | sh

Both scripts check the download against the published SHA256SUMS, install into your home directory, and need no administrator rights.

Package managers

Manager	Command
Homebrew	brew install black-rainbow-labs/inillucent/inillucent
npm	npm install -g inillucent
pip	pip install inillucent
Go	go install github.com/Black-Rainbow-Labs/Inillucent/packages/go/v2/cmd/inillucent-install@latest && inillucent-install
Composer	composer require black-rainbow-labs/inillucent && vendor/bin/inillucent-install
cargo	cargo install inillucent-cli inillucent-migrate. For the embed() function, run cargo install inillucent-cli --features embed

A signed macOS installer, .deb and .rpm packages, and plain archives for every platform are on inillucent.com and the GitHub release. To check a download by hand:

minisign -Vm SHA256SUMS -p inillucent.pub     # inillucent.com/downloads/inillucent.pub
sha256sum -c SHA256SUMS --ignore-missing

Your first database

inillucent create app.rdb
inillucent --db app.rdb exec "CREATE TABLE note (id INTEGER PRIMARY KEY, body TEXT)"
inillucent --db app.rdb exec "INSERT INTO note (body) VALUES (?1)" --params '["hello"]'
inillucent --db app.rdb query "SELECT * FROM note" --output json

Every install gives you four programs:

Program	What it does
inillucent	the command line, with --output json on every command
inillucent-shell	an interactive shell that works like sqlite3
inillucent-mcp	an MCP server, so an AI agent can use a database with no code written
inillucent-migrate	builds a database from a legacy retrieval index. inillucent migrate copies a SQLite file, a PostgreSQL database or a MySQL database

What it does

Your SQLite, faster

Your SQLite queries, schemas and sqlite3 scripts run unchanged: joins, recursive CTEs, window functions, triggers, foreign keys, upserts, RETURNING, JSON, FTS5 and more. The storage engine under that SQL is written from scratch in Rust. It is faster than SQLite on 110 of 116 benchmark workloads and 499% faster overall,¹ and through the API a program calls it uses 66% less processor time than SQLite.² SQL support

Search by meaning and by keyword

Store embeddings in a VECTOR(768) column, index them with HNSW, and order results by vector_distance_cos. Keyword search with BM25 is in the same file. One query can combine the two, so an agent finds "how does the release process work" and PROJ-1932 with the same call. Semantic search is 174% faster than PostgreSQL with pgvector, and finding identifiers is 302% better than PostgreSQL full text search.⁴ Vector search

A search that can come back empty

Most search engines return their ten closest matches even when nothing in the data answers the question. An agent then writes a confident answer from those matches. Inillucent gives every result a confidence score, so a search with no good answer returns nothing. On 200 questions with no answer, PostgreSQL with pgvector returned a result every time. Inillucent returned one for 1 of the 200. Retrieval quality

The embedding model runs inside your process

inillucent setup-embeddings all downloads the embedding model once. After that, embed('some text') works in any SQL statement. There is no embedding server to deploy or keep running. Embeddings

One file, many processes

Tables, vector indexes and keyword indexes all live in one .rdb file, and they commit and roll back together. Several processes can open the file at the same time. One process writes at a time, and another writer waits for up to PRAGMA busy_timeout, which is 5 seconds by default. Readers do not wait for a write transaction; they read the last committed state. Architecture in one page

Encrypted on disk

Open a database with a key and every file it writes is encrypted: the database file, the log and the journals. A changed byte is found on the next read. The key comes from a file or from the INILLUCENT_KEY environment variable, and inillucent encrypt writes an encrypted copy of a database you already have. Encryption at rest

Bring your data with you

inillucent migrate copies a SQLite file, a PostgreSQL database or a MySQL database into Inillucent. It never writes to the source. It checks every table by row count and by checksum, and it publishes the new file only when every check passes. Migrating

A first search

examples/rag-agent/cli-example/ holds a ready made database of Greek philosophy: 80 Wikipedia articles split into 2,661 passages, each with its embedding. Install the embedding model and ask a question:

inillucent setup-embeddings all

inillucent --db examples/rag-agent/cli-example/greek-philosophy.rdb query \
  "SELECT title, body FROM passage
   ORDER BY vector_distance_cos(v, embed('search_query: ' || ?1)) LIMIT 5" \
  --params '["who was Seneca"]'

examples/rag-agent/rust-example/ serves the same articles to an agent through an MCP server written in Rust, which chunks, embeds and syncs them itself. examples/todo-mvc/ is a todo service with a REST API in Rust, whose SQL uses foreign keys that cascade, triggers, recursive CTEs, window functions and FTS5. examples/coffee-shop/ is a coffee shop's till and back office, with orders, stock and double entry books kept by triggers. examples/ describes every example.

For AI agents

To give an agent a database over MCP:

{
  "mcpServers": {
    "inillucent": {
      "command": "inillucent-mcp",
      "args": ["--db", "app.rdb"]
    }
  }
}

Add --readonly to refuse every statement that changes data. Add --root DIR to refuse any file outside one directory.

agent-skills/ has a skill for each common job: installing, querying, searching, migrating, putting Inillucent in an application, and troubleshooting. Each skill is a plain SKILL.md file. Claude Code loads skills from ~/.claude/skills, and any other agent can read them as Markdown.

Client libraries

From Node, the npm package runs a query and returns rows as objects:

import { query } from 'inillucent';

const rows = await query('SELECT id, body FROM note WHERE id > ?1', { db: 'app.rdb', params: [0] });

From Python, the pip package runs the engine inside your process:

from inillucent import Database

with Database("app.rdb") as database:
    rows = database.connect().execute("SELECT id, body FROM note")

The Go and PHP packages have the same kind of query call. The Node, Go and PHP packages, and the Python query and run functions, run the inillucent program and read its JSON output. The Python Database class calls the C library directly, which ships in each archive with its header. The driver page documents the C library for anyone writing a new binding. Client libraries for TypeScript, Rust, Java and C# are being built in inillucent-clients and are not on a package registry yet.

Licence

MIT. See LICENSE.

Footnotes

1. Measured against SQLite 3.53.4, built from the official source and run as a separate program over the same data, with the same SQL, the same durability setting and the same cache size. Thirty paired rounds, three runs in a row, at 100,000 rows on Windows x64, on 11 October 2026 with release 2.5.4, with both programs on the same eight performance cores. Every run was graded: SQLite ran within 2% of its idle reference. Overall: 499% faster, the weighted geometric mean across ten families of work, with a 95% lower bound of 459%. Reads by key: 3,304% faster. Every result is hashed and compared with SQLite's before its time counts. Of the 116 workloads timed through the engine's API and through the Connection API, 110 are faster than SQLite. Of the six that are not, one pays for folding the log into the database file, one compiles SELECT 1 on every call through an API no program uses, and four are within 6% of SQLite. Performance names each one and says why, and Performance history has every earlier run. ↩ ↩²

2. Measured on 11 October 2026 with release 2.5.4, through Connection::prepare and Statement::step, the API every driver calls, on 48 workloads at 100,000 rows: rows written by INSERT, tables that churn, queries applications write and edge cases. 47 of the 48 are faster than SQLite. The 28 training workloads are 297% faster than SQLite and the 20 held out workloads 266% faster. One round took 641 ms of processor time against 1,906 ms for SQLite, 66% less. On 3 October 2026 release 2.1.1 was 18% slower than SQLite on the same workloads and used 115% more processor time. Performance has the figures. ↩ ↩²

3. Measured on 8 October 2026 with release 2.4.2, over 25 workloads called the way programs call each engine: one process per command, a SQL script piped into the shell, the Python driver and the npm package, against the sqlite3 3.53.4 shell, Python's sqlite3 module and Node's node:sqlite. Fifteen rounds, each engine with its own default settings. The command line is 6% faster than SQLite, because starting a program costs both engines the same and is most of a short command. Performance has every workload. ↩

4. Graded on 20 September 2026 against PostgreSQL with pgvector over a corpus of 185,078 passages at 768 dimensions. Both engines were loaded with the same vectors and given the same embedded query. Semantic search: a median of 0.85 ms against 2.32 ms for the faster of two pgvector configurations, 174% faster. Keyword search on identifiers: mean reciprocal rank 0.546 against 0.136 for PostgreSQL full text search, 302% better. Of 17 graded comparisons, Inillucent was better on 15, equivalent on 1, inconclusive on 1 and worse on none. Retrieval quality has the full table. ↩ ↩² ↩³