Nexus
Persistent memory and semantic search for Claude. Three storage tiers that survive across sessions, an event-sourced document catalog with typed links, and a specification-before-code workflow for tracking decisions. Local-first; no API keys required. Knowledge compounds across conversations instead of evaporating when the window closes.
Start here
Three pages, in order:
- Install — set up Nexus for how you use Claude: Claude Desktop, Claude Code, or Claude Cowork.
- Getting started — learn the tooling, eleven lessons done inside Claude Code.
- Working with RDRs — record a decision with an RDR, eight lessons on the practised cycle.
- Research with Nexus — how the store grounds answers, and what it does for each step of research work.
Prerequisites
Python 3.12–3.13 (3.14 not yet supported — upstream dependency issue), uv, git. For hybrid search, ripgrep. For the Claude Code plugin, Node.js (the bundled sequential-thinking and context7 servers spawn via npx).
Install for Claude
One host package, the nx CLI (conexus on PyPI), serves three surfaces. The install guide walks each one with copyable commands; the short form:
- Claude Desktop: download
conexus.mcpbfrom the latest release and double-click it. Requires uv on the host. - Claude Code:
uv tool install conexus # the nx CLI; the plugin's MCP servers are this package nx self install # move it onto the generation layout nx init # provision the local service (Postgres + pgvector + bge-768) /plugin marketplace add Hellblazer/nexus /plugin install conexus@nexus-plugins
The CLI must be installed first:/plugin installalone leaves the servers unable to launch. - Claude Cowork: works once the plugin is installed in Claude Code on the host.
The full deployment story across all three surfaces is docs/desktop-deployment.md.
What it does
- Persistent memory — three storage tiers (T1 session scratch, T2 memory bank, T3 semantic knowledge store, both persistent tiers served by the native Postgres-backed
nexus-service) so Claude remembers across conversations. - Semantic search — index your code, docs, RDRs, and PDFs once; search by meaning afterward. Tree-sitter AST chunking across 31 languages, CCE prose chunking, PDF auto-routing.
- Typed document catalog — Xanadu-inspired addressing with typed links (
cites,implements,supersedes). Walk from a design doc to the code that implements it. - RDR: Research-Design-Review — write a spec before you code. Captures the problem, research, alternatives, and chosen approach. The corpus is searchable, so prior decisions surface during new design work.
- Local-first — runs entirely on your machine: an on-device bge-768 ONNX embedder over a bundled Postgres 17 + pgvector service that
nx initprovisions for you. Voyage AI (server-side embeddings) is opt-in for the managed-cloud deployment.
Learn
Getting started — eleven lessons, done inside Claude Code:
- Start a session
- End a session, start the next one
- Index your repository, then search it
- Memory: what Claude keeps between sessions
- Scratch: how Claude and its agents share notes
- Knowledge: notes, documents, and the catalog
- Explore: research, links, and the topic map
- Render and iterate
- Questions that need many documents
- Record a decision with an RDR
- Maintenance
Working with RDRs — eight lessons on the practised cycle:
- What an RDR is here
- It starts as a conversation
- Research, in cycles
- Read it, react, repeat
- The gate
- Accept, and the plan follows
- Build it, across many sessions
- Close it, and what remains
Research with Nexus — what the store does for each step of research work:
- What the system does
- Grounding
- Curating
- Reading
- Chronicling
- Coupling
- Asking and analyzing
- Synthesizing and extracting
- Verifying
- Rendering
- Where it ends up
- Appendix: topics, aspects, sections, projections
Updating
nx self install # 1. update the code (keeps your extras)
nx upgrade # 2. converge the service, the data, and the plugins
Both steps, every time. Never uv tool install conexus or --force to upgrade: that drops [local] and empties search; nx self install repairs it. Details, including what /plugin update does and the path for an install that never left ChromaDB, are on the site under Update.
Telemetry
Once a day the MCP server sends one anonymous ping to the managed service so
the project can count active installs. It carries exactly six fields: a random
install id (a UUID minted on first use, stored in ~/.config/nexus/install_id),
the conexus version, the install mode (local or cloud), OS, CPU
architecture, and Python major.minor. No hostname, no paths, no collection
names, no content. It runs on a background thread with a two second timeout
and never blocks or retries. Turn it off with either:
nx telemetry off # writes telemetry.enabled: false to config.yml
export NX_NO_TELEMETRY=1 # or per environment
nx telemetry status shows the current setting and the last ping time.
Something broken?
The site's Problems section covers the common ones. For a broken install, nexus-recovery-runbook is a diagnose-first recovery procedure meant to be handed to a Claude Code session as its first message — the assistant runs it phase by phase, pausing for your explicit go-ahead before anything that upgrades or migrates data, and gathers redacted forensics + opens a GitHub issue (or emails a fallback address) if it can't resolve things itself. It's a convenience for a broken install, not a substitute for filing an issue directly if something looks wrong — and it carries its own guardrails (read-only diagnosis first, no destructive commands without confirmation, no secrets ever leave the machine), but you're trusting an LLM to run real commands against your install. Review what it does before handing it off, especially the first time.
Going deeper
| If you want to... | Read |
|---|---|
| Understand the architecture | Storage Tiers, Architecture |
| Install, upgrade, or uninstall the agent | Agent Lifecycle & Operations |
| Use the hosted managed service | Managed Onboarding |
| Write an RDR | RDR: Research-Design-Review |
| Index a repo or PDFs | Repo Indexing |
| Configure or tune | Configuration |
| Run in containers or Cowork | Container Integration |
| Back up my knowledge store | Storage Tiers § T3 Backup and Migration |
| Fix empty search results after upgrading | Getting Started § Troubleshooting |
| Browse the docs tree | docs/README.md |
License
Dual-licensed. Open source under AGPL-3.0-or-later (LICENSE); commercial licenses are available for organizations that need non-AGPL terms — see LICENSING.md.
1 maintainer
Release files for conexus 7.41.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| conexus-7.41.1.tar.gz | 5.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| conexus-7.41.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 8.7 MB
Release files / conexus-7.41.1.tar.gz
| Download URL | conexus-7.41.1.tar.gz |
|---|---|
| Size | 5.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
58d394809807a9e9d5227d078bd801ceb078f9b586e88739279d4220a5f1c069
|
|
BLAKE2b-256 checksum How to use checksums |
e5bcaa4dd2ee320874be57bf4dc16ef01eefab185acbe676c16ced170ed2bd77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / conexus-7.41.1-py3-none-any.whl
| Download URL | conexus-7.41.1-py3-none-any.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc0e0846a80c0e09fb750453a53ff9a6a5db8475863d6522a2d90422b9f01f39
|
|
BLAKE2b-256 checksum How to use checksums |
e82b637b786d2218beba95e7f8bb840089eb6ed56746a2e962f1f944c2072587
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency log
