Outages and angry support calls often start with a small value that changed. A credit limit. A price. A timeout. A feature flag. More and more often, a setting an AI agent touched. The store holds the new value and nothing else. The reason lives in a log, a chat thread, a ticket or somebody’s memory, and three weeks later nobody can say why it’s 50 instead of 100.
XKV, short for explainable key-value, puts the reason in the write itself. Every write records who made it, why, and which earlier change caused it. Ask any value why it is what it is, and XKV walks the chain of causes back across keys to where it started. It’s one Go package, one file per store, with no dependencies.
The Pitch in Four Numbers
- 0 lost acknowledged writes across 1,000 hard kills of a writing process.
- 397 of 397 torn-write cut points recovered to the last whole transaction.
- 197 milliseconds to open a store holding a million revisions.
- 124 MB to 5.2 MB after compacting a million revisions, with every chain of causes kept.
How It Works
A write in XKV carries a value, an author, a reason and up to eight earlier revisions, on any keys, as its causes. The store checks that each named cause exists before it accepts the write. A write with no reason is refused. That’s the default, on purpose.
Then “why” is just a call. Why follows the causes back and returns a tree, newest first. The xkv command prints it, and HTTP mode returns it as JSON. The site’s example is a credit limit of 50, traced back through a risk policy, a risk score and a card dispute. Other cases include a Q4 price list that went out as one transaction with one reason, a timeout raised during an incident that still explains itself three weeks later, and a cache setting an AI agent changed, with the tool call behind it kept on record.
The store is safe for many goroutines, with transactions, full history and lookups at any past revision. Compaction can drop old revisions, except those a kept value still points to, so chains stay followable. The same code compiled to WebAssembly powers a live demo in the browser. And there’s no AI in the explanations: they’re built only from what each writer recorded. Nothing is guessed.
Who It’s For
- Teams that manage small, consequential settings: limits, prices, flags and timeouts.
- Go developers who want an embedded store with history and reasons built in.
- Anyone letting AI agents change configuration, who needs to know what the agent did and why.
- Incident responders who want the answer to “who changed this?” to be a lookup, not an investigation.
Limits
One writer process per file at a time. Other processes can open it read-only, and for many writers you run xkv serve and send writes over HTTP. The index sits in memory, values are capped at 16 MB and causes at eight per write. Those limits are chosen to keep the code short enough to check. And XKV doesn’t infer reasons. The explanations are only as good as what the writing code records.
The Four-Question Screening
Every project featured here gets the same four questions, the way you’d screen a startup idea.
1. Where is the money in it?
XKV is open source under Apache 2.0, with no paid tier. The money is in accountability, which regulated industries pay for. Banks, insurers and healthcare companies need to show why a limit, a price or a rule changed, and AI agents changing settings make that harder every month. Paid paths include a managed, replicated server; compliance-ready exports, such as the W3C PROV format the project is working toward; integrations with feature-flag and config systems; and support for teams that put it in production.
2. What real problem does it solve?
Lost reasons. The value is stored, but the why is scattered and decays fast. Audit tables, history columns and commit-message habits help, but none of them link one change to the change that caused it. XKV makes that link part of the data.
3. The technology in plain words
Imagine a notebook where every time you change a number, you have to write next to it who you are, why you changed it, and which other note made you do it. Months later, you can point at any number and follow the trail of notes back to the very first decision. XKV is that notebook, enforced by the computer.
4. Moat and differentiation
Key-value stores are everywhere, and so are audit logs. An audit log records changes one key at a time. XKV links changes across keys and returns the whole chain in one call, and it refuses writes without reasons. That combination is rare. The crash testing, a thousand kills and every torn write recovered, makes it safe to trust. The moat that can grow is the causal-history model itself, plus standard exports that let compliance teams use it directly.
Why It Matters
As agents start changing settings on their own, “who changed this and why” is going to be asked far more often. A store that answers it by design turns a forensic exercise into a single lookup.
Follow the Project
Read what an explainable key-value store is, try the live demo, start with the quick start, see how XKV was tested, or get the code from the XKV repository on GitHub. XKV is listed with the other open-source projects on SoftDevStudio.com, and more featured projects are in the Projects section.