The vault
The system has no special database for a brain. Its brain is a folder of plain text files, kept in git (a tool that saves every version of every file). That folder is called the vault, and it is the one place that is true.
Where you see it
On a laptop, the vault is a normal folder of notes. The owner can open any file and read it. On the box, the same folder sits at ~/vault.
Most of the time the owner never looks at it directly. It shows up through the doors: the chat page, email, Discord. When the agent answers a question, it is reading these files.
What happens, step by step
- The owner tells the agent: "Our new supplier is Maple Street Flour. They deliver on Tuesdays."
- The agent writes that fact into one markdown file (a plain text file with light formatting).
- The change is saved in git and pushed to the shared copy.
- Every other machine pulls the change down.
- A week later the owner asks on their phone: "When does the flour come?"
- The door reads the file fresh, not a stored copy, and answers: "Tuesdays."
What powers it
| Part | What it does |
|---|---|
| Markdown files | Hold every fact, rule, and procedure as plain text. |
git | Saves every version and keeps machines in step. |
filing-doctrine.md | The filing rule: five kinds of thing, each with one home. |
CLAUDE.md (at the vault root) | The routing map. It tells the agent which bucket to look in. |
how-it-works.md | Explains why files were chosen over a database. |
The filing rule
Everything in the vault is one of five kinds of thing. Each kind has exactly one home, so nothing is written twice.
- An entity: a person, a company, a client.
- A list or view: a table that pulls entities together, like a contact list.
- A procedure: how to do something.
- A rule or guardrail: what must always or never happen.
- A fact or reference: something true that other files point to.
The four buckets
When the agent needs something, it first asks which bucket it is in. Then it goes to that bucket's index and follows the pointer.
| The thing is... | Bucket | Where to look |
|---|---|---|
| A procedure the agent runs | Skill | The skills index. See Skills. |
| Code the owner built that does a job | Tool | The tools index. |
| A website the owner runs (a domain plus a deploy) | Website | The websites rows in the services table. |
| An outside service or logged-in site | Service | The services table. See Services and logins. |
| A fact about the owner or the company | Knowledge | The standing context and company files. |
The table has five rows because websites live inside the services table but are their own kind.
Why it works this way
There are three reasons plain files beat a database here.
- The AI reads them with no integration. Claude opens a text file the same way a person does. There is no app, no connector, and nothing to break in between.
- The owner truly owns them. The files live in the owner's own git account. If the owner ever stops working with whoever set the system up, they keep every file, in a format any person or AI can open.
- Git keeps every change. Every edit has a date and a history. A wrong change is one step to undo.
Files are worse than a database at anything relational, like "show me every customer who ordered twice in March." If a company needs real reporting like that, the plan is to run a proper tool beside the vault, not to replace it.
The vault holds what is true and how things are done. It does not hold what is happening this minute. That live state sits in the logbook database.
Connected to
- One vault, many machines: how git keeps every copy the same.
- Skills: the procedure bucket.
- Services and logins: the service and website bucket.
- Memory and standing context: small lessons and the owner's current state.
- The logbook database: the one thing that is not in the vault, and why.