{"id":51272291,"url":"https://github.com/NoKV-Lab/NoKV","last_synced_at":"2026-07-05T09:00:37.131Z","repository":{"id":252733915,"uuid":"841059560","full_name":"NoKV-Lab/NoKV","owner":"NoKV-Lab","description":"AI native distributed file system","archived":false,"fork":false,"pushed_at":"2026-06-30T06:06:22.000Z","size":377653,"stargazers_count":439,"open_issues_count":4,"forks_count":50,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-06-30T08:08:55.522Z","etag":null,"topics":["distributed-systems","filesystem","nokv","object-storage","raft","rust"],"latest_commit_sha":null,"homepage":"https://nokv.io/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NoKV-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":"DCO","cla":null}},"created_at":"2024-08-11T14:19:45.000Z","updated_at":"2026-06-30T06:16:24.000Z","dependencies_parsed_at":"2024-09-14T20:48:17.436Z","dependency_job_id":"4d709aca-7fec-4402-a309-73b5dd11fbd3","html_url":"https://github.com/NoKV-Lab/NoKV","commit_stats":null,"previous_names":["feichai0017/cloud_distributed_file-system","feichai0017/norag","feichai0017/nokv","nokv-lab/nokv"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/NoKV-Lab/NoKV","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NoKV-Lab%2FNoKV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NoKV-Lab%2FNoKV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NoKV-Lab%2FNoKV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NoKV-Lab%2FNoKV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NoKV-Lab","download_url":"https://codeload.github.com/NoKV-Lab/NoKV/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NoKV-Lab%2FNoKV/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35148606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-systems","filesystem","nokv","object-storage","raft","rust"],"created_at":"2026-06-29T19:00:25.587Z","updated_at":"2026-07-05T09:00:37.117Z","avatar_url":"https://github.com/NoKV-Lab.png","language":"Rust","funding_links":[],"categories":["Applications"],"sub_categories":["Database"],"readme":"\u003c!--\nCopyright 2024-2026 The NoKV Authors.\nSPDX-License-Identifier: Apache-2.0\n--\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/public/img/logo.png\" width=\"320\" alt=\"NoKV\" /\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eMetadata control plane for object-backed agent artifacts.\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://nokv.io/architecture\"\u003e\u003cstrong\u003eDocs\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"https://nokv.io/blog/agents-want-filesystems\"\u003e\u003cstrong\u003eWhy Filesystems\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"#-quick-start\"\u003e\u003cstrong\u003eQuick Start\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"#-measured-evidence\"\u003e\u003cstrong\u003eBenchmarks\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/feichai0017/NoKV/discussions\"\u003e\u003cstrong\u003eDiscussions\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"#-contributing\"\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/a\u003e ·\n    \u003ca href=\"https://deepwiki.com/feichai0017/NoKV\"\u003e\u003cstrong\u003eDeepWiki\u003c/strong\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n## Latest update\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/orgs/NoKV-Lab/discussions/378\"\u003e\n    \u003cimg src=\"docs/public/img/community/nokv-lingtai-banner-en.png\" alt=\"NoKV × Lingtai — Design Partner Collaboration\" width=\"100%\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003e **NoKV × Lingtai** is now a design partner collaboration.  \n\u003e\n\u003e [中文公告 →](https://github.com/orgs/NoKV-Lab/discussions/380)\n\u003e\n\u003e [Read the announcement(English) →](https://github.com/orgs/NoKV-Lab/discussions/378)\n\n\n## Recognition\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"120\"\u003e\n      \u003ca href=\"https://landscape.cncf.io/?group=projects-and-products\u0026item=runtime--cloud-native-storage--nokv\"\u003e\n        \u003cimg src=\"./docs/public/img/recognition/cncf.svg\" width=\"56\" alt=\"Linux Foundation CNCF Landscape\" /\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cstrong\u003eCNCF Landscape\u003c/strong\u003e\u003cbr/\u003e\n      Listed in \u003cstrong\u003eAI Native Infra / Storage\u003c/strong\u003e and \u003cstrong\u003eCloud Native Storage\u003c/strong\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://dbdb.io/db/nokv\"\u003e\n        \u003cimg src=\"./docs/public/img/recognition/dbdb.svg\" width=\"56\" alt=\"DBDB.io Database of Databases\" /\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cstrong\u003eDBDB.io\u003c/strong\u003e\u003cbr/\u003e\n      Profiled on DBDB.io. The current NoKV entry refers to the Rust filesystem product line.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## What Is NoKV?\n\nNoKV is a metadata control plane for object-backed agent artifacts: run\noutputs, log files, checkpoints, reports, and citable evidence in one\nfilesystem-shaped namespace. For the longer interface argument, see\n[Agents Want Filesystems](https://nokv.io/blog/agents-want-filesystems).\n\nIt is not a trace database. Keep JSONL, SQLite, or Postgres as the source of\ntruth for runtime events; use NoKV as the agent-facing namespace over the\nartifacts and evidence those systems produce.\n\nNoKV keeps namespace metadata in its own path-native engine\n([Holt](https://crates.io/crates/holt)) and stores file bodies as immutable\nblocks in S3-compatible object storage such as RustFS, MinIO, Ceph RGW, or AWS\nS3.\n\n```text\nFUSE / SDK / CLI\n  -\u003e NoKV metadata service     (self-contained; no separate metadata DB to run)\n  -\u003e Holt inode/dentry metadata\n  -\u003e S3-compatible object store for file bodies\n```\n\nNoKV owns namespace truth, metadata transactions, snapshots, watches, and\nobject-reference GC. The object store owns byte durability and replication. The\nmetadata engine is built in, so local deployments operate a filesystem rather\nthan a filesystem plus a separate Redis, MySQL, or TiKV cluster.\n\n## Why NoKV\n\nAgent workflows are artifact-heavy; their workspaces aren't. Every run leaves\nbehind configs, metrics, logs, checkpoints — and that state scatters across\nfolders, JSON files, object-store keys, and database rows. Agents pay a\nnavigation tax in tokens every time they go looking. NoKV gives that state one\naddress, with the metadata guarantees the workload actually needs:\n\n- **Checkpoints publish atomically.** Readers see the complete new checkpoint\n  or the previous one — never a half-written file, even across a crash.\n- **Snapshots are time travel.** Pin a frozen view of any subtree and keep\n  reading it while jobs write; GC never deletes what a snapshot still needs.\n- **Changes are events, not polls.** Every create, rename, and publish lands as\n  a typed, replayable event with a cursor.\n- **Artifacts carry body references and digests**, with cleanup of failed\n  staged uploads.\n- **Bodies are immutable, versioned blocks.** Replacement publishes a new\n  generation, so node-local caches never invalidate object bytes after publish.\n\nThe primary write model is write-once publish, matching how datasets,\ncheckpoints, and artifacts are commonly written.\n\n## 🤝 Contributing\n\nContributions are welcome, from first-timers to seasoned Rustaceans. Read [CONTRIBUTING.md](CONTRIBUTING.md) to get started: it covers setup, conventions, and the review gate. Pick up a [good first issue](https://github.com/NoKV-Lab/NoKV/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22), or follow the recommended newcomer track in [#354](https://github.com/NoKV-Lab/NoKV/issues/354) (MCP server for the agent namespace surface).\n\nTo understand the project first, read [Why filesystems](https://nokv.io/blog/agents-want-filesystems), [the metadata engine](https://nokv.io/blog/holt-in-nokv), and [the benchmark](https://nokv.io/benchmark).\n\n## 📚 Documentation\n\n- [Architecture](docs/architecture.md)\n- [Product Design](docs/product-design.md)\n- [AI-Native Metadata HA And Fast Path](docs/metadata-ha-fast-path.md)\n- [Metadata Schema](docs/metadata-schema.md)\n- [Object Layout](docs/object-layout.md)\n- [Checkpointing](docs/checkpointing.md)\n- [RustFS Backend](docs/rustfs.md)\n- [Benchmarks](docs/benchmarks.md)\n\n## 🤖 The Agent Interface\n\n`ls` · `stat` · `catalog` · `find` · `aggregate` · `read` · `grep`\n\nSeven verbs, one progressive-disclosure surface: an agent discovers what\nexists, learns what is queryable, and pays to read only what it needs.\nPredicates, sort, and projection are pushed into the engine, so a \"top-5 runs\nby val_loss\" report costs two calls — one `catalog`, one `find`. `grep` sweeps\na subtree and returns line-numbered matches with citable evidence URIs\n(`nokv-native://path@generation:N#L3`).\n\nThe verbs live in [`nokv-agent`](crates/nokv-agent/src/lib.rs): the tool\ndefinitions are LLM-ready JSON schemas, and `execute_agent_tool` routes calls\nover the same `AgentNamespace` trait whether the namespace is embedded\n(in-process) or remote (metadata RPC via `nokv-client`). The crate is\ntransport-free — it depends only on `nokv-meta`, `nokv-object`, and\n`nokv-types`. See the [contributor handbook](docs/development/nokv-agent.md).\n\n**Today** the agent verbs ship in the Rust SDK, the `nokv` CLI and FUSE\nmount, and a native MCP server over stdio transport. Run `nokv mcp` to\nserve the seven read-only agent tools to any MCP-capable client.\n\n```bash\ncargo run --release -p nokv --bin nokv -- mcp\n```\n\nTo configure it in an MCP client (e.g. Cursor, VS Code, Claude Desktop):\n\n```json\n{\n  \"nokv-mcp\": {\n    \"command\": \"/path/to/NoKV/target/release/nokv\",\n    \"args\": [\"mcp\"]\n  }\n}\n```\n\nThe same `--server-bind`, `--object-backend`, `--mount`, and control-plane\nflags from the rest of the CLI apply, e.g.:\n\n```bash\nnokv --server-bind 127.0.0.1:7777 --object-backend rustfs mcp\n```\n\n**v1 constraints:** stdio transport only (no HTTP/SSE); read-only — the\nseven existing agent tools only, no write or publish tools; no network\nregistration path for `register_namespace_index` (it remains\nembedded-only — see the [contributor handbook](docs/development/nokv-agent.md)\nsection 6 for why).\n\n## NoKV vs JuiceFS\n\nNoKV follows the same high-level separation used by systems like JuiceFS and\n3FS: metadata is separate from file body storage. The difference is that NoKV\nships its metadata engine as part of the filesystem and optimizes for\nagent-workspace and artifact publish/read patterns first.\n\n| | JuiceFS | NoKV |\n| --- | --- | --- |\n| Metadata engine | External DB such as Redis, MySQL, or TiKV | Built-in, path-native Holt engine |\n| Atomic checkpoint publish | POSIX rename/write semantics over the metadata engine | First-class publish-by-generation primitive |\n| Block model | Slice/block model supporting broad POSIX behavior | Immutable object blocks plus new-generation manifests |\n| Workspace-native primitives | Layered on top of the filesystem | Snapshots, typed watch, body descriptors, and GC floors are core metadata concepts |\n| Agent query surface | None | `ls`/`stat`/`catalog`/`find`/`aggregate`/`read`/`grep` with push-down and line-numbered evidence |\n| POSIX completeness | Mature production filesystem | P0 subset implemented; still hardening compatibility gates |\n| Maturity | Production, large deployments | Young Rust implementation; single-node local mode is usable, replication is roadmap |\n\nNoKV is an object-backed filesystem with a sharded Holt metadata plane: multiple\nmetadata shards (one Holt engine each) behind long-running metadata servers,\nrouted through an etcd control plane, with cross-shard grafts presenting a single\nFUSE namespace across shards. Metadata HA today is single-writer-per-shard with\ncheckpoint-image + shared-log, epoch-fenced failover — not yet consensus\nreplication — so it is not yet a JuiceFS/3FS class production-HA distributed\nfilesystem.\n\n\n\n## 🚦 Quick Start\n\nBuild and test:\n\n```bash\ncargo test --workspace\ncargo build --release -p nokv --bin nokv\n```\n\nStart a local RustFS-compatible S3 endpoint and create the default bucket:\n\n```bash\nmkdir -p /tmp/rustfs-data\nRUSTFS_ACCESS_KEY=rustfsadmin \\\nRUSTFS_SECRET_KEY=rustfsadmin \\\nrustfs server --address 127.0.0.1:9000 /tmp/rustfs-data \u0026\n\nAWS_ACCESS_KEY_ID=rustfsadmin \\\nAWS_SECRET_ACCESS_KEY=rustfsadmin \\\naws --endpoint-url http://127.0.0.1:9000 \\\n  s3api create-bucket --bucket nokv\n```\n\nBy default NoKV expects bucket `nokv` at `http://127.0.0.1:9000` with\ndevelopment credentials `rustfsadmin` / `rustfsadmin`. See\n[docs/rustfs.md](docs/rustfs.md) for other deployment modes.\n\nStart the metadata server, then initialize the namespace. Every other command\ntalks to the server on `127.0.0.1:7777`, so keep it running:\n\n```bash\ncargo run --release -p nokv --bin nokv -- serve \u0026\n\ncargo run --release -p nokv --bin nokv -- init\n```\n\nPublish and read an artifact:\n\n```bash\ncargo run --release -p nokv --bin nokv -- \\\n  put-artifact /runs/1/checkpoint.bin ./checkpoint.bin\n\ncargo run --release -p nokv --bin nokv -- \\\n  cat /runs/1/checkpoint.bin \u003e restored.bin\n```\n\nMount with FUSE:\n\n```bash\nmkdir -p /tmp/nokv-mount\n\ncargo run --release -p nokv --bin nokv -- \\\n  mount /tmp/nokv-mount\n```\n\nOn macOS this requires macFUSE. NoKV passes the `noappledouble` mount option to\navoid Finder/resource-fork AppleDouble sidecars; user xattr roundtrip is\ncovered by the FUSE smoke test.\n\n## 🧩 Crates\n\n| Crate | Role |\n| --- | --- |\n| [`nokv-types`](https://crates.io/crates/nokv-types) | Storage-neutral namespace model |\n| [`nokv-protocol`](https://crates.io/crates/nokv-protocol) | Framed metadata RPC DTOs and binary codec |\n| [`nokv-object`](https://crates.io/crates/nokv-object) | S3-compatible object body storage |\n| [`nokv-meta`](https://crates.io/crates/nokv-meta) | Schema, `MetadataCommand`, Holt store, service core |\n| [`nokv-control`](https://crates.io/crates/nokv-control) | Shard ownership, epochs, and failover coordination |\n| [`nokv-agent`](https://crates.io/crates/nokv-agent) | Transport-free agent tool surface (the seven verbs) |\n| [`nokv-client`](https://crates.io/crates/nokv-client) | Rust SDK over the metadata service |\n| [`nokv-fuse`](https://crates.io/crates/nokv-fuse) | Low-level FUSE frontend |\n| [`nokv-server`](https://crates.io/crates/nokv-server) | Long-running metad process and framed RPC |\n| [`nokv`](https://crates.io/crates/nokv) | `nokv` CLI binary |\n\n\n## 📄 License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNoKV-Lab%2FNoKV","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNoKV-Lab%2FNoKV","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNoKV-Lab%2FNoKV/lists"}