Noetrix

Grounded, cited question-answering over your own documents.

Point it at a folder: a notes vault, a research library, a documentation tree, a pile of scanned PDFs. Ask questions in plain language. Answers are assembled only from what you indexed, with inline [n] citations and a per-answer confidence line. When your corpus is silent on something, it says so rather than inventing an answer.

At a glance

• Reads what you already have: Markdown (wikilinks and YAML frontmatter included), PDFs (scanned ones too, via OCR), Jupyter and R notebooks, source code in most languages, and Office documents.
• Free / local by default: CPU embeddings, on-disk vector and sparse indexes, no managed service. By default generation is the only part that calls out to an endpoint, and retrieval works with no LLM at all.
• Metadata-aware: domain, path, file-type and user-tag metadata support scoped retrieval without splitting the corpus into separate indexes.
• Read the live shape from GET /stats — no copied total stays accurate as a corpus grows.

Why a purpose-built pipeline

A general chatbot answers from the open web. It cannot tell you what your policy says, how your codebase solved a problem, or which page of your reference carries a proof. This system indexes a document collection and answers strictly from it, so every claim traces back to a source you already trust.

It is a full retrieval pipeline rather than a thin wrapper:

• Hybrid retrieval — dense embeddings + BM25, fused by Reciprocal Rank Fusion.
• Query expansion — optional HyDE and HyPE to bridge the vocabulary gap between a short question and long-form documents.
• Intent-aware scope routing — soft-routes a query toward the right subject area, path or file type, without ever being able to empty the result set.
• A dedicated code lane so scripts and notebooks surface for code questions instead of being buried under prose.
• Swappable reranking — cross-encoder, external HTTP reranker, model-free lexical, or none, plus an experimental fine-tuned scorer (Laya) behind a flag.
• Citation-audited generation — answers cite their sources and can self-verify.
• A management console and an agent-facing API, plus a reproducible evaluation suite.

Where to go next

• Getting started

  Install, configure, build the indexes, ask your first question.

• Architecture

  The full query path, scope routing, the code lane, and the RRF math.

• Usage

  CLI, the warm HTTP API, the console, presets, and per-query knobs.

• API reference

  Every endpoint on both services, with permission tiers.

• Agent integration

  Driving this from an LLM agent, efficiently and without fabricated citations.

• MCP server

  The two services as tools for Claude Code, Claude Desktop, Codex and other MCP clients.

• Knowledge maps

  Turn a PDF chapter into a grounded Obsidian canvas whose every node quotes the book.

• Evaluation

  The per-configuration bench, the metrics, and an honest read of what they mean.

• Operations

  Content-addressed IDs, the swap playbook, index integrity, retagging.

• Docker deployment

  Run the whole stack in containers, from a release archive or a checkout, and stop the parts you aren't using.

Highlights

• An MCP server exposes both services as tools for Claude Code, Claude Desktop, Codex and other MCP clients; every tool carries its operation's permission tier. See MCP server.
• A request guard checks Host on every request to either service and Origin on every state-changing one, and RAG_API_TOKEN adds an optional bearer token. See Security.
• Hand-guided OCR and canvas editing in the console: the OCR tab reads a page region by region, each with its own engine, and the Graph tab edits an Obsidian canvas, suggests edge labels with a model you pick, and re-indexes it.
• A PaddleOCR sidecar gives scanned PDFs a real detection + recognition pipeline — far better than Tesseract on skewed, multi-column and non-Latin pages — in its own container, so it can be stopped when you are not ingesting.
• Container profiles make the heavy optional services (OCR, an external reranker) opt-in and independently stoppable, so a laptop can reclaim their memory.
• Readiness that explains itself: GET /health distinguishes loading from failed and carries the reason, and the console can tail the query API's startup log — so a restart that fails says why instead of spinning.
• Reranker preflight checks whether a cross-encoder is reachable and cached before you commit to the restart that applies it.
• Query comparison trees run one question under multiple presets, rerank methods, or generation backends and report source membership, rank shifts and overlap.
• Generated content is not evidence. Maps and summaries an LLM wrote are kept out of every evidence path by default (retrieval.generated_mode), so a citation is authored or source text, and each source reports its provenance. The optional route mode lets them find the primary pages they cite; a source found that way carries found_via. See Route mode.
• An outline and file filters. GET /outline says what the vault holds, by domain and course with chunk and page counts, and source_file / pages restrict a search to one file or a page range of it. See Start from the outline.
• A Navigator engine and skill for multi-hop questions: POST /evidence_pack searches several sub-questions at once and returns evidence with provenance, coverage and gaps, optionally walking canvas graphs (switches off by default), and the noetrix-navigator skill (SKILL_NAVIGATOR.md) turns a question into the right calls. See Evidence pack.
• Stable evidence ids connect /search, /query and /compare results to direct /chunks/{id} lookup when the source reports lookup_available: true.
• Provider discovery and per-query overrides expose resolved backend/model provenance without exposing secrets; provider-only branches reuse identical evidence for fair answer comparisons.

What changed in each release is in the Release notes.