For AI agents

Read this before generating a call to Persia or a patch against the repo. The design contract is SPEC.md. If a page on this site disagrees with the SPEC, the SPEC wins. Machine-readable copies of these pages: llms.txt and llms-full.txt.

Status

Pre-alpha. 321 of 521 roadmap leaves done (62%) in the 2026-11-05 PROGRESS.md snapshot, with 0 marked in progress. The live counter is PROGRESS.md. Do not treat a number on an older page as newer than that file.

Persia DB is pre-alpha. The public persia crate has no Db::open. persia-engine can put, delete, and commit a document. persia-engine runs a ranked search over a collection snapshot: BM25F, filters, sorts, facets, and pages. persia-format implements the on-disk codecs (M1 done, 53/53). persia-storage implements the Storage trait, memory and local-file backends, and the single-file container (M2 done, 46/46). S3, GCS, and Azure have not been started (M12). persia-engine implements collection schema, documents, and manifests (M3 done, 15/15) and a segment builder, writer, and reader (M5 done, 48/48). Its write path is in progress (M6, 49/58): a memtable, a WAL with chunks, group commit, and replay, flush, commit, snapshots, auto-commit, and open checks, deletes and upserts across segments with tombstone sidecars, and segment merging (a merge policy, a segment merger, a background scheduler, and deletion of obsolete objects). Its query path is in progress (M7, 46/51): a query AST, user-text compiler, filter DSL, and query limits, collection statistics (document count, document frequency, average field length), BM25F scoring with static rank and score bounds, matching and score top-k over one view, and a collection search with sorts, pages, facets, and stored fields (CollectionViews::search). Relaxation has not been started (M8). A collection snapshot can be searched as library code. There is no search call on the database handle. persia-analysis implements tokenizers and the built-in analyzers de, en, es, fr, it, keyword, pt, standard, and whitespace (M4 done, 29/29). It does not search. persia-blob exports no API (M9 not started; its dependencies are done). The public persia crate exports no Db and no Collection. The crates are unpublished (publish = false, version 0.0.0). The on-disk format is unstable until v1.0 (SPEC §15).

Question	Answer
Usable database API?	No. The public persia crate exports no Db and no Collection. A search runs only through persia-engine (CollectionViews::search). The crates are unpublished (publish = false, version 0.0.0).
Published on crates.io?	No. publish = false.
CLI?	File sweep (container / store files and sweep), plus inspect segment and dump segment (--verify on inspect). Not compact, import, or search.
Working library code?	persia-format implements the on-disk codecs (M1 done, 53/53). persia-storage implements the Storage trait, memory and local-file backends, and the single-file container (M2 done, 46/46). S3, GCS, and Azure have not been started (M12). persia-engine implements collection schema, documents, and manifests (M3 done, 15/15) and a segment builder, writer, and reader (M5 done, 48/48). Its write path is in progress (M6, 49/58): a memtable, a WAL with chunks, group commit, and replay, flush, commit, snapshots, auto-commit, and open checks, deletes and upserts across segments with tombstone sidecars, and segment merging (a merge policy, a segment merger, a background scheduler, and deletion of obsolete objects). Its query path is in progress (M7, 46/51): a query AST, user-text compiler, filter DSL, and query limits, collection statistics (document count, document frequency, average field length), BM25F scoring with static rank and score bounds, matching and score top-k over one view, and a collection search with sorts, pages, facets, and stored fields (CollectionViews::search). Relaxation has not been started (M8). A collection snapshot can be searched as library code. There is no search call on the database handle. persia-analysis implements tokenizers and the built-in analyzers de, en, es, fr, it, keyword, pt, standard, and whitespace (M4 done, 29/29). It does not search. persia-blob exports no API (M9 not started; its dependencies are done). The public persia crate exports no Db and no Collection. The crates are unpublished (publish = false, version 0.0.0).
Next work?	The ready-next list in PROGRESS.md.
First callable release?	The first release a caller is supposed to use is v0.1 (M10). That milestone is blocked on M6 (in progress), M7 (in progress), M8 (not started), and M9 (not started).

The walkthrough with the illustrative calls, and the FAQ, is Getting started.

Do not invent these calls

The following names appear in the SPEC and the README. persia_engine::db::Database has open, create_collection, put, put_batch, delete, and commit. CollectionSnapshot::get fetches one document by id. CollectionViews::search runs a ranked search over a collection snapshot. There is no persia::Db, no search on the database handle, no put_struct, no put_blob, no get_blob, and no OpenOptions. Those SPEC names are not the public embedded API. Do not emit persia::Db::open or search as working code, and do not describe them as the public API.

A search result’s relaxation object (level, applied, original, effective, corrected) is specified in SPEC §7.6 and returned by nothing today. QueryCompiler, Filter, and TermScorer are in persia-engine. They compile text and score a term; CollectionViews::search runs the ranked search. Typo-tolerant search is that split.

There is no Go module and no npm package. sdk/go in the SPEC is a future gRPC client. The embedded Go and TypeScript design (Embedded SDKs, ADR-0018) is a document, not a library. Do not emit import "github.com/tomiok/persiaDB/sdk/persia" or import { open } from "@persiadb/node" as working code.

Code that only needs the byte codecs can use persia-format (Header, Reader, Writer, BlobId, BlobRef, and the modules listed in lib.rs). Quote those from the source. The code page links the line ranges.

Constraints on patches

CLAUDE.md is the engineering ruleset. The short list:

• The engine is written here. Do not add Tantivy, Lucene, SQLite, RocksDB, or another search or storage engine.
• unsafe is allowed only in files listed in xtask/src/repo_checks.rs (UNSAFE_ALLOWED): persia-format’s mmap and the container’s mapped-read module. Each block needs a SAFETY comment and an ADR. ADR-0018 reserves one future module, the C exports of persia-ffi, which is not in the tree.
• Bytes from disk, network, or callers return Err, never a panic. Corruption is Error::Corrupt.
• A change to on-disk layout updates SPEC.md, bumps a version or feature flag, adds an ADR, and adds a golden test.
• Segments are immutable once written. Data is written first, the commit record last, then fsync.
• Dependencies point downward. The allowed list is the workspace [workspace.dependencies] and cargo xtask check-deps.
• One roadmap leaf is one change. Do not mark a leaf done until its definition of done is met.

How to read the docs

Each guide page has a description in its frontmatter and stable headings. llms.txt is the index. llms-full.txt is the pages in Markdown. Prefer those, plus SPEC.md, over guessing from the crate names. persia-engine, persia-storage, and persia-analysis export the library code in the table above. persia-blob and persia-proto are module docs only.