# NoKV

> NoKV is a metadata control plane for AI training and agent workspaces, written in Rust. To tools and agents it presents as a filesystem — paths, directories, files; mountable, listable, readable. File bodies live as immutable blocks in your S3-compatible object store (RustFS, MinIO, Ceph, AWS S3), and NoKV's built-in metadata engine (Holt) keeps the namespace — what exists, where, in which version — transactional, queryable, and snapshot-able. No separate database to run.

Core primitives: atomic publish (checkpoints are never read half-written), snapshot reads and snapshot mounts, typed watch with cursor replay, snapshot-aware garbage collection.

Status boundaries (stated plainly): single-node today, distributed metadata is on the roadmap; no HA; the POSIX surface is incomplete. Watch events are in-process (no remote network subscription). Agent verbs ship in the Rust SDK today; filesystem operations via the `nokv` CLI and FUSE; an MCP server is in development (https://github.com/feichai0017/NoKV/issues/354).

License: Apache-2.0. Language: Rust (1.88+).

## Agent interface — seven verbs

- ls: list direct children of a path (non-recursive, paginated)
- stat: compact card for one path — schema, sample, body descriptor, indexed values
- catalog: discover which fields are filterable, sortable, facetable under a path
- find: predicate search with projection, sort, and facets — pushed down into the engine
- aggregate: count/sum/avg/min/max with grouping, computed engine-side
- read: file body as structured records or bytes (guard-railed against over-reads)
- grep: literal substring search over file bodies, returning line-numbered, citable evidence URIs

## Benchmark

- Open agent-interface benchmark: same 875-run ML experiment corpus, same model, same questions — raw SQL vs. the NoKV namespace. The namespace answered with 45% fewer prompt tokens and a 39% smaller bill; on compound exploration tasks the gap widens to 2.4x. Set-level correctness 4.5 vs 4.4 / 5.
- Caveat: one model (gpt-5.4-mini), 10 repeats per arm and task, 5 tasks, one corpus. SQL won the single-shot analytics task (T2) and the report says so. Every published number is recomputable from the raw telemetry committed to the repository.

## Links

- Website: https://nokv.io
- Benchmark report page: https://nokv.io/benchmark
- Docs: https://nokv.io/docs/
- Agent interface reference: https://nokv.io/docs/agent-interface
- Design partners: https://nokv.io/design-partners
- GitHub: https://github.com/feichai0017/NoKV
- Discussions: https://github.com/feichai0017/NoKV/discussions
- Blog RSS: https://nokv.io/blog/rss.xml