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: boot / 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), page_work / /api/page-work for addressed assignments, work_context / /api/work-context for saved progress, work_session / /api/work-session to claim or hand off. find_process, read_node and search remain on the MCP connection. find_process names 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 recorded GitHub account; 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, 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, when a ruling settles it, or when it is promoted into a Lesson.
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. under_strain shows both queues, and what is waiting on a ruling, in one answer. Each strained path also carries how many runs, asks and notes hit it over 28 days, so a later run can rank the queue. Those counts are exposure, not proof a Lesson worked.
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 calls weigh. If a proposal is already waiting for a ruling, it continues that proposal using its existing decision key; it does not open a second ask for the same choice.
Weigh it against what is known.weigh 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; it cannot grant permission or turn ask into go. If advice is uncertain or unavailable, the question and past decisions remain usable. Model confidence is uncalibrated; the person still decides.
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 calls 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, use deposit_lesson while the run is still open to retain the evidence and name the document to improve. Then finish the run with its actual status. The Lesson can be reviewed and absorbed later through propose_change under that document's existing write and approval rules. 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.
ask
Gets the connected owner's own words in chat and records them with decide.
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. Access to a file or a decision link never grants authority.
One history, across chat and the app
ask_founder files a question; propose_change prepares a concrete knowledge change. weigh helps resolve a choice before acting. They feed the same ruling path, not separate approval systems. An owner answers where they are, and an owner-connected agent records that answer with decide. A co-owner uses authenticated app review because decide is owner-only. Live membership and the candidate's current authority still determine who may rule.
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. weigh 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 GitHub sign-in their invitation bound. 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 (for example ask_founder); 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 with invite_member; an agent gets its place through register_agent, 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.
