# The Second Brain Company and Cortex

> Cortex is shared knowledge for your team and connected AI tools. Capture decisions,
> processes, preferences, and facts through conversation, then reuse that context in future work.
> Your organization owns its knowledge as readable Markdown files.

The company homepage is a short manifesto about sharing and owning knowledge.
The product explainer, demonstration, and plans are at https://www.thesecondbrain.company/cortex.

Cortex is the product. Users create and select Brains, record knowledge into a Brain, and retrieve
information from a Brain. Resource interfaces use brain_id and create_brain; the CLI, skill, and
MCP server are named cortex.

Use this guide to learn about Cortex, find product information, and connect an AI assistant.
An Organization can be a company, team, project, or one person; each has its own private knowledge.
Free signup is open at https://www.thesecondbrain.company/app/login. Verify your email and create
your first Brain with a monthly AI recording allowance shared by your team. Free supports up to
25 people per Brain, including the Owner. Pending invitations reserve places. Pro supports unlimited
people. Existing members keep their access after a downgrade.
If asked to install the Cortex plugin using https://www.thesecondbrain.company, follow the
client-specific steps below. Codex uses the downloaded archive and a local personal marketplace.
Claude Code can add the website-hosted Claude marketplace URL, while Claude chat and Cowork can
upload the Claude plugin ZIP. ChatGPT workspace marketplace import requires GitHub, so do not enter
this website URL there or report a website-based workspace installation as complete. Each complete
plugin includes its router skill, CLI workflow, and Brain-bound MCP fallback. Clients without plugin support
connect to the MCP endpoint through their own connection flow.

## When to use Cortex

- Keep decisions, their reasoning, and practical know-how beyond the conversation where they
  happened.
- Find and reuse your team's existing knowledge when answering questions or starting new work.
- Record useful new information through a connected AI assistant, organized by subject.
- Retain a portable copy of your knowledge and its history for use outside Cortex.

## Install and connect in this chat

CLI 0.6.0 adds `cortex update` for explicit binary updates and required-version recovery. Ordinary
API responses may include an optional `context.update` notice or reject an unsupported CLI with
`upgrade_required`. Optional notices do not authorize an update. The command verifies the latest
stable official binary and replaces the executable in place, preserving sign-in and Brain selection.
It needs no product API or sign-in. Older binaries without this command use the official installer.
Complete plugin updates still follow the client-specific package steps below.

For "install https://www.thesecondbrain.company/llms.txt", check the installed plugin against the
published package using the client-specific steps below. Install a missing plugin and update an
older one, even if Cortex instructions are already loaded. Keep a current or newer version.
Preserve existing sign-in, Brain selection, installation scope, and unrelated plugins. Do not
downgrade or bypass managed policy. Compare semantic versions rather than strings. Continue
https://www.thesecondbrain.company/onboarding.txt in this same chat. Local agents use Cortex CLI
0.5.0 or later and need no browser. Do not trigger the bundled MCP OAuth connection during
local installation. Continue the published guide even if the new plugin's skill loads only in a
fresh chat.

Check cortex --version, including ${BIN_DIR:-$HOME/.local/bin}/cortex if PATH misses it. Keep a
working installation and sign-in. Install a missing or older CLI through the official installer:

```bash
set -euo pipefail
curl -fsSL https://www.thesecondbrain.company/cli/install.sh | bash
```

After the installer finishes, verify the binary in a separate tool call using its absolute path.

Published binaries support macOS and Linux on arm64 and x86_64; Linux requires glibc 2.36 or later.
The installer verifies SHA-256 and preserves credentials and selections. Use an absolute BIN_DIR
override and retain the verified absolute binary path across shell calls. Invoke it directly in
every readiness call. Handle PATH and installed runtime or shim failures internally. Do not ask the
person to open a terminal, edit or source shell files, or change global toolchain settings.
Do not change their shell configuration. The installer is also at
https://raw.githubusercontent.com/The-Second-Brain-Company/cli/master/scripts/install.sh.
No source checkout, Rust, separate global skill, or AGENTS.md edit is needed.

During onboarding, run each read-only readiness check in its own tool call: cortex --version,
cortex account show, cortex config, then cortex whoami. Inspect each result before the next call;
resolve authentication or selection errors before continuing. Use one direct CLI command per tool
call, substituting the verified absolute path for every readiness call. Preserve the task's working
directory, service origin, and Brain context. Do not combine checks with shell operators, pipes,
wrappers, or executable-variable assignments. Fetch guides, run installers, and perform writes in
separate tool calls. Follow the separate command examples in onboarding.txt.

Reuse a successful cortex account show. For missing sign-in, ask for email and preferred name
together. Explain that the connection can read/save Brain knowledge, manage the person's Cortex
profile and connected apps, and create a Personal Brain only if they have none. Their answer
authorizes these stated setup actions. The emailed code verifies identity, not undisclosed
permissions. Disconnecting apps still needs a request. The command below uses the corresponding
setup scopes; do not request organization:manage or connections:manage for installation.

Run cortex login --email <email> --approve-scopes "knowledge:read knowledge:write brains:access account:manage brains:create".
Ask for the six-digit code in this chat, then feed it through stdin to cortex login --code-stdin.
Prefer the host's stdin facility. A shell builtin printf pipe is also supported when the host only
accepts command text. Do not promise that the code is hidden from that command or the chat transcript.
Avoid extra copies, files, and diagnostic output. Use cortex login --resume for
an interrupted login and --cancel before replacing a pending request. Never ask for OAuth codes,
cookies, tokens, challenges, or credential files. The CLI handles those privately.

Follow onboarding.txt to save the supplied name, preserve an existing Brain selection, select a sole
membership, or create Personal Brain after a successful empty list and founder eligibility.
Retain creation's original request ID and Brain. Verify cortex config and cortex whoami. Then
follow onboarding.txt's Finish local transport setup section and the installed complete plugin's
skills/cortex/references/local-mcp.md. Only after the CLI account and intended Brain are verified,
disable Cortex's bundled MCP server in the current local client's settings and read back its
effective state. Keep the plugin and skills, other servers, and existing OAuth grants. Reconcile
pending MCP writes first. Claude Code disables the server per canonical project, not across all
projects. Report an unavailable or policy-blocked control instead of claiming MCP is disabled. Then
say "You're ready. Open a new chat and ask 'What can I do with my Brain?'" Keep the verified Brain ID,
service origin, binary path, and recovery details in internal task context. Do not turn them into
instructions the person must copy. Prefer the same project; another directory can use this handoff
ID or its sole membership for that explicit request. Installation does not require an interview or
a knowledge save. Keep resolved PATH and runtime diagnostics internal; report an unresolved blocker
only when it prevents readiness.

For questions about what Cortex, a Brain, or "Second Brain" can do, follow the
"What can I do with my Brain?" section in https://www.thesecondbrain.company/onboarding.txt.
Answer with concrete examples and let the person choose what to try. Explaining capabilities
does not require setup or authorize saving knowledge.

## MCP fallback

If no supported local CLI can run after permitted recovery, explain that hosted clients require
their own OAuth account linking. Local CLI credentials cannot connect hosted MCP. Use
the enabled Cortex MCP server, restoring only its local setting if an earlier CLI onboarding
disabled it. Clients without a working CLI keep this MCP path. Connect to
/app/api/mcp/brain at the intended service origin through the client's native flow. In that
fallback, the user enters the email code on its requesting browser page, selects a Brain, and
approves consent. Verify whoami. A Brain ID argument or project file cannot switch this grant;
reconnect to choose another Brain. If the host exposes no connection flow, report the blocker.

Preserve origin, Brain, input, and request IDs for pending writes. Recover CLI failures through the
CLI; changing transports requires an explicit choice and identity verification. Inspect known runs
instead of replaying uncertain writes. A permission or network failure does not establish that
knowledge is absent. Installation is verified by the client; connection additionally needs the
intended Brain verified through CLI account/config/whoami or MCP whoami.

For ordinary project work, retrieve relevant evidence from the already selected Brain without a
Cortex keyword. Skip generic unrelated and no-Brain requests. Do not install, sign in, or select a
Brain implicitly for ordinary work. Record supplied facts only when authorized; only saved confirms
a durable result. Knowledge onboarding starts in the fresh chat described in onboarding.txt.

## Install in Codex or ChatGPT desktop

The complete Cortex plugin includes its skill, CLI workflow, and MCP fallback. Install that package from
https://www.thesecondbrain.company/plugins/cortex.tar.gz:

Keep both the plugin and its marketplace in `~/.agents/plugins/`. The marketplace source path below
is relative to your home directory, not to the marketplace file.

1. Download the archive and
   https://www.thesecondbrain.company/plugins/cortex.tar.gz.sha256. Verify the checksum, then
   extract its `cortex` folder into a temporary directory. Read its `.codex-plugin/plugin.json`
   version and compare it with the installed Cortex manifest and `codex plugin list`.
   Install when absent. Replace only `~/.agents/plugins/cortex` when the published version is
   newer. Keep a current or newer installation. Do not treat a loaded skill as a version check.
   Save both downloads in the same directory. On macOS, run
   `shasum -a 256 -c cortex.tar.gz.sha256` from there; the checksum refers to the archive by
   filename.
2. Create or update `~/.agents/plugins/marketplace.json`. Preserve its existing name and other
   plugins; add or replace the `cortex` entry below. For a new file, use `personal` as the
   marketplace name:

   ```json
   {
     "name": "personal",
     "interface": { "displayName": "Personal Plugins" },
     "plugins": [
       {
         "name": "cortex",
         "source": { "source": "local", "path": "./.agents/plugins/cortex" },
         "category": "Productivity",
         "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" }
       }
     ]
   }
   ```

3. For an absent or updated package, install with `codex plugin add cortex@personal`, replacing
   `personal` with the existing marketplace name if different, or select Cortex from that marketplace in the desktop
   Plugins Directory. Restart the desktop app if the new entry does not appear. Verify that Cortex
   is installed at the expected version in `codex plugin list` or the Plugins Directory, then
   continue the CLI setup above in this chat. A running chat may retain older instructions; follow
   this published guide now and let the fresh chat load the updated package after setup.

If a shell reports `Could not resolve host` while the website opens in a browser, check whether the
shell's network sandbox blocked DNS. Retry the same archive and checksum URLs with the client's
authorized network access. If that access is unavailable, report the environment blocker; do not
infer that the website or plugin archive is missing from the shell error alone.

## Install in Claude

For Claude Code 2.1.224 or later, inspect `claude plugin list --json` and
`claude plugin marketplace list` first. Fetch the published marketplace below and find
`plugins[].name == "cortex"`. Its `version` is the package version, not a top-level catalog field.
Compare semantic versions, not strings. If version metadata is unavailable, verify the ZIP checksum
and read `cortex/.claude-plugin/plugin.json` from that published archive.

When absent, add the official marketplace if missing and install the complete plugin:

```sh
claude plugin marketplace add https://www.thesecondbrain.company/plugins/claude/marketplace.json
claude plugin install cortex@cortex-plugins
claude plugin list
```

For an installed older version, refresh the registered official marketplace, then update the plugin
in its existing scope:

```sh
claude plugin marketplace update cortex-plugins
claude plugin update cortex@cortex-plugins --scope <existing-scope>
claude plugin list --json
```

Marketplace refresh alone does not update an installed plugin. Use the existing user, project, or
local scope and its project directory; respect managed policy. Keep a current or newer plugin and
never uninstall it as an update shortcut. Verify the installed version after the update. Preserve
unrelated marketplace entries and plugins. If the official marketplace name points to a different
source, report the conflict rather than replacing it silently.

The marketplace pins the downloaded ZIP by SHA-256. This install is for Claude Code sessions.
Continue CLI setup in this installation chat. A running chat can retain older instructions; follow
this published guide now. A new session loads the updated skill and MCP fallback after setup.
The fresh Claude Code chat is that new session. Do not turn the CLI's generic restart notice into a
separate desktop-app restart or `/reload-plugins` step. Report a loading blocker only if a fresh
session actually fails to load the updated package.
Do not start the hosted OAuth fallback when the local CLI works. A CLI-installed marketplace plugin
may appear in Claude Desktop with a disabled Connect button; it does not add an account-level
connector for Claude chat. Hosted MCP uses browser email-code sign-in and consent. Local CLI agents
complete code verification in chat. New users can sign up on Free through the same flow. Installing
the plugin does not grant access to private knowledge; current membership and approval are required.

For Claude chat or Cowork on a paid Claude plan, download
https://www.thesecondbrain.company/plugins/cortex-claude.zip and its checksum at
https://www.thesecondbrain.company/plugins/cortex-claude.zip.sha256. Save both in the same
directory and run `shasum -a 256 -c cortex-claude.zip.sha256`. In Claude, open Customize >
Plugins > Add > Upload plugin and select the ZIP. Connect Cortex from that account-installed
plugin. Compare the installed version with the verified ZIP's `.claude-plugin/plugin.json`.
A manually uploaded older plugin needs a new complete ZIP upload through the host's controls.
If the host exposes no upload control to the assistant, explain that required step instead of
claiming an automatic update. Local Claude Code setup remains entirely in chat.

To connect Claude chat or Desktop without a plugin install, open Customize > Connectors > Add custom
connector. Name it Cortex and use https://www.thesecondbrain.company/app/api/mcp/brain as its remote
MCP URL. Follow the browser OAuth flow. The Cortex page asks for email and sends a six-digit sign-in code. Enter it on that same page,
then approve consent to return to Claude. If the connector control on a CLI-installed plugin is disabled,
use this account-level custom connector path instead of retrying the local marketplace installation.
The custom connector supplies tools; upload the ZIP separately to add the knowledge skill in Claude
chat.

## Connect from a chat in other clients

For clients that cannot install this plugin, connect the shared remote MCP endpoint below using the
client's supported flow. Native confirmation may be required; report the connection only after the
client confirms it. Free signup works through OAuth. In ChatGPT, configure mixed
authentication when adding a custom connection.

1. Call cortex_account to start the client's native OAuth flow. If the client does not open it,
   ask the user to connect Cortex in the client's connection UI. The Cortex browser page
   asks for email and sends a six-digit sign-in code without revealing eligibility. The user enters
   it on that same page, selects a Brain, and approves permissions to return to the client. Keep
   browser challenges and credentials in the client's storage; this is the hosted fallback.
2. Return to chat. If the profile is incomplete, ask what to call the user and use
   cortex_update_profile. An empty name records their choice to skip.
3. If account says canCreateBrain, ask for the first Brain's name. Suggest their workplace for work,
   or a personal name. Call cortex_create_brain. Returning users keep their existing Brain.
4. Verify whoami before knowledge access. First-Brain creation binds once. Additional creation leaves
   the current MCP Brain unchanged; reconnect and select the new Brain before following
   https://www.thesecondbrain.company/onboarding.txt. Calls need no brain_id selector.

## Getting started and connection

- [Get started](https://www.thesecondbrain.company/cortex#signup): Copy the install prompt into
  ChatGPT or Claude to connect your assistant and create a Brain on Free.
- [Sign up or sign in](https://www.thesecondbrain.company/app/login): Verify your email to create a
  Free account or sign in to an existing account. Team invitations let you join an existing Brain.
  Find AI connection and setup instructions in the app.
- [Cortex MCP endpoint](https://www.thesecondbrain.company/app/api/mcp/brain): Remote MCP connection
  URL for compatible OAuth clients. The desktop plugin already bundles this connection. Public setup
  tools work before sign-in; private knowledge requires membership and OAuth authorization.
- [AI onboarding guide](https://www.thesecondbrain.company/onboarding.txt): Steps for the assistant to complete email-code setup in chat and invite a fresh Brain conversation.

## Product information

- [The Second Brain Company](https://www.thesecondbrain.company/): Our manifesto about sharing,
  building on, and owning knowledge.
- [Cortex product page](https://www.thesecondbrain.company/cortex): Product overview and shared
  knowledge for teams and AI.
- [How it works](https://www.thesecondbrain.company/cortex#how-it-works): Capture useful context through
  conversation, give it a shared home, and bring it into future AI conversations.
- [Knowledge ownership](https://www.thesecondbrain.company/cortex#your-knowledge): Your organization owns
  its Markdown files and can take them to other tools.
- [Questions and answers](https://www.thesecondbrain.company/cortex#questions): Access, knowledge entries,
  team allowances, read-only Git access, and upcoming plans.

- [Compare with Dropbox](https://www.thesecondbrain.company/compare/dropbox): Tradeoffs between
  Cortex and shared Markdown files with an AI skill, including change history, coordinated
  saves, permissions, and planned consistency checks.

## Plans and availability

- [Plans and pricing](https://www.thesecondbrain.company/cortex#pricing): Free is available now at $0
  per month, with a shared Brain and a monthly AI recording allowance shared by the team. Larger
  imports and complex updates use more allowance. Members see the remaining percentage and renewal
  date. Saved knowledge remains searchable when recording pauses. There are no per-user fees.
- Pro is available by invitation in private preview with roles and access controls. Intelligence is coming later.
  Pricing is unannounced.
- Intelligence is coming later, includes Pro, and is planned to add automatic conflict detection and
  regular consistency scans. Pricing is unannounced.
- Every plan includes knowledge ownership and read-only Git access to download Markdown files and
  their history. Editing a downloaded copy does not update Cortex.

## Optional

- [Cortex on X](https://x.com/secondbrainco): Follow product news and updates.