XKV 0.1.0 Is Released as an Open Source Key-Value Store That Remembers Why

XKV 0.1.0 is out. It’s a small key-value store for Go that keeps one thing other stores throw away: the reason. Every write records who made it, why, and which earlier change caused it. Ask a value how it got there and XKV walks the chain back, across keys, to where it started.

The release has four parts. The Go package, with no dependencies, stores everything in one file. The xkv command reads and writes that file from a shell and can serve it over HTTP for other languages. A WebAssembly build runs the same code in a browser, and the live demo is built on it. Four example programs act out the case studies on this site.

Here’s what it looks like. Three services each wrote one value, and each named the value it acted on:

XKV explaining a credit limit of 50: the limits service lowered it under risk policy v3, because the risk model raised the score to 0.82, because billing recorded a card dispute from the bank.

$ xkv why limits.xkv account:42:limit
account:42:limit = 50   r5
│ was 100 · by limits-service · risk policy v3
└─ risk:42:score = 0.82   r4
   │ was 0.31 · by risk-model · new chargeback
   └─ chargeback:cb_991 = card dispute filed   r3
        by billing-worker · bank notice · ref BANK-7731

Nothing in that answer was guessed. Each line is what a writer recorded at the moment it wrote.

What’s in 0.1.0

Revisions with a reason, an actor, a ref and causes. A cause points at an earlier revision of any key. The store checks every cause before writing, and refuses the write if one doesn’t exist or belongs to another key.
Strict mode by default. A write without a reason is refused. Open the store as relaxed and such writes are recorded with the reason “unspecified”, so the gap still shows.
Why, history and time travel. Why returns the tree of causes. History lists a key’s revisions. GetAt shows a key as the store stood at any revision.
Transactions. Update writes several keys at once; all of them commit or none does.
Compaction that keeps chains whole. It drops old revisions but keeps every one that a kept value points at, however far back.
Crash safety. A transaction is written with one write call and an fsync. A torn end of file is trimmed on the next open, with the cut bytes kept in a side file. Damage in the middle is refused instead of trimmed, until you run xkv repair.
The xkv command and an HTTP mode, with binaries for Linux, macOS and Windows on the download page.

How Much It Was Tested

The promises have tests aimed at them, and every number is in the repository’s test results. A writing process was killed 1000 times and lost none of its 53,701 acknowledged transactions. A million revisions opened in 181 ms and compacted from 124 MB to 5.2 MB with every chain of causes still whole. The testing write-up has the details.

Where It Fits

XKV is for the small values that cause big trouble: limits, prices, timeouts, feature switches, and the settings AI agents now change on their own. It isn’t a database for large data. One process writes to a file at a time, and the index sits in memory. Those limits keep it small enough to check.

Start with the quick start, or open the live demo and ask a value why. The code is on GitHub under the Apache License 2.0.