Download the PHP package black-rainbow-labs/inillucent without Composer

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.
• 419% faster than SQLite overall, and 3,061% faster on reads by key.[^1]
• 174% faster than PostgreSQL with pgvector for semantic search.[^3]
• 302% better than PostgreSQL full text search at finding identifiers.[^3]
• 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.

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

macOS and Linux

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:

Your first database

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 runs 419% faster than SQLite overall and 3,061% faster on reads by key,[^1] and it uses 67% less processor time.[^2] 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.[^3] 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 the others wait for up to PRAGMA busy_timeout, which is 5 seconds by default. Architecture in one page

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:

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/ describes every example.

For AI agents

To give an agent a database over MCP:

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:

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

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.

[^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, four runs in a row, at 100,000 rows on Windows x64, on 26 September 2026 with release 1.0.32, with both programs on the same eight performance cores. Overall: 419% faster, the weighted geometric mean across ten families of work, with a 95% lower bound of 405%. Reads by key: 3,061% faster. Every result is hashed and compared with SQLite's before its time counts. Five of the thirty workloads are slower than SQLite. Performance names each one.

[^2]: Processor time was 344 ms against 1,043 ms for SQLite for one round of the same plan at 100,000 rows, on 26 September 2026.

[^3]: 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.