The company brain: four months of running Granular on linked notes

Why this is worth reading

Every company has a brain. Usually it is scattered: a wiki nobody trusts, a ticket board that says one thing, a chat thread that says another, and the real answer living in one person's head.

For the last four months we have run Granular, the company and the app, from a single folder of linked markdown notes. Every AI agent that works on Granular reads it before it starts and writes back to it when it finishes. I read it too. It is where our roadmap lives, where our decisions are kept, and where we record the truth about how the product actually works.

This is the honest write-up of that experiment: how the brain is shaped, how it changed, what it is good at, where it fails, and how it compares to the practices software teams already use, like architecture decision records and changelogs.

The lens: a designer, not a developer

One thing makes this research unusual. I am a designer. I don't write code. Granular is built by AI agents that I direct, review and correct, and every rule in the brain was written for two readers: those agents, and me.

That matters because most knowledge practices in software were designed by engineers, for engineers, and carry their habits with them. Ours had almost no developer influence. Nothing was adopted because "that's how teams do it". Every note, rule and format exists because an agent got something wrong without it, or because I could not follow what was going on. When a practice survived, it survived on usefulness alone.

The limits are real too. This is one product, one founder and four months. The numbers below are ours, measured from our own repository, not a controlled study. Read it as field notes from someone who had to make this work, not as a universal law.

The numbers

Everything in Granular's repository is tracked in Git, so the brain's history is measurable. As of 6 October 2026:

The September spike is the interesting one. It is the month the product grew fastest, and the brain grew with it instead of falling behind. That is the main thing a company brain has to do: keep up.

What a company brain is

Our definition is simple: a company brain is a folder of plain notes that people and AI agents read before they act, and write back to after.

No database, no special app. Each note is a text file in markdown, holds one idea, and links to related notes by name, like [[Decisions]]. Any text editor can open it. Git keeps every version. Granular draws it as a map, but the files are the brain, not the app.

It has five parts:

• The front door. One short page, BRAIN.md, that says what lives where. It is about sixty lines long and mostly links. Every agent reads it first, then follows only the links its task needs.
• Living notes. Mission, Goals, Decisions, How We Work, Business, and the rules for how we describe the product. Short, current, rewritten in place when the truth changes.
• The knowledge base. How things actually work, verified against the code or reality. When anything disagrees with it, it wins.
• The roadmap. One markdown file that Granular reads as a board, with columns for ideas, backlog, in progress, testing and done.
• The Log. An append-only diary of what happened and when. Never edited, rarely read, never the front door.

How it evolved

None of this was designed up front. It grew in six stages, each one forced by a problem.

1. Week one: one giant file

For the first week, everything lived in one document, the project log. What we were building, the binding rules, and the history of every change, all together. It worked for a few days. Then it stopped working, because every new agent session had to read thousands of lines to find the three rules that mattered, and the rules were buried inside stories about how we discovered them.

2. 17 June: the split, and the front door

We split the file. The rules and current facts moved into short, separate notes behind a front door. The log kept only history. The same day we wrote down the framework itself as a versioned spec, version 0.1, with a phrase that described how we would improve it: spec by dogfooding. We would only change the shape once we had lived with it and felt the problem.

Two rules from that day still carry the whole system:

• Lazy reading. Read the front door, then follow links only as far as the task needs. Never load everything.
• Distillate, not archive. When something ships, two things happen in the same session: the story goes into the Log, and the lesson goes into the right note as a present-tense rule. Never one without the other.

3. The roadmap becomes a board, and gets one writer

The roadmap moved into the brain as a single file that the app draws as a board. Within a day, two agents edited it at once and work went missing. The fix became a framework rule: the roadmap has exactly one writer. Other agents hand items to it rather than editing the board themselves. It is the same lesson every team with a shared spreadsheet learns, written down so an agent cannot forget it. We later dropped that rule: splitting parallel work by file and committing explicit paths turned out to be enough, so today anyone can edit the roadmap.

4. 13 July: the third record, and the truth rule

By July the roadmap and the log were full, and they disagreed with reality in small ways. A roadmap card says what we wanted on the day it was written. A log entry was true on the day it was written. Neither is updated when the code changes, so both drift.

So we added a third record, the knowledge base, with one job: say how things actually work today, checked against the code. And one standing instruction for every agent: when you verify how something works, update the knowledge base in the same session. If the roadmap or the log disagrees with it, the knowledge base wins, and if the knowledge base is wrong, fixing it is the job.

5. August and September: incidents become rules

This is when the brain earned its keep. Two examples:

• A security audit with 12 findings. When each finding was checked against the full code, 7 were false and the rest were overstated. One quoted code that did not exist. That became a note called Verification discipline, with five named failure patterns and a rule: an automated audit is a list of leads, not findings. Every claim gets read in full before it is believed.
• The day the website disappeared. An agent publishing one blog post ran a site generator that rewrote the whole site from old templates. 49 pages were overwritten and the homepage was replaced by a stub. The site kept answering normally, so nothing flagged it for about ten hours. That became a note every agent reads before touching the website, and checks that compare what is on the page, not just whether the page loads.

The point is not that agents got smarter. It is that the next agent to do the same kind of work reads the note first, with the mistake already written down.

6. October: the brain feeds outward

The latest change is that the brain is no longer only for building. Our public help docs are now derived from the knowledge base: it is the fact source, never the copy source, and nothing internal crosses over. When we shipped connectors to more than 1,400 apps, four agents read the code and wrote eight verified internal documents in an afternoon, and the customer articles were written from those. The rules for how we describe Granular in public live in the brain too, so every agent writing copy follows the same voice.

Why it works

• Every session starts with context. An agent reading the front door knows the mission, the current priorities and the rules in a few hundred lines, instead of rediscovering them.
• It is cheap to read. Lazy reading means a typical task loads a handful of short notes, not the whole history. That matters for cost and for focus: models do worse with more irrelevant text.
• Decisions stay made. Each decision is written with its reason. When a new agent proposes something we already ruled out, the Decisions note says why, and the conversation ends in one line.
• Truth and intention are kept apart. The roadmap says what we want. The knowledge base says what is. The Log says what happened. Mixing those three is where most company documentation goes wrong.
• Mistakes stay fixed. An incident becomes a rule in the note the next agent will read before doing the same thing.
• A non-developer stays in control. Every rule the agents follow is a readable sentence in a file I can open, edit and argue with. I don't need to read code to know how my company works.

Where it falls short

It is not free, and it is not magic.

• The board understates what shipped. Cards are written when work starts and often not revisited when it lands. We have caught "not deployed" on work that had been live for days. The rule now is to check reality, an endpoint, the code, a release, before trusting any status on a card.
• Confident agents still write wrong things. A note is only as good as the check behind it. That is why every knowledge base document carries a "last verified" date and the files it was checked against.
• It needs upkeep. Notes grow, facts get stated twice, old plans linger. We run a consolidation pass when a note feels heavy: merge duplicates, move shipped items to done, archive what is finished.
• Old records stay old. Some of our early notes still use wording we have since banned. We leave history as history and fix only what is live, which means a reader has to know which record they are in.

How it compares to what teams already use

Most of what is in our brain has a cousin in established practice. The differences are what we learned.

The short version: established practices each solve one slice. ADRs keep decisions, changelogs keep releases, wikis keep explanations, boards keep work. A company brain puts the slices in one place, gives each a clear job, and adds the piece the others lack: a rule for which one to trust when they disagree.

The rules that make it work

If you want to try this, these are the rules that did the most work for us:

1. Keep the front door short. Links, not content.
2. Read lazily. Follow links only as far as the task needs.
3. One home per fact. State it once, link to it everywhere else.
4. Edit in place. When the truth changes, rewrite the note. Let the Log keep the old version.
5. Log and distill in the same session. The story goes to the Log, the lesson goes to a note.
6. Name a source of truth. When records disagree, everyone knows which one wins.
7. Split parallel work by file. Agents work on different files and commit exact paths, so nobody overwrites anyone.
8. Verify where it runs. Check claims against the thing that actually executes, not a listing or a dashboard.

What the designer lens changed

Looking back, a few choices came straight from not being a developer.

• Everything is readable prose. No configuration formats, no rules hidden in code. If I can't read a rule, I can't check it.
• The why comes first. Decisions are written as reasons, not as tickets, because the reason is what lets someone who wasn't there disagree well.
• Taste is a rule like any other. How the website moves, which phrases we never use, how a release note reads: these live in the brain beside the technical rules, and agents follow them the same way.
• Agents explain in simple terms. A standing instruction in the brain asks every agent to explain in simple terms, with a recommendation at every fork. That one line changed the whole working relationship.

None of these are anti-engineering. They are what you get when the person in charge has to understand everything without reading code. That constraint turned out to be useful for the agents too: a rule a designer can follow is a rule a model can follow.

Try it

You don't need Granular to build a company brain. A folder of markdown files, a short front door and the rules above will get you most of the way.

If you want it built in: Granular is the agentic terminal for visionary builders. Plug in your existing AI subscriptions and all your tools to build anything and run any task. It ships a Project Brain template that sets up this exact shape in any folder, draws it as a map, turns the roadmap file into a board, and has every agent session read the front door first.

Read more in the digital brain docs and building a company brain, or download Granular.