XKV.org

A Credit Limit Dropped From 100 to 50 and XKV Shows the Three Steps Behind It

Mon, 19 Oct 2026 00:00:00 +0000

A customer calls support. Their credit limit was 100 yesterday and it’s 50 today, and nobody told them why. The support agent can see the 50. Everything else is spread across three services.

The limits service set the 50, under its risk policy. The risk model raised the account’s score the day before. Billing had recorded a chargeback from the bank that morning. Each service did one reasonable thing, and each logged it in its own way. Putting the story together means knowing which logs to open and in what order.

A Q4 Price List Goes Out as One Transaction With One Reason

Mon, 19 Oct 2026 00:00:00 +0000

Prices change together. A new quarter’s price list touches every plan at once, and a half-applied list is worse than an old one: for a few minutes Pro might cost less than Basic. The list also has one reason behind it, usually a decision made in a meeting, with a ticket that tracked the rollout.

XKV writes the whole list in one transaction. Every price commits or none does, and every price carries the same reason, ticket and cause, given once.

A Timeout Raised During an Incident Explains Itself Three Weeks Later

Mon, 19 Oct 2026 00:00:00 +0000

At two in the morning an alert fires: the orders database is answering slowly, and order requests are timing out. The on-call engineer raises the database timeout from 5 seconds to 30 so requests stop failing while a replica catches up. It works. The alert resolves. Everyone goes back to bed.

Three weeks later someone notices the timeout is 30 seconds and wonders whether that’s a typo. Changing it back might be right. It might also bring the incident back. The person who knows is on holiday, and the incident channel has scrolled far out of sight.

An AI Agent Changed a Cache Setting and XKV Kept the Tool Call Behind It

Mon, 19 Oct 2026 00:00:00 +0000

An operations agent watches the product catalog. Its metrics show 4.1% of reads returning stale data, above the 2% target, so it shortens the catalog cache’s time-to-live from 300 seconds to 30. That’s a reasonable move. An hour later the catalog database is at 91% CPU, because the cache now sends ten times as many reads its way. An engineer puts the TTL back.

The next morning the team wants to know what happened. The questions are the usual ones, with a new twist: which change did the agent make, what was it looking at, and which of its tool calls did it? Agents act fast and often, so their changes need a trail at least as good as a person’s.

How XKV Was Tested With 1000 Kills, Torn Writes and a Million Revisions

Mon, 19 Oct 2026 00:00:00 +0000

A store that keeps the reason behind every value is only useful if it keeps the value too. So before 0.1.0 went out, each promise XKV makes got a test aimed straight at it, and every number below sits in the repository’s test results, written by one script on a 2-CPU Linux machine.

The promises are short. A transaction is all or nothing. An acknowledged write survives a crash. Committed data is never dropped quietly. Compaction never breaks a chain of causes. Here is how each was tried.

What an Explainable Key-Value Store Is and Why Small Values Need One

Mon, 19 Oct 2026 00:00:00 +0000

The values that cause the most trouble are small. A credit limit. A timeout. A price. A flag that switches a feature on for ten percent of users. Each one fits in a few bytes, and each one can stop a business for an afternoon when it changes and nobody knows why.

Every key-value store keeps the value. Some keep old values too. What none of them keep is the reason, and above all the link from one change to the change that caused it. That link is what people ask about. Support can already see the customer’s limit. What they need is why it’s 50 when it was 100 yesterday.

Why the Project Is Called XKV

Mon, 19 Oct 2026 00:00:00 +0000

XKV stands for explainable key-value. KV is the usual shorthand for a key-value store, the simplest kind of database there is: you put a value under a key and get it back later. The X is the part this project adds.

An X marks the spot on a map, and it’s the letter that stands for an unknown in algebra. Both fit. Every value in a store has a story behind it, and in most stores that story is the unknown. XKV keeps it next to the value, so the question every value should be able to answer, why, has an answer.

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

Mon, 19 Oct 2026 00:00:00 +0000

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.

About

Mon, 01 Jan 0001 00:00:00 +0000

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.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Teams who keep limits, prices, settings or flags in a store and keep getting asked why a value changed.
Engineers who tried XKV and hit a bug, a missing feature, or a number that didn’t match their own test.
Anyone with a question about the store, the demo or the figures on this site.

Write to info@xkv.org.

Bugs and feature requests are also welcome as issues on GitHub. For a bug, the output of xkv check on the file and the version from xkv version help a lot.

Download XKV

Mon, 01 Jan 0001 00:00:00 +0000

The xkv command reads and writes a store from the shell and serves it over HTTP. Each archive holds the command with the license files and the README. The links always point to the latest release.

System	Download
Linux, x86-64	xkv_linux_amd64.tar.gz
Linux, ARM64	xkv_linux_arm64.tar.gz
macOS, Apple silicon	xkv_darwin_arm64.tar.gz
macOS, Intel	xkv_darwin_amd64.tar.gz
Windows, x86-64	xkv_windows_amd64.zip

SHA256SUMS lists the checksums. Every release and its notes are on the releases page.

The binaries are pure Go with no outside libraries; the Linux ones are static. The macOS binaries aren’t signed by Apple, so macOS may ask you to allow them the first time, or you can run xattr -d com.apple.quarantine xkv.

Live Demo

Mon, 01 Jan 0001 00:00:00 +0000

The demo runs XKV in your browser. It’s the Go package itself, compiled to WebAssembly, with the store’s file kept in memory. Nothing needs installing, and nothing you type leaves the page.

Open the live demo

What You Can Do

Load a story. Three short histories are ready to load: a credit limit that dropped, a timeout raised during an incident, and a cache setting an AI agent changed before an engineer put it back. Each is a handful of real writes made through the store, with their causes.
Click a value. The store answers why, and the tree unfolds one level at a time: the value, the change that caused it, the change that caused that, and so on, across keys. Each step shows who made it, the reason they gave, the value before, and any outside reference such as a ticket or a tool call id.
Write your own change. Pick a key, a value and a reason, tick the keys whose current value caused your change, and write it. It joins the chain at once. Leave the reason out and the store refuses, with the same error the Go package and the xkv command give.
See the history. The History tab lists every revision of a key, newest first, with what caused each one.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Ten minutes from nothing to a value that explains itself. Use the xkv command first to see the idea, then the Go package to build it into a program.

1. Get the Command

Download the archive for your system from the download page, unpack it, and put xkv on your PATH. Check it runs:

xkv version

2. Write a Chain

Three services each write one value. Each names what it acted on with --cause.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Everything XKV offers, on one page: the Go package, the xkv command, the HTTP mode, and the file. The README is the full manual, and the Go documentation is on pkg.go.dev.

Revisions

Every write is a revision. A revision has:

Field	Meaning
`Rev`	store-wide revision number; only goes up
`Tx`	transaction id; revisions written together share it
`Key`, `Value`	the key and its new value
`Deleted`	true when the revision deletes the key
`Actor`	who made it
`Reason`	why; required unless the store is relaxed
`Ref`	an outside reference: a ticket, a request id, a tool call id
`Causes`	up to 8 earlier revisions, as key and revision number
`Time`	when it was written

The Go Package

Call	Does
`Open(path, opts)`	opens or creates a store file; one writer per file
`OpenMemory(opts)`	a store in memory, for tests and the browser
`Put(ctx, key, value, opts...)`	writes one value
`Delete(ctx, key, opts...)`	deletes a key; the delete is a revision too
`Update(ctx, fn, opts...)`	writes several keys in one transaction
`Get(ctx, key)`	the current revision
`GetAt(ctx, key, rev)`	the key as the store stood at revision `rev`, or `ErrCompacted` if compaction removed that state
`Revision(ctx, rev)`	one revision by number
`History(ctx, key, limit)`	a key’s revisions, newest first
`Why(ctx, key, depth)`	the tree of causes behind the current value
`WhyRev(ctx, rev, depth)`	the same for one revision
`Keys(ctx, prefix)`	keys that have a value
`Compact(ctx, opts)`	drops old revisions, keeping every one a kept value points at. On Windows it fails with nothing changed while another process has the file open
`Check(path)`	reads every record and cause of a file

Write options: Reason(s), Actor(s), Ref(s), Cause(key, rev) and CauseLatest(key). WithActor(ctx, name) sets the actor for every write made with that context.