Skip to main content

Self-hosted semantic search and knowledge management for LLM-driven development

Project description

Nexus

CI PyPI version Python versions License: AGPL v3

Nexus is a lightweight knowledge management system for AI coding agents. It provides persistent memory and semantic search through tiered storage that preserves decisions, findings, and project knowledge across agent sessions. That knowledge compounds over time, becoming more valuable as the corpus grows.

Nexus includes RDR (Research-Design-Review), an integrated human-AI design and audit system. RDRs capture the reasoning behind technical decisions — problem, research, chosen approach, rejected alternatives — as structured, searchable documents that live in the repository alongside the code. Nexus indexes the RDR corpus so team members and their agents can quickly get up to speed on a project's design history and stay aligned as the codebase evolves.

What it does

Semantic search. Standard text search matches exact strings. Nexus matches by meaning: querying "how does authentication work" returns the auth middleware, the login handler, and the JWT validation — even when none contain the word "authentication."

nx index repo .                  # index current repo
nx search "error handling"       # finds try/catch, Result types, error middleware, logging
nx search "auth" --hybrid        # combine semantic + keyword matching

Persistent memory. Agents share ephemeral session context for inter-agent coordination, project-level decisions persist locally with full-text search, and cross-project knowledge is stored permanently with semantic retrieval.

nx scratch put "the bug is in the retry logic"    # T1: inter-agent session context
nx memory put --project myapp --title "DB choice"  "Chose Postgres over SQLite for concurrency"
nx store put --collection knowledge__myapp "API rate limit is 10k/min per the vendor docs"

Decision tracking. RDR documents record the reasoning behind technical choices and are searchable alongside code, so prior decisions surface automatically during new design work.

Quick Start

uv tool install conexus          # install the nx CLI
nx index repo .                  # index your repo (works immediately — no API keys needed)
nx search "what does X do"       # semantic search, fully local

Local mode uses bundled ONNX embeddings — zero configuration required. For higher-quality cloud embeddings, run nx config init to set up API keys. See Getting Started for the full walkthrough.

For Claude Code, also install the plugin (see plugin documentation):

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

All three tiers work with zero API keys — including semantic search, which uses local ONNX embeddings by default. For higher-quality embeddings, optionally configure ChromaDB Cloud and Voyage AI (free tiers available). See Getting Started for the full walkthrough.

Three tiers, one lifecycle

Different information has different lifetimes. Together the three tiers form an integrated memory system that extends agent context across sessions and projects.

Tier Purpose Storage API keys?
Scratch (T1) Inter-agent session context — coordination and knowledge sharing across agent invocations In-memory ChromaDB No
Memory (T2) Project-level persistence with full-text search Local SQLite + FTS5 No
Knowledge (T3) Permanent semantic knowledge — code, papers, docs, decisions searchable by meaning Local ChromaDB (default) or ChromaDB Cloud + Voyage AI No (local) / Yes (cloud)

Agents use all three tiers cooperatively. T1 enables inter-agent communication — sharing findings and preventing duplicate work within a session. T2 provides project decisions that constrain solutions. T3 surfaces how similar problems were resolved in other contexts. As the T3 knowledge base grows, it becomes the project's institutional memory — managing the information overload that accompanies complex designs and long-lived codebases.

What you can index

Code, documents, PDFs, and manual knowledge entries — anything that benefits from semantic search:

nx index repo .                          # code + docs + RDRs from a git repo
nx index pdf paper.pdf --collection knowledge__ml  # reference papers
nx store put --collection knowledge__ops "Redis maxmemory-policy: allkeys-lru for cache, noeviction for queues"

Repository indexing (nx index repo) is the most automated path. It classifies git-tracked files, chunks code into logical pieces via tree-sitter AST parsing across 31 languages, and embeds each chunk with purpose-matched Voyage AI models. Recently-touched files rank higher via git frecency scoring.

See Repo Indexing for details and .nexus.yml configuration.

RDR: Research-Design-Review

Technical decisions made during rapid development lose their reasoning quickly. An RDR captures the problem, investigation, chosen approach, and rejected alternatives in a structured document. Each research finding is tagged with its evidence quality — verified against source code, supported by documentation only, or assumed — so readers know which conclusions are load-bearing and which need further validation.

RDRs are iterative: write, build, learn, revise. The growing corpus remains searchable, so prior decisions surface automatically when starting new design work — preventing contradictions and avoiding redundant investigation across the team.

RDR is fully optional. See RDR Overview for the full process.

Claude Code plugin

The nx/ directory is a Claude Code plugin that gives agents access to everything above. Install via the marketplace:

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

The plugin provides 15 specialized agents, 28 skills covering the RDR lifecycle and development workflows, session hooks for automatic context initialization, and MCP servers for structured storage access. Agents search indexed code before proposing changes, check prior RDR decisions before designing new features, and coordinate through standard pipelines (plan → implement → review → test) with built-in quality gates.

The plugin integrates with Beads for task tracking. See nx/README.md for the full plugin documentation.

CLI Reference

The nx command provides direct access to all storage tiers, indexing, and search.

Command What it does
nx search Semantic and hybrid search across indexed code, docs, and knowledge
nx index Index git repos, PDFs, and markdown into searchable collections
nx store Store, retrieve, export, and import knowledge entries
nx memory Per-project persistent notes (local, no API keys)
nx scratch Inter-agent session context (in-memory, no API keys)
nx collection Inspect and manage cloud collections
nx config Credentials and settings
nx doctor Health check — verifies dependencies, credentials, connectivity
nx hooks Install git hooks for automatic re-indexing on commit

Full details: CLI Reference.

Documentation

Document What it covers
Getting Started Install, local usage, Claude Code plugin, semantic search setup
CLI Reference Every command, every flag
Storage Tiers T1/T2/T3 architecture and data flow
Memory and Tasks T2 memory, beads integration, session context
Repo Indexing File classification, chunking pipeline, frecency scoring
Configuration Config hierarchy, .nexus.yml, tuning parameters
Architecture Module map, design decisions
Contributing Dev setup, testing, code style

RDR (Research-Design-Review):

  1. Overview — What RDRs are, when to write one, evidence classification
  2. Workflow — Create → Research → Gate → Accept → Close
  3. Nexus Integration — How storage tiers and agents amplify RDRs
  4. Templates — Minimal and full examples, post-mortem template
  5. Project RDR Index — All 36 project RDRs with status

Prerequisites

License

AGPL-3.0-or-later. See LICENSE.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

conexus-2.3.2.tar.gz (1.4 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

conexus-2.3.2-py3-none-any.whl (150.6 kB view details)

Uploaded Python 3

File details

Details for the file conexus-2.3.2.tar.gz.

File metadata

  • Download URL: conexus-2.3.2.tar.gz
  • Upload date:
  • Size: 1.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for conexus-2.3.2.tar.gz
Algorithm Hash digest
SHA256 da60740618825f9be69e87da06d9603192410cbb5a239f566c7081ac557ea9c2
MD5 9f06aab0bc2358f50fcbe468e4a16239
BLAKE2b-256 217b82f693fa43bd3de0a977637a722584f7b14e448e36caa04265ce310b31b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for conexus-2.3.2.tar.gz:

Publisher: release.yml on Hellblazer/nexus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file conexus-2.3.2-py3-none-any.whl.

File metadata

  • Download URL: conexus-2.3.2-py3-none-any.whl
  • Upload date:
  • Size: 150.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for conexus-2.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 9af6080054d2c49e3c7a58dde9219e7686413696e5e46549da31cbbc21ae7d23
MD5 5886c09c8c551e658716325e4f13674f
BLAKE2b-256 a471fffd3a6d2aa0dbd4a9a63a70426ed7fce7670c228afb3fdb06515dc1bf44

See more details on using hashes here.

Provenance

The following attestation bundles were made for conexus-2.3.2-py3-none-any.whl:

Publisher: release.yml on Hellblazer/nexus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page