Knowledge format

Bonsai is a knowledge space that you and your AI agents share. Everything in it is a plain Markdown file: text that any Markdown editor can open, today or twenty years from now.

This page explains how those files are put together, and how Bonsai reads today’s tasks, project progress and habits out of a folder of notes.

What a note looks like

Here’s a project note, say 1_Projects/Kitchen-Renovation/Kitchen-Renovation.md:

---
tags:
  - home
---

# 🔨 Project · Kitchen Renovation

- **Key Result:** The kitchen is usable for cooking before December.

## 🧩 Context

- Contractor: [[Sam Lee]], their phone number is in their note
- Budget cap: $8,000

## Next Steps

- [x] Measure the space
- [/] Pick a cabinet design 📅 2026-11-05
- [ ] Order the cabinets
- [!] Waiting for the building to approve work hours

That’s it. Ordinary Markdown with a few simple patterns. Most of the time your AI agent writes notes like this for you; you just tell it what you want to keep. But it helps to know what you’re looking at, so let’s go through the pieces.

Front matter

The block at the very top, between the two --- lines, is called YAML front matter. Think of it as an index card for machines: one key: value per line, with list items starting with -.

---
tags:
  - home
---

The body is for people; the front matter is for programs. Keeping them apart means the body can stay natural writing, with no odd markup added just so software can follow it.

Bonsai only knows a handful of keys:

A note’s title is its file name, so there’s no separate title key.

Why agents can’t write some keys

An agent can help write the body, but it can’t freely edit front matter. It writes front matter once, when it creates the note. After that, changes go through dedicated tools and the server writes them.

The reason is that some of these lines are promises. archived decides whether something still shows up in your to-dos. verified records whether a person has looked at the note. If an agent could rewrite those lines at will, it could close a project for you, or sign “I’ve read this” in your name. So each of these keys is written either only by you or only by the server.

How much to trust a note

As agents write more of your notes, you need to see at a glance where a note came from. That’s what generated, verified, status and stale_after answer. Bonsai takes their definitions word for word from the open OKF spec.

generated:
  by: claude/claude-opus-5
  at: 2026-08-20T10:53:00+09:00
verified:
  - by: codex/gpt-5.4
    at: 2026-08-20T11:20:00+09:00
  - by: human:alex
    at: 2026-08-20T13:37:00+09:00

verified is a list that only grows. Several agents may work in the same space; if it held a single value, the next agent to run a cross-check would overwrite your sign-off. As a list, your entry stays there for good.

When reading, look at the whole list. No entries means unverified. Only agents means machine-confirmed. At least one entry from you means human-reviewed.

Only notes written by an agent carry these keys. Your own daily notes and quick captures need none of them.

Tasks

The character inside a checkbox is the task’s state:

There are two more states than the usual done / not done because the question a to-do list most needs to answer is “what can I do right now?”. Bonsai’s Today screen uses these characters to sort tasks into due, ready and blockers.

Several [/] items under the same heading are read as one ordered chain. Today shows only the first and folds the rest away. So if you have two parallel lines of work, give each its own heading.

For a deadline, add 📅 YYYY-MM-DD after the task. There’s no need to link it to a daily note; Bonsai finds what’s due on its own.

Links

[[Note name]] links to another note. You can click through, and an agent can follow it to read on.

In Bonsai, each fact lives in one place. Sam’s phone number goes in Sam’s note, and the project just links to it. Copy it into two places and sooner or later the copies disagree.

Tables and diagrams

Some structure is information in itself, and Bonsai draws it for you:

• A table with step, date and status columns in a project note becomes a timeline in place, showing where today falls and how long until the next step.
• A table under ## Habit in an area note defines your habits and becomes a heatmap on the Log screen.
• A mermaid code block is drawn as a diagram, for example the dependencies between tasks.

They’re all still ordinary Markdown tables and code blocks. Open the note in any other editor and you get a perfectly readable table.

Why Markdown

Your notes exist once. Bonsai’s screens are computed from these files. There’s no database behind them holding the “real” data. Indexes and caches can be thrown away and rebuilt at any time; the files are the only source of truth.

People and agents read the same thing. The structure comes from conventions you can read, like the character in a checkbox, agreed section headings and front matter keys, not from a format only software understands. It reads naturally to you and precisely to an agent.

It doesn’t lock you in. Plain text doesn’t depend on any one company. Change apps, agents or devices, and your notes are still there and still readable.

AGENTS.md: the manual for agents

Every space has an AGENTS.md at its root. It spells out everything on this page, plus how the space is organised and how agents may read and write, for every agent that comes in. It’s the same for every user.

Your own rules, like which language you want replies in or how an agent should address you, go in 7_Self/Instructions.md. That file can add rules, but it can’t change the format, because the format is the agreement between Bonsai and your notes.