knowledge-rag

Purpose

knowledge-rag is a local RAG (Retrieval-Augmented Generation) server for MCP clients, suitable for Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI, Zed, and others. It enables AI agents to prioritize retrieving from a local knowledge base before answering, turning "an AI that can access RAG" into "an AI that truly uses RAG first." The project emphasizes 100% local operation with zero cloud dependency; embedding generation, indexing, and retrieval are all performed locally.

Main Capabilities

• Hybrid retrieval: semantic vectors + BM25 keyword retrieval, with an optional FTS5 lexical fast path.
• Cross-encoder reranking: uses Xenova/ms-marco-MiniLM-L-6-v2 to score the candidate pool.
• Markdown-aware chunking and query expansion; supports parsing of 35 file formats (the materials also contain the expression "20 format parsers"; the specific number is subject to the repository).
• 13 MCP tools, covering retrieval and knowledge base CRUD operations.
• Query caching: LRU + 5-minute TTL, invalidated on write operations.
• Staged rebuild: builds and validates a new collection without affecting the current collection, with rollback if publishing fails.
• Asynchronous background rebuild, with status polled via get_reindex_status().
• 10 behavioral skills for AI agents (skills/ directory), organized by type, helping agents proactively use RAG.
• Enterprise-grade features: Bearer token authentication, Prometheus /metrics, rate limiting, health probes, structured JSON logging, path traversal and symlink escape protection.

Usage

There are three integration paths, and the server is the same in each channel.

Path 1: MCP clients (Claude Code, Cursor, Windsurf, Cline, VS Code, Gemini CLI, Zed) Place PDFs, Markdown, and code files into the documents/ directory, restart the MCP client, and you can ask questions. The first query loads the approximately 200MB ONNX embedding model (one-time download); subsequent queries use the cache and can achieve sub-second latency.

Installation command: pip install knowledge-rag

There are two shortest paths for installing skills,After installation, restart Claude Code:

• Option 1 (the materials do not provide the specific command)
• Option 2 supports the --project, --only rag-check-first,rag-cite-sources, --dry-run, and --help parameters (the materials do not provide the complete command string).

Path 2: HTTP / SSE server (multi-user, air-gapped, load balancing)

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

Multi-client sharing (Streamable HTTP): when multiple clients share the same index and process, run once in Streamable HTTP mode, and each HTTP client points to the same endpoint. Local MCP clients (Cursor, LM Studio, etc.) can point the remote server URL to http://127.0.0.1:8179/mcp。Claude Custom connector (remote MCP) requests come from Anthropic cloud infrastructure and cannot access local 127.0.0.1; they must be exposed through a public HTTPS endpoint, such as Cloudflare Tunnel, ngrok, or a reverse proxy, pointing to https://your-public-domain/mcp；代理需发送 Host acceptable to the HTTP application; the default loopback configuration is 127.0.0.1:8179, otherwise a 421 Invalid Host header may occur. In Claude (Pro/Max: Customize > Connectors > + Add > Add custom connector; Team/Enterprise: Organization settings > Connectors), enter the public endpoint, and in Request headers set Authorization: Bearer <your-token>, consistent with server.auth.bearer_token in config.yaml. When HTTP transport is enabled, knowledge-rag automatically enables a single-instance lock (KNOWLEDGE_RAG_SINGLE_INSTANCE=1) to prevent multiple servers from binding to the same data directory or port. The default host is 127.0.0.1; if binding to 0.0.0.0 or deploying across networks, you should configure server.auth.bearer_token in config.yaml and terminate TLS via a reverse proxy (Caddy, Nginx), otherwise the server will warn that the HTTP endpoint is unauthenticated.

Path 3: Docker (models pre-downloaded, air-gap ready).

Full installation instructions (5 methods, 8 MCP client configurations, GPU setup): docs/INSTALLATION.md

Applicable scenarios

• Security teams (red team/blue team/CTF): preset cybersecurity.yaml, 8 categories, 200+ routing keywords, 69 query expansions, can index MITRE ATT&CK, threat reports, exploit articles, and incident reports, retrieved via search_knowledge("privilege escalation windows").
• Development teams: preset developer.yaml, 9 categories, 150+ routing keywords, 50+ expansions, indexes architecture documents, ADRs, runbooks, code, API specifications, replacing digging through Confluence.
• Research labs: preset research.yaml, 9 categories, 100+ routing keywords, 40+ expansions, indexes arXiv papers, experiment notes, dataset documentation.
• Enterprise knowledge base (air-gapped, auditable): preset general.yaml, deployed via SSE on a single VM, 40+ users with Bearer authentication, rate limiting, Prometheus monitoring, /health probe integrated with load balancing, JSON logs sent to Datadog.

Limitations and notes

• 100% local means embedding generation, indexing, and retrieval run locally; model downloads and add_from_url require network access, and the configured MCP client will receive the retrieved content.
• The project does not certify regulatory compliance; customers must choose the corpus, client permissions, and network exposure scope themselves.
• The default host is 127.0.0.1; cross-network deployments require configuring authentication and TLS yourself.
• Retrieved content should be treated as untrusted data, and clients must handle it themselves.
• CI coverage does not guarantee zero defects; the audit report records reproducible local workloads and their limitations, and the comparison with the old implementation is not a speed comparison with other RAG frameworks.
• GPU is optional; CPU works fine with FastEmbed ONNX; NVIDIA CUDA embeddings and experimental Windows AMD DirectML are optional, with CPU fallback.
• Specific pricing and billing model information was not provided.