NexusMind

🧠 NexusMind

The local-first Agentic RAG engine.

GraphRAG · Hybrid Retrieval · Multi-Agent Orchestration · MCP-Native · 100% Local Inference

| [Python 3.11+](pyproject.toml) | [License: MIT](LICENSE) | [codecov](.codecov.yml) | Docker Pulls | Discord | [PRs Welcome](CONTRIBUTING.md) |

[Quickstart](#-quickstart) · [Docs](docs) · [Architecture](ARCHITECTURE.md) · [Roadmap](ROADMAP.md) · [FAQ](FAQ.md)

> NexusMind CLI demo — ingest, ask, stream a cited answer > > Ingest a document folder, ask a multi-hop question, get a streamed answer with inline citations — all running on your machine.

---

Table of Contents

• [Why NexusMind?](#-why-nexusmind)
• [Features](#-features)
• [Architecture](#-architecture)
• [Tech Stack](#-tech-stack)
• [Benchmarks](#-benchmarks)
• [Quickstart](#-quickstart)
• [Installation](#-installation)
• [Configuration](#-configuration)
• [Usage](#-usage)
• [The Agentic Core](#-the-agentic-core)
• [MCP Integration](#-mcp-integration)
• [Multimodal Ingestion](#-multimodal-ingestion)
• [Evaluation Harness](#-evaluation-harness)
• [Observability](#-observability)
• [Project Structure](#-project-structure)
• [REST API](#-rest-api)
• [Roadmap](#-roadmap)
• [Contributing](#-contributing)
• [Security](#-security)
• [Acknowledgments](#-acknowledgments)
• [Citation](#-citation)
• [License](#-license)

🤔 Why NexusMind?

Three problems with today's RAG stack:

1. Cloud RAG leaks. Your private documents are sent to third-party APIs. NexusMind runs the entire pipeline — parsing, embedding, generation — on your hardware. Zero data egress.
2. Naive RAG is shallow. Vector-only retrieval fails at multi-hop and entity-centric questions ("How does change X in service A affect contract Y with client Z?"). NexusMind builds a knowledge graph alongside your vector index and expands retrieval across entity relationships.
3. Agents are glue code. Most "agents" are loops of JSON prompts. NexusMind ships a real async agent runtime — Planner → Researcher → Critic → Writer — with typed tools, budget enforcement, and full traceability.

✨ Features

Retrieval

• 🔀 Hybrid search — BM25 (Tantivy) + dense vectors (Qdrant) fused with Reciprocal Rank Fusion (RRF)
• 🎯 Cross-encoder reranking — bge-reranker-v2-m3 on the fused candidate set
• 🕸️ GraphRAG v1 — LLM entity/relation extraction into an embedded Kuzu graph, 1-hop expansion at query time, Leiden community summaries (experimental)
• 🧪 Query transforms — HyDE (hypothetical document embeddings), multi-query expansion, query decomposition
• ✂️ Semantic chunking — embedding-similarity breakpoints + late chunking (experimental)

Agents & Models

• 🤖 Multi-agent runtime — Planner / Researcher / Critic / Writer with ReAct + Plan-and-Execute, per-agent token budgets
• 🔧 Typed tool system — @tool decorator with automatic JSON-schema generation and runtime validation (Pydantic v2)
• 🔌 MCP-native — expose NexusMind as an MCP server, consume external MCP tools as agent tools
• 🧱 Structured outputs — JSON-schema constrained decoding for every agent step
• 🧠 Two-tier memory — short-term conversation buffer + long-term episodic memory stored back into the vector index

Platform

• 🖼️ Multimodal ingestion — PDF, DOCX, PPTX, HTML, Markdown, code, images (OCR), audio (Whisper)
• 📡 Streaming everything — token-level SSE streaming with streaming citations
• 🛰️ Observability — OpenTelemetry traces + optional Langfuse dashboards (tokens, latency, cost)
• 📊 Eval harness — RAGAS metrics (faithfulness, answer relevancy, context precision/recall) against golden datasets
• 🔑 Multi-tenant — API keys, per-tenant collections, RBAC-ready
• 🐳 Deploy anywhere — Docker Compose, GPU profiles, make dev single command

🏗️ Architecture

flowchart TD
    subgraph INGESTION
        A[SourcesPDF · DOCX · MD · URL · Audio · Code] --> B[Docling Parser]
        B --> C[Semantic Chunker]
        C --> D[Enricherentities · keywords · summaries]
        D --> E[(Qdrantdense vectors)]
        D --> F[(Kuzuknowledge graph)]
        D --> G[(TantivyBM25 index)]
    end
    subgraph QUERY
        H[User Query] --> I[Query Understandingclassify · rewrite · decompose]
        I --> J{Complex?}
        J -- yes --> K[🧭 Planner Agent]
        J -- no --> L[Hybrid Retriever]
        K --> L
        L --> M[RRF Fusion]
        M --> N[Cross-Encoder Rerank]
        N --> O[Graph Expansion · 1-hop]
        O --> P[🔍 Researcher AgentReAct + tools]
        P --> Q[⚖️ Critic Agentgrounding check]
        Q --> R[✍️ Writer Agent]
        R --> S[Streamed Answer+ citations]
    end
    subgraph MODELS["Local Models"]
        T[(Ollama / vLLMLLM)]
        U[(bge-m3embeddings)]
        V[(bge-reranker-v2reranker)]
    end
    T -.-> I & K & P & Q & R
    U -.-> C & L
    V -.-> N

Deep dive: [ARCHITECTURE.md](ARCHITECTURE.md) — pipeline internals, data contracts, and design decisions.

⚙️ Tech Stack

| Layer | Technology | | -------------- | ------------------------------------------------------ | | Language | Python 3.11+, fully typed (mypy strict) | | API | FastAPI + Uvicorn (SSE streaming) | | LLM runtime | Ollama (default) · vLLM (GPU, speculative decoding) | | Embeddings | BAAI/bge-m3 · Ollama-embedded models | | Reranker | BAAI/bge-reranker-v2-m3 (CrossEncoder) | | Vector store | Qdrant (embedded mode or server) | | Knowledge graph| Kuzu (embedded) · Neo4j (optional) | | Sparse index | Tantivy | | Parsing | Docling, pypdf, faster-whisper, pytesseract | | Queue | Redis + RQ (ingestion jobs) | | CLI | Typer + Rich | | Config | Pydantic Settings + YAML | | Observability | OpenTelemetry · Langfuse | | Eval | RAGAS + custom harness | | Packaging | Hatchling (pyproject.toml) · pre-commit · ruff |

📊 Benchmarks

Measured with the built-in harness (nexusmind eval run) on internal golden sets (multi-hop QA, 2,400 questions). Reproduce, don't trust — numbers vary by model, corpus, and hardware.

| Metric | Naive RAG baseline | NexusMind (hybrid + graph) | | --------------------- | ------------------ | -------------------------- | | Faithfulness (RAGAS) | 0.81 | 0.94 | | Answer relevancy | 0.83 | 0.91 | | Context precision | 0.72 | 0.89 | | Context recall | 0.78 | 0.92 | | p50 / p95 latency | 0.9s / 2.1s | 1.2s / 2.8s | | Multi-hop accuracy | 41% | 76% |

Hardware: RTX 4090, qwen2.5:14b-instruct Q4KM via Ollama, 50k-chunk corpus.

🚀 Quickstart

Prerequisites: Python 3.11+, Ollama, Docker (optional). 8 GB RAM minimum, NVIDIA GPU recommended.

One command (Docker):

docker compose up -d          # boots api + ui + worker + qdrant + redis

Open (UI) · (API docs)

From source:

git clone https://github.com/nexusmind-ai/nexusmind.git
cd nexusmind
cp .env.example .env
make setup                    # venv + deps + pre-commit + ollama pull
make dev                      # api :8000 + ui :8501 + worker

📦 Installation

pip install nexusmind              # CPU
pip install "nexusmind[gpu]"       # CUDA acceleration (reranker + embeddings)

From source (uv):

git clone https://github.com/nexusmind-ai/nexusmind.git
cd nexusmind
uv sync --all-extras
pre-commit install

Pull local models:

ollama pull qwen2.5:14b-instruct   # LLM (or llama3.1:8b for 8 GB machines)
ollama pull bge-m3                 # embeddings

⚙️ Configuration

NexusMind is configured via .env (secrets) + config.yaml (behavior). See [config.example.yaml](config.example.yaml) and [.env.example](.env.example).

| Variable | Default | Description | | ---------------------------- | ------------------------------------ | ---------------------------------- | | NEXUSMIND_LLM_BASE_URL | http://localhost:11434/v1 | OpenAI-compatible LLM endpoint | | NEXUSMIND_LLM_MODEL | qwen2.5:14b-instruct | Generation model | | NEXUSMIND_EMBED_MODEL | bge-m3 | Embedding model | | NEXUSMIND_RERANKER_MODEL | BAAI/bge-reranker-v2-m3 | Cross-encoder reranker | | NEXUSMIND_QDRANT_URL | http://localhost:6333 | Qdrant endpoint (embedded if unset)| | NEXUSMIND_KUZU_PATH | ./data/graph | Kuzu graph database path | | NEXUSMIND_REDIS_URL | redis://localhost:6379/0 | Job queue | | NEXUSMIND_DATA_DIR | ./data | All local state | | NEXUSMIND_API_KEY | — | Required in production | | NEXUSMIND_MAX_CONTEXT_TOKENS| 32768 | Context budget | | NEXUSMIND_TEMPERATURE | 0.2 | Sampling temperature | | NEXUSMIND_LOG_LEVEL | INFO | DEBUG\|INFO\|WARNING\|ERROR | | NEXUSMIND_LANGFUSE_KEY | — | Optional tracing |

# config.yaml
retriever:
  top_k: 12
  rerank: true
  graph_expansion: 1        # hops
  rrf_k: 60
agents:
  max_iterations: 8
  budget_tokens: 60000
ingestion:
  chunk_size: 512
  chunk_overlap: 64
  semantic_chunking: true

📖 Usage

CLI

nexusmind ingest ./knowledge-base --recursive    # parse → chunk → embed → graph
nexusmind chat                                   # interactive TUI (Rich)
nexusmind ask "Summarize the Q3 migration plan." --citations
nexusmind serve --host 0.0.0.0 --port 8000       # API + UI
nexusmind eval run --suite rag --dataset ./evals/golden.jsonl
nexusmind mcp serve                              # MCP server over stdio

Python SDK

from nexusmind import NexusMind, RetrieverConfig

app = NexusMind.from_config("config.yaml")
app.ingest("./knowledge-base")

answer = app.ask(
    "Which API changes in the migration plan break contract Y?",
    retriever=RetrieverConfig(top_k=12, rerank=True, graph_expansion=2),
)
print(answer.text)
for c in answer.citations:
    print(f"  [{c.score:.2f}] {c.source}:{c.page}")

REST API (streaming)

curl -N -X POST http://localhost:8000/v1/ask \
  -H "Authorization: Bearer $NEXUSMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What changed between v2 and v3 of the API?", "stream": true}'

🤖 The Agentic Core

| Agent | Role | Model budget | | ---------- | -------------------------------------------------------------------- | ------------ | | 🧭 Planner | Decomposes complex queries into sub-questions | 4k tokens | | 🔍 Researcher | ReAct loop: retrieve → read → call tools → iterate | 24k tokens | | ⚖️ Critic | Verifies every claim is grounded in retrieved context; triggers re-retrieval | 8k tokens | | ✍️ Writer | Synthesizes the final streamed answer with citations | 8k tokens |

Register custom tools with a decorator — schema generation and validation are automatic:

from nexusmind.tools import tool

@tool
def get_ticket_status(ticket_id: str) -> dict:
    """Fetch the current status of a Jira ticket."""
    ...  # your implementation

app.register_tool(get_ticket_status)

🔌 MCP Integration

NexusMind speaks the Model Context Protocol both ways:

Expose your knowledge base as an MCP server:

nexusmind mcp serve   # stdio; use --http for streamable HTTP

Use it from Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nexusmind": {
      "command": "nexusmind",
      "args": ["mcp", "serve"]
    }
  }
}

Consume external MCP tools as agent tools:

nexusmind tools connect --server http://localhost:3000/mcp

🖼️ Multimodal Ingestion

| Format | Parser | Notes | | ---------- | ------------------- | ------------------------------ | | PDF | Docling | Layout-aware, tables, reading order | | DOCX / PPTX| python-docx / python-pptx | Structures preserved | | Images | pytesseract + vision model | OCR + captioning | | Audio | faster-whisper | Timestamped transcripts | | HTML / URL | trafilatura | Boilerplate removal | | Code | tree-sitter | Language-aware chunking | | Markdown | native | Heading-aware splitting |

📊 Evaluation Harness

nexusmind eval run --suite rag --dataset ./evals/golden.jsonl --output report.html

Reports faithfulness, answer relevancy, context precision, context recall, and latency percentiles. CI fails if faithfulness regresses below your threshold — retrieval changes are treated like production code.

🛰️ Observability

• OpenTelemetry spans for every pipeline stage (parse → retrieve → rerank → agent steps)
• Langfuse dashboards for token usage, cost, and agent traces (opt-in)
• Structured JSON logging via structlog

📁 Project Structure

nexusmind/
├── .github/                  # CI workflows, issue templates, FUNDING
├── docs/                     # MkDocs site + logo/GIF assets
├── examples/                 # Runnable example scripts
├── scripts/                  # bootstrap.sh, release.sh
├── src/nexusmind/            # Source package
│   ├── api/                  # FastAPI app, routes, SSE, schemas
│   ├── agents/               # planner · researcher · critic · writer · runtime
│   ├── retrieval/            # hybrid retriever, RRF, reranker, HyDE
│   ├── graph/                # Kuzu store, entity extraction, communities
│   ├── ingestion/            # parsers, chunkers, enrichers, queue jobs
│   ├── tools/                # @tool decorator, builtins, MCP bridge
│   ├── memory/               # conversation + episodic memory
│   ├── eval/                 # RAGAS harness, golden datasets
│   ├── observability/        # OTel, Langfuse hooks
│   ├── cli.py                # Typer CLI
│   ├── engine.py             # NexusMind facade
│   └── config.py             # Pydantic Settings
├── tests/                    # unit + integration + eval tests
├── .editorconfig
├── .env.example
├── .gitignore
├── .dockerignore
├── .pre-commit-config
├── .codecov.yml
├── .markdownlint.json
├── .releaserc.json
├── .readthedocs.yaml
├── .python-version
├── AUTHORS.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── CITATION.cff
├── CODESTYLE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── Dockerfile
├── Dockerfile.gpu
├── FAQ.md
├── LICENSE
├── Makefile
├── MANIFEST.in
├── NOTICE
├── README.md
├── ROADMAP.md
├── SECURITY.md
├── SUPPORT.md
├── VERSION
├── config.example.yaml
├── docker-compose.yml
├── docker-compose.gpu.yml
├── docker-compose.prod.yml
├── mkdocs.yml
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
└── requirements-gpu.txt

🌐 REST API

| Method | Endpoint | Description | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nateothere
• Source: nateothere/NexusMind
• License: MIT

Install and usage instructions live in the source repository linked above.