04 / Case study
Agent OS
a second brain the agent edits in the open.
An agent that maintains a working knowledge base — deals, notes, research, tasks — with a dashboard that displays it and a panel where you watch it work live.
The obvious build is Postgres, an ORM, and tools the agent calls to write rows. That was rejected for one reason, and the reason shaped everything else.
You have to see exactly what the agent changed, without special tools.
Stack
Architecture
Agent OS
markdown-native agent runtime
Dashboard — vault rendered as deals and notes
screenshot pending
The problem with a database here
An agent writing to Postgres is opaque. The row changed. You can log that it changed, and you can diff two snapshots if you thought to take them, but there is no natural artefact that says here is what it did.
That is tolerable when the agent is a feature. It is not tolerable when the agent’s trustworthiness is the thing being demonstrated — when someone is sitting in front of the screen deciding whether to believe it.
So the state is a folder of markdown files with typed frontmatter, and the folder is a git repository.
vault/Deals/acme-corp.md
--- company: "Acme Corp" status: "In Progress" deal_value: 24000 last_contact: 2026-07-20 next_step: "Send proposal by Friday" --- # Deal History - 2026-07-20 — Demo call. Jordan brought their RevOps lead.
Typed frontmatter for the fields a dashboard needs; prose underneath for everything a schema would have flattened.
What that choice bought
No tool definitions for CRUD
An agent already reads and writes files natively. Storing state as files means no create/update/delete tools to define, no schema for the agent to misuse, and no ORM in the loop. The capability you were going to build already exists.
No migrations
Adding a field to a record is editing frontmatter. There is no migration to write, run, or roll back — which matters when the shape of the data is still being argued about.
Every change is reviewable
The vault is a git repository. What the agent did to it is a diff, in the same tooling used to review human changes. This is the reason the whole design exists.
What it cost
Written down at design time rather than discovered later. A decision without a stated cost is not a decision, it is a preference.
The scale ceiling is the one that would end this design. It is written into the spec so that whoever hits it knows it was anticipated rather than missed — and the read model exists precisely so the query cost is paid once rather than per request.
Around the vault
An agent bridge runs the agent against the vault and streams a typed event vocabulary to the browser — started, tool call, output, error, done — so the panel is showing real execution rather than a progress bar.
Each agent declares which MCP servers it may use, and everything else is denied by name. A prompt is not a permission system; the registry is.
A voice layer holds the conversation and delegates real work to the agent through a single tool call, so speech never becomes a second, weaker path to the same actions.
Event vocabulary
Agent panel — a run streaming tool calls in real time
screenshot pending
What happened
Built and running — around a hundred commits, eight specification documents, a dashboard, a chat panel and a voice path. It is commissioned work, so the product it belongs to and the organisation it was built for are not named here, and there are no screenshots.
What is on this page is the architecture and the reasoning, which is the part that transfers to your system anyway.