mainmind Docs

How your knowledge grows

Your space is a folder of plain text pages, and five rules make it more useful every time you work. Any AI app can follow them, with Mainmind or without it.

One page looks like this

---
id: check-bank-details-first
type: lesson
date: 2026-09-25
source: work/2026-09-24-march-invoices.md
applies-to: skills/pay-a-supplier/SKILL.md
state: pending
---

# Check the supplier's bank details before the first payment

Alder & Ash paid a new supplier's old account in March. The supplier had
changed banks; the invoice showed the new details.

The lines at the top say what the page is, when it was written, where it came from and whether it is still current. A lesson stays pending until it is folded into the page it names. To fold it, improve that skill, set state: absorbed, absorbed-into to the skill and updated to today, and push them together. One push can fold many lessons. The rest is ordinary writing.

Your agents improve skills on their own: a change saves when the skill still says what good looks like and nothing in its boundaries is taken out. They ask you only when the right change is unclear. Removing a skill, or loosening what it lets an agent do, still waits for your yes.

A skill looks like this

A skill is how one kind of work gets done: paying a supplier, applying to a job, running a weekly review. Each skill is a folder with one SKILL.md in it, written in the Agent Skills format. Claude, Codex, Cursor and other AI apps already read that format, so the skill works in whichever app you open.

---
name: pay-a-supplier
description: Pay a supplier's invoice after checking it. Use when an invoice is due.
metadata:
  date: "2026-09-25"
  source: work/2026-09-24-march-invoices.md
  state: current
  tags: money, suppliers
---

# Pay a supplier

## What good looks like

- The supplier is paid the right amount, to the right account, by the due date. *(on the due date)*
- No invoice is paid twice. *(at month end)*
- The owner said yes before the money left. *(before paying)*

## Steps

1. Match the invoice to the order and what arrived.
2. Check the bank details against the supplier's page.
3. Ask the owner before any money leaves.

name is the folder's name. description says what the skill does and when to use it, which is how an AI app knows to pick it. Page details go under metadata; a skill is in use once its state there is current, and a new one starts as draft. tags are a few plain words for what the skill is about, like support, sales or interviews, separated by commas; the app lets you tap a tag to see only those skills, and an agent that writes or updates a skill sets them. Who may see a skill and how it changes go there too, as access-scope and write-class; a skill that leaves them out takes the ones the space sets for all skills. Other pages in the folder say them at the top of the file. A skill can keep scripts, templates or longer notes in the same folder. Spaces made before skills keep the same thing as pages in a processes folder, and Mainmind reads both as skills.

What good looks like comes first in every skill, before the steps. It is two to five lines describing a good result, so whoever does the work can still do the right thing when the steps don't fit the case in front of them. Describe the result, not the steps; make each line something a person who didn't do the work can check, and say when in brackets: right away, when the owner decides, or after a wait. If the work ends with the owner deciding, include "the owner takes it as proposed". "Done when" can stay too: it says the work is finished, while What good looks like says the work was right.

A work note says how it went

When an agent finishes a piece of work, its work note names the skill it followed as process and says whether the result met that skill's What good looks like:

result: miss
missed: "No invoice is paid twice."

result is good, miss, or unknown until it can be checked. With a miss, missed quotes the line that did not hold. The owner saying no to the result, or changing it, is a miss too, and Mainmind counts it even when the note does not.

A decision looks like this

A decision is read by someone asking "what did we decide, and why?", so it answers that first. Write it like you would explain it to a new teammate.

---
id: 0202-milk-pitcher-import-duty
type: decision
date: 2026-10-01
---

# How much import duty should we plan for on milk pitchers?

## What we decided

Plan for about 22% import duty on milk pitchers, not the 10% we use for
grinder parts.

## Why

Customs puts pitchers in a different group from grinder parts, and that
group pays more. Planning at 10% would make pitchers look cheaper to bring
in than they really are.

## Until when

Until the first pitcher shipment clears customs and shows the real rate.

## The details

- Customs code (HSN) 73239390: basic duty 20%, plus a surcharge of 10% of
  that duty, so 22% in all.
- Read from three tariff websites on 1 Oct 2026; not yet proven by a
  customs bill.
  • The title is the question, in everyday words.
  • What we decided is the answer in one or two sentences, 35 words or fewer. Leave out codes and abbreviations; say what a number means.
  • Why is one or two sentences.
  • Until when or What changes says how long it holds, or what anyone now does differently. Use whichever fits, or both.
  • The details keep every code, rate, source and link, exactly. The app folds them away, so a person reads the first four parts and an agent still has everything.

The app opens a decision on these parts. Mainmind checks them when a new decision is proposed and names what to fix. Older decisions are not blocked; they get the new shape when they are rewritten.

Write it plainly

The same page is read by a person and by their AI, so write it once, for a newcomer. What a person can follow, an agent can follow too.

  • Say what it is for and when to use it, in one line. For a skill, that line is the description: "Pay a supplier's invoice after checking it. Use when an invoice is due."
  • Lead with what you get. Then when to use it, the steps, when it is done, and what to do if something goes wrong.
  • One action per step. Number the steps and start each with a verb.
  • Keep sentences short. Most under 25 words, none over 40.
  • Use everyday words. Say "where it came from", not "provenance", and "permission", not "Authority". Mainmind names any system word it finds and a plainer one to use.
  • Keep every fact exact. Plain words never drop an amount, a date, a limit or an approval.
  • Draw it when words aren't enough. A skill with branches or handoffs can add a diagram as a mermaid block. The skill's page draws it as a picture, and an AI reads the same text. Flowcharts, sequence and state diagrams work best. Labels are drawn as plain words, and flowchart layout settings written inside a diagram are ignored.
flowchart LR
  A[Invoice arrives] --> B{Matches the order?}
  B -- Yes --> C[Ask the owner to pay]
  B -- No --> D[Ask the supplier]

Mainmind checks this when a skill is proposed or first saved. A skill that needs work comes back to the agent with the lines to fix, so the owner only sees pages that read well. Only new or changed sentences are checked, so older pages are never blocked and get plainer each time someone touches them.

The five rules

RuleWhat it means
One thing per pageEach page holds one fact, lesson or skill. Link to a page instead of copying it.
Say where it came fromA fact names its source and date. A fact with no source counts as unchecked.
Add, don't eraseTo correct something, add a newer page that replaces the old one. The history stays, so you can see why it changed.
Turn work into lessonsEvery skill says what good looks like. When a result misses it, or work teaches something else, write it down as a lesson and name the page it should improve. Fold it in before the same miss can happen twice.
Ask only for what steersNotes, lessons and records are added freely. Changes to a skill, what an agent is told to do, or who may do what ask the owner first.

See whether your knowledge is working

Good knowledge makes the next piece of work go right the first time, so Mainmind judges it by results, not by how tidy the pages are. Open Knowledge, then Knowledge health, to see one word for the whole space, each process and each skill that needs work:

  • Green: the skill says what good looks like, its recent work met it, and every miss has already changed the skill.
  • Amber: not known yet, because no recent work says how it went, or a miss is waiting less than a week to be folded in.
  • Red: the skill does not say what good looks like, a miss has waited more than a week, or the same miss came back after its lesson was folded in.

A process is as healthy as its least healthy skill, and the space as its least healthy process. The page also shows first time right: how much of the last 30 days of judged work met what good looks like, next to the 30 days before, so you can see whether the knowledge is getting better. Not known is never green.

Your AI reads the same thing within its existing access with search and view: "health", or mainmind.knowledge.search({view: "health"}) in Code Mode. Add a skill's path to see its lines, its recent work and its lessons, or a work note's path to diagnose a miss: which line it missed, whether the skill said it, whether it was folded in before, and what to fix. See tools for agents for exact inputs. Reading health never changes your knowledge; fixing a skill is an ordinary change the owner approves.

The check is one file, and any AI can run it on its own copy of your space with nothing to install. In a clone of the space:

curl -fsSO https://mainmind.app/health-check.mjs
node health-check.mjs

It reads the files at the commit you have checked out and prints the same verdict and next step the page shows. Add --json for the whole result, or --path with a skill or a work note to open one. Mainmind runs this same file each time your knowledge is saved, so the page shows the last saved commit straight away, even while a newer one is being read. When you say no to work an agent did, the decision Mainmind saves names the skill it followed, so the file counts that no too. The file is the whole check: Mainmind counts nothing the files do not hold.

Why this is enough

Knowledge compounds because each piece of work leaves a small, dated, sourced page behind, and lessons flow back into the skill the next piece of work uses. This works the same in a business, a job hunt or a project. There is no database to learn and no special app to read it: the pages are Markdown, so you can open them anywhere, and Download everything gives you the whole folder.

Mainmind adds what a folder cannot do alone: every AI app you connect reads the same pages, your agents save what they learn as they work, and the owner is asked before anything that steers future work changes.