Pages on XKV.org

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.