# Mega Mind guide

Mega Mind (`mind`) is a shared, long-term memory for AI coding agents. Every agent on a machine
(Claude Code, Codex, Grok, Copilot, or anything that can run a command) reads from and writes to the same
store, so:

- **nothing gets rediscovered:** before building or debugging, an agent searches how another agent
  already did it, and gets the files to read;
- **nothing is lost** when an agent's context window is wiped: it searches its own past work;
- **knowledge stays accurate:** entries are tied to the code they describe and are flagged when it changes.

It is a single command-line program plus a folder of markdown files. Nothing listens on a port and no
server is needed; the only scheduled work is the optional nightly review (section 8).

---

## 1. What goes in it

An **entry** is a short markdown note with a header of facts (frontmatter). Each has a **kind**:

| Kind | What it captures | Required sections |
|---|---|---|
| `system` | How something was built: a service, feature, pipeline, game system | Goal, Approach, Key files |
| `workflow` | How to do a multi-step task: a release, migration, trailer, screenshot set | Goal, Steps |
| `fix` | A problem that took real digging, and what solved it | Problem, Solution |
| `gotcha` | A trap that is easy to fall into | What happens, Avoid it |
| `decision` | A choice that was made and why, so nobody silently reverses it | Decision, Why |
| `runbook` | An exact operational procedure: deploys, ops tasks | Purpose, Steps, Verify |
| `overview` | One per project: stack, layout, main systems | Stack, Layout |

Frontmatter fields: `title`, `kind`, `project`, `owner` (defaults to project), `tags`, `engine` (stack and
versions), `genre`, `platform`, `verified` + `verified_how`, `refs` (the real files, as
`project:path/in/repo`; a ref must be inside a registered project, since agents open refs), `related`, `supersedes`. `mind template <kind>` prints a ready skeleton.

What **not** to record: routine steps ("ran the tests"), or anything the repo's docs already say clearly.
The mind should be dense with things that save the next agent real time.

---

## 2. How agents use it

```sh
mind search "retry webhooks with backoff"        # by meaning + keywords; --kind, --project, --engine, --tags…
mind search "retry webhooks" --brief             # one line per result, to scan them all before opening any
mind get <id>                                    # full entry, its files (absolute paths), staleness, related entries
mind record --file entry.md                      # new entry (or pipe it in: mind record < entry.md)
mind get <id> --raw > e.md; …edit…; mind update <id> --file e.md
mind ack <id>                                    # "the code changed, but this entry is still right"
mind stale                                       # this project's entries that need checking
mind who <project>                               # where a project lives, its entries, how to reach its agent
mind uses <tech>                                 # which projects/entries use a technology
```

Agents run `mind` from inside their project's folder; it works out the project from the working
directory and records the writer as `<project>-agent` (or `$MIND_AGENT`).

The intended rhythm:

1. **Session start:** check stale entries and fix or confirm them.
2. **Before non-trivial work:** search, read the best entries, open their files.
3. **After building or solving something reusable:** record it, or update the existing entry.
4. **After a context reset:** search before re-deriving anything.

---

## 3. How it works

### Storage

- Entries are files in `entries/` inside the mind folder (`~/.local/share/mega-mind`, or
  `%LOCALAPPDATA%\mega-mind` on Windows; override with `MIND_HOME`).
- The folder is a **git repo**. Every write is a commit authored by the agent that made it, so
  `mind log` shows who wrote what, and anything can be undone with git.
- `projects.toml` maps project names to folders; refs like `payments-api:src/retry.rs` resolve through it.
- `config.toml` holds your settings (section 6).
- `index.db` is a search index **derived** from the files. It is rebuilt automatically when files
  change, and deleting it is always safe.

### Search

Each entry is split by `##` section. Each section gets an **embedding**, a list of numbers capturing its
meaning, so "make failed deliveries try again later" finds an entry titled "retry queue with exponential
backoff". Keyword matching (SQLite FTS5) runs alongside, so exact names and error strings also hit. The two
rankings are merged; the result shows the best-matching section of each entry.

Without an embedding provider (or when it is unreachable) search is **keyword-only**, and it catches up
automatically once embeddings work again.

### Staleness

When an entry is saved, the mind stores a fingerprint of each file in its `refs`. If a file later
changes (or disappears), the entry is **stale**: it may describe code that no longer exists. Stale entries
show a ⚠ in search results, and the owning project's agent is told:

| When | How |
|---|---|
| Session start | the hook lists the project's stale entries (up to 10) |
| Each message you send | a one-time note about anything newly stale; repeated after 10 messages if still not handled |
| `mind stale` | on demand, or at session start for tools whose hooks can't reach the model |
| `mind review` | the librarian (an LLM) compares each stale entry with the code change and writes a verdict: accurate / needs update, with notes |

The agent then updates the entry or confirms it (`mind ack`). The librarian only writes notes; it never
changes entries.

Staleness only sees the files an entry refs, so agents are told to ref what an entry *relies on* as well
as what it describes: the interface, schema or shared config it assumes, even in another project. A note
about a service that calls an API refs the API's definition too, so changing that API flags the note.

### Recording safeguards

- **Validation:** kind and required sections, a known project, real files in `refs`, valid YAML.
- **No duplicates:** with embeddings on, a near-identical entry of the same kind is refused, pointing to
  the existing one (override with `--new` when it really is different). Keyword-only minds skip this check.
- **No secrets:** text that looks like a key, token, password or private key is refused. Name the
  environment variable or file that holds it instead.
- **Runbook review** (optional): changes to runbooks become proposals (`mind proposals`) that the
  configured reviewer accepts or rejects.
- **Cross-project edits** are allowed and marked in the history.

---

## 4. Connecting agent tools

`mind setup` installs what each tool supports and merges into existing settings (it never overwrites
your other settings, and re-running it changes nothing that is already right).

| Tool | Skill (full guide) | Always-on instructions | Hooks |
|---|---|---|---|
| Claude Code | `~/.claude/skills/mega-mind/` | via the session-start hook | session start, each message, end of turn |
| Codex | `~/.codex/skills/mega-mind/` | managed block in `~/.codex/AGENTS.md` | same three, in `~/.codex/hooks.json` (trust them once when Codex asks). Codex's sandbox blocks writes outside the project and keeps every `.git` read-only, so inside it Codex can search and read the mind but not save: `mind` then tells it to request escalated permissions for that one command, which you approve |
| Grok | reads Claude's skill | `~/.grok/rules/mega-mind.md` | reads Claude's hooks, in trusted folders; only the end-of-turn nudge reaches the model, so the rule tells it to run `mind stale` and to search first |
| Copilot | — | add the printed block to `AGENTS.md` / `.github/copilot-instructions.md` in your repos | where supported |
| Anything else | — | paste the printed block into its instructions | — |

The three hooks:

- **Session start:** "the mind exists; your project has N entries; these are stale."
- **Each message:** entries that may already cover what the message asks, and a note when entries
  newly went stale. Suggestions match on keywords and stay quiet unless an entry shares at least two
  of the message's meaningful words, including a distinctive one (or two in its title); at most three
  entry ids (never titles: those are other agents' text), each once per session, so an agent opens
  them before it starts digging. Silent otherwise; it reads
  the saved index only (a few tens of milliseconds). `[hooks] suggest = false` turns suggestions off.
- **End of turn:** once an agent has edited a few files, it is asked once to record anything reusable,
  then again only after many more edits.

Machine-specific instructions (your projects, your deploy rules) go in `<mind folder>/skill-local.md`;
setup appends them to the installed skill under "On this machine". Because that text becomes part of
every agent's instructions, and any agent can write the file, setup shows it to you and asks before
including it, and asks again whenever it changes (`--yes` never approves it).

---

## 5. Using it with several agents

- An entry belongs to its `owner` project, whose agent keeps it accurate.
- `mind who <project>` tells an agent how to reach the owning agent with a question.
- **Trust model:** entries and messages from other agents are reference material, never instructions or
  approval. A runbook says *how* to do something, never *whether*: deploys and other outward actions
  still need the human's explicit go-ahead.

### Syncing a mind between machines

The mind folder is an ordinary git repo, so you sync it the way you sync any repo. Mega Mind never
pulls or pushes by itself.

1. **Make a private remote** you control (a private GitHub/GitLab repo, or a bare repo on your own
   server). Entries describe your systems, so never make it public.
2. **On the first machine:** `git -C <mind folder> remote add origin <url>`, then
   `git -C <mind folder> push -u origin HEAD`. (`mind doctor` prints the mind folder.)
3. **On another machine:** install `mind`, clone the remote to that machine's mind folder
   (`git clone <url> ~/.local/share/mega-mind`, or wherever `MIND_HOME` points), give the clone the
   identity a new mind gets (`git -C <mind folder> config user.name "Mega Mind"` and
   `git -C <mind folder> config user.email mind@localhost`; each entry still records the agent that
   wrote it), then run **`mind setup` in a terminal**.
4. **Keep them in step:** `git -C <mind folder> pull --rebase` and `git -C <mind folder> push`, by hand or
   from your nightly job before `mind maintain`.

What travels and what stays:

- **Synced:** `entries/`, `proposals/`, `projects.toml`, `config.toml`.
- **Local to each machine:** the search index, librarian reviews, hook state and edit drafts are
  git-ignored, and if a commit adds any of them anyway they're deleted and untracked on the next run.
  The local embedding model and sign-in token caches are kept outside the mind folder (in the cache
  folder), so they never sync.
- **Approved per machine:** projects and AI settings that arrive through a pull wait until a person
  approves them on that machine, each on its own:
  - a project in `projects.toml` that this machine hasn't approved isn't used (agents aren't pointed
    at its folder); the other projects and the AI settings carry on as before;
  - changed AI settings in `config.toml` are held: search is keyword-only and the librarian is off
    until you approve them. On a fresh clone, settings that send nothing anywhere (`local` or `none`
    for both) are approved automatically; anything remote waits.

  `mind setup` shows each held item and asks; `mind doctor` says what's held, and commands that would
  use it print a warning.

**Project paths:** `mind project add` and setup's scan store full paths. If your repos are in the same
place on every machine (say `~/code/<repo>`, with the same user name), that just works. If the home
folders differ (`/home/<you>` on Linux, `/Users/<you>` on a Mac), write the paths in `projects.toml` with `~`
(`path = "~/code/payments-api"`); `~` is your home folder on each machine.

**Conflicts:** resolve a pull that stops on a conflict before using `mind` again. While a merge or
rebase is unfinished, `mind` won't commit, and its message gives the git commands to finish or abort
it; a `config.toml` or `projects.toml` with conflict markers fails to load until it's fixed. Two agents
editing the same entry on two machines is the usual cause: keep the version that's right, `git add`
it, and continue the rebase.

**Secrets:** none of this needs a key in the repo. Use `auth = "azure"` (keyless) or `env:VAR`, which
is read from each machine's own environment.

---

## 6. Settings (`config.toml`)

`mind setup` writes this; you can also edit it directly. After you change the AI settings by hand
(provider, url, auth, models, privacy), run `mind setup` in a terminal once to approve them on this
machine: until then they are held back, search is keyword-only and the librarian is off (`mind doctor`
says so). This protects you when a synced mind's config.toml changes.

```toml
[identity]
user = "Alex"                    # how agents refer to you
reviewer = "Alex"                # who accepts runbook proposals
review_runbooks = true

[embeddings]
provider = "azure"               # local | azure | openai | none
url = "https://my-resource.openai.azure.com"
model = "my-embedding-deployment"
auth = "azure"                   # azure | env:VAR | command:<cmd> | none
token_hosts = []                 # non-Azure hosts allowed to receive the Azure token (a company gateway)

[librarian]
provider = "azure"               # lmstudio | azure | openai | none
url = "https://my-resource.openai.azure.com"
auth = "azure"
model = "my-strong-chat-deployment"   # for reviews
quick_model = "my-fast-chat-deployment"   # for search --deep
timeout_secs = 600

[hooks]
prompt_every = 1                 # check for stale entries on every Nth message

[privacy]
mask = true                      # mask emails, IP addresses and home-folder user names sent to remote models
patterns = []                    # extra regexes to mask, e.g. ['\bACCT-\d{8}\b', '\bsrv-[a-z0-9-]+\.corp\b']
```

Masking applies to everything sent to a model that isn't on this machine (remote embeddings, the
librarian, `--deep`); LM Studio on localhost gets the text unchanged. It complements, not replaces,
the secret check: entries that look like they hold a secret are never sent at all.

Providers:

- **local:** a built-in CPU model (bge-base-en-v1.5). Needs the `local-embeddings` build feature, which
  downloads ONNX Runtime at build time and the model from Hugging Face on first use. On Linux, ONNX
  Runtime needs glibc 2.38+ and GCC 13+ (Ubuntu 24.04+, Debian 13+); older systems build without it.
- **azure:** Azure OpenAI through its v1 API (`<resource>/openai/v1`). `model` is the **deployment name**.
- **openai:** any OpenAI-compatible server (LM Studio, vLLM, …); `url` includes `/v1`.
- **lmstudio** (librarian only): like openai, but Mega Mind starts LM Studio's server and loads the model
  when needed (`lms` CLI, 16k context), then puts LM Studio back the way it found it.
- **none:** embeddings off means keyword-only search; librarian off means no reviews or `--deep`.

Auth:

- **azure:** keyless. Uses the managed identity when running on an Azure VM (set `AZURE_CLIENT_ID` if the
  VM has several user-assigned identities), otherwise your Azure CLI sign-in (`az login`). Tokens are for
  `https://cognitiveservices.azure.com`; use `azure:https://ai.azure.com` for Microsoft Foundry resources
  that need that audience. Tokens are cached until they expire, per scope and identity, in your private
  cache folder (`~/.cache/mega-mind/auth-cache.json`, `%LOCALAPPDATA%\mega-mind-cache\auth-cache.json`
  on Windows), outside the mind, so copying or backing up the mind never carries a live token.
  The Azure token is only ever sent over https to Azure OpenAI / AI Services endpoints
  (`*.openai.azure.com`, `*.cognitiveservices.azure.com`, `*.services.ai.azure.com`, and their
  government/China equivalents). An API Management gateway (`*.azure-api.net`) or any other company
  gateway must be listed: `mind setup` asks whether that host may receive the token and records it in
  `token_hosts`.
- **env:VAR:** an API key read from environment variable `VAR` (sent as `api-key` to Azure, as a bearer
  token elsewhere). The key is never stored by the mind.
- **command:\<cmd\>:** a command that prints a bearer token, for company-specific sign-in tools. It
  runs through your shell, so treat `config.toml` like a script: only you should edit it.

Keys and tokens are only sent over https (plain http is allowed only to this machine, e.g. LM Studio),
and the mind never follows a redirect with them.

---

## 7. Azure: first-time setup and troubleshooting

This path is built to Azure's documented v1 API but has not been tested against a real tenant, so expect
to adjust it the first time.

1. `mind setup` → embeddings `azure` → endpoint, embedding deployment name, auth `azure`. Setup runs a
   one-line embedding test and prints `✓ works (N dimensions)` or the exact error.
2. If it fails:
   - **"no managed identity here, and `az account get-access-token` failed":** run `az login` (and
     `az account set --subscription …` if you have several), then retry.
   - **HTTP 401 / 403:** your identity needs a role on the Azure OpenAI resource, typically
     *Cognitive Services OpenAI User*. Ask whoever owns the resource.
   - **HTTP 404:** check the endpoint (the resource URL, e.g. `https://name.openai.azure.com`; the mind
     adds `/openai/v1`) and that `model` is the *deployment* name, not the model family name.
   - **HTTP 400 on chat:** some deployments reject a parameter. The mind sends `model`, `messages` and
     `max_completion_tokens` (no `temperature`), which GPT-5-family deployments expect. Mega Mind
     shows the status and Azure's error code, not the full response (it can echo your text); try the
     same request with `curl` to see which parameter the deployment rejects.
   - **"refusing to send your Azure sign-in token to …":** the endpoint isn't an Azure domain. If it is
     your company's API gateway, add its host to `token_hosts` (or answer yes when setup asks).
   - **A corporate proxy or a different auth flow:** use `auth = "command:<your token command>"`.
3. Re-run `mind setup` (if you edit `config.toml` by hand, run `mind setup` afterwards to approve the
   change) and try `mind search "test"`. If embeddings fail, search
   still works on keywords and warns; entries are embedded once the connection works.
4. Changing the embedding provider or deployment rebuilds the index automatically: vectors from
   different models can't be compared.

What leaves the machine with Azure: entry text (for embeddings) and, for reviews, an entry plus the
**git diff** of its changed files. The librarian never sends whole files, never sends anything for refs
outside a registered project, and withholds any diff that looks like it contains a secret. Entries are
checked for secrets again before they are sent (a hand edit or a git pull skips `mind record`'s
check): one that looks like it holds a key stays keyword-searchable, is not sent, and is reported
until someone removes the secret. It goes only to the endpoint you configure.

Company networks: the mind trusts the operating system's certificate store, so TLS-inspecting proxies
whose certificate is installed on the machine work, and it honours `HTTPS_PROXY`/`NO_PROXY`.

Match thresholds differ by model (OpenAI/Azure embeddings score lower than the local model). The
defaults suit each provider; to tune them, set `duplicate_at`, `weak_below` and `related_at` under
`[embeddings]`.

---

## 8. Maintenance

- `mind doctor` checks everything is wired up: settings, AI providers, the index, and each agent tool's
  skill, instructions and hooks. With remote embeddings it sends one real one-word embedding request
  (the only way to know the deployment works); the librarian check only lists models, which costs
  nothing. Start here when something seems off.
- `mind` on its own (or `mind stats`) shows what's in the mind: entries per project and kind, stale
  counts, most active writers, newest entries.
- `mind digest` lists what agents recorded in the last day (`--since 3d`, `--since 2026-10-01`).
- `mind check` validates every entry and lists stale refs.
- `mind maintain` is the nightly upkeep; schedule it (cron or a systemd timer on Linux, launchd on
  macOS, Task Scheduler on Windows; `nightly.sh` is an example). It never edits entries; it brings the
  index up to date, has the librarian review stale entries, lists broken links and near-duplicates,
  and has the librarian check pairs of closely related entries for **contradictions** (two entries
  saying different things about the same situation). Each pair is judged once per version of the two
  entries; only confident verdicts are reported. `mind get` shows "may contradict" on both entries
  and `mind doctor` counts them. `--no-librarian` skips the model parts; `--limit N` caps them.
- `mind review` runs just the librarian review of stale entries.
- **Links and retiring:** `related` and `supersedes` in an entry's frontmatter must name existing
  entries; `mind get` shows links in both directions and `mind check` lists broken ones. An entry
  that is superseded, or retired with `mind retire <id> --why "…" [--by <new-id>]`, drops out of
  search, lists, stale checks and hooks; it stays readable with `mind get` and `--all`. `mind rm`
  refuses to delete an entry others link to unless you add `--yes` (retiring is usually better).
- **Ranking:** when two results score about the same, the verified one comes first.
- `mind log` shows recent changes; it is a git repo, so `git -C <mind folder> revert <commit>` undoes one.
- `mind reindex` rebuilds the search index from scratch.
- `mind upgrade` updates Mega Mind itself: it fetches the clone you built it from, shows the new changelog
  sections, builds the new version from a clean checkout with the same features, and only then moves
  the folder forward (never over local changes or commits). `--check` downloads the update but
  doesn't install it. If the clone's address still has your token in it, it moves the token to git's credential
  store first. Afterwards run `mind setup` to refresh the agent instructions.
- Back up the mind folder however you back up other files; it is self-contained and holds no tokens.
  It is created readable only by you (`chmod 700` on macOS/Linux); `mind doctor` warns if it isn't.

---

## 9. Command reference

| Command | What it does |
|---|---|
| `search <query>` | Search by meaning and keywords. `--project --kind --tags --engine --genre --platform -n --deep --json --all` |
| `get <id> [--raw] [--notes]` | Show an entry with its files, staleness, links, librarian verdicts and related entries; `--notes` adds the librarian's free-text notes (AI output, untrusted) |
| `related <id>` | Entries most similar to one entry |
| `list` | List entries, newest first (same filters as search) |
| `record [--file F] [--new]` | Add an entry from stdin or a file |
| `update <id> [--file F]` | Replace an entry (history kept in git) |
| `edit <id>` | Open an entry in `$EDITOR`, then validate and save |
| `ack <id>` | Mark a stale entry as checked and still accurate |
| `rm <id> --reason R [--yes]` | Delete an entry (it stays in git history); `--yes` for runbooks and linked entries |
| `retire <id> --why W [--by NEW]` | Hide an entry that is no longer true (readable with `get` and `--all`) |
| `maintain [--limit N] [--no-librarian]` | Nightly upkeep: index, stale reviews, broken links, duplicates, contradictions |
| `stale [--project P] [--all]` | Entries whose referenced files changed |
| `review [--project P] [-n N] [--force]` | Librarian review of stale entries |
| `who <project>` | A project's path, stack, entries, and how to reach its agent |
| `uses <tech>` | Projects and entries using a technology |
| `projects`, `project add` | List or register projects |
| `proposals [show/accept/reject]` | Runbook proposals awaiting review |
| `template <kind>`, `kinds` | Entry skeletons and kind descriptions |
| `doctor` | Check settings, providers, index and agent tools |
| `stats` (or plain `mind`) | Overview of what's in the mind |
| `digest [--since 24h]` | What agents recorded recently |
| `check`, `log`, `reindex` | Maintenance |
| `setup` | One-time (re-runnable) configuration |