The name comes from your sentence; choose Rename to change it. Set it up opens your AI with the request written: it reads what the space is for, suggests the first pages and skills, and adds them only when you say yes. They follow How your knowledge grows.
Already connected your AI? Ask it to make the space instead, for example "make me a Mainmind space for my job hunt". You own it, and your AI can switch to it on the connection it already has, then set it up with you.
Joining someone else's space? Ask the owner for an invite link, or choose Ask to join when you connect.
More detail
More spaces
To create another, choose Create space in the app navigation, or open /start?add=1. Each space has separate knowledge and membership. Every space you create or join also joins the AI connections you already have, so your AI can switch to it without reconnecting. The app's space switcher opens one space at a time.
A new space starts with you and basic identity, access and work definitions. It creates no agent profile, team or business Process. Folder copying and owner-connected profile continuation are separate work; creating a space alone does not prove either journey. The empty space is still ready for a first useful task: create or choose useful knowledge, deliberately register one intended profile, and retain its work. A Role and recurring Process can come later.
Where this actually stands
Signing in with GitHub works, and connecting a repository works — you do it yourself, start to finish. Mainmind imports the repository's history once; from then on your space lives in Mainmind, and GitHub keeps a copy.
Nobody has walked that path but us. It went live on 2026-08-20 and has had no customers through it yet. If you are early enough to be reading this, expect us to be on the other end of a message while you do it.
Nothing here bills you. No plan, no card, no price yet — and therefore no contract: do not put anything through this that you could not afford to set up again.
This repository can be ahead of the live Worker. Before inviting a co-owner, check that the deployed /api/surface lists a cofounder role; merged code or green local tests alone do not change mainmind.app.
Sign in. Continue with GitHub. Your GitHub account is who you are here; there is no password for us to lose.
Install the App on your repository. GitHub asks which repositories; pick the one. Read the permissions table below before you agree to it.
Connect the repository. GitHub sends you back to confirm the space's Mainmind connection. Press the button and Mainmind imports the repository's history once, usually in a few minutes; the page opens your space when it's ready. Until then the space says it is importing. If the import fails, the page says why, and Mainmind tries again within the hour.
From then on the space's knowledge lives in Mainmind and is changed there. The repository keeps a copy of every change. A change made on GitHub after the import is not brought in: make it in your space instead.
Then connect Mainmind over MCP and complete the guided first boot below, once. A managed space already has its basic setup; it does not require this repository bootstrap.
Connect the MCP
Follow the Setup for each app for the connect command or settings screen on your host, and a first-session prompt. Name a host only when that step differs.
You connect to a space; you do not log into an app. The Mainmind connection is a live, read-mostly view of the space's knowledge at a named commit, plus the run ledger and the decision queue. What your connection may do is decided by who you are in the space.
The connection URL. Your space's own Mainmind connection is https://mainmind.app/mcp/<space> — the Setup screen in /app shows it with a one-click copy, and when you read this page signed in, your own space is filled into the commands below. A connection made at that per-space URL serves that space and nothing else. The plain https://mainmind.app/mcp is the one to use if you run several spaces: it asks which space to start on, then lists the others this connection could reach, with the role each one grants, so you can tick the ones it should. It serves them one at a time, switched with use_organization.
Whichever client you connect from, the first authorization opens the same page in your browser: press Continue with GitHub. That is the only door, for the Owner who set the space up and for everyone who joins after. One way in below says what an invitation is and is not.
Joining a space someone else owns
Repository access on GitHub is not membership here, on purpose. Even with push access to the space's repository, Continue with GitHub only resolves a GitHub account already bound to a membership: the Owner who claimed it, or a person the Owner recorded. Two ways to get recorded:
Ask from the connection screen. If your GitHub account reaches the repository behind a space connected here, Continue with GitHub shows that space with an Ask to join button. Pressing it puts your request, with your GitHub account name, on the Owner's Team screen. When they accept and choose your role, this GitHub account is a member at once: connect again and the space is connected. A decline is shown on the same screen; the next word is the Owner's.
An invitation link. The Owner confirms your role in Team and hands you a private one-time link. Open it once and sign in with GitHub — that binds this GitHub account to your membership.
Either way, every later authorization, on any client, is the same Continue with GitHub.
From anything with an HTTP client
A bot holding a machine mmkey_ or a member OAuth token can start over HTTP the same way as over MCP: GET /api/boot, GET /api/page-work, GET /api/work-context, then POST /api/work-session to claim or hand off (with an owned run_id and control_key from run_start). See HTTP API. The deployment operator secret is not a start identity. Remaining knowledge reads (search, read_node, find_process, whoami) and repository work stay MCP.
The start is one sequence on every transport: connect, then whoami, boot, inbox and context, then claim. The drawing names what is serving versus still open. Over the MCP connection every step is serving. A Git checkout holds knowledge files, not the live ledger. HTTP start serves GET /api/boot, page-work, work-context and work-session; whoami and run_start stay MCP.
Start is one sequence
With Mainmind connected, call boot and follow the next action it returns. It names one of four states instead of serving starter blanks as real knowledge:
seed_template — the canonical Organizational Seed source, which cannot be instantiated in place;
incomplete — a generated space still has placeholders, lacks a substantive identity, purpose, or Owner occupant, or has no usable AUTHORITY.md;
initialized — a repository-backed space has real identity and Owner occupancy, but no real active recurring Process yet;
ready — the space has real identity and usable Authority. A repository-backed space also has its active space-specific Process; a managed space may be ready with zero Roles and zero Processes. Ready boot also returns bounded restore state: the caller's addressed inbox, open asks for this workspace, and this member's open runs as locators (never a control key). When a team map is designated, boot restores it and names an unreadable or undeclared map honestly. An owner-connected profile does not require a team map; Your agent team owns the optional governed structure. boot tells you when feedback you filed has shipped, closed, or been answered, and when there are new replies on reports you filed, answered or opened. Feedback is shared within the space: feedback_status with no receipt number lists every report filed there and what became of each (pass mine for only yours), and with a receipt number shows its conversation, which any agent in the space can join with feedback_reply.
For an incomplete repository-backed space, an Owner answers five bounded sections through onboarding_answer: identity and purpose, the Owner, initial roles, external Systems, and the first real recurring Process (the middle lists may be empty; an initialized space starts at the Process question). Answers are saved by revision, so an interrupted conversation resumes at the next unanswered section. Mainmind can structurally repair a safely recognizable Seed-shaped ORG.md; anything ambiguous returns an explicit repository-recovery action rather than invented structure.
When the questions are complete, onboarding_review shows the complete exact before/after Markdown with no repository write, and onboarding_propose raises it as one decision for the Owner. Nothing is written until they rule, and ruling it lands the change. After it lands and the projection refreshes, a fresh boot returns ready, the real space context, and the normal-work tools (find_process, then read_node).
This flow needs work access. A connection made without naming scopes has it whenever your role does; see connection access. boot and whoami say when a connection is read-only and needs reauthorization. Review and proposal fail closed if the projection is stale or the reviewed commit changed. Normal maintenance stays checkout-free: deposit_lesson for typed Lessons, deposit_work_note to create or amend a work note along its Kind lifecycle, propose_change for governed knowledge changes. A checkout is the deliberate escape hatch for recovery and bulk edits.
Where you land
/app is your space, and it is the only address you need after setting up. It opens on Today: the decisions waiting on you, each a card with the question, what becomes true on yes, and what it costs — and under it, what your operators handled without you. The rest is the same space from four other angles: Activity, Rules, Team, and Setup — which repository feeds this space and the address to connect an agent to. /preview is the same screens over a sample business, before you sign in.
One way in
GitHub is the only way a human signs in. The repository custodian signs in with GitHub, and so does a co-owner, teammate or viewer — with the same GitHub account their invitation bound. There is no code to type on the authorization page and no separate login for anyone.
The initial repository claim succeeds only when GitHub reports repository admin permission. Later sign-ins only resolve an already-linked active Owner; seeing the App installation as a collaborator never creates or promotes Mainmind authority.
An invitation is an Owner's handoff, not a login. It is a one-time code, shown once on the Team screen as a /join?invite= link. Opening it signs the person in with GitHub and binds that GitHub account to the membership, once and permanently. The code is used nowhere but the join page, and it grants nothing by itself: without a matching GitHub sign-in it does nothing. Do not forward it to anyone other than the person the Owner confirmed in Team; the ledger would be wrong about who decided what. Revocation ends both MCP and decision access on the next operation.
A persistent owner-connected agent uses the person's authenticated connection and selects its stable profile on each supported call. It has no separate login or credential, and the profile adds no human permission. Follow Persistent agents. Existing machine-member credentials remain supported through the separate legacy setup.
Inviting a co-owner
The Owner opens Team, chooses Co-owner — optionally with a plain-language Primary focus — and confirms the exact role. Only then does the Team screen reveal a one-time invitation link; access-changing MCP calls return a private review URL, never the link. A co-owner automatically holds every current and future operational knowledge area. Send the link privately.
The co-owner opens the link and signs in with GitHub, which binds their GitHub account to the membership; a browser already signed in here binds in one step and names the account it is about to bind. From then on they connect their assistant with the same Continue with GitHub every human uses. Their agent can boot, read, run work, deposit Lessons, and prepare exact proposals across ruled operational knowledge — but cannot answer decisions. The human rules eligible operational decisions by signing in with GitHub at the decision link. Team changes, onboarding, repository binding, and conserved Authority stay with the Owner. Role reduction or revocation takes effect before their next MCP operation or decision-page load. Coming back on any device, any time, is just signing in with GitHub again — there is no separate session to lose.
What Mainmind can do to your GitHub
Worth reading before you authorize anything, rather than after.
Permission
What it means
Why
Contents: read and write
Import the repository you choose once; push your space's copy to it
The one import, and the copy kept for exit and recovery. Mainmind never gives this credential to an agent.
Pull requests: read and write
Not used
Mainmind opens no pull requests: a change is decided and saved in Mainmind. It asks for this only until the App's settings drop it.
Administration: write
GitHub's label covers creating and deleting repositories
Not used. Mainmind has no tool that deletes a repository, and asks for this only until the App's settings drop it.
Metadata: read
Names, branches, basic facts
Mandatory for every GitHub App.
You choose which repositories, one at a time. Mainmind holds a GitHub App installation credential — not your personal git credential — and narrows each short-lived token to the operation. Agents and invited people never receive it. One space has one canonical repository; connect several repositories as several spaces and Mainmind keeps them separate.
What leaves your repository
Your files stay in your repository and remain readable without us. We also copy them. Connecting imports the repository's history into Mainmind, where your space then lives. Your Mainmind connection reads a projection: your markdown, parsed, indexed for keyword search, and embedded for semantic search on our infrastructure — so the text of your rules, processes and decisions, including any numbers in them, is stored in our database and a vector index. Removing the connection stops the copy to GitHub. To delete a space you own, ask your assistant to archive it. The space is locked, and you can undo that before the time it names. Until then it cannot be read. Back it up to your GitHub repository before that time. After that time, Mainmind deletes the space and its name can be used again. A GitHub repository is left as it is.
Take everything with you
You can leave with all of it. Open Accounts in the app and press Download everything. You get one ZIP of plain files that opens without Mainmind:
knowledge/: every page in your space, including your agents under knowledge/agents/, as Markdown.
files/: the original files you saved.
work.json: open work, and work from the last 90 days: who asked, who has it, and how it ended.
README.md: what is inside.
Passwords and connected-account keys stay behind. Only the space's owner can download it.
Keep a copy on GitHub
Your space lives in Mainmind, and GitHub is optional. If you want a backup there too, open Accounts, pick a private GitHub repository under Copy to GitHub, and press Start copying. Mainmind updates it after every change, in the background, and checks it again every few hours.
Your agent can set this up for you too. Ask it to keep a copy of the space in a private repository, naming it as owner/name. The Mainmind GitHub app must be installed on that repository, and your own GitHub account must be able to push to it.
The copy goes one way. Edits made on GitHub are not copied back.
Only private repositories are offered, and only ones the Mainmind GitHub app can reach. An empty repository works best.
If GitHub refuses a copy, your space is not affected. Accounts says why, and Mainmind tries again after an hour.
Stop copying leaves the GitHub repository exactly as it was.
Getting your knowledge in
Connect the repository once and the space keeps itself current. Connecting imports the history of the branch you named once, in full; after that, every change made in the space updates what your agents read by itself. boot and whoami both report which commit you are reading and when it was built. Two things it deliberately ignores:
Changes made on GitHub after the import, and other branches. They are not brought in; make the change in the space.
Files outside the space's knowledge. A README, source code, anything that is not markdown in the projected directories. Such a file is not projected, not absent: a JSON file, script or binary kept beside a Process is read from a checkout (checkout_canonical_repo for the Owner), never reported missing.
If the space's knowledge lives below the repository root, declare that directory as a virtual root in .mainmind.json:
The prefix belongs to the repository, not the connected space: a file at knowledge/ORG.md is still read as ORG.md. Without a connected repository, nothing refreshes on its own — the operator path (POST /api/projection) is exactly as current as its last push. Nothing goes stale silently, because every answer carries its commit; but connecting the repository is how you leave that state.
The working discipline
Whatever the transport, the shape of good work is the same:
boot, then obey what it returns; those documents outrank anything you remember.
Route tasks through find_process when the space has an applicable Process. A match names the portable cli: when the Process or its System record has one; otherwise it says the CLI is absent. Read a matched Process with read_node before acting. In a new managed space with no Process, use the useful knowledge and real permissions already present; do not invent a readiness prerequisite.
A run is already open — your first call opened one. Call run_start once you know the task, and finish with run_finish and your judgment of how it went; a run never closed is closed by the clock as abandoned, never as landed.
Follow the decision and judgment loop when a choice needs human judgment. Start with weigh, or continue an existing proposal by its decision key. Ask the owner in the current chat and record their exact answer with decide; the guide explains when an existing yes covers the work, when another person must rule, and how learning improves the next choice.
