knowledge-rag

The MCP-first local RAG server for Claude Code, Cursor, and every AI agent.

Hybrid search · Cross-encoder reranking · 35 file formats · 100% local · Zero cloud · Enterprise-grade plumbing built-in.

pip install knowledge-rag   →   restart Claude Code   →   search_knowledge("your query")

Quick Start · Why knowledge-rag · Compare · Enterprise Features · Docs

⭐ Star History

Chart updated daily by GitHub Action

🎯 Why knowledge-rag

Most RAG frameworks fall into one of three traps: (1) they require you to ship your data to a cloud API, (2) they hand you 300 building blocks and 0 opinionated defaults, or (3) they bundle RAG as a 5% feature of a much bigger platform you didn't ask for.

knowledge-rag does one thing well: it is the MCP-native local RAG server that Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI and Zed can search out of the box — with enterprise plumbing (bearer auth, Prometheus metrics, rate limiting, health probes, structured JSON logging, zero-downtime reindex) that no other RAG-focused OSS ships built-in.

🔒 100% local, 0% cloud

Your files never leave the machine. No vendor lock-in, no data-residency headache, no forced cloud dependency. LGPD / GDPR / HIPAA compliant by architecture — because there is nothing to comply about when nothing leaves.

🚀 Zero-friction setup

pip install knowledge-rag → restart your MCP client → done. No Docker mandatory. No Ollama required. No separate embedding server. Everything runs in-process via FastEmbed ONNX. Works offline after the first model download.

🛡️ Production-grade OSS

7-pillar quality gate on every PR (35+ automated checks), 9-cell OS×Python CI matrix (Linux + Windows + macOS × 3.11/3.12/3.13), nightly chaos + 50K-iteration soak + mutation testing. 700+ tests. 0 known regressions.

💰 Zero ongoing cost

No token bills. No SaaS tier. No paid features hidden behind a wall. MIT license, forever. Runs on the laptop you already have — GPU optional, CPU works fine with FastEmbed ONNX.

📊 How knowledge-rag compares to other RAG frameworks

We audited 16 popular RAG frameworks and platforms (LlamaIndex, LangChain, ChromaDB, Weaviate, Qdrant, RAGFlow, LightRAG, DSPy, GraphRAG, Haystack, RAG-Anything, kotaemon, txtai, llmware, Dify, open-webui, FastGPT) so you can pick honestly.

Legend: ✅ built-in · 🟡 plugin / paid tier / partial · ❌ not available · ⚠️ license or default concern

The 5 dimensions where knowledge-rag is unique: health probes + JSON logging + Prometheus + rate limit + bearer auth simultaneously built-in on an OSS RAG-focused MCP server. Zero-downtime reindex + async background reindex + nightly chaos/soak/mutation are documented on nobody else's README.

🚀 Quick Start (3 minutes, from zero to your first query)

Pick your integration path — knowledge-rag ships the same server through every channel.

Path 1 — Claude Code, Cursor, Windsurf, Cline, VS Code, Gemini CLI, Zed (MCP)

pip install knowledge-rag
knowledge-rag init                    # scaffolds config.yaml + documents/

Drop your PDFs, markdown, code files into documents/. Restart your MCP client. Ask it:

search_knowledge("your query")

That's it. First query loads the ONNX embedding model (~200MB, one-off download). Subsequent queries are cached and hit sub-second latency.

Path 2 — HTTP / SSE server (multi-user, air-gapped, load-balanced)

# config.yaml
server:
  transport: "sse"                    # or "streamable-http"
  host: "0.0.0.0"
  port: 8179
  auth:
    bearer_token: "your-secret-token"
  rate_limit:
    enabled: true
    requests_per_minute: 60
  metrics:
    enabled: true
    port: 9179
  logging:
    format: "json"                    # ELK / Loki / Datadog / CloudWatch ready

knowledge-rag --transport sse

• Health probe: curl http://your-host:8179/health → 200 + JSON payload
• Prometheus scrape: http://your-host:9179/metrics
• MCP dispatcher: authenticated via Authorization: Bearer your-secret-token

Path 3 — Docker (models pre-downloaded, air-gapped ready)

docker pull ghcr.io/lyonzin/knowledge-rag:latest
docker run -v $(pwd)/documents:/app/documents -p 8179:8179 ghcr.io/lyonzin/knowledge-rag:latest

Full installation guide with all 5 methods, 8 MCP client configurations, and GPU setup: docs/INSTALLATION.md →

🤖 Ready-to-use skills for AI agents

Installing knowledge-rag gives your agent 13 MCP tools. It does not tell the agent when to use them. That is what the skills/ folder solves — drop-in behavioural skills for Claude Code, Cursor, Windsurf, Cline, Zed, VS Code Copilot that turn "AI with access to RAG" into "AI th