fathomdb

The Rust facade crate for FathomDB — a local-first, embedded retrieval engine for application and agent workloads, built on SQLite.

If you are writing a Rust application against FathomDB, this is the crate to depend on. It is a thin re-export of the public surface of fathomdb-engine, so you get one dependency and one import path instead of the workspace's internal crate split.

Status: pre-1.0, beta

The 0.8.x line is under active development. The public surface can change between minor releases, and scale/stability guarantees are staged for 0.9.x and later. Do not read the release engineering maturity of the 0.8.x publish pipeline as an API stability promise.

Install

cargo add fathomdb

Example

use fathomdb::{Engine, InitialState, PreparedWrite, SourceId};

let opened = Engine::open("./app.sqlite").expect("open");
let engine = opened.engine;

engine
    .write(&[PreparedWrite::Node {
        kind: "doc".to_string(),
        body: "the quick brown fox".to_string(),
        // Provenance is MANDATORY on every canonical row: `source_id` is the
        // axis `erase_source` erases on, so a row without one is unerasable.
        source_id: SourceId::new("import-2026-07").expect("valid source id"),
        logical_id: None,
        state: InitialState::Active,
        reason: None,
        valid_from: None,
        valid_until: None,
    }])
    .expect("write");

let result = engine.search("brown fox").expect("search");
println!("{} hit(s)", result.results.len());

engine.close().expect("close");

What the default surface gives you

With default features the crate exposes the governed application surface:

• open / close / drain, plus engine counters and a subscriber seam
• write of canonical nodes and edges, with mandatory source_id provenance
• hybrid retrieval — search, search_filter, search_reranked, search_explained, search_text_only, and graph-expanded search_expand
• read verbs — read_get, read_get_many, read_list, read_collection, read_mutations, graph_neighbors, crossed_boundary_since
• record lifecycle — transition, purge, erase_source
• declarative projections — configure_projections, read_projections

The default build is deliberately free of recovery-named and raw-SQL methods.

Cargo features

Embedder and GPU features (default-embedder, embed-cuda, embed-metal, default-reranker, rerank-cuda, rerank-metal) live on fathomdb-engine and are not forwarded through this facade.

Related crates

There are also Python (pip install fathomdb) and Node.js (npm install fathomdb) SDKs over the same engine.

License

MIT. See the LICENSE file shipped in this crate.

Source, issues and full documentation: https://github.com/coreyt/fathomdb