Metadata-Version: 2.5
Name: conexus
Version: 7.54.0
Summary: Self-hosted semantic search and knowledge management for LLM-driven development
Project-URL: Homepage, https://github.com/Hellblazer/nexus
Project-URL: Repository, https://github.com/Hellblazer/nexus
Project-URL: Documentation, https://github.com/Hellblazer/nexus/tree/main/docs
Project-URL: Bug Tracker, https://github.com/Hellblazer/nexus/issues
Author-email: Hal Hildebrand <hellblazer@me.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: cli,code-search,knowledge-management,llm,pgvector,rag,semantic-search,voyage-ai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: <3.14,>=3.12
Requires-Dist: click<9,>=8.1
Requires-Dist: docling-slim[convert-core,format-pdf,models-local]<2.125.1,>=2.125.0
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: llama-index-core<0.15,>=0.14.21
Requires-Dist: markdown-it-py<5,>=4.0.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: mineru[pipeline]<3.1.12,>=3.1.11
Requires-Dist: msgpack<2,>=1.0
Requires-Dist: numpy<3,>=1.24
Requires-Dist: onnxruntime<2,>=1.20
Requires-Dist: pdftext<0.7,>=0.6.3
Requires-Dist: pymupdf<2,>=1.26.6
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: scikit-learn<2,>=1.3
Requires-Dist: sigstore<5,>=3.0
Requires-Dist: structlog<26,>=24.0
Requires-Dist: tokenizers<0.23,>=0.22
Requires-Dist: torch<2.11,>=2.10; sys_platform != 'linux' and python_version >= '3.13'
Requires-Dist: torch<2.9,>=2.8; sys_platform != 'linux' and python_version < '3.13'
Requires-Dist: torch<2.9,>=2.8; sys_platform == 'linux'
Requires-Dist: torchvision<0.24,>=0.23; sys_platform != 'linux' and python_version < '3.13'
Requires-Dist: torchvision<0.24,>=0.23; sys_platform == 'linux'
Requires-Dist: torchvision<0.26,>=0.25; sys_platform != 'linux' and python_version >= '3.13'
Requires-Dist: tqdm<5,>=4.65
Requires-Dist: tree-sitter-language-pack<0.14,>=0.13.0
Requires-Dist: uvicorn<1.0,>=0.41
Requires-Dist: voyageai<0.4,>=0.3
Provides-Extra: local
Requires-Dist: fastembed<0.8,>=0.7.0; extra == 'local'
Description-Content-Type: text/markdown

# Nexus

**Permanent memory and search by meaning for Claude.** Nexus runs on your computer. You need no API key, no account, and no separate database install. What Claude learns in one session is there in the next.

[![CI](https://github.com/Hellblazer/nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/Hellblazer/nexus/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/conexus)](https://pypi.org/project/conexus/)
[![Python versions](https://img.shields.io/pypi/pyversions/conexus)](https://pypi.org/project/conexus/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

The package on PyPI is `conexus`. The command it installs is `nx`. The full install guide, with a version for each way of using Claude, is at [hellblazer.github.io/nexus](https://hellblazer.github.io/nexus/). The commands below are the same ones.

## Before you start

| Need | Why | Check |
|---|---|---|
| Python 3.12 or 3.13 | Python 3.14 does not work yet. If needed, uv downloads 3.13 for you. | `python3 --version` |
| [uv](https://docs.astral.sh/uv/) | Installs and runs the `nx` command. | `uv --version` |
| git | Nexus reads git information when it indexes a repository. | `git --version` |
| Node.js with npm | Required for the Claude Code plugin. Without it the plugin installs but its tools never appear, with no error message. | `node --version` |
| About 600 MB, a few minutes | The first run downloads the service program, a database, and the search model. | |
| Apple Silicon Mac, or Linux on x86-64 or arm64 | Nexus ships its own PostgreSQL and never uses one you installed. The bundle exists for these three only, so an Intel Mac or Windows cannot run a local install: setup stops with an error rather than falling back. | `uname -sm` |
| No GPU | Search 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. | |

## Install

Run the steps in this order. Each step can be run again without harm.

**1. Install the `nx` command.** The second command moves it to the layout that Nexus manages.

```bash
uv tool install conexus
nx self install
```

If the terminal cannot find `nx` afterward, add `~/.local/bin` to your PATH and open a new terminal.

**2. Set up the storage service.** This downloads the service program, the database, and the search model, starts the service, and asks whether it should start at login. Answer yes.

```bash
nx init
```

`nx init --yes` answers for you. `nx init --no-autostart` skips the login item.

**3. Check the install.**

```bash
nx doctor
```

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

**4. Add the Claude Code plugin.** Check `node --version` first. Then start `claude` and 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, which is why step 1 comes first.

**5. Index a repository and search it.**

```bash
cd your-project
nx index repo .
nx search "how does retry work"
```

Indexing the same repository again skips files that did not change. For a large repository, add `--monitor` to see progress per file.

**Claude Desktop without Claude Code:** do steps 1 to 3, then download `conexus.mcpb` from the [latest release](https://github.com/Hellblazer/nexus/releases/latest) and double-click it. Claude Desktop adds it under Settings, Connectors, as "Conexus". If you already use the plugin in Claude Code, do not add the extension as well; Claude Desktop already sees the plugin's tools.

## Update

Two commands. Always run both.

```bash
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 removes the local search model, and search then returns nothing. If that happened, `nx self install` repairs it.

## Remove

```bash
nx uninstall                          # preview, changes nothing
nx uninstall --yes --remove-data      # stop the service, remove autostart, delete the data
uv tool uninstall conexus
rm -rf ~/.local/share/nexus
```

The full sequence, including exporting your knowledge first and removing the Claude integration, is on the site under [Remove Nexus completely](https://hellblazer.github.io/nexus/#uninstall).

## Problems

| Symptom | Do this |
|---|---|
| `nx: command not found` | Add `~/.local/bin` to your PATH and open a new terminal. If PATH is right, run `nx self install`. |
| Crash on startup, or an import error naming voyageai or Pydantic v1 | You are on Python 3.14. Run `uv python install 3.13`, then `uv tool install conexus --force --python 3.13`, then `nx self install`. |
| `nx doctor` says credentials not set | 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. If you updated with `uv tool install`, see Update above. |
| Plugin installed but its tools never appear | The `nx` command or Node.js is missing. Run `/conexus:nx-preflight`; it says which. |
| Nothing above helps | Paste the [recovery runbook](https://gist.github.com/Hellblazer/08f0a615e3d73e47d8062bce4829b611) as the first message of a Claude Code session. It checks the install step by step and asks before changing 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 anonymous 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. `nx telemetry off` stops it; `nx telemetry status` shows the setting.

## Learn

- [Getting started](https://hellblazer.github.io/nexus/getting-started.html): twelve lessons, all done inside Claude Code.
- [Working with RDRs](https://hellblazer.github.io/nexus/rdr.html): record a decision before you build, in eight lessons.
- [Research with Nexus](https://hellblazer.github.io/nexus/research.html): what you say to Claude at each step of research work, and what you see.
- [Research in Nexus](https://hellblazer.github.io/nexus/research-in-nexus.html): the thinking behind the method, what was borrowed from experimental science and what was left out.
- [The Nexus Tuple Space](https://hellblazer.github.io/nexus/tuple-space.html): how sessions, agents, and hooks coordinate.
- [Coordination](https://hellblazer.github.io/nexus/coordination.html): how sessions and agents coordinate through the tuple space, and which steps the hooks, the channel, and Claude each do.
- [CLI reference](https://github.com/Hellblazer/nexus/blob/main/docs/cli-reference.md), [architecture](https://github.com/Hellblazer/nexus/blob/main/docs/architecture.md), [storage tiers](https://github.com/Hellblazer/nexus/blob/main/docs/storage-tiers.md), and the [docs tree](https://github.com/Hellblazer/nexus/blob/main/docs/README.md).
- [Managed service](https://github.com/Hellblazer/nexus/blob/main/docs/managed-onboarding.md), 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](https://hellblazer.github.io/nexus/coordination.html#l5) and [Getting started](https://hellblazer.github.io/nexus/getting-started.html#push-delivery) 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](https://github.com/Hellblazer/nexus/blob/main/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](https://github.com/Hellblazer/nexus/blob/main/LICENSING.md).
