About

XKV is a small key-value store that remembers why. Every write records who made it, why, and which earlier change caused it. Any value can then explain itself, one cause at a time, back across keys to where the chain started. It is open source, written in Go, and the first release is out.

Why the Project Exists

Most outages and most support calls begin with a small value that changed. A limit, a price, a timeout, a feature switch. The store holds the new value. The reason sits somewhere else: in a log that rotated away, a chat thread, a ticket, or the head of whoever was on call.

Teams patch this together by hand. They add an audit table here, a history column there, a convention that commit messages should say why. None of it links one change to the change that caused it, which is the question people actually ask. Why is this 50? Because the risk score went up. Why did the score go up? Because a chargeback came in.

XKV puts that link into the write itself. A writer names what it acted on, and the store keeps the pointer. Asking why becomes a lookup.

What XKV Is

  • A Go package with no dependencies. One file per store, safe for many goroutines, with transactions, history, and lookups at any past revision. Quick start
  • Causes as data. Each write can name up to eight earlier revisions, of any key, as its causes. The store checks every one before writing. What an explainable key-value store is
  • Why as a call. Why walks the causes back and returns a tree, newest first. The xkv command prints it; the HTTP mode returns it as JSON.
  • Compaction that keeps the story. Old revisions can go, except the ones a kept value still points at, so a chain that can be followed today can be followed after compaction too.
  • A command and an HTTP mode for scripts, shells and other languages. Reference
  • A browser build. The same Go code, compiled to WebAssembly, runs the live demo.

How the Project Works

  • Strict by default. A write without a reason is refused. A store that explains itself badly is worse than one that doesn’t try.
  • Nothing is guessed. There’s no AI in an explanation. It is built from what each writer recorded when it wrote.
  • Measured, then said. Every number on this site comes from the test results kept in the code repository, with the commands that produced them. How XKV was tested
  • Small on purpose. One writer process per file, the index in memory, values up to 16 MB. Those limits keep the code short enough to check.

License and Availability

XKV is open source under the Apache License 2.0. The code, the tests and the documentation are on GitHub, and ready-built binaries for Linux, macOS and Windows are on the download page.

Questions People Ask

Is this an audit log? An audit log records changes one key at a time. XKV records which change led to which, across keys, and answers with the whole chain in one call.

Does it work out explanations on its own? No. It records what writers tell it and checks that the causes they name exist. The quality of a reason depends on the code that writes it, which is why the reason is required.

Can several processes write to one file? One process writes at a time; others can open the file read-only. For many writers, run xkv serve and send writes over HTTP.

What’s next? Two ideas are on the list: exchanging changes between machines as a file that carries its reasons and causes, and a stream of new revisions to watch. Neither is scheduled yet.