> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the Mnemom record

> Turn on the Mnemom record from the CLI, link one or more GitHub orgs, add more later, use it without GitHub, and see what it costs.

The Mnemom record is a signed statement of what happened in your recorded coding sessions. [The conduct record spec](https://docs.mnemom.ai/specifications/conduct-record.md) describes the format. This guide shows how to turn it on.

You can set it up yourself. Any owner or admin of your Mnemom org can do it. A member can link the App installed on their own personal GitHub account; see [Who can link an install](#who-can-link-an-install). You do not need a durable invite or a contracted agents setup. Linking a GitHub org never turns contracted agents on.

## The first-run step

The first time you run `mnemom agent` in a terminal, it offers an optional step to set up the Mnemom record. You answer `[Y/n/never]`.

| Answer | What happens |
| - | - |
| `Y` | The setup starts. |
| `n` | The step is skipped this time. |
| `never` | You are never asked again. |

Scripts and CI are never asked. The step is for terminals only.

The offer repeats on later launches until you link an org or answer `never`.

You need an active Mnemom org. If none is set, the CLI asks you to pick one. Change it later with `mnemom org use <slug>`.

What happens next depends on where your code lives. The CLI looks at your repo's `origin` remote to decide.

## On GitHub, with several orgs

The Mnemom record uses a GitHub App named `mnemom-record`. The App posts the PR check and writes the PR-keyed bundle. See [PR checks](https://docs.mnemom.ai/specifications/conduct-record.md#pr-checks).

1. The CLI starts a GitHub device sign-in. It prints a link and a code. Open the link and enter the code.
2. The CLI lists the GitHub accounts where the `mnemom-record` App is installed. This can include your personal account.
3. You pick which to link to your active Mnemom org. With one choice, the CLI asks `[Y/n]`. With several, you type numbers separated by commas, or `all`. Pressing Enter picks all.
4. For each GitHub org you belong to that does not have the App yet, the CLI shows an install link:

   ```text theme={null}
   https://github.com/apps/mnemom-record/installations/new
   ```

   Install the App there, then run `mnemom record add` to link that org.

Two rules to keep in mind:

* One GitHub install belongs to one Mnemom org.
* One Mnemom org can link many installs.

Your GitHub sign-in proves that you can see the install. Mnemom uses it for that check and does not store it.

### Who can link an install

| Your Mnemom org role | What you can link |
| - | - |
| Owner or admin | Any install of the App: a GitHub org or a personal account. |
| Member | Only the App installed on your own personal GitHub account. GitHub confirms that the install's account is a user account and that its id matches the account you signed in with. |
| Viewer or auditor | Nothing. |

A member who tries to link a GitHub org's install, or another person's personal install, gets `403 org_role_required`. Ask an owner or admin of your Mnemom org to link it.

In `mnemom record add`, a member who picks several installs gets the ones they can link. The CLI skips each install that needs an owner or admin, links the rest, and ends with a line naming up to three owners or admins to ask. A viewer or auditor gets one message that linking needs an owner or admin, and nothing is linked.

Unlinking an install and turning the record on or off stay owner or admin only.

Linking an install turns the record on for your Mnemom org. Every repo in an active linked install is then enrolled. If a repo's GitHub org shows as suspended or removed, its repos are not enrolled.

If an install is already linked to a different Mnemom org, the CLI skips it and says so. Unlink it there first, with that org active. If GitHub says your account can't see an install, sign in as a member of that GitHub org and run `mnemom record add` again.

Check which Mnemom org is active with `mnemom org show`. Switch with `mnemom org use`. See [Organizations](https://docs.mnemom.ai/gateway/cli.md#organizations).

## Add more orgs later

Run this at any time:

```bash theme={null}
mnemom record add
```

It runs the same GitHub sign-in and list, and links the orgs you pick to your active Mnemom org. Installs that are already linked are shown and not linked again.

The step reads your repo's remote. Run it inside a repo on GitHub.

See what is linked:

```bash theme={null}
mnemom record status
```

It shows whether the record is on for the active Mnemom org, each linked GitHub org with its status and repo selection, and whether this repo's GitHub org is linked.

`mnemom agent doctor` also shows a record line: on or off for the org, which GitHub orgs are linked, and whether this repo's org is linked. See [Preflight](https://docs.mnemom.ai/gateway/agent.md#preflight-mnemom-agent-doctor).

When you launch `mnemom agent` in a terminal, in a repo whose GitHub org is not linked, the CLI prints a one-line hint. The hint never blocks the launch. It is not shown if you answered `never`.

## Not on GitHub

GitLab, Bitbucket, Azure DevOps and repos with no remote need no App.

For these repos, the record comes as the terminal receipt you get at exit. See `mnemom agent show`. The CLI prints a short note about this once. A PR check and a PR-keyed bundle exist on GitHub only today. There is no commit-keyed bundle for other hosts yet.

## Cost

Turning the record on adds a provisional µ charge of 4% of model cost. It is shown on the receipt. The CLI prints this before you link an org.

## Remove an org

Unlink a GitHub org from your Mnemom org:

```bash theme={null}
mnemom record remove <github-org>
```

Use the GitHub org's login, for example `acme`. This unlinks the install from your active Mnemom org. It does not uninstall the App from GitHub. To uninstall the App, use your GitHub org's settings.

After you unlink an org, its repos leave the record. You can link the org again with `mnemom record add`.

If the name is not linked, the CLI lists the orgs that are. Only an owner or admin can unlink.

## Use the API

The CLI calls these endpoints. All paths start with `/v1`. Any member role can read. Writes need an owner or admin, except that a member can link the App installed on their own personal GitHub account (see [Who can link an install](#who-can-link-an-install)). Use a session token or an org API key. An org API key reaches only the org it was issued for.

| Method and path | Purpose |
| - | - |
| `GET /orgs/{org_id}/record` | Read whether the record is on for the org, and the installs linked to it. It returns `enabled` and `installations`. |
| `PUT /orgs/{org_id}/record` | Turn the record on or off for the org. The body is `{ "enabled": true }`. It returns the same shape as `GET`. Linked installs are kept when you turn it off. |
| `POST /orgs/{org_id}/record/installations` | Link a GitHub install. The body is `{ "installation_id": ..., "github_user_token": "..." }`. The token proves the user can see the install. It is never stored. Returns `201`. Linking turns the record on. Errors: `403 github_user_cannot_see_installation`, `403 org_role_required` (your role cannot link this install), `404 installation_not_found`, `409 installation_linked_to_other_org`, `503 github_unavailable` (retry). |
| `DELETE /orgs/{org_id}/record/installations/{installation_id}` | Unlink a GitHub install. Owner or admin only. Returns `204`, also when the install was not linked. |

See also [Org Admin](https://docs.mnemom.ai/guides/org-admin.md) for who counts as an owner or admin.

## Related

* [Conduct Record](https://docs.mnemom.ai/specifications/conduct-record.md): the format, signing and offline verification.
* [`mnemom record`](https://docs.mnemom.ai/gateway/cli#record-commands): the command reference.
* [`mnemom agent`](https://docs.mnemom.ai/gateway/agent): the launcher and its first-run steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.