Nexus

Permanent memory and search by meaning for Claude. Nexus runs on your computer. Search and storage need no API key, no account, and no separate database install. What Claude learns in one session is there in the next. The steps that call a language model (the nx_answer operators, aspect extraction, topic labels) use the Claude Code CLI when it is installed, and otherwise an Anthropic API key you set with nx config set anthropic_api_key.

Install: follow the install guide at hellblazer.github.io/nexus. It has a version for Claude Code, for the nx CLI alone, and for Claude Desktop, on macOS, Linux and Windows. On macOS, Nexus needs macOS 14 or later on Apple Silicon (the embedder runtime, onnxruntime, ships only macOS 14 wheels from 1.24 on). Windows 11 x64 is supported, with the limits listed in the Windows install guide.

The package on PyPI is conexus. The command it installs is nx.

Install

There are two routes, and both end in the same install.

Route one: run one command in a terminal. It installs uv if you do not have it, installs the nx command, adds the plugin to Claude Code when claude is on your PATH, and asks you one question before it downloads anything. With Local it asks a second, whether to start at login.

On macOS and Linux:

curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh

On Windows, in a normal PowerShell window:

irm https://hellblazer.github.io/nexus/install.ps1 | iex

To skip the question, add a flag: --local, --cloud or --cli-only, and with --local also --autostart or --no-autostart. The script installs everything, PDF support included; add --slim to leave PDF support out. On macOS and Linux put them after sh -s --, for example curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh -s -- --local --no-autostart. The iex form cannot take flags, so on Windows run the script as a script block: & ([scriptblock]::Create((irm https://hellblazer.github.io/nexus/install.ps1))) --local --no-autostart. When the script asks whether the service should start at login, the answer is No unless you type y. The script itself does not need Git, but Claude Code fetches the plugin with Git, so on Windows install Git first if you want the script to add the plugin. If you press Enter at the question, or the script has no terminal, it installs the nx command only. /conexus:setup in Claude Code, or nx init (Local) or nx config init (Cloud) in a terminal, sets up a service later. On Linux the script asks uv for the CPU build of torch. If your uv is older than 0.9.19, run uv self update first, or the build downloads about 4.5 GB of GPU libraries that Nexus does not use.

Route two: install uv, add the plugin, answer one question. Install uv (and git, if you do not have it), then start claude and type these two lines inside Claude Code, not in the terminal:

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

When the install finishes, run /reload-plugins or start a new session. In that session Claude tells you that Nexus is not installed and asks the question. If you answered Not now or want to answer later, type /conexus:setup. Setup runs in the background. When Claude says it is done, reconnect the nexus server (/mcp, the server, Reconnect) or start a new session.

In Claude Desktop, install uv, open Customize → Plugins, add the marketplace Hellblazer/nexus, install conexus, and say "Set up Nexus" in a conversation. When setup is done, quit Desktop fully and open it again; a new conversation keeps the old server. If you added Hellblazer/nexus before, remove it and add it again first. An older copy has no setup tool. Do not type /conexus:setup in Desktop; it lists the plugin's skills, not its commands (seen on Claude Desktop 2.42304.0 on macOS). To update the plugin in Desktop, remove the marketplace and add it again.

The question. Route two asks it with these four choices. The script asks the same question without Not now, because typing the command is your permission to install:

These sizes include PDF support (docling, MinerU and torch). The script and the setup tool install it by default; the script's --slim and the setup tool's slim leave it out, which takes about 0.28 GB off the download on macOS, 0.39 GB on Linux, and 1.0 GB off the disk on macOS, 1.3 GB on Linux. A slim install and a bare uv tool install conexus arrive without it, and so does the Claude Desktop extension unless its Include PDF support setting is on (off by default; turning it on installs PDF support into the extension at its next start). On a slim install the first time you index a PDF, nx installs it: about 285 MB down on macOS and 390 MB on Linux, 1.0 GB on disk on macOS and 1.3 GB on Linux, and it is kept by later upgrades. It installs only into the generation layout a normal install uses, so a bare uv tool install conexus tree does not fetch it: the PDF command stops with exit 69 and "Run: nx self install", and that command moves the tree onto the generation layout and brings PDF support with it. Where it cannot (the Desktop extension with the setting off, a source checkout, an install built from a checkout, a uv tool install tree that has not moved to generations, a Windows machine without the Visual C++ runtime) or must not (NX_PDF_STACK=refuse, which the post-commit hook sets), it stops before writing anything with exit 69 and the command to run, and a network failure stops it with 75. The model weights follow on first use, about 0.5 GB, plus 1.2 GB for the first PDF with formulas. To fetch it ahead of time, for instance before going offline, run nx self install --extras pdf. On Linux that install asks uv for the CPU build of torch (NX_TORCH_BACKEND, default cpu); without it uv would take the CUDA build, about 4.3 GB of downloads that Nexus never uses. An install that already had PDF support keeps it. The sizes are measured on 7.86.0 on macOS and Linux (2026-10-25): the download is the wheels in the lock, the Python and, for Local, the service and its models; the sizes on disk are the install itself. Windows was not measured. uv also keeps a download cache, about 2.2 GB on Linux and 1.9 GB on macOS after a first install (running install.sh on macOS adds about 0.84 GB for its throwaway bootstrap environment, 2.8 GB in all) (an earlier 7.81.0 measurement found 4.8 GB on Windows). On Linux the cache and the install together measured about 2.3 GB, not 4.5 GB, because they share files, so the cache is not all extra space. uv cache clean empties it but frees only the files the install does not share. The install guide has the requirements, the Windows path, the Claude Desktop extension, and how to index your first repository.

Install by hand

Use these commands when a route above fails, or when you want each step yourself. The common case is Claude Code on macOS or Linux, with uv and git already installed.

uv tool install conexus --python 3.12   # install nx; --python 3.12 is required, Python 3.14 does not work yet
nx self install                         # move nx to the layout Nexus manages
nx init                                 # download and start the storage service; answer yes to start at each login (route one defaults to no)
nx doctor                               # every line must show ✓ ("credentials not set" is normal)

The commands are the same on every platform. A bare uv tool install conexus carries no torch, so Linux needs no extra flag here; the PDF install described above names the CPU build of torch for you.

Then add the plugin with the two lines from route two.

Update, remove, problems

• Update: run nx self install, then nx upgrade. Do not update with uv tool install conexus or --force: on a generation install that rebuilds the uv tree and takes the nx shims back, and it drops the [local] extra. Details: Update Nexus.
• Remove: Remove Nexus completely covers exporting your knowledge first, removing the Claude integration, and deleting the service and data.
• Problems: see Problems. If nothing there helps, paste the recovery runbook as the first message of a Claude Code session. It checks the install step by step and asks before it changes any data.

What you installed

One service on your computer: Postgres 17 with pgvector, holding three stores. Scratch lasts one session. Memory holds project facts. Knowledge holds everything you index: code, documents, PDFs, and the decisions you record. The search model runs locally, so your data does not leave the machine.

Once a day the MCP server sends one message with six values: a random install id, the conexus version, the install mode, operating system, CPU type, and Python version. No hostname, paths, collection names, or content. The service also keeps a keyed fingerprint of the network address the message came from, never the address itself; see the privacy policy. nx telemetry off stops it; nx telemetry status shows the setting.

Learn

• Getting started: twelve lessons, all done inside Claude Code.
• Working with RDRs: record a decision before you build, in eight lessons.
• Research with Nexus: what you say to Claude at each step of research work, and what you see.
• Research in Nexus: the thinking behind the method, what was borrowed from experimental science and what was left out.
• The Nexus Tuple Space: how sessions, agents, and hooks coordinate.
• Coordination: how sessions and agents coordinate through the tuple space, and which steps the hooks, the channel, and Claude each do.
• How Agents Build and Ship Nexus: how agent sessions, the conexus instance, GitHub and a second build machine coordinate through the tuple space to build, test, review and release Nexus.
• CLI reference, architecture, storage tiers, and the docs tree.
• Managed service, for a hosted deployment with server-side embeddings.

Push delivery into your session (Claude Code channels)

By default, a message that arrives while you are away — an agent's report, a peer session's reply — waits until your next prompt, when a hook delivers it. Claude Code's channel preview can push it into a running session instead, but only when the session is launched with a channel flag, every time; nothing Nexus installs can set that flag for you.

1. Launch with claude --channels plugin:conexus@nexus-plugins (no confirmation dialog once the plugin is on Claude Code's channel allowlist), or claude --dangerously-load-development-channels server:nexus (works everywhere the preview does, with a one-keystroke confirmation dialog on every launch).
2. For the dialog-free form, put the plugin on the allowlist: on macOS, write /Library/Application Support/ClaudeCode/managed-settings.json (admin-written) with {"channelsEnabled": true, "allowedChannelPlugins": [{"marketplace": "nexus-plugins", "plugin": "conexus"}]}.
3. Make it stick: add alias claude='claude --channels plugin:conexus@nexus-plugins' to your shell's startup file.
4. Check it worked: the startup screen shows "Channels (experimental) messages from plugin:conexus@nexus-plugins inject directly in this session · restart without --channels to stop"; nx doctor's tuples.channel_delivery row reports the waiter's own status once it has run here (alive, last wake, messages announced and pending), or an informational "no record" line for a session whose waiter has not run yet.

Without the flag, mail still arrives at your next prompt through the drain hook — degraded, not broken. Channels are a Claude Code research preview, not available on Amazon Bedrock, Google Cloud Agent Platform, or Microsoft Foundry. See Coordination and Getting started for more.

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 this license and carry no obligation from it.

The code is AGPL-3.0-or-later (LICENSE). That 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.