Inillucent

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:

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

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:

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. ↩ ↩² ↩³