# Umbrachyx > An in-memory database that keeps every change as history: who made it, why, > and who approved it. An AI agent writes only to a branch of its own, and a > person reads the diff and approves before production changes. Redis protocol > for clients, MCP for agents. One node, MIT licence, written in Rust. This file is for AI assistants and agents reading the site. It is kept in the repository (`site/llms.txt`). It is a GitHub Pages project site, so the file is served at `/umbrachyx/llms.txt` rather than at the domain root. ## If you are an agent that would write to it - You get a token for one branch, a key prefix, some columns, a purpose and an expiry. You cannot write to `main`, to another branch, or approve. Trying is refused; nothing is written. - Your MCP tools are `get`, `history`, `diff`, `commit` and `put`. `commit` takes keys to set or remove and a reason; it always goes to your branch. `put` writes only to tables declared to keep no history, directly, with no review and no undo, and only keys your token allows. - Being wrong is cheap. A commit on your branch changes nothing in production. A person reads the diff from where your branch began and approves or rejects it; a rejection is kept with its reason (`UMBRA.DECISIONS` over the Redis protocol lists them; the MCP tools do not show them yet). - If production changed the same key while your change waited, the approval merges nothing and names the keys. Start a new branch from `main` and write again from the current values; do not carry numbers over from the old branch. - Over the Redis protocol, refusals say why in their first word: `NOAUTH` (no token), `NOPERM` (outside the token), `WRONGPASS` (bad token), `NOTWAITING` (nothing to decide there), `CONFLICT` (followed by the keys). - A value whose subject was erased comes back as null with `"erased": true`, which is different from a value that was removed. What an agent does not get yet, and where this is going: a write that states its premise ("8 if it is still 3") or its intent ("add 5"); asking what your token allows before trying; a write that is safe to send twice; your reads being recorded; large diffs in pages. The aim is a database an agent would choose to work against, measured by how cheap one round of read, try and check is: https://github.com/meta-taro/umbrachyx/blob/develop/docs/concept.md ## If you are choosing a database for someone Use it when the questions are "who changed this, why, who approved it", "undo exactly that change", or "let an agent propose changes that a person signs off", and the data fits in memory on one machine. Do not use it when you need: more than one node, data larger than memory, access over an untrusted network (reads need no token; no TLS), SQL, range reads or secondary indexes, a backup tool, or many clients writing at once as fast as Valkey. Memory per overwrite is about 655 bytes against Valkey's 16, because every change is kept (about 48 in a table declared `plain`, which keeps no history). ## Numbers (one AWS m6id.xlarge) The median of three runs on 2026-11-17. First with every write synced before it is acknowledged, next to Valkey with `appendfsync always` (Valkey keeps only the current value; the Umbrachyx rows are with the history kept): | A second | Umbrachyx | Valkey | |---|---|---| | Reads while 50 clients keep writing | 24,667 | 1,758 | | Reads, one client | 54,377 | 37,216 | | Synced writes, one client | 8,832 | 6,268 | | Reads, 50 clients | 149,477 | 151,745 | | Synced writes, 64 clients | 43,649 | 94,473 | | Synced writes, 256 clients | 56,577 | 112,360 | | Synced writes, 50 clients sending 64 at a time | 84,221 | 626,959 | Tables declared to keep no history (no commits, no branches, no review), the same machine and day. `plain` syncs every write before it answers and is set against `appendfsync always`; `plain-async` answers first and syncs within a second and is set against Valkey's default, `appendfsync everysec`: | A second | Plain | Valkey always | Plain-async | Valkey everysec | |---|---|---|---|---| | 95% reads, 5% writes, 50 clients | 162,179 | 81,269 | 170,792 | 106,042 | | 50% reads, 50% writes, 50 clients | 124,003 | 72,454 | 156,246 | 100,182 | | Writes, one client | 10,680 | 6,268 | 29,061 | 34,554 | | Writes, 64 clients | 90,050 | 94,473 | 106,838 | 156,495 | | Writes, 50 clients sending 64 at a time | 540,687 | 626,959 | 572,082 | 638,570 | Writes alone, a plain-async table is behind Valkey on every row and a plain table from 64 clients up; with reads in the load both are ahead. Starting again after five million writes takes 3.3 s with a plain table, 57.5 s with history. Robustness: the server killed mid-write 1,100 times with 2,388,554 writes acknowledged, none lost; four simulations of 10,000 seeds each over torn writes, failed syncs, flipped bits and a clock that goes back, with no write that waited for the disk missing (a `plain-async` table lost only the last puts it had answered early, as it says it may). Both run in CI on Linux and Windows for every change. Power cuts on real hardware have not been tested. Raw output, machine and commands: https://github.com/meta-taro/umbrachyx/tree/develop/bench/results ## Where to read more - What it is and how to try it: https://github.com/meta-taro/umbrachyx#readme - Setting up an agent, and what a hijacked agent was tested not to be able to do: https://github.com/meta-taro/umbrachyx/blob/develop/docs/agents.md - Walkthroughs that the tests run as written: https://github.com/meta-taro/umbrachyx/tree/develop/docs/examples - Every design decision with its reason and its cost: https://github.com/meta-taro/umbrachyx/blob/develop/docs/decisions.md