What an Explainable Key-Value Store Is and Why Small Values Need One
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.
An explainable key-value store keeps the answer next to the value. Each write carries who made it, why they made it, and which earlier writes it acted on. Asking why is then a lookup that walks those links back.
Where the Reason Goes Today
Without a store that keeps it, the reason ends up in one of four places, and each one leaks.
The application log. The service that changed the limit probably logged something. Logs rotate, live in a different system, and record events as text that has to be searched for. Finding the line is possible on a good day. Finding the line that explains the line before it, in another service’s log, is the part that takes the afternoon.
An audit table. Teams add a history table with old value, new value, who and when. That’s real progress, and it answers “who changed this key”. It doesn’t say what they were reacting to, because the table has no place for a pointer to another key’s change.
A ticket or a chat thread. People write good reasons in tickets. The ticket number rarely makes it into the data, so the reason can only be found by someone who already knows where to look.
Memory. The person on call knew exactly why they raised the timeout. Three weeks later, so does nobody.
The common gap is the link. Each of these can record a single change. None of them records that change B happened because of change A, in a form a program can follow.
What Changes When the Store Keeps It
In XKV a write is a revision with four things attached. The actor names who made it: a service, a person, or an agent. The reason is a short sentence, and it’s required by default. The ref is an optional outside reference, such as a ticket or a tool call id. The causes are up to eight earlier revisions, of any key, that the writer acted on.
Causes are checked when the write happens. A cause must exist, must belong to the key it names, and must be older than the write. A program can’t record a link to something that isn’t there, and the links can’t form a loop, because they always point backwards.
So why is a short walk. Take the current revision, read its causes, read theirs, and stop when a revision names none. The answer comes back as a tree, newest first, across as many keys as the story touched. There’s no inference in it and no AI. It’s built from what the writers said when they wrote.
Why Now
Two things have made this more pressing.
The first is how many services now write to shared settings. A limit might be touched by a risk model, a billing job, a support tool and a person, each in its own codebase. When they all write to one store, the store is the only place that sees every change, so it’s the natural place to keep the links.
The second is AI agents. An agent that tunes a cache or raises a quota is doing exactly what an operator does, and someone will ask why. If the agent’s write carries its reason, the observation it acted on, and the id of the tool call that made the change, the answer is one lookup away. The agent case study shows that chain.
What It Costs
Keeping reasons costs a little space and a little discipline. Each revision is a few dozen bytes larger. Old revisions pile up until compaction removes the ones nothing points at. Writers have to say why, so XKV makes the reason required by default. A store that explains itself badly is worse than one that doesn’t try.
It also has edges. XKV records what writers tell it; it can’t check that a reason is true. It’s a store for small values, with one writing process per file and its index in memory, not a database for large data.
Where It Fits
An explainable store earns its place where a small value has big effects and several writers: credit and spending limits, prices and discounts, timeouts and retry settings, feature flags, quotas, and the settings agents adjust. For those, the question is never only what the value is. It’s how it got there.
The quick start has a working chain in ten minutes, and the live demo lets you ask values why in your browser.