What Mainmind keeps, who can use it, and how work is checked.
Agents and sessions
A standing agent has a Mainmind identity and a continuing responsibility. Its harness is where a session runs. Reuse that identity when the agent returns or changes to another supported host; ordinary conversations and temporary helpers do not automatically become standing team members.
The agent reports its harness and contact through its own connection. That contact helps you see where work was last active; it does not attest that the host is available now. The persistent-agent guide owns setup and the distinction between identity, contact and execution.
The Mainmind connection
Work happens through the Mainmind connection or the matching HTTP start routes. An agent (over MCP) or a bot holding a member credential (over plain HTTP) connects to one space and gets everything through that door: start / GET /api/boot for the entry documents and bounded restore state (addressed inbox, open asks, this member's open run locators, and a notice when feedback you filed has shipped), sync with mode inbox / /api/page-work for addressed assignments, sync with mode context / /api/work-context for saved progress, sync with mode session / /api/work-session to claim or hand off. search remains on the MCP connection: it reads a path, lists, and routes a task with kind process, naming each match's System tool-route when the space's knowledge records one. Identity comes from the authenticated membership in that space. People sign in with their linked email and a one-time code; a standing machine uses its own connection. The connection guide owns those setup steps. The deployment operator secret is not a member. A tool outside the connection's effective authority is unavailable. Agents may hold a disposable workspace while working. Retain relevant knowledge and released progress through Mainmind before replacing it. An agent does not need a credential for the space's GitHub repository. Live ops boards (Slack, cron health, a vendor dashboard) stay out of Mainmind until they are deposited into the space's knowledge or reached via call_provider on a connected account.
The space's knowledge
The format is Organizational Seed (Apache-2.0). The space is a folder of plain markdown, kept in Mainmind and copied to GitHub if the owner wants a copy: ORG.md (what it is), AUTHORITY.md (what may happen, access is not permission), AUTHORING.md (how to write durable knowledge), processes/ (how kinds of work are done), records/ (the nouns the business touches), decisions/ (every ruling, verbatim), lessons/ (what it learned). Write so a fact still makes sense after a harness switch; that teaching belongs in AUTHORING.md. The Worker does not refuse a write for vendor strings. Each System record may carry one portable tool-route table in frontmatter (tool-route-reads, tool-route-writes, and tool-route-command or tool-route-connection) so a later harness follows reads → CLI X / writes → CLI Y instead of inventing call_provider. A side may name an ordered list, preferred first (tool-route-reads: cli books-cli, call_provider books), when the CLI is the spine and the gateway is a real fallback; call_provider is refused only when a side's whole list excludes it, and tool-route-never is the explicit prohibition. A Process names the Systems it uses (systems: or a link to records/systems/...). Absence is explicit; a missing table is not a first-class vendor account. Retained Markdown remains readable when the AI tool changes. Continuing work also requires the agent's authenticated membership, retained work state and any original sources it needs. Unsaved chats and live browser sessions do not travel with those files. See source export and restore for today's bounded options; copying Markdown is not a complete space backup.
Projection
What you read through Mainmind is a projection of the space's knowledge: derived, disposable, rebuildable from the repository at any commit. Every answer carries the commit it reflects, so any claim can be traced to real bytes in git. If something looks missing or stale, that is a fact worth reporting. The repository is the truth; the projection is only a view of it.
Several agents may read one space at once. Notes, events, task starts, heartbeats and task completion can also proceed alongside a landing or deposit. Each ledger write checks current knowledge and access when it saves. Closing a task waits for that task's pending effects, not another agent's task. Canonical writes still use a workspace lease and Git conflict checks. A pending landing releases the lease while Git finishes; a typed deposit releases it after Git confirms the save, with refresh admission continuing separately. A rebuild still pauses knowledge-dependent calls. See the Setup for each app for concurrency and recovery.
Search
One search runs two layers (lexical (BM25) and semantic (embeddings)) fuses them, and reranks the shortlist with a model that reads the query and each finalist together. If the semantic layer is unavailable, search degrades to lexical rather than failing.
Runs
A run is the unit of visible work: who is working, on what, right now. Real work opens a run, heartbeats as it moves, and closes with an honest terminal status, landed (it wrote something), no-change (it only read, or found nothing to write), awaiting-ruling (parked on a human decision; not over), conflict (the target moved; rebuild), or failed. A run that stops heartbeating shows as stalled, a fact derived from the clock, not a verdict.
Notes and Lessons
Useful learning is retained deliberately and applied in later work. Saving a report or reading a Lesson does not by itself prove that the next task improved; the later result should name the earlier finding and show how it changed the work.
Two different things come out of real work, and it is worth keeping them apart.
A note is a complaint about one passage: this rule is stale, wrong, unclear, missing, contradictory, or it cost more to obey than it should have. Any role may leave one, it changes nothing, and no agent reading that document ever sees it — nobody should obey a note instead of the rule. A note ends when its author withdraws it, or when a ruling settles it.
A Lesson is what the work taught, written so the space can act on it: what happened, what it teaches, the evidence, and the one document it should improve. It lands in the space's knowledge as a file like any other, waits in the review queue, and ends either absorbed into that document by an approved change, or retired with the reason preserved.
A note says something is wrong here; a Lesson says here is what we learned, and where it goes. Promoting a note lets an agent propose an evidenced improvement to standing guidance. Recorded human decisions can also inform later choices through the decision loop. The app shows on each knowledge page what it is struggling with: its open notes, waiting Lessons and what is waiting on a ruling, with how many runs, asks and notes hit it over 28 days. Those counts are exposure, not proof a Lesson worked.
Space health
Mainmind checks each space about once an hour. Open notes that need a new answer are gathered into one question for each area, instead of one question per note. A page is not changed on its own unless you have turned that on for this space. When it is on, a page is updated only when a yes you already recorded covers that exact page and a live decision already says the words to add. The check runs before anything is saved. Anything else waits for you.
decide with mode list shows the gathered question while it waits for you.
Decisions
A choice usually starts inside an agent session: the agent reaches a question that its task and existing permission do not settle. Mainmind helps it use past decisions, ask the right person, and carry what the work teaches into later choices. This is the decision and judgment loop.
A choice goes through weighing, a human answer when needed, action and verification, and an evidenced improvement to judgment that informs the next choice. An existing standing yes can cover the exact file change.
Bring the choice. The agent states the question, options, recommendation and affected files, then weighs it (decide with mode weigh). If one of its own questions is already waiting, it retires that question or replaces it, and does not ask the owner to decline the old one. A new question that touches the same files says so. The owner is asked one plain yes or no, with no key and no link.
Weigh it against what is known. Weighing retrieves relevant past rulings, rules and saved judgment that this connection may read. It returns go, ask or stop, with the reason. Cloudflare Clef adds an advisory suggested answer to an ask. It suggests the owner's likely answer from that same permitted context. Outside a standing rule, Clef cannot grant permission or turn ask into go, and it can only lower a lean the past answers already gave. Inside a rule the owner already ruled, Clef may confirm that an inexact item fits that rule, and only after the code has checked the rule's bounds. If Clef is unsure, the answer stays ask. The number it returns is that code match, lowered by Clef when Clef was asked. Model confidence is uncalibrated; the person still decides. The rule is on Decisions. If advice is uncertain or unavailable, the question and past decisions remain usable.
Record the person's answer. On ask, the agent puts one plain question to the owner in the current chat, with what yes means and where the answer will be kept. The owner replies there. The agent records it with decide, quoting the exact words and where they were said, with the weigh_id or the existing proposal's key. The receipt attributes the ruling to the person and the recording to the agent. The agent's own recommendation is never approval.
Act and check what happened. Proceed only within the recorded permission. Read the receipt: an answer recorded, a change scheduled and a change landed are different results. Verify the actual effect and keep its evidence with the work. An answer matching the suggestion measures agreement, not whether the decision produced a good outcome.
Improve judgment when the evidence warrants it. The agent compares the outcome with the expectation and proposes a useful, reusable principle or exception. For work under a Process, save a Lesson while the run is still open, to keep the evidence and name the document to improve: the owner pushes lessons/<today>-<a-few-words>.md to main, and another member pushes it on a branch with the task's control key, which lands it. Then finish the run with its actual status. The Lesson can be reviewed and absorbed later by the owner's push, which sets it state: absorbed beside that document's change and waits for their yes. A judgment file can be that document. The next weigh can retrieve the improved guidance alongside prior decisions. Later work must show it helped; saving a Lesson alone does not prove improvement.
Which answer lets work continue?
Answer
What the agent does
go
Changes only the exact files covered by an active standing yes for this agent, and names that yes. It approves no other action in the question. A go that names an item is covered by a standing rule the owner already ruled, and it does not approve a write to a connected account. See Decisions.
ask
Gets the connected owner's own words in chat and records them with decide, mode record.
stop
Pauses the action and routes one ask or proposal to the eligible person named in the result. A co-owner rules eligible decisions in authenticated app review.
Money leaving the business, pay, tax, filed books, decisions about someone's job, irreversible customer or external effects, and changes to authority or instruction files cannot receive go, unless a standing rule the owner already ruled covers this item and names that reason. A filed month and FY26 do not wait by themselves. Ask only when the entry would change a GST return for a month whose filing record says filed. The go names the rule and the outcome. It does not approve a write to a connected account. The rule is on Decisions. Access to a file or a decision link never grants authority.
One history, across chat and the app
decide with mode ask files a question. A push to main uses the owner's live grant and saves the exact commit. Push a branch and open a change request when you need the owner's review; pushing the branch alone does not publish it.
Decision URLs belong to app review and host cards. Agent chat asks the question and records the answer without sending the owner to a decision link. For an existing proposal, changes reopens it with the person's note and lands nothing; for a weighed choice, changed terms require weighing the revised choice. settled closes an existing ask already answered elsewhere and lands nothing.
Saved judgment is readable guidance, not another permission system. Weighing reads relevant judgment files' Principles and Always ask sections for the agent and Cloudflare Clef. The agent must follow applicable guidance; those lines do not become new server-enforced approval gates. The model receives the question, options, recommendation, target paths and the permitted context used for its suggestion, including quoted rulings. It does not receive the whole space. Mainmind does not automatically rewrite judgment or train the model after an answer: the agent carries evidenced improvements through the same knowledge change process described above.
Roles
A membership records a person or standing machine in one space, with a role and current access:
viewer: reads granted knowledge and reports what looks wrong; changes no canonical knowledge.
teammate: reads granted knowledge, runs work, reports events, deposits shaped Lessons, and prepares changes where the current write class permits.
co-owner: an operational peer who does governed work, may propose changes to ruled knowledge, and may rule eligible operational decisions through the same email sign-in their invitation linked. They automatically receive every non-Owner knowledge scope and cannot manage members, onboarding, repository binding, or conserved authority.
owner: repository custodian and administrator, with all knowledge scopes, onboarding, team management, and workspace-wide human ruling authority.
The app and these pages say owner and co-owner. Tool names, role values and a space's own files still use the older names; they mean the same two roles.
Roles, OAuth operation scopes, member status, knowledge policy, and the target's write class intersect. Mainmind reloads live membership on every MCP operation and decision-page load, so revocation or a role change takes effect without waiting for a new token. A teammate or viewer charter explains responsibility; a co-owner's optional Primary focus helps route work. Neither widens permission.
The consuming agent team — chief of staff, seats, reports-to, Process bounds, channels — follows the Role map and live-member relationship in Your agent team. People join through the app's Team screen; an agent gets its place through sync with mode register, not a separate bot login.
Workspaces
Every space is a workspace with its own projection, runs, events, decisions, and members. Reads and writes are scoped to one workspace; a Mainmind connection sees exactly one space. To work in another space, make another authorization instead of switching the current connection. Every space, including the vendor's, is one workspace in the same system: the isolation that protects you is the isolation the vendor depends on.
How pages are written
Every page follows five rules: one thing per page, say where it came from, add rather than erase, turn work into lessons, and ask the owner only for changes that steer future work. How your knowledge grows shows a page and explains each rule.