Every TaskGoblin run is a fresh goblin. There is no long-lived session holding your context, and often not even the same model account between one turn and the next. That sounds like a weakness until you look at what it forces: nothing is remembered by accident. Anything that matters between runs has to be written down — which means you can read it, correct it, and rely on it.
The place it gets written down is the brain: your organisation's own body of written knowledge, kept as markdown pages that both you and your goblins can read, search and edit. Everything else on this page is a consequence of that one decision.
One brain, made of pages
A brain is a set of pages. Each has an address — conventions/testing, people/alice, runbooks/rollback — a title, some markdown, and any tags you give it.
Addresses are paths, so they read like files, and TaskGoblin shows them that way: /conventions/testing.md is a page, /conventions is a folder. That is also the URL, so a page can be linked into a chat, a merge request or a ticket the same way you would link anything else.
Folders are worth one sentence of explanation, because they are not what they look like. There is no such thing as creating a folder. A folder is just an address prefix that more than one page happens to share: write runbooks/rollback and runbooks/incident and you have a runbooks folder; move the last page out of it and it stops existing. Nothing to set up, nothing to clean up.
The two addresses that already exist
Two parts of the brain are written by goblins whether or not anyone ever opens the section.
memory — the playbook. One page, read by every goblin on every thread before it starts work. This is where the durable, organisation-wide facts live: which repository is the default, how the test suite is actually run, that migrations are never edited after the fact, that this team writes merge-request descriptions in a particular shape. It is how "correct it once and every goblin after it gets it right" actually works.
Goblins write to it themselves when they learn something durable — tell one which repository to use for a repo-less Jira ticket and it records the answer rather than asking again next week. You can also just say it: "remember that we run the suite with make test, not npm test". And you can open the page and edit it like any other.
tasks/… — a page per piece of work. Each thread — one issue, one merge request, one loop — gets its own page under tasks/. At the end of a shift the goblin writes what it learned, what it decided, what it deliberately did not do, and what it hit a wall on. When the next turn fires, that page is the first thing the next goblin reads, alongside the branch its predecessor already pushed.
These are written on every shift, including the ones that achieved nothing. A goblin that spent its run blocked on a missing credential records that, so the next one does not spend its run rediscovering the same wall.
The practical effect is the one you feel first: come back three days later with "actually, can we do it the other way?" and the run resumes with the history in hand. Nobody pastes context back in, because the context lives with the work rather than in someone's chat window.
Why a task page is an ordinary page
tasks/ is a normal, visible, searchable folder — not a hidden compartment. That is the whole upgrade over a note stapled to one row in a database: what one task learned is findable from every other task.
Six weeks ago a goblin worked out that your staging deploy needs an extra migration step, and wrote it into that ticket's page. Today a different goblin, on an unrelated ticket, searches before it starts and finds it. Nobody had to promote that note anywhere, and nobody had to remember it existed.
Pages that link themselves
Refer to another page by its address in a sentence — "see conventions/testing before changing the suite" — and the two pages link. Write it as [[conventions/testing]] and it renders as a link as well.
You do not maintain the reverse direction. Every page shows a Linked from panel listing what points at it, with the sentence each reference sits in — so before you change a page you can see who is relying on it. Refer to a page that does not exist yet and the link renders as missing, pointing at a create form with the address already filled in; write the page later and every reference to it lights up.
This is the part that makes a brain accumulate rather than sprawl. A folder of unrelated documents gets harder to use as it grows. A graph of documents that cite each other gets easier, because the way in is any page adjacent to what you were already reading.
What belongs where
| Put it in the task page | Put it in memory |
|---|---|
| What this branch already changed | Which repository is the default |
| An approach that was tried and reverted | The command that actually runs the tests |
| A decision waiting on a reviewer's answer | Conventions: branch names, commit style, MR descriptions |
| A wall hit on this specific ticket | Standing preferences: "never touch generated files" |
The dividing line is simple: if it stops being true when this ticket closes, it belongs on the task page.
Everything else — architecture notes, runbooks, the reasoning behind a decision nobody remembers making, notes on who owns what — is just a page you write at an address that makes sense. The brain is not limited to the two reserved addresses; those are only the two that fill themselves in.
Conventions beat instructions
The brain exists so your loop instructions can stay short. An instruction that has to re-explain your repository layout, your test command and your review conventions on every single run is one you will stop maintaining. Push the durable parts into the brain and the instruction shrinks to the part that is actually about this loop.
This is also the fastest fix when a loop starts producing work you do not like. Before rewriting the instruction, ask whether the goblin is missing a fact — a convention nobody ever wrote down. Recording it once fixes every loop at the same time.
Where memory does not go
The brain is written by goblins and readable by you. Credentials are not part of it: tokens are injected into the environment around the agent at run time and never enter what it reads or writes. A goblin cannot record a secret in a task page because it never had one to record. See The cloud sandbox for how that boundary is drawn.
Each organisation's brain is its own. It is never shared, never pooled, and never read by a run belonging to anyone else.
Where to go next
- Writing and organising the brain — writing pages, importing what you already have, and keeping it tidy as it grows.
- How a run works — where the brain is read and written inside a single turn.
- Loops — why written continuity is what makes a loop compound rather than repeat.
- The cloud sandbox — the other half of continuity: an environment that survives between turns.