Working memory

A mesh accumulates two kinds of knowledge: what the graph says and what the people running it decided. The first is derived — gtmesh doctor, gtmesh topic status, gtmesh status and gtmesh next compute it fresh on every run. The second has to be written down, and where you write it decides whether a future session can still read it.

The five homes

Each file holds one lifecycle, and each has a budget it stays inside:

What	Where	Lifecycle	Budget
Rules for this mesh, read every session	`OPERATOR.md`	edited in place	~200 lines
Settled decisions + hard-won learnings	`operator/decisions.md`	appended, newest first	~400 lines
What happened in a session	`operator/journal/YYYY-MM-DD.md`	written once, read rarely	~40 lines
The plan for one piece of work	`operator/tasks/<slug>.md`	kept after it lands	—
Work that’s planned but not started	a GitHub issue, or a task file	closed when done	—

gtmesh init scaffolds all of them; gtmesh upgrade adds them to an existing mesh. They’re project-owned — yours to write in, never overwritten by an upgrade.

There is no status file. Anything a gtmesh verb can compute is left to the verb. Prose that restates the mesh’s state is stale as soon as the next command runs, and nothing tells you it went stale — that’s precisely how a single notes file grows past what a session can read.

The promotion test

Before writing anything down, ask in order:

Can gtmesh doctor / topic status / status / the graph tell me this? → write nothing.
Will it still be true in three months, and does it change how the operator works? → OPERATOR.md.
Is it a decision or a learning, with a why, that a future session must not re-litigate? → operator/decisions.md.
Will someone pick it up as work? → an issue (planned) or operator/tasks/<slug>.md (in flight).
Otherwise it’s history → today’s operator/journal/YYYY-MM-DD.md.

Writing a decision

Keep entries short and prescriptive — state the action to take, hold Why to one line, and name a wrong path only where an agent would plausibly take it anyway:


### 2026-07-14 — Fold a demand cluster onto a source-less hub
**Decision** — Mint the apex with `gtmesh page add --role hub`, then catalogue the cluster under it
with `gtmesh topic fill`.
**Why** — The demand rows carry no page of their own, so nothing has anything to hang from until the
hub exists.
**Consequence** — Owning a topic is two commands, and `topic status` reads *covered* immediately after.

A decision written as a list of things to avoid ages badly: the warnings outlive the context that made them make sense, and naming a wrong move plants it.

What goes in the journal

Git already holds the diff, so a day’s entry records what git can’t — what you chose and why, what you tried that failed, and a pointer to whatever carries the work on. One file per working day means an entry can never outgrow a read, and the directory sorts itself.

Coming from a `NEXT-STEPS.md`

Meshes scaffolded before this structure kept one root NEXT-STEPS.md. gtmesh doctor flags it, and the operator can split it for you in one pass — ask it to:

run the operator’s migrate-next-steps routine on this mesh

It inventories the file’s headings, classifies each by the promotion test, shows you the destination map for approval, writes the new homes, and removes NEXT-STEPS.md in a single commit. Nothing is moved without your sign-off.