Nexus gives AI coding agents a shared, lasting memory of your project. It indexes your code and documents so agents find things by meaning, not keywords, and it keeps the decisions they reach as records you can read and review. Everything runs on your machine: no account, no API key, no database to install.
How do you use Claude?
You run claude in a terminal. You install the nx command and a plugin that adds tools, agents, and skills to Claude Code.
Nexus runs on Apple Silicon Macs with macOS 14 or later, on Linux with x86-64 or arm64, and on Windows 11 with x64. It ships its own PostgreSQL, built for those platforms only, so an Intel Mac or Windows on ARM stops at setup with an error. On macOS 13 or earlier the install fails while it resolves dependencies. It needs no GPU, because search runs on the CPU.
uv runs the nx command. The one command in the next section installs it if it is missing. Adding the plugin first needs uv already installed, because the plugin starts its tools and hooks through uv. Check with uv --version. To install it yourself:
brew install uv
When you install uv this way, Claude Desktop finds it, so you do not need to change your PATH.
git is what Nexus reads when it indexes a repository, and nx doctor checks for it. Check with git --version. To install it:
brew install git
Python needs no install, because the install command names Python 3.12 and uv downloads it.
The command installs uv if it is missing and then the nx command. It asks one question before it downloads anything.
It also adds the plugin to Claude Code when claude is on your PATH.
It cannot add the plugin to Claude Desktop, because that plugin store belongs to your Claude account, so add the plugin after it finishes.
curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh
The script offers three choices and no Not now, because typing the command is your permission to install. Through the plugin, Claude offers all four.
| Choice | What happens | Download |
|---|---|---|
| Local | Install the nx command and run a Nexus service on this machine | about 0.8 GB down (1.0 GB on Linux), 2.6 to 2.9 GB on disk |
| Cloud | Install the nx command and connect it to a managed service you already have an address and token for | about 0.5 GB down (0.6 GB on Linux), 1.9 to 2.2 GB on disk |
| CLI only | Install the nx command and decide about a service later | about 0.5 GB down (0.6 GB on Linux), 1.9 to 2.2 GB on disk |
| Not now | Nothing is installed | none |
These sizes include PDF support. --slim leaves it out, and the first PDF you index then installs it. The sizes on disk are the install itself, and uv keeps a separate download cache that uv cache clean empties. Windows sizes have not been measured.
Pressing Enter at the question, or running the script without a terminal, picks CLI only. Local adds a second question, whether the service should start when you log in, and the answer is No unless you type y.
Cloud needs the service address and token. If your token is a mint credential, which is bound to one tenant, the script asks for that tenant too. The script asks for them in the terminal. Through the plugin a page opens in your browser instead, so Claude never sees the token.
Add a flag after sh -s --: --local, --cloud or --cli-only. With --local you can add --autostart or --no-autostart. The --slim flag leaves out PDF support. This example installs the service and does not start it at login:
curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh -s -- --local --no-autostart
The iex form cannot take flags, so run the script as a script block and add them after it. The flags are --local, --cloud or --cli-only, and with --local also --autostart or --no-autostart. The --slim flag leaves out PDF support. For example:
Claude Code needs the plugin for its tools, agents, and skills. The one command already added it if claude was on your PATH. If not, start claude and type these two commands inside it, not in the terminal:
/plugin marketplace add Hellblazer/nexus /plugin install conexus@nexus-plugins
If you add the plugin before the nx command exists, and uv is installed, Claude runs the install for you. Run /reload-plugins or start a new session, and Claude says that Nexus is not installed and asks the question above. If you choose Not now, each session shows one line that names /conexus:setup, so you can answer later.
Setup runs in the background, and you can ask Claude for progress. When Claude says it is done, reconnect the Nexus server: type /mcp, choose nexus, and choose Reconnect. A new session works too.
Chat and Cowork read the plugins on your Claude account, not the ones Claude Code installed. Add the plugin here even if you added it in Claude Code. In Claude Desktop, open Customize → Plugins, add the marketplace Hellblazer/nexus, and install conexus. If you added the marketplace before, remove it and add it again first, because an older copy has no setup tool.
Then open a conversation and say this. Claude Desktop does not tell you when Nexus is missing, so you have to ask. Claude shows what is missing and asks before it installs anything, and Desktop may ask you to allow the tool first.
Set up Nexus.
Setup runs in the background, so ask "Is Nexus set up yet?" for progress. When Claude says it is done, quit Claude Desktop fully and open it again. A new conversation is not enough, because Desktop keeps the plugin's server running across conversations.
Desktop also has a conexus.mcpb extension, but it does not update itself, and it is not a working route on Windows. Do not install both it and the plugin, because you would get two copies of the tools. The Desktop deployment guide covers the extension.
nx doctor
No line may show ✗. Read every ⚠ line. The ⚠ line "Orphan uv install" means a copy of conexus installed with uv is still on disk next to the one Nexus manages. Right after nx self install that is normal, and the next nx self install, nx self gc, or Claude Code session with the plugin removes the old copy.
CLI only has no service yet. Run nx init first for a local service, or nx config init for a managed one. In Claude Code, /conexus:setup does the same.
cd your-project nx index repo . nx search "how does retry work"
If you index the same repository again, Nexus skips files that did not change. For a large repository, add --monitor to see the progress for each file.
Next: Getting started, the lessons for working inside Claude Code.
Run both of these commands every time:
nx self install # install the new version next to the current one nx upgrade # update the service, the data, and the plugins
Do not update with uv tool install conexus. A plain install builds a second copy that Nexus does not use. With --force it also takes the nx shims, so your terminal runs that copy without telling you. nx self install puts the shims back.
If nx upgrade stops and says to run nx backup, see Problems.
If you update the plugin with /plugin update in Claude Code, the next session runs both commands for you.
Follow these four steps in this order. None of them touches a managed cloud tenant, because they remove only what is on this computer.
On a local install, nx backup writes the whole database, memory included, to one file in ~/nexus-backups/. On a managed service it writes your own tenant to a .nxtenant file in the same folder, and it needs a tenant or data token and engine 0.1.191 or later. Move that file somewhere you keep before you remove the data.
nx backup
For a cloud file, nx backup --check <FILE>.nxtenant verifies it on your computer without contacting the service.
To keep only the knowledge store, in a form a new install can import one collection at a time, export it:
nx store export --all -o <A-DIRECTORY-TO-KEEP> # one .nxexp file per collection
Later, nx store import <FILE>.nxexp restores a collection into a new install.
In Claude Code:
/plugin uninstall conexus@nexus-plugins
In Claude Desktop, open Customize → Plugins and remove conexus. Remove the Hellblazer/nexus marketplace too if you want it gone.
If you use both Claude Code and Claude Desktop, do both. If you installed the Desktop extension instead, the Desktop deployment guide shows how to remove it.
nx uninstall # preview, changes nothing nx uninstall --yes --remove-data # stop the service and its workers, remove autostart, delete notes, plans, catalog, the database and the search models
Without --remove-data, the service stops and autostart is removed, but your data stays in ~/.config/nexus. Use that form if you plan to install again later.
nx uninstall does not remove nx itself or older versions kept side by side. Remove them by hand:
uv tool uninstall conexus 2>/dev/null # the uv install, if one exists rm -rf ~/.local/share/nexus # program versions rm -f ~/.local/bin/nx ~/.local/bin/nx-mcp ~/.local/bin/nx-mcp-catalog ~/.local/bin/nx-session-end-launcher ~/.local/bin/nx-hook
which nx # must print nothing launchctl list | grep -i nexus # must print nothing ls ~/.config/nexus # must not exist ls ~/.cache/nexus # must not exist
If ~/.cache/nexus still exists, an older release left it behind. Delete it with rm -rf ~/.cache/nexus.
The hint names torch and cp314 because you left --python 3.12 off the install command and your python3 is 3.14. Run the command again with the flag.
Your install runs on Python 3.14, which does not work yet. This is the one case where --force is right. Run these two commands: uv tool install conexus --force --python 3.12, then nx self install. The second command puts the nx shims back. On Windows, run nx daemon service stop first, because the install replaces files that the running service uses.
An old python3.exe in %USERPROFILE%\.local\bin hides the Python that uv manages. Add --python-preference only-managed to the install command and run it again.
Add ~/.local/bin to your PATH and open a new terminal. If PATH is already correct, run nx self install. If nx was never installed, run uv tool install conexus --python 3.12.
Open a new PowerShell window. If nx is still not found, check that %USERPROFILE%\.local\share\nexus\tools\current\bin is on your user PATH.
Your uv is too old for the option the install uses to get the CPU build of torch on Linux. Run uv self update, or update uv with the package manager that installed it, and then run the install again.
nx backupYour store holds old-format rows that the engine's first start would delete, so Nexus refuses to start the engine until a backup exists. Run nx backup now, because a backup taken before the refusal does not count. Then run nx daemon service start. Do not run nx upgrade again, because it can time out while it checks a large backup and the start command has no time limit. This applies only to the bundled local Postgres. The operator of a managed or self-hosted Postgres owns the backups.
Run nx doctor. If you chose CLI only, no service runs yet, so run nx init for a local service or nx config init for a managed one. If the index was interrupted, run nx index repo . again and it continues where it stopped.
Usually the nx command is not installed, setup has not finished, or you chose Not now. Type /conexus:setup, which shows what is missing and asks before it installs anything. After setup is done, reconnect the nexus server with /mcp. /conexus:nx-preflight also lists what is missing.
Usually the nx command is not installed or setup has not finished. Say Set up Nexus in a conversation, and Claude shows what is missing and asks before it installs anything. After setup is done, quit Claude Desktop fully and open it again, because a new conversation keeps the old server.
Paste the recovery runbook as the first message of a Claude Code session. Claude checks the install step by step and asks you before it changes any data.
These are the commands that the one command and the setup tool run for you. Run them in this order, and each is safe to run again.
nx commandThe first command installs nx, and the second moves it to the layout that Nexus manages.
The first command installs nx for your user. The second moves it to the layout that Nexus manages, so that an update never replaces a file that a running program uses, and it adds %USERPROFILE%\.local\share\nexus\tools\current\bin to the front of your user PATH.
uv tool install conexus --python 3.12 nx self install
A fresh install needs no nx upgrade, even if nx self install suggests it.
If the terminal cannot find nx after this, add ~/.local/bin to your PATH and open a new terminal.
This command first asks whether the service should start at login. It then downloads the service program, the database, and the search model, and starts the service.
nx init
Use nx init --yes to answer yes automatically, or nx init --no-autostart to skip starting at login.
Start claude and type these two commands inside it, not in the terminal:
/plugin marketplace add Hellblazer/nexus /plugin install conexus@nexus-plugins
Then run /conexus:nx-preflight, which checks that everything the plugin needs is present.
Add the plugin in Claude Desktop, as Add the plugin shows.
Then index a repository.
Nexus is one service on your computer. It holds a database (Postgres 17 with pgvector) and three stores: scratch for one session, memory for project facts, and knowledge for everything you index. The search model also runs on your computer, so your data does not leave it unless you add a Voyage AI key. That key sends your text to an outside embedding service.
While Claude uses Nexus, it sends one short message a day, with no hostname, paths, or content. The privacy policy lists the fields, nx telemetry off stops it, and nx telemetry status shows the setting.
More: CLI reference. The code is AGPL-3.0-or-later, and everything you make with Nexus is yours. LICENSING.md covers commercial licenses.