Ingest, index, and query your PDFs, Word docs, Markdown, and images — on your own filesystem. A bundled pure-Go embedding model means it works fully offline from the first run; point it at a local Ollama when you want higher-quality embeddings or reranking. No Docker, no API keys, no cloud.
A local RAG database shouldn't need infrastructure. Install the binary, run go-rag init, and you have a working system.
Everything runs on your machine. A bundled pure-Go embedding model handles ingest and query out of the box; point it at a local Ollama instance later for alternative models and reranking — never required.
A single static binary, built with CGO_ENABLED=0. Copy it, run it, done. Or pull the multi-arch container image if that's your preference.
Every transport binds to 127.0.0.1. Reaching the network is an explicit, logged opt-in (--bind-external).
Every piece exists to answer one question honestly: is this result actually relevant, and can you trust it?
Fuses BM25 keyword and vector semantic ranked lists with Reciprocal Rank Fusion — one tunable constant, honoured identically across CLI, REST, gRPC, and MCP.
A pure-Go embedding model ships in the binary — ingest and query work fully offline from the first run, with no external service to install first. Bring your own model via Ollama when you want.
Each vault gets its own config and indexes — isolated by key-space prefixes within a single Pebble store. No cross-vault contamination, without a database per vault.
Instruction-injection chunks are flagged and quarantined out of default results, with per-signal verdicts and an audit trail — so a poisoned document can't silently steer retrieval.
A background daemon serves 30 MCP tools over HTTP — wire it into Claude Desktop and query, ingest, inspect, triage, and manage your vault directly from the model.
Point go-rag at a local Ollama for alternative embedding models and cross-encoder reranking — an upgrade you opt into, never a prerequisite to get started.
Hybrid mode fuses the BM25 and vector ranked lists with a single symmetric constant. Hover a row (when JavaScript is on) to see how each list contributes to the final ranking.
The same k applies to both lists, so the fusion stays reviewable and matches the standard RRF formula. Tune it per corpus with go-rag config set rrf_k 120, or override it for a single query with go-rag query "…" --rrf-k 30.
A single binary, but not a single blob — the CLI, ingest pipeline, retrieval, and storage layers are cleanly separated internally.
macOS and Linux, amd64 and arm64. The script resolves the latest release, verifies the download against the published SHA-256 checksums, and puts go-rag on your PATH.
# verify the download against the published SHA-256 checksums, then install
curl -fsSL https://madeinoz67.github.io/go-rag/install.sh | sh
Prefer to read it first? curl -fsSL https://madeinoz67.github.io/go-rag/install.sh -o install.sh, open it, then sh install.sh.
brew install madeinoz67/tap/go-rag
Published from the release pipeline alongside the binaries. Requires the tap to be live for the current release.
# requires Go 1.22+
go install github.com/madeinoz67/go-rag/cmd/go-rag@latest
Windows has no curl | sh path. Download the build from the latest release and extract the go-rag.exe from the zip:
Or, with Go installed: go install github.com/madeinoz67/go-rag/cmd/go-rag@latest (produces go-rag.exe).
docker pull ghcr.io/madeinoz67/go-raggo-rag upgrade fetches the latest release, verifies the checksum, and atomically replaces the running binary.Create a vault with default config and the bundled offline embedder.
go-rag init
Point it at a folder. Idempotent, with a progress bar. PDF, Word, Markdown, images, text.
go-rag add ./my-docs/
Hybrid search with source-cited results, reranked by default. Tune mode, k, threshold, filters.
go-rag query "how does X work?"
A small subset shown here — run go-rag --help for the full list.
| go-rag init | Initialize a new RAG database |
| go-rag add <path> | Add files or directories (idempotent; progress bar) |
| go-rag scan [--watch] | Scan for changes (fsnotify + polling) |
| go-rag query "<q>" | Hybrid semantic + keyword search |
| go-rag reprocess <path> | Force re-ingest, bypassing dedup |
| go-rag delete <doc-id> | Remove a document + its chunks (index-only) |
| go-rag start | Start the daemon (MCP + REST + gRPC + console) |
| go-rag stop | Stop the running daemon |
| go-rag mcp | stdio→HTTP proxy, bridges Claude Desktop to the daemon |
| go-rag status | Daemon + database statistics and health |
| go-rag health | Probe the running daemon's health endpoint |
| go-rag upgrade | Upgrade the binary to the latest release |
| go-rag files | List ingested file paths |
| go-rag dirs | Per-directory file + chunk counts |
| go-rag documents | List documents (cursor + status + pagination) |
| go-rag chunk <id> | Fetch a single chunk by content-addressed ID |
| go-rag audit | Read the structured audit log |
| go-rag vault … | create / list / delete / clear / clone / export / import |
| go-rag eval | Measure recall@k, MRR, NDCG@k on a golden dataset |
| go-rag poison … | list / release / reset injection-flagged chunks |
| go-rag migrate | Re-embed documents to the current model |
| go-rag auth … | Manage API keys, sessions, the admin user |
| go-rag config [get|set] | View or change configuration |
The daemon owns the database and serves 30 MCP tools over HTTP. They cover the full surface — query and status, ingest and maintenance, document/chunk inspection, injection-poisoning triage, vaults, retrieval-quality eval, and admin auth — so an agent can run the whole system without shelling out.
{
"mcpServers": {
"go-rag": {
"command": "/abs/path/to/go-rag",
"args": ["mcp", "--vault", "cyber-notes"]
}
}
}
go-rag mcp is a stdio→HTTP proxy that bridges a stdio MCP client (Claude Desktop) to your running daemon. Start the daemon with go-rag start first.
go-rag ships a built-in retrieval evaluator so you can score recall@k, precision@k, MRR, and NDCG@k over your own golden dataset — offline, reproducible, no Ollama required.
Run it on the bundled golden corpus, or point it at your own:
go-rag eval --benchmark scifact # recall@k, MRR, NDCG@k
go-rag eval-gen # emit candidate query→chunk pairs for triage
The eval harness is the same one used to regression-test retrieval changes in CI — what you measure is what shipped.
A management console, container deployment, isolated vaults, alternative embeddings and enrichment, and a MuninnDB memory bridge — all opt-in, all local-first. For the full references, see the docs.
A single-operator web UI — the fourth loopback transport at 127.0.0.1:7881, Bearer-guarded. Browse and inspect documents, run queries with the full retrieval controls, triage injection-poisoned chunks, manage vaults, and read live observability — all from the browser. It starts with the daemon.
go-rag start # console at http://127.0.0.1:7881
A multi-arch distroless image (linux/amd64 + linux/arm64), built on every release. The container runs the foreground daemon against a named volume; map the port to host loopback to keep the loopback-only posture.
docker pull ghcr.io/madeinoz67/go-rag docker run -d --name go-rag \ -p 127.0.0.1:7878:7878 \ -v go-rag-data:/data \ ghcr.io/madeinoz67/go-rag
Multiple vaults in one Pebble store — each with its own config, embeddings, and indexes, isolated by key-space prefixes. One daemon serves them all; --vault targets a specific one per command. Clone, export, and import for backup or migration.
go-rag vault create work go-rag --vault work add ./work-docs/ go-rag --vault work query "release process"
A bundled pure-Go embedder works offline from the first run; point go-rag at a local Ollama when you want a different model. An embedding-drift monitor pins the profile a corpus was built under and fails loudly if it changes. Opt-in background enrichment (local model) writes auto-tags and per-document summaries to a sidecar — and the tags flow straight into the --tags filter.
go-rag model install # fetch + verify the bundled model go-rag enrich # back-fill tags + summaries (opt-in)
Promote chunks into long-term memory — go-rag chunks become content-addressed engrams in a local MuninnDB vault, auto-backfilled when you enable it. It's opt-in, loopback-only, and never blocks a core operation; if MuninnDB is down, go-rag carries on unaffected.
export GORAG_BRIDGE_TOKEN=… go-rag bridge muninn init go-rag bridge muninn status
go-rag never silently exposes your document vault to the network. Every transport binds to 127.0.0.1 — reaching further requires an explicit, logged opt-in. Single-operator auth (API keys, admin user, sessions) is there when you need it.