github.com/NoKV-Lab/NoKV @v0.9.0

<strong>An open-source namespace metadata substrate for distributed filesystems, object storage, and AI dataset metadata.</strong>







<a href="https://github.com/feichai0017/NoKV/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/feichai0017/NoKV/go.yml?branch=main" /></a>
<a href="https://codecov.io/gh/feichai0017/NoKV"><img alt="Coverage" src="https://img.shields.io/codecov/c/gh/feichai0017/NoKV" /></a>
<a href="https://goreportcard.com/report/github.com/feichai0017/NoKV"><img alt="Go Report Card" src="https://img.shields.io/badge/go%20report-A+-brightgreen" /></a>
<a href="https://pkg.go.dev/github.com/feichai0017/NoKV"><img alt="Go Reference" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white" /></a>
<a href="https://github.com/avelino/awesome-go#databases-implemented-in-go"><img alt="Mentioned in Awesome" src="https://awesome.re/mentioned-badge.svg" /></a>
<a href="https://landscape.cncf.io/?group=projects-and-products&item=runtime--cloud-native-storage--nokv"><img alt="CNCF Landscape" src="https://img.shields.io/badge/CNCF%20Landscape-listed-5699C6?logo=cncf&logoColor=white" /></a>







<img alt="Go Version" src="https://img.shields.io/badge/go-1.26%2B-00ADD8?logo=go&logoColor=white" />
<img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-yellow" />
<a href="https://deepwiki.com/feichai0017/NoKV"><img alt="DeepWiki" src="https://img.shields.io/badge/DeepWiki-Ask-6f42c1" /></a>

What is NoKV?

NoKV is the metadata substrate that filesystems, object storage, and AI dataset layers shouldn't have to build themselves.

Meta Tectonic uses ZippyDB. Google Colossus uses Spanner. DeepSeek 3FS uses FoundationDB. Each big-tech system extracted a separate metadata layer from its data layer — because grafting namespace semantics onto a generic KV is the part that breaks under scale.

NoKV is that layer, open-sourced and namespace-native: server-side ReadDirPlus / WatchSubtree / SnapshotSubtree / RenameSubtree, formally-verified authority handoff, sub-second prefix-scoped change feeds. You bring the data plane (FUSE driver, S3 frontend, dataset SDK); NoKV owns namespace truth.

Where it sits: NoKV is the layer above generic KV (FoundationDB / TiKV / etcd) and below filesystem-shaped consumers (CephFS / JuiceFS / S3 gateways / AI training pipelines). Apache-2.0.

Why namespace metadata is its own layer, not a feature you bolt onto generic KV:

1. Server-side namespace primitives. ReadDirPlus returns one directory + N child stats in one round-trip; client-side stitching on a generic KV does 1+N round-trips with a 42× end-to-end latency penalty (measured on the same NoKV cluster — see Headline Evidence). WatchSubtree ships a prefix-scoped change feed at 178 ms p50, vs. client-side prefix scans on key-range watches.

2. Namespace correctness is its own class. Subtree authority handoff, mount lifecycle, snapshot epoch, and quota fence have a formal correctness model that generic KV doesn't speak. NoKV's Eunomia protocol is TLC-model-checked under finite bounds for handoff legality — a property no general-purpose KV provides because it isn't a general-purpose KV property.

3. Bring your own data plane. NoKV does not store object bytes, chunk data, or POSIX file content. You wire it under a FUSE driver, an S3 gateway, or a dataset SDK; NoKV is the namespace truth those frontends consume. This is the layer split Meta / Google / DeepSeek already chose internally — extracted, packaged, and Apache-2.0.

Three audiences that all sit on the same substrate:

• 🗂️ Distributed filesystems — DFS frontends (FUSE / NFS / SMB drivers, JuiceFS / CubeFS-style services) consume fsmeta for inode / dentry / mount / subtree authority instead of writing their own metadata layer on top of Redis / TiKV / FoundationDB
• 🪣 Object storage namespace layers — S3-compatible gateways consume the same fsmeta for bucket / prefix / version metadata, getting fast LIST (server-side ReadDirPlus) and prefix-scoped event streams without client-side stitching
• 🧪 AI dataset and agent workspace metadata — checkpoint storms (atomic multi-key AssertionNotExist), point-in-time namespace reads (SnapshotSubtree; long-lived retention is a GC boundary), prefix-scoped change feeds for training pipelines and shared agent workspaces (WatchSubtree) — without retrofitting them onto a generic KV

NoKV does for namespace metadata what etcd did for cluster state: a purpose-built coordination layer instead of forcing engineers to re-derive namespace semantics on every project.

📬 Contact Us

We are looking for design partners, contributors, and research collaborators working on distributed filesystems, object-storage namespace layers, AI dataset infrastructure, or agent workspace metadata.

• Eric — songguocheng348@gmail.com
• Jason — wch19961116@gmail.com

📊 Headline Evidence

Underlying KV layer (YCSB single-node, NoKV vs Badger / Pebble)

Apple M3 Pro · records=1M · ops=1M · value_size=1000 · conc=16

Units: ops/sec. Full latency in benchmark/README.md. Single-node localhost, not multi-host production.

🧭 Why NoKV vs X?

NoKV's value comes from being metadata-native, not generic-KV-with-metadata-glued-on. The same architectural slice big-tech filesystems already extract internally — ReadDirPlus, prefix-scoped event streams, formally-verified authority handoff — packaged as a layer you can drop in instead of writing yourself.

🏗️ Architecture

🗂️ fsmeta — Namespace Metadata Service

Native API surface (gRPC at nokv-fsmeta:8090, also embedded Go via fsmeta/runtime/raftstore.Open):

Authority lifecycle (rooted in meta/root, managed via nokv mount / nokv quota CLI):

Documentation: docs/guide/fsmeta.md

🚦 Quick Start

Run a full cluster

# Local processes — meta-root + coordinator + 3-store cluster + fsmeta gateway
./scripts/dev/cluster.sh --config ./raft_config.example.json

# Or: Docker Compose (cluster + fsmeta gateway, with mount-init bootstrap)
docker compose up -d

# Local Docker development build
docker compose up -d --build

# Return to the published image after a local build when available
make docker-up

Use fsmeta from Go (embedded — same Executor as the gRPC server)

package main

import (
    "context"

    "github.com/feichai0017/NoKV/fsmeta"
    fsmetaraftstore "github.com/feichai0017/NoKV/fsmeta/runtime/raftstore"
)

func main() {
    ctx := context.Background()
    rt, err := fsmetaraftstore.Open(ctx, fsmetaraftstore.Options{
        CoordinatorAddr: "127.0.0.1:2379",
    })
    if err != nil {
        panic(err)
    }
    defer rt.Close()

    // mount must be registered first (see `nokv mount register`)
    _, err = rt.Executor.Create(ctx, fsmeta.CreateRequest{
        Mount:  "default",
        Parent: 1,
        Name:   "hello.txt",
        Attrs: fsmeta.CreateAttrs{
            Type: fsmeta.InodeTypeFile,
            Size: 13,
        },
    })
    if err != nil {
        panic(err)
    }

    page, _ := rt.Executor.ReadDirPlus(ctx, fsmeta.ReadDirRequest{
        Mount: "default", Parent: 1, Limit: 100,
    })
    for _, e := range page {
        println(e.Dentry.Name, e.Inode.Size)
    }
}

Use fsmeta from any language (gRPC)

# Bootstrap a mount (required before first write)
nokv mount register --coordinator-addr 127.0.0.1:2379 \
  --mount default --root-inode 1 --schema-version 1

# Set a quota fence (mount-level)
nokv quota set --coordinator-addr 127.0.0.1:2379 \
  --mount default --limit-bytes 1073741824 --limit-inodes 1000000

# Run the standalone fsmeta gRPC gateway with metrics
nokv-fsmeta --addr 127.0.0.1:8090 --coordinator-addr 127.0.0.1:2379 \
  --metrics-addr 127.0.0.1:9101

Then use any gRPC client against fsmeta.proto (Go typed client at fsmeta/client/).

Inspect runtime state

# Live, via expvar (executor / watch / quota / mount / session metrics)
curl http://127.0.0.1:9101/debug/vars | jq '.nokv_fsmeta_executor, .nokv_fsmeta_watch, .nokv_fsmeta_quota, .nokv_fsmeta_mount, .nokv_fsmeta_sessions'

# Offline forensics from a stopped node's workdir
nokv stats --workdir ./artifacts/cluster/store-1
nokv manifest --workdir ./artifacts/cluster/store-1
nokv regions --workdir ./artifacts/cluster/store-1 --json

Full guide: docs/guide/getting_started.md · CLI reference: docs/guide/cli.md

🧩 Modules