Repository avatar
Search & Data Extraction
v0.10.0
active

sextant

io.github.hulagerushikesh/sextant

Search your own PDFs, Markdown and text files from any assistant. Local, no key, cited passages.

Documentation

sextant

Search your own documents from any AI assistant — and see the numbers that say how well the search works.

sextant is a knowledge base that runs on your own machine as a standard Model Context Protocol server. Point it at a folder of PDF, Markdown or text files, plug it into Claude Desktop or any other MCP client, and ask. Answers come from your documents and name the file and the page.

A question answered from the indexed documents, each claim followed by a numbered citation

A real answer from the project's own web interface (2026-11-12). Each numbered marker opens the passage it came from.

Quickstart

Four steps. Most of the time is two downloads — about 170 MB of libraries, then about 180 MB of search models. No account and no key. It needs Python 3.11 or newer — check first, because an older one fails with a confusing "no matching distribution" message:

python3 --version

1. Install it into a folder of its own, so its location is known:

python3 -m venv ~/sextant
~/sextant/bin/pip install sextant-kb

2. Add your documents — any folder of PDF, Markdown or text files:

~/sextant/bin/sextant-ingest ~/Documents/notes -r

The first run downloads the search models, once; after that it works offline. A note that it is storing text only is expected: an optional model-written overview per document needs a Gemini key, and nothing else does. Searching happens on your machine; the passages it finds go to whichever assistant you plug it into.

3. Plug it into your assistant. In Claude Desktop: Settings → Developer → Edit Config, then add this and restart the app. The command must be a full path; echo ~/sextant/bin/sextant-kb prints yours.

{
  "mcpServers": {
    "knowledge-base": {
      "command": "/Users/you/sextant/bin/sextant-kb"
    }
  }
}

4. Ask. For example: "Search my knowledge base — what do my notes say about onboarding?" The assistant calls the search tool and answers from your documents, with the source of each passage.

To see what is indexed, or take a document back out:

~/sextant/bin/sextant-forget --list

Any other MCP client works the same way: its server command is the full path to sextant-kb. On Windows the config file is %APPDATA%\Claude\claude_desktop_config.json and a virtual environment keeps its commands in Scripts\ rather than bin/; this project has not been tested on Windows.

One line instead: Claude Code, VS Code, Cursor

With uv installed, one pasted line replaces the four steps: it installs sextant, tells the assistant about it, and points it at a folder. Change ~/Documents to the folder you want searched. Each line runs --version first, so the first install (a few hundred MB) finishes in the terminal rather than timing out inside the assistant. When the assistant starts it, the folder is indexed in the background and kb_stats shows the progress and any file it could not read.

Claude Code:

uvx --from 'sextant-kb>=0.10' sextant-kb --version && claude mcp add sextant --scope user --env SEXTANT_FOLDER=~/Documents -- uvx --from 'sextant-kb>=0.10' sextant-kb

VS Code (needs the code command: in VS Code run Shell Command: Install 'code' command in PATH once):

uvx --from 'sextant-kb>=0.10' sextant-kb --version && code --add-mcp '{"name":"sextant","command":"uvx","args":["--from","sextant-kb>=0.10","sextant-kb"],"env":{"SEXTANT_FOLDER":"~/Documents"}}'

Cursor: add this to ~/.cursor/mcp.json. It has not been tried in Cursor yet.

{"mcpServers": {"sextant": {"command": "uvx", "args": ["--from", "sextant-kb>=0.10", "sextant-kb"], "env": {"SEXTANT_FOLDER": "~/Documents"}}}}

What your assistant gets

ToolDoes
kb_searchFinds the passages that answer a question, ranked, with source and page
kb_listLists every document with its title, size and what it is about
kb_ingestAdds documents; re-using an id replaces the old version
kb_statsLibrary size, search model, where it is stored
kb_ann_benchmark, kb_ann_compareCompare index types on your own library

Your library is stored in your user-data folder (set SEXTANT_CHROMA_DIR to move it), never inside the install, so reinstalling does not lose it.

How good is the search

Measured, on a committed test set, and re-checked on every change:

Search stageRight passage first
Meaning search only87%
Keyword search only78%
Both, fused91%
Both, fused, then re-read (the shipped pipeline)93%

65 test questions over 21 documents. Asked 10 questions those documents cannot answer, it declines 8.

The full comparison, the nine ideas that were measured and rejected, and what a question costs are on one page: docs/RESULTS.md. Every figure there is generated from the measurement files.

The full app (optional)

The package above is the reusable part. This repository also holds what is built on it: an agent that decides for itself what to look up, a web interface with clickable citations, and the evaluation tools. That part needs a Gemini API key, which is the only key the project reads.

git clone https://github.com/hulagerushikesh/sextant && cd sextant
python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]" && (cd frontend && npm install)
cp .env.example .env

Add your key to .env, then:

./start_all_services.sh

The interface opens on http://localhost:3000. Or run both halves in containers with docker compose up --build. Details, every setting and the HTTP routes are in docs/running.md.

Honest status

Last checked 2026-11-12.

WhatState
Search over your own documents: PDF, Markdown, text; add, replace, removeWorking
Standard MCP server, published as sextant-kbWorking — on the public package index and in the official MCP registry as io.github.hulagerushikesh/sextant; the quickstart installs the latest release
Measured search quality with a check on every changeWorking
Agent, web interface, citations, cost per question, daily spend capWorking
Each person's uploads kept apart on a shared deploymentWorking — proven on a hosted box 2026-11-04
Hosted demoNone. The hosted box was removed 2026-11-13; deploy/ is the recipe to build one
Used by anyone outside the projectNot yet — see planning/PLAN.md

Known limits, stated plainly, are in docs/known-issues.md. The two that matter most to a new user: a scanned PDF with no text layer is refused rather than read, and the test questions were written alongside the test documents, so the numbers grade the search pipeline, not your library.

Read more

PageWhat is in it
docs/RESULTS.mdThe numbers, and what was rejected
docs/how-it-works.mdThe agent loop, the search stages and why each exists, the model port
docs/running.mdSetup, settings, routes, repository layout
docs/interface.mdWhat the web interface does and why
docs/known-issues.mdLimits and deliberate trade-offs
docs/history.mdThe roadmap as it was built, phase by phase
learning/A study path, plus the note behind every measurement
planning/The plan, progress and cost

Credits

Started as SudhanshuR37/AgenticRAG with Sudhanshu Randive; rebuilt from the ground up in September 2026 and renamed from AgenticRAG in 0.7. MIT licensed — see LICENSE. PDF reading uses PyMuPDF, which is AGPL-licensed.

PYPI
sextant-kb
Install Command
pip install sextant-kb
Runtime: uvx