Nexus
Sign inStart building
Guides / Brain

Setting up the brain for your AI agents

How an agent connects to the brain and which search mode to pick the first time.

This guide takes you from nothing to a working brain that your AI agents can read from and write to. You create the brain with nexusbrain init, pick a search mode, connect an agent over MCP, and check that everything works.

Follow it the first time you set up the brain on a machine, or when an agent is doing the setup for you. If an agent runs nexusbrain init for you, it prints a cost table and a note asking it to show that table to you before it moves on. That handoff is Step 3.5 below.

Time
10 minutes
For
Anyone setting up Nexus Brain for Claude Code, Codex, OpenClaw or another MCP agent, and agents doing that setup on their behalf

Before you start

  • The Nexus Desktop app is installed. The brain ships inside it, so there is nothing separate to install.
  • A terminal where the nexusbrain command runs.
  • An API key for an embedding provider (OpenAI, ZeroEntropy or Voyage), or you are happy to set that up later.
  • For a hosted database only: a Supabase project or another Postgres database with the pgvector extension. See Choosing a database engine.

01Step 1: Check the brain command works

Every step in this guide uses the nexusbrain command line tool. Start by making sure your terminal can find it.

  1. Print the brain version.

    nexusbrain --version

    You should seeOne line with the word nexusbrain followed by your installed version number.

02Step 2: Give the brain an embedding key

An embedding is a list of numbers that captures what a piece of text means. The brain stores one for every chunk of your notes so it can find things by meaning, not just by exact words. Making embeddings needs an API key from an embedding provider.

nexusbrain init looks at your environment variables to pick the provider. If exactly one supported key is set, it uses that provider and tells you which model it chose.

  1. Set one embedding key in your shell.

    Set only one of these. If more than one is set and init cannot ask you which to use, it stops and asks you to choose with --embedding-model.

    export OPENAI_API_KEY=sk-...

    You should seeNo output. The key is now available to the next command in this shell.

Environment variableModel init picks
OPENAI_API_KEYopenai:text-embedding-3-large
ZEROENTROPY_API_KEYzeroentropyai:zembed-1
VOYAGE_API_KEYvoyage:voyage-3-large
Tip

No key yet? Add --no-embedding to the init command in Step 3. Keyword search still works, and you can set a model later with nexusbrain config set embedding_model <id>.

03Step 3: Create the brain

A brain is a database that holds your pages, their embeddings and the facts your agents remember. By default it uses PGLite, a copy of Postgres that runs inside the brain process and keeps everything in one folder on your machine. No server is needed.

  1. Run init with the local engine.

    nexusbrain init --pglite

    You should seeIt starts with Setting up local brain with PGLite (no server needed)..., shows the embedding model it chose, and ends with Brain ready at followed by the brain path and 0 pages. Engine: PGLite (local Postgres).

  2. Read the quickstart printed at the end.

    Init finishes by printing three commands under Give your agent memory (copy these three commands):. You will use them in Step 4 and Step 5.

    You should seeYou see Next: nexusbrain import <dir> and the three quickstart commands.

  • ~/.nexusbrain/config.json: which engine to use, where the database lives, the embedding model and its size, and the schema pack (nexusbrain-base-v2 on new brains).
  • ~/.nexusbrain/brain.pglite: the database folder. Use --path <DIR> to put it somewhere else.
  • The database schema, plus your search mode choice from Step 3.5.
  • Update checks set to notify, and skill publishing over MCP turned on.
FlagWhat it does
--pgliteUse the built-in local engine. This is the default for a bare nexusbrain init.
--supabaseAsk for a Supabase or Postgres connection string and use that database.
--url <URL>Use this Postgres connection string without prompting.
--non-interactiveNever prompt. Needs --url or NEXUS_BRAIN_DATABASE_URL for Postgres.
--embedding-model <PROVIDER:MODEL>Choose the embedding model instead of letting init detect it.
--embedding-dimensions <N>The vector size. It must match the model.
--no-embeddingSkip embedding setup for now.
--skip-embed-checkSkip the check that tests your embedding key during init.
--jsonPrint machine readable status instead of text.
--mcp-onlyConnect this machine to a brain hosted elsewhere, with no local database. See Step 4.
Note

Running init inside a folder with 1000 or more .md files prints a suggestion to use nexusbrain init --supabase for faster search at that size. It still sets up PGLite unless you pass --supabase.

04Step 3.5: Pick a search mode with your operator

The search mode decides how much text a search sends back to your agent. More text usually means better answers, but your agent pays its model provider for every token it reads. The brain itself adds almost nothing to the cost.

Init runs a picker right after the schema is created. In a normal terminal it shows a menu, suggests a mode, and waits up to 60 seconds. Press Enter to accept the suggestion or type 1, 2, 3 or a mode name. It suggests conservative if your subagent model is a Haiku model or no OPENAI_API_KEY is set, and tokenmax otherwise.

When init runs without a terminal, for example when an agent runs it, the picker applies the suggested mode and prints lines starting with [AGENT]. They tell the agent to show the cost table to the operator and ask which mode they want before continuing. Agents: do this, and change the mode if the operator picks a different one.

  1. Show the table to the person who pays for the agent and ask which mode they want.

    The monthly figures are what the agent model spends reading search results at 10,000 queries a month, before any prompt caching savings. They scale linearly: multiply by 10 for 100,000 queries, divide by 10 for 1,000.

    Pair the mode with the model. tokenmax on Haiku, or conservative on Opus, wastes capacity in opposite directions.

  2. Set the mode they chose.

    nexusbrain config set search.mode balanced

    You should seeSet search.mode = balanced.

  3. Confirm the mode that is now active.

    nexusbrain search modes

    You should seeA report that starts with Search mode (active): balanced, followed by the resolved settings.

ModeWhat it returnsBest forHaiku 4.5Sonnet 4.6Opus 4.7
conservativeUp to 4K tokens, no LLM query expansion, at most 10 chunksHaiku subagents, high volume search loops, MCP servers with many users$40/mo$120/mo$200/mo
balancedUp to 12K tokens, no LLM query expansion, at most 25 chunksSonnet tier work and mixed workloads$100/mo$300/mo$500/mo
tokenmaxNo token cap, LLM query expansion on, 50 chunksOpus or frontier models, low volume work where quality matters most$200/mo$600/mo$1,000/mo
Tip

Running init again does not ask again once a mode is set. Change it any time with nexusbrain config set search.mode <conservative|balanced|tokenmax>, and tune individual settings with nexusbrain search tune.

05Step 4: Connect your agent over MCP

MCP (Model Context Protocol) is the standard way agents call outside tools. nexusbrain serve starts an MCP server that talks to the agent over standard input and output, so the agent host starts it for you. You only register the command once.

The server has two tool sets. The full set, which is the default, exposes every brain operation, including search, query, get_page and put_page. The verbs set exposes only the five memory actions described in Memory for agents.

  1. Register the brain with Claude Code.

    Use the full tool set if the agent should search and edit pages. Use --surface verbs if it only needs memory.

    claude mcp add nexusbrain -- nexusbrain serve

    You should seeClaude Code confirms it added an MCP server named nexusbrain.

  2. For any other MCP client, use the same command.

    Add a server whose command is nexusbrain with the argument serve (and optionally --surface verbs). The OpenClaw plugin bundle already declares a nexusbrain serve server.

  3. If the brain runs on another machine, print a ready made setup block instead.

    The other machine must run nexusbrain serve --http. Get a token there with nexusbrain auth create. --agent accepts claude-code, codex, perplexity or generic, and --install runs the command for Claude Code and Codex.

    nexusbrain connect https://brain.example.com/mcp --token <token> --agent codex

    You should seeA block that starts # Paste into Codex: with the commands to run.

Warning

The local engine lets only one process open the database at a time. While your agent host is running nexusbrain serve, most other nexusbrain commands in a terminal cannot open the brain. Use the agent's tools, or stop the server first. See Running serve and sync together.

06Step 5: Check that it works

  1. Stop any running nexusbrain serve, then run the health check.

    nexusbrain doctor

    You should seeA list of checks ending with Overall health score: N/100. All checks passed. or All checks OK (some warnings).

  2. Save a test memory.

    nexusbrain remember "I prefer dark mode in every editor" --provenance demo --entity people/me

    You should seeA line such as remembered as fact #1 and entity: people/me.

  3. Read it back.

    nexusbrain recall --entity people/me

    You should seeThe fact you just saved.

  4. Open a new agent session and ask what you prefer in an editor.

    You should seeThe agent calls the brain and answers with dark mode.

Tip

Agents doing setup can use nexusbrain doctor --json for a machine readable report. When the brain is empty, load your notes next with nexusbrain import <dir>.

07Troubleshooting

Init stops with No embedding provider configured. Set one of:

No supported embedding key was found and init could not ask you. Set OPENAI_API_KEY, ZEROENTROPY_API_KEY or VOYAGE_API_KEY and run init again.

Or pick a model with --embedding-model, or skip embeddings for now with --no-embedding.

If init adds Note: detected ...; did you mean ...?, you have a typo in the variable name.

Init stops with Multiple embedding providers env-ready:

More than one provider key is set. Pass --embedding-model <provider>:<model> to choose, or unset the keys you do not want.

nexusbrain init: unknown flag or requires a value

Check the flag table in Step 3, or run nexusbrain init --help for the full list.

Thin-client config already present at when running init

This machine was set up earlier to use a brain on another machine. Keep that setup, or pass --force to replace it with a local brain.

A command says the local database is already open through nexusbrain serve

Your agent host is running the MCP server, which holds the local database. Close the agent session or stop the server, then run the command again. Or keep it running and use the agent's tools.

No brain configured. Run: nexusbrain init

No config file was found in ~/.nexusbrain. Run Step 3. If you set NEXUS_BRAIN_HOME, make sure it points at the same folder your brain was created in.