Nexus · conexus 7.xUpdateUninstallProblemsGetting started →RDRs →Research →Research in Nexus →Tuple space →Coordination →

Installing Nexus

A brass-ribbed crystal dome on a hilltop at dusk

Nexus gives Claude a permanent memory and search by meaning. It runs on your computer. You need no API key, no account, and no separate database install. The install takes about ten minutes.

How do you use Claude?

You run claude in a terminal. You install the nx command and a plugin. The plugin adds 62 tools, 10 agents, and 44 skills to Claude Code. The plugin needs Node.js.

Operating system

Before you start

NeedWhyCheck
Python 3.12 or 3.13Python 3.14 does not work yet, which is why the install command names 3.12. uv downloads it for you.python3 --version
uvInstalls and runs the nx command.uv --version
gitNexus reads git information when it indexes a repository.git --version
Node.js (with npm)Required for the plugin. The plugin starts one of its servers with npx. Without Node.js there is no error message. The plugin installs, but its tools never appear.node --version
npm --version
Apple Silicon Mac, or Linux on x86-64 or arm64Nexus ships its own PostgreSQL and never uses one you installed, and that bundle is built for these three only. An Intel Mac or Windows cannot run a local install: setup stops with an error rather than falling back.uname -sm
No GPUSearch runs a bundled CPU model. On Linux the installer pins torch to its CPU build, since the default wheel pulls ~4.5 GB of CUDA packages nothing here uses; NX_TORCH_BACKEND opts a GPU box back in.—
About 1.2 GB idle, up to about 4.5 GB while indexingThe bundled PostgreSQL is light; the embedding and reranking model running inside the engine process holds the rest. Measured on an Apple Silicon Mac indexing a real, medium-sized code repository.—
~600 MB download, a few minutesThe first run downloads the service program, a database, and the search model.—

If uv or Node.js is not installed, install them first:

# macOS
brew install uv
brew install node

The install command in step 1 names the interpreter it needs, so a python3 of 3.14 does not matter.

Install

Before step 1

Install Node.js now. The plugin starts one of its servers with npx. If node and npm are not installed, step 4 reports success, but the tools never appear. There is no error message.

Check with node --version and npm --version before you continue.

Run the steps in this order. You can run each step more than once without harm.

  1. Install the nx command

    The first command installs nx. The second command moves it to the layout that Nexus manages. This removes one package that causes conflicts. On Linux, it also replaces a 4.5 GB GPU package with a smaller CPU package.

    uv tool install conexus --python 3.12
nx self install

    --python 3.12 is part of the command. Without it uv picks an interpreter itself, and on a machine with no other one — a fresh Ubuntu 26.04, whose python3 is 3.14 — the install stops with a resolver error about torch wheels. uv downloads 3.12 for you.

    If the terminal cannot find nx after this, add ~/.local/bin to your PATH. Then open a new terminal.

  2. Set up the storage service

    This command downloads the service program, the database, and the search model. It starts the service. Then it asks if the service should start at login. Answer yes.

    nx init
    ~600 MBdownloaded, first run only
    2–5 minon a normal connection
    0settings to change

    To answer yes automatically: nx init --yes. To not start at login: nx init --no-autostart.

  3. Check the install

    nx doctor

    Every line must show ✓. One line may say "credentials not set". This is normal for a local install. It is not a problem.

  4. Add the Claude Code plugin

    First, check Node.js: node --version must print a version number. If it does not, install Node.js and return here. The plugin cannot start without it.

    Then start claude. Type these two commands inside Claude Code, not in the terminal:

    /plugin marketplace add Hellblazer/nexus
/plugin install conexus@nexus-plugins

    Then run /conexus:nx-preflight. It checks that everything the plugin needs is present. The plugin uses the nx command from step 1. This is why step 1 must come first.

  5. Index a repository and search it

    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.

The install is complete. Search runs on your computer. After indexing, Nexus finds topics automatically. nx taxonomy status shows them.

Next: Getting started. Twelve lessons, all done inside Claude Code.

Update Nexus

Two commands. Always run both:

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 or with --force. That command removes the local search model, and search then returns nothing. If this happened, nx self install repairs it.

If you update the plugin with /plugin update in Claude Code, the next session runs both commands for you.

Remove Nexus completely

Four steps, in this order. The first one is optional. Nothing here touches a managed cloud tenant. It removes only what is on this computer.

  1. Optional: keep a copy of your knowledge

    The knowledge store can be exported to a file and imported into a later install. Memory and scratch cannot be exported.

    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.

  2. Remove the Claude integration

    In Claude Code:

    /plugin uninstall conexus@nexus-plugins

    In Claude Desktop: Settings → Connectors → Desktop → Conexus → Uninstall. This removes the extension only. The service and the data stay. Steps 3 and 4 remove them.

    If you use both Claude Code and Claude Desktop, do both.

  3. Stop the service and delete the data

    The first command only shows what would be removed. The second command does it.

    nx uninstall                          # preview, changes nothing
nx uninstall --yes --remove-data      # stop the service, remove autostart, delete notes, plans, catalog and the database

    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.

  4. Remove the program

    nx uninstall does not remove nx itself, the downloaded search model, 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, search model cache
rm -f ~/.local/bin/nx ~/.local/bin/nx-mcp ~/.local/bin/nx-mcp-catalog ~/.local/bin/nx-session-end-launcher ~/.local/bin/nx-hook

Check

which nx                        # must print nothing
launchctl list | grep -i nexus  # must print nothing
ls ~/.config/nexus              # must not exist

Old installs from before mid-2026 may also have a directory ~/.local/share/nexus/chroma or a com.nexus.t2 unit. The commands above remove both.

Problems

The install fails with "No solution found when resolving dependencies"

The hint names torch and cp314. You left --python 3.12 off the install command and your python3 is 3.14. Run the command again with the flag.

nx: command not found

Add ~/.local/bin to your PATH. Then 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.

Crash on startup, or an import error mentioning voyageai or Pydantic v1

Nexus runs on Python 3.14, which does not work. Run these two commands in order: uv tool install conexus --force --python 3.12, then nx self install.

nx doctor says credentials not set

This is normal for a local install. Only the cloud service needs a token.

nx search returns nothing

Run nx doctor. If the index was interrupted, run nx index repo . again. It continues where it stopped. If you updated with uv tool install, see "Update Nexus" above.

Plugin installed but its tools never appear

There are two common causes. The nx command is not installed, or Node.js is not installed. Run /conexus:nx-preflight. It tells you which one.

Nothing above helps

Use the recovery runbook. Paste it as the first message of a Claude Code session. Claude then checks the install step by step. It asks you before it changes any data.

What you installed

One service on your computer. It contains 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. One time per day, Nexus sends one anonymous message with six values: install id, version, mode, operating system, CPU type, and Python version. nx telemetry off stops this.

License

Nexus, the nx command, and the plugin are free to use. The license covers the Nexus code only. Everything you make with it is yours: the repositories you index, the notes and memory Claude keeps, the documents you store, the RDRs you write, and anything Claude produces in a session are not covered by the license and carry no obligation from it. The code is AGPL-3.0-or-later, which matters only if you modify Nexus itself and offer the modified version to others. Commercial licenses are available for organizations that need other terms; see LICENSING.md.

More: Getting started · Working with RDRs · CLI reference

Source: Hellblazer/nexus README and docs. The commands match the current conexus release. This page is web/index.html in the repo. Corrections are welcome.