One memory. Every coding agent.

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:

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

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:

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).

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).

The rest of the guide (several agents and syncing between machines, settings, Azure, maintenance, every command) is on the guide page.