What Polaris is, and why your agent keeps reading whole files

What Polaris is, in one paragraph

Polaris is a small Rust binary that indexes your project's documentation, embeds it with a local ONNX model, stores the vectors in SQLite next to your repo, and serves hybrid semantic plus keyword search over two interfaces: a CLI you can use yourself, and an MCP server your coding agent calls directly. Claude Code, Cursor and Codex all speak MCP, so the agent gains a polaris.search tool alongside its own grep and read.

It is not a chatbot, not a hosted service, and not a replacement for your agent. It is the thing your agent should have had from the start: a way to find the right paragraph without reading the whole file.

The problem: grep matches strings, questions are about meaning

An agent without retrieval has exactly two moves: match a literal string, or read a file top to bottom. Both fail the same way. Grep for "auth" and you get every log line, comment and variable name that happens to contain those four letters, and none of the section titled "Session lifecycle" that actually answers the question. So the agent falls back to reading whole files, and your context window fills with paragraphs nobody needed.

That has a cost you can feel: less room for the code being worked on, slower turns, and an agent that starts forgetting the beginning of the session because the middle is full of documentation it skimmed once. We took that argument apart properly, with the per-project numbers, in grep vs semantic search for coding agents.

How it works

Four steps, and only the first two involve you.

• Index: Polaris walks your docs, splits them along their heading structure so every chunk keeps the section it came from, and embeds each chunk with a local model. The walk is gitignore-aware, so node_modules never lands in your index
• Serve: polaris serve exposes search, index and status as MCP tools over stdio
• Search: your agent sends a question. Polaris runs vector similarity and BM25 keyword search in parallel, fuses the two rankings, and reranks the survivors for diversity so you get two different answers rather than the same paragraph twice
• Answer: the agent gets a handful of ranked, section-labelled chunks. Not file paths to go open. The passage itself

Every stage of that has a reason behind it and a default you can change. If you want the version with the constants and the trade-offs, read how Polaris search actually works.

What it actually saves

Polaris logs every search it serves and compares what it returned against the full contents of the files that search would have sent an agent off to read. polaris savings prints the running total. Across 110 real searches on three of our own repos: ~530 tokens per lookup against a 10.7-15.4k grep-and-read baseline, roughly 20x. On a 200k context window that is a quarter of a percent per lookup instead of five to eight percent.

These are our numbers on our repos, which is exactly as much as they are worth. The honest version of this claim is that you can reproduce it: run polaris savings on your own project after a week and see what it says there. The per-project breakdown shows the spread rather than the average.

Everything stays on your machine

Indexing, embedding and search all run locally. The embedding model is an ONNX model that runs on your CPU, the index is a SQLite file sitting in your project, and there is no cloud in the retrieval path and no telemetry. Your queries are not a product, your code is not training data, and Polaris works with the network unplugged.

This is not a privacy posture bolted on after the fact. It is why the thing is a Rust binary with an embedded model rather than an API key.

Who this is for

Polaris earns its place when a project has more documentation than fits comfortably in a context window and you work in it through an agent. A repo with a real docs tree, architecture notes, specs, runbooks, ADRs. The bigger the docs and the longer the sessions, the more it pays.

It is worth saying who it is not for. If your entire documentation is one README your agent can read in a single call, you do not need a retrieval layer, you need that README. Polaris is not going to make a small project faster, and pretending otherwise would waste your afternoon.

The three questions everyone asks

"Isn't grep good enough?" For finding a symbol you already know the name of, grep is perfect and Polaris does not try to replace it. Your agent keeps both tools and picks. The gap opens on questions phrased as questions, where the words you would search for are not the words in the document.

"Another index to keep fresh?" That was the original objection, and it was fair, so we removed the manual step. A Claude Code hook re-indexes on every write, so the index refreshes as you edit and you never think about it again. polaris setup wires it up. There is a whole post on the hooks.

"What does it cost?" The CLI and the MCP server are free and MIT licensed, and that is the whole product for Markdown docs. Polaris Pro adds ingestion of source code, PDF, .docx and more through the same pipeline, which is what you want when the answer lives in the code rather than the docs. That post is here, and pricing is here.