TaiDB

TaiDB is a small embeddable Rust key-value and vector database for local-first AI-native apps. It provides optional zstd compression, authenticated encryption, exact cosine vector search, a versioned storage header, a CLI, native FFI, and simple CLI bridges for other languages.

Use the Rust crate first:

cargo add taidb

Full documentation is available at https://mienetic.github.io/taiDB/.

Rust Quick Start

cargo new taidb-demo
cd taidb-demo
cargo add taidb

use taidb::{EngineConfig, Options};

fn main() -> taidb::Result<()> {
    let options = Options::builder().flush().zstd_fast().build();
    let mut db = EngineConfig::new("./app.taidb")
        .options(options)
        .open()?;

    db.put_text("user:1", "Alice")?;
    db.put_text("user:2", "Bob")?;
    db.put_vector("vec:1", &[0.1, 0.9, 0.2])?;
    db.put_vector("vec:2", &[0.9, 0.1, 0.1])?;

    for info in db.scan_prefix("user:", 10) {
        println!("{}", String::from_utf8_lossy(&info.key));
    }

    for hit in db.search_vector(&[0.0, 1.0, 0.2], 1)? {
        println!("{}\t{:.6}", String::from_utf8_lossy(&hit.key), hit.score);
    }

    drop(db);
    let mut readonly = EngineConfig::new("./app.taidb").read_only().open()?;
    assert_eq!(readonly.get_text("user:1")?, Some("Alice".to_string()));

    Ok(())
}

cargo run

CLI Quick Start

The crate also ships the taidb CLI:

cargo install taidb

taidb put ./app.taidb hello "world"
taidb get ./app.taidb hello
taidb vector-put ./app.taidb doc:1 "0.1,0.9,0.2"
taidb vector-search ./app.taidb "0.0,1.0,0.2" --limit 1
taidb stats ./app.taidb --json
taidb --read-only get ./app.taidb hello
taidb verify ./app.taidb
taidb compact ./app.taidb
taidb bench-compression ./compression-bench

Other Languages

For now, non-Rust languages can use the public CLI bridge for simple local apps and scripts. Install the TaiDB binary once:

cargo install taidb

Run the examples:

node examples/node/cli.mjs
python3 examples/python/cli_bridge.py
go run examples/go/cli_bridge.go
ruby examples/ruby/cli_bridge.rb
php examples/php/cli_bridge.php
sh examples/bash/cli_bridge.sh
javac -d /tmp/taidb-java examples/java/CliBridge.java && java -cp /tmp/taidb-java CliBridge

Node example:

import { spawnSync } from "node:child_process";

const db = "./node.taidb";
const binary = process.env.TAIDB_BIN || "taidb";

function taidb(...args) {
  const result = spawnSync(binary, args, { encoding: "utf8" });
  if (result.status !== 0) {
    throw new Error(result.stderr || result.error?.message || `taidb failed: ${args.join(" ")}`);
  }
  return result.stdout.trim();
}

taidb("put", db, "user:1", "Alice");
taidb("vector-put", db, "vec:1", "0.1,0.9,0.2");
taidb("vector-put", db, "vec:2", "0.9,0.1,0.1");

console.log(taidb("get", db, "user:1"));
console.log(taidb("vector-search", db, "0.0,1.0,0.2", "--limit", "1"));

make language-smoke

Native FFI

cargo build --release --features native-ffi

Artifacts:

• macOS: target/release/libtaidb.dylib
• Linux: target/release/libtaidb.so
• Windows: target/release/taidb.dll
• Header: include/taidb.h

Examples are in examples/ for Rust metadata stores, embedding caches, local document indexes, CLI bridges, Python, Go, Ruby, PHP, Bash, Java, TypeScript/Deno, and C.

cargo run --example metadata_store
cargo run --example embedding_cache
cargo run --example local_document_index
make language-smoke
make native-smoke

Development

make help
make check
make smoke
cargo publish --dry-run --allow-dirty
make docs-build

See ROADMAP.md for the path to 1.0.0.

Keep .env, build output, databases, benchmark output, and local agent state out of Git. The repository is intentionally source-only.