Installation

There are two ways to give an agent a brain:

1. The hosted MCP connector — the universal path. One streamable-HTTP + OAuth endpoint (https://mcp.brainmemory.ai/mcp) reaches every supported host, including the Claude.ai and ChatGPT apps. Nothing to install locally.
2. The local-first native plugin — free, stores everything in ~/.brain/ on your machine, and wires slash commands and prompt sections into the agent's own config. Claude Code and Codex can also take it as a marketplace plugin that adds deterministic session hooks.

Most people start with the connector; reach for the native plugin when you want a fully local, no-account brain.

The hosted MCP connector (universal)

The connector is a remote MCP server (https://mcp.brainmemory.ai/mcp, streamable-HTTP + OAuth). A single connector reaches Claude Code, OpenAI Codex CLI, OpenCode, GitHub Copilot CLI, Kilo, the Claude.ai apps, ChatGPT (paid plans + Developer Mode), and Google Antigravity / Gemini Enterprise. Point each host at the URL:

# Claude Code
claude mcp add --transport http brain https://mcp.brainmemory.ai/mcp
 
# OpenAI Codex CLI
codex mcp add brain --url https://mcp.brainmemory.ai/mcp

• OpenCode — add a remote MCP server in opencode.json (mcp → remote url: https://mcp.brainmemory.ai/mcp).
• GitHub Copilot CLI — add to ~/.copilot/mcp-config.json ("type": "http", "url": "https://mcp.brainmemory.ai/mcp"), then authenticate with /mcp auth in-session.
• Kilo — add to kilo.jsonc (mcp → "type": "remote", "url": "https://mcp.brainmemory.ai/mcp"). OAuth starts automatically on first connect.
• Antigravity — set serverUrl to https://mcp.brainmemory.ai/mcp in mcp_config.json.
• Claude.ai / ChatGPT apps — add a custom connector (URL + OAuth) in Settings → Connectors. See Use Brain in the Claude apps for the full walkthrough.

The local-first native plugin

Prefer a fully local brain with no hosted service? Install the plugin globally, then run the setup wizard.

Install

npm install -g brain-memory
brain

The first command installs the package globally — this gives you both the interactive setup wizard and the brain CLI (brain recall, brain memorize, brain reinforce, …) that agents rely on for deterministic scoring.

The second command runs the setup wizard, which asks which runtime(s) to configure (Claude Code, OpenAI Codex CLI, OpenCode, GitHub Copilot CLI, Kilo, or Antigravity) and whether to install globally or for the current project.

Non-Interactive Install

Pass flags to skip the interactive prompts:

npm install -g brain-memory
 
# Claude Code, global
brain --claude --global
 
# OpenAI Codex CLI, global (also registers hooks in ~/.codex/hooks.json)
brain --codex --global
 
# OpenCode, local project
brain --opencode --local
 
# GitHub Copilot CLI, global
brain --copilot --global
 
# Kilo, global
brain --kilo --global
 
# Antigravity (experimental), global
brain --antigravity --global
 
# Core CLIs (Claude Code + Codex + OpenCode), global
brain --all --global

brain --codex also registers Brain's three hooks — SessionStart, UserPromptSubmit, SessionEnd — in ~/.codex/hooks.json. The merge is non-destructive (your other hooks stay), and Codex asks you to trust them once: run /hooks inside Codex. The scripts are the same ones the plugin ships and run the engine in-process, so they work without the brain binary on PATH. Codex caps hook context at roughly 2,500 tokens, below Brain's default 3,000-token working-memory budget — lower working_memory_budget_tokens in ~/.brain/config.json to about 2,000, or raise Codex's additionalContextLimit. See Hook injection points for what each hook injects. The Claude Code installer stays prompt-based; Claude Code gets hooks through the plugin below.

Plugin Install

The repository is also a plugin marketplace (omelas-tech/brain) for Claude Code, Codex, and ChatGPT workspaces. It lists two plugins:

Claude Code

claude plugin marketplace add omelas-tech/brain
claude plugin install brain@brain-memory          # local-first: hooks + /brain:* commands
claude plugin install brain-cloud@brain-memory    # optional: the hosted MCP connector

The plugin is named brain, so commands stay /brain:*. This is the hook path for Claude Code — SessionStart injects the budget-bounded session payload as context and UserPromptSubmit runs prompt-time recall, with nothing for the model to remember to run.

OpenAI Codex CLI

Run codex /plugins, add the marketplace omelas-tech/brain, then install brain (and optionally brain-cloud). Codex reads the Claude manifest (.claude-plugin/plugin.json, with a .codex-plugin/plugin.json overlay) and exports CLAUDE_PLUGIN_ROOT to plugin hooks, so both hosts run the same hook scripts.

ChatGPT workspaces

For ChatGPT Business, Enterprise, and Edu, a workspace admin imports the marketplace once — Admin → Plugins → Add → Import marketplace → the repository URL (https://github.com/omelas-tech/brain) — and the workspace picks up new versions daily.

• Plugins that declare MCP servers (brain-cloud) are Desktop-only in ChatGPT.
• Import does not grant access by itself: each user completes the connector's OAuth sign-in on first use.

What Gets Installed

The installer copies two things to your agent's configuration directory (three for Codex CLI):

1. Command prompts — Slash command definitions (e.g., /brain:memorize, /brain:remember) that teach the agent how to use the memory system
2. Prompt section — Instructions appended to your agent's main prompt file (CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md, or Kilo's rules/brain-memory.md) that enable session lifecycle behavior (auto-loading memories at start, suggesting memorization at end)
3. Hooks (Codex CLI only) — SessionStart, UserPromptSubmit, and SessionEnd entries merged into ~/.codex/hooks.json, pointing at the package's hooks/*.mjs

Your actual memories live in ~/.brain/, which the installer creates for you (it's also auto-created on your first /brain:memorize or /brain:sync).

Manual Install

If you prefer to install manually, copy the command files and prompt section yourself:

Claude Code

# Copy commands
cp -r commands/brain/ ~/.claude/commands/brain/
 
# Append prompt section to CLAUDE.md
cat prompts/claude.md >> ~/.claude/CLAUDE.md

OpenAI Codex CLI

# Each command becomes a skill
for f in commands/brain/*.md; do
  name=$(basename "$f" .md)
  mkdir -p ~/.agents/skills/brain-"$name"
  cp "$f" ~/.agents/skills/brain-"$name"/SKILL.md
done
 
# Append prompt section to AGENTS.md
cat prompts/openai.md >> ~/.codex/AGENTS.md
 
# Hooks (optional): merge hooks/hooks.json into ~/.codex/hooks.json with
# ${CLAUDE_PLUGIN_ROOT} replaced by the package path, then run /hooks in Codex

OpenCode

# Copy commands
cp -r commands/brain/ ~/.config/opencode/command/brain/
 
# Append prompt section to AGENTS.md
cat prompts/openai.md >> ~/.config/opencode/AGENTS.md

GitHub Copilot CLI

# Each command becomes a skill (~/.agents/skills/ is shared with Codex)
for f in commands/brain/*.md; do
  name=$(basename "$f" .md)
  mkdir -p ~/.agents/skills/brain-"$name"
  cp "$f" ~/.agents/skills/brain-"$name"/SKILL.md
done
 
# Append prompt section to the global instructions file
cat prompts/copilot.md >> ~/.copilot/copilot-instructions.md

Kilo

# Slash commands (invoked as /brain-remember, /brain-memorize, /brain-status)
mkdir -p ~/.config/kilo/commands
cp integrations/kilo/commands/brain-*.md ~/.config/kilo/commands/
 
# Write the prompt, then register it in kilo.jsonc
mkdir -p ~/.config/kilo/rules
cp prompts/kilo.md ~/.config/kilo/rules/brain-memory.md

Then add "~/.config/kilo/rules/brain-memory.md" to the instructions array in ~/.config/kilo/kilo.jsonc (the installer does this automatically when the file is strict JSON).

Antigravity (experimental)

# Each command becomes a skill
for f in commands/brain/*.md; do
  name=$(basename "$f" .md)
  mkdir -p ~/.gemini/skills/brain-"$name"
  cp "$f" ~/.gemini/skills/brain-"$name"/SKILL.md
done
 
# Append prompt section to GEMINI.md
cat prompts/gemini.md >> ~/.gemini/GEMINI.md

Update

To update Brain Memory to the latest version:

npm install -g brain-memory
brain update

The first command updates the package and CLI tools. The second command refreshes the slash command prompts for your installed runtimes. You can target specific runtimes:

brain update --claude
brain update --codex
brain update --opencode
brain update --copilot
brain update --kilo
brain update --antigravity
brain update --all

Uninstall

brain uninstall
npm uninstall -g brain-memory

The first command removes slash commands, prompt sections, and Codex hooks from your agent's configuration. The second removes the package and CLI tools. Your ~/.brain/ directory (all your memories) is preserved by default.

To also delete your memories:

brain uninstall --delete-data

To skip confirmation prompts:

brain uninstall --yes