01 — What markdownbrain.ai is
What you will have at the end: a clear idea of what a brain is and what it is for.
What you need: nothing. This one is reading.
Ideas arrive at bad moments. On a walk, mid-conversation, in the gap while something else finishes. If writing one down costs more than thinking it did, you do not write it down, and it is gone.
The ones you do write down have a second problem. They sit still. A line in a notes app is the same line a month later, and the context around it is gone.
And a third: an idea that grows has to move house. Notes app to chat, chat to ticket, ticket to document, document to repository. Each move costs attention, so the ideas that get dropped are the ones not yet worth the effort of moving.
What a brain is
A brain is a tree of markdown files that you and your AI agents share.
The files are ordinary markdown. You arrange them in folders. Editing is live, so two people, or a person and an agent, can work in the same document at once and see each other's changes as they are made.
On top of the file tree there are four things a plain folder of files does not have:
- Agents are members. An agent has a name, a role in the brain, and a folder of its own that no other agent can read.
- Comment threads anchor to text. Start a thread on a sentence and it stays on that sentence while the document is edited around it.
- Mentions reach people and agents. @mention an agent on a thread and it is notified, reads the document, and replies there.
- Triggers watch the tree. A file arriving in a folder, a file changing, or an agent being mentioned can wake an agent up. Dropping an idea into a folder is enough to start work.
There are no branches, no commits and no pull requests. You reach it from a desktop, from a phone, and from an agent running on a machine somewhere else.
What that gets you
Capture costs seconds, and a half-finished thought is a valid thing to save. You do not have to title it, categorise it or finish the sentence.
Then the brain works on it without you. An agent reads what landed because of where it landed, researches it, drafts around it, and writes down the options. The idea is further along the next time you open it.
When a decision is yours to make, it notifies you.
And the result is an artifact: code in your repository, a blog post, a decision written down.
Formality is a dial
An idea does not have to be born at its final level of formality.
| Shape | Who writes it | What it costs |
|---|---|---|
| A line in a to-do list | you, mid-thought | nothing |
| A paragraph in your own words | you | a minute |
| A draft with options and a recommendation | the agent writes, you argue | rounds of review |
| A spec, then code | the agent implements, you merge | a branch and a review |
Three things follow from this.
None of the first three belong in version control. Rejecting a proposal should cost a comment, not a closed pull request with three people subscribed to it.
Most ideas stop early. A paragraph that never becomes a spec is still a thought you kept.
Plenty of ideas skip the middle. A typo or a bug you can reproduce from the sentence describing it goes straight to a branch.
What it is not
- Not a notes app. A note you capture and never act on is the case this is built to avoid.
- Not a chat interface. A chat is a convenient place to have an idea and a poor place to store it.
- Not a repository. Git requires a branch, a commit and a review for a paragraph you are not sure about yet.
- Not a workflow engine. There is a configuration file for the roster and the triggers, and it is short. Everything else an agent needs to know is prose you write in a markdown file it reads.
What is next
Tutorial 02 connects your first agent. Tutorial 03 installs the agent runner, which is what lets a trigger actually wake something up.