knowledge-rag
A local MCP RAG server that indexes your documents/code and exposes tools to search, retrieve, ingest, maintain, and evaluate the knowledge base.
Search: hybrid semantic + BM25 keyword search with cross-encoder reranking, filters, snippets, score thresholds, and folder/category scoping.
Retrieve: fetch full document content by filepath and find documents similar to an indexed reference file.
Browse: list indexed documents page-by-page and list categories with document counts.
Manage content: add text documents, update or remove documents, and ingest web pages by URL.
Maintain the index: run incremental, forced, full, or resumed reindexing in the background and poll reindex status.
Inspect health: view index stats including document/chunk counts, embedding model, BM25 status, cache hit rate, watcher status, and HNSW recall.
Evaluate quality: measure retrieval quality with MRR@5 and Recall@5 using your own query/expected-file test cases.
knowledge-rag: local RAG server for Claude Code, Cursor and other MCP clients
knowledge-rag is a local retrieval-augmented generation (RAG) server for the Model Context Protocol (MCP). It indexes the documents and code on your machine and gives Claude Code, Cursor, VS Code and other MCP clients 13 tools to search them, using hybrid search (BM25 keywords plus vector similarity) with cross-encoder reranking on by default. Everything runs in one Python process with embedded ChromaDB and FastEmbed ONNX models: no Docker, no database server, no API key. Indexing and search work offline once the models are cached.
11.1 ms median uncached hybrid query on CPU, 6.1 ms on CUDA: 36 queries over 149 chunks on one Windows host, reranker off (audit)
0.03 ms median for a repeated query served from the cache, same workload (audit)
75,016 chunks from 5,889 documents: full rebuild completed in a production reproduction (v4.8.3)
1,500+ tests collected on each of 9 OS × Python CI cells (platform-specific ones skip), 84% line coverage against an 80% floor (CI run, 2026-11-06)
Install and register with Claude Code (needs Python 3.11+ and Node.js 16+):
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-ragPut files in ~/knowledge-rag/documents/ and ask your agent to search them. The folder is created on first start, new and changed files are indexed automatically, and the models (about 150 MB) download the first time they are needed.
Install · Results · How it works · Tools · Skills · Comparison · FAQ · Docs
Star history
Related MCP server: nexus-mcp-ci
Measured results
Measurements from the project's own audits. They come from one host and small corpora, so treat them as orders of magnitude for your planning, not as guarantees.
Measurement | CPU | NVIDIA CUDA |
Hybrid query, uncached, median | 11.13 ms | 6.10 ms |
Hybrid query, uncached, p95 | 13.91 ms | 7.44 ms |
Repeated query (cache hit), median | 0.033 ms | 0.028 ms |
Initial indexing, including first model load | 13.655 s | 0.832 s |
Sampled peak process memory (RSS) | 1,416 MB | 990 MB |
Workload: scripts/audit_retrieval.py indexing 7 public repository documents (149 chunks) into a temporary ChromaDB and FTS5 index; 36 uncached queries; cross-encoder disabled to isolate retrieval; Windows 11, RTX 3080 Ti, Python 3.12.7, FastEmbed 0.8.1, ChromaDB 1.5.9, model BAAI/bge-small-en-v1.5, Hugging Face offline mode. Source: audit 2026-10-03.
Retrieval check | Result | Workload and source |
Expected source in the top 5 | 12 of 12 questions; MRR@5 0.875 (English), 0.792 (Portuguese) | 6 English and 6 Portuguese questions over the same 149 chunks, default English model; a small smoke test, not a general quality claim (audit) |
Cross-encoder rerank of 8 candidates | 141.9 ms first call including model load, 19.7 ms next call (CPU) | One English and one Portuguese query, network blocked (audit) |
Large corpus | Full rebuild completed and filled 75,016 FTS5 rows on the first attempt | 5,889 documents / 75,016 chunks, v4.8.3 reproduction (CHANGELOG) |
BM25 memory: retained Python memory fell from 120.7 MB to 26.9 MB (−77.75%) for 10,000 documents / 1.99 million tokens after the token pool was added in v4.10.0 (audit).
Metrics memory: 100,001 metric observations retained 328 bytes instead of 3,201,024 (audit).
Multilingual model: on a 60-question diagnostic set over a private ~70,000-chunk corpus,
intfloat/multilingual-e5-largefound the expected source for 36 questions against 37 for the defaultBAAI/bge-small-en-v1.5; re-embedding 70,083 chunks on CUDA took 1,186.58 s (audit 2026-10-04).Historical baseline: v4.7.1 microbenchmarks and a 100-document rebuild on CPU (perf-baseline-v4.7.1). The ratios apply to those workloads only.
Live dashboard: the benchmark dashboard tracks CI microbenchmarks. They use mocked storage and models, so they answer a different question than the real-model numbers above.
How it works
Ingest. Files under
documents/are parsed by format: code files get their function, class and import names as metadata, notebooks keep only Markdown and code cells, PDFs contribute their text. Markdown is split at##/###sections; every other format is cut into 1,000-character chunks with 200 characters of overlap. Chunks are de-duplicated by SHA-256, embedded with FastEmbed (defaultBAAI/bge-small-en-v1.5, 384 dimensions) and stored in an embedded ChromaDB.Watch. While the server runs, a watcher re-indexes changed files after 10 seconds without new changes. Full rebuilds fill a staging collection and swap it in after validation, so searches keep using the current index.
Search.
search_knowledgechecks a query cache (100 entries, 5-minute TTL), runs BM25 over an inverted index and vector search, fuses both rankings with weighted reciprocal rank fusion (hybrid_alpha, default 0.3, leaning towards keywords) and reranks the top candidates with theXenova/ms-marco-MiniLM-L-6-v2cross-encoder. With the opt-in FTS5 fast path, identifier-like queries such as CVE IDs, ticket keys and hashes go to SQLite FTS5 first.Answer. Results go back to the MCP client with the file path, chunk index, snippet and scores. The client's model writes the answer; knowledge-rag never calls an LLM.
Serve. Over stdio for one client, or as one Streamable HTTP or SSE server for many. HTTP mode answers health probes first, then checks the bearer token. Every tool call passes through the optional rate limiter and metrics.
config.yamland five presets configure all of it.
flowchart TB
subgraph CLIENTS["MCP clients"]
direction LR
C1[Claude Code]
C2[Claude Desktop]
C3[Cursor]
C4[Windsurf]
C5[VS Code · other stdio or HTTP clients]
end
subgraph TRANSPORT["Transport"]
T1[stdio<br/>1 process per client]
T2[Streamable HTTP / SSE<br/>1 server for N clients]
end
subgraph MIDDLEWARE["ASGI middleware (HTTP transports)"]
M1[HealthMiddleware<br/>/health · /healthz]
M2[BearerAuthMiddleware<br/>constant-time compare]
end
subgraph MCP["13 MCP tools (contract checked in CI)"]
W[Tool wrappers<br/>optional rate limit · metrics]
MT1[search_knowledge]
MT2[get_document · search_similar]
MT3[add_document · add_from_url · update · remove]
MT4[reindex_documents · get_reindex_status]
MT5[list_documents · list_categories · get_index_stats · evaluate_retrieval]
end
subgraph SEARCH["Retrieval pipeline"]
QC[Query cache<br/>LRU 100 · 5-min TTL]
R[Query router<br/>regex, FTS5 fast path only]
F[FTS5 fast path<br/>opt-in lexical retrieval]
H[Hybrid search]
BM[BM25<br/>inverted index]
SE[Vector search<br/>FastEmbed ONNX, lazy-loaded]
RRF[Weighted reciprocal rank fusion]
CE[Cross-encoder rerank<br/>MiniLM-L-6-v2]
end
subgraph STORAGE["Local storage (data_dir)"]
CH[ChromaDB<br/>vectors + metadata<br/>WAL with HTTP transports]
FT[SQLite FTS5<br/>lexical index<br/>WAL + busy timeout]
MD[index_metadata.json<br/>durable state]
end
subgraph INGEST["Document ingestion"]
FS[documents/ folder]
WD[Watcher<br/>10 s debounce]
PA[Format parsers<br/>MD · PDF · DOCX · code · IaC · IPYNB]
CK[Chunker<br/>Markdown sections · 1,000-char windows]
EM[FastEmbed ONNX<br/>default bge-small-en-v1.5, 384-d]
DD[SHA-256 dedup]
SW[Staging rebuild<br/>rollback on handled publication failure]
end
subgraph OBS["Observability (opt-in)"]
PM[Prometheus /metrics<br/>separate port, HTTP transports]
LG[Structured JSON logs]
HC[Health payload<br/>version · uptime · cache stats]
end
subgraph CFG["Configuration"]
YM[config.yaml<br/>+ 5 presets]
end
CLIENTS -->|MCP over stdio| T1
CLIENTS -.->|MCP over HTTP| T2
T1 --> W
T2 --> M1 --> M2 --> W
W --> MT1 & MT2 & MT3 & MT4 & MT5
MT1 --> QC
QC -->|cache miss| R
R -->|identifier-like| F
R -->|everything else| H
H --> BM
H --> SE
F --> FT
BM --> CH
SE --> CH
BM --> RRF
SE --> RRF
RRF --> CE
CE --> QC
MT2 --> CH
MT3 --> INGEST
MT4 --> SW
MT5 --> CH
FS --> WD --> PA
PA --> CK --> DD --> EM --> CH
SW -.->|validated swap| CH
SW -.-> FT
CH -.-> MD
W -.->|instrumented| PM
W -.->|logs| LG
M1 --> HC
YM -.-> SEARCH
YM -.-> STORAGE
YM -.-> OBS
YM -.-> MIDDLEWARE
classDef client fill:#3776AB,stroke:#1e5a8a,color:#fff
classDef transport fill:#00A67E,stroke:#006e54,color:#fff
classDef middleware fill:#6b46c1,stroke:#4c1d95,color:#fff
classDef storage fill:#4b5563,stroke:#1f2937,color:#fff
classDef obs fill:#dc2626,stroke:#7f1d1d,color:#fff
classDef ingest fill:#b45309,stroke:#78350f,color:#fff
class C1,C2,C3,C4,C5 client
class T1,T2 transport
class M1,M2 middleware
class CH,FT,MD storage
class PM,LG,HC obs
class FS,WD,PA,CK,EM,DD,SW ingestComponent ownership, memory and concurrency boundaries and the hybrid_alpha weights: docs/ARCHITECTURE.md.
Install
Every path below runs the same server. Each claude mcp add sets KNOWLEDGE_RAG_DIR, the folder that holds config.yaml, documents/, data/ and models_cache/. Without it, the server picks a folder from its install location and the working directory the client starts it in, which can be a project you did not intend (config.py).
Claude Code with the npx launcher
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-ragThe npm package is a launcher. It finds Python 3.11+ (python3/python, or python/py -3 on Windows), creates a virtual environment in ~/.knowledge-rag/venv, installs the matching knowledge-rag version from PyPI and starts the server over stdio. --install-only does the installation once ahead of time, so the client's first start does not wait for pip. A new npm version reinstalls the package on the next start. If a client on native Windows fails to start npx, register cmd /c npx -y knowledge-rag instead.
pip in a virtual environment
python3 -m venv ~/knowledge-rag/venv
~/knowledge-rag/venv/bin/python -m pip install knowledge-rag
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag \
-- ~/knowledge-rag/venv/bin/python -m mcp_server.serverOn Windows (PowerShell), use python and $HOME\knowledge-rag\venv\Scripts\python.exe in place of python3 and ~/knowledge-rag/venv/bin/python.
Optional: knowledge-rag init, run inside ~/knowledge-rag with the virtual environment active, copies config.example.yaml and the five presets and creates documents/. It does not create config.yaml or register the server: copy the template or a preset to config.yaml yourself. Without a config.yaml, the defaults apply, including all 33 default file types.
Docker
The image is published for linux/amd64 and linux/arm64. For stdio, the client starts one container per session:
claude mcp add knowledge-rag -s user -- docker run -i --rm \
-v ~/knowledge-rag/documents:/app/documents \
-v ~/knowledge-rag/data:/app/data \
-v knowledge-rag-models:/app/models_cache \
ghcr.io/lyonzin/knowledge-rag:latestThe image runs python -m mcp_server.server, which reads /app/config.yaml and defaults to stdio on 127.0.0.1. To serve HTTP from a container, mount a config that listens on all container interfaces and pass --transport:
mkdir -p ~/knowledge-rag
cat > ~/knowledge-rag/config.yaml <<'EOF'
server:
host: "0.0.0.0"
auth:
bearer_token: "replace-with-a-long-random-token"
EOF
docker run -d --name knowledge-rag -p 127.0.0.1:8179:8179 \
-v ~/knowledge-rag/config.yaml:/app/config.yaml:ro \
-v ~/knowledge-rag/documents:/app/documents \
-v ~/knowledge-rag/data:/app/data \
-v knowledge-rag-models:/app/models_cache \
ghcr.io/lyonzin/knowledge-rag:latest --transport streamable-http
curl http://127.0.0.1:8179/health
claude mcp add --transport http knowledge-rag http://127.0.0.1:8179/mcp \
# if server.auth.bearer_token is set, add the token as a Bearer auth headerThe image builds its model copies into FastEmbed's default cache, but the server reads /app/models_cache, so the models download again the first time they are needed. The knowledge-rag-models volume keeps them across containers.
Shared HTTP server for several clients
stdio fits one client that owns one process. For several clients on one index (Claude Code, Cursor, LM Studio, more terminals), run one Streamable HTTP server and point every client at it (#217, #223):
# ~/knowledge-rag/config.yaml
server:
transport: "streamable-http" # "sse" for clients that only speak SSE
host: "127.0.0.1"
port: 8179
auth:
bearer_token: "replace-with-a-long-random-token"
rate_limit:
enabled: true
requests_per_minute: 60
burst: 10
metrics:
enabled: true
port: 9179 # binds 0.0.0.0 with no auth: firewall it
logging:
format: "json"KNOWLEDGE_RAG_DIR=~/knowledge-rag knowledge-rag # run from the venv where you installed it
curl http://127.0.0.1:8179/health # {"status":"ok","version":"5.0.0",...}
claude mcp add --transport http knowledge-rag http://127.0.0.1:8179/mcp \
# if server.auth.bearer_token is set, add the token as a Bearer auth headerTransport | Clients per server process | Who runs the process | Use it for |
| 1 | The MCP client, per session | One client; models load in each process on first use |
| Many | You, one background server | Several clients sharing one index and one model load (preferred) |
| Many | You, one background server | HTTP clients that only support SSE |
HTTP transports switch on the single-instance lock (KNOWLEDGE_RAG_SINGLE_INSTANCE=1), so a second server cannot open the same data directory. The default host is 127.0.0.1. If you bind to 0.0.0.0 or serve a network, set server.auth.bearer_token and put TLS in front with a reverse proxy such as Caddy or Nginx; without a token, the server prints a warning that the endpoint is unauthenticated.
Network requirement: custom connector requests come from Anthropic's cloud on web, desktop and mobile, so they cannot reach
127.0.0.1. Expose the server through a secure public HTTPS endpoint (for example Cloudflare Tunnel, ngrok or a reverse proxy) athttps://your-public-domain/mcp. Configure the proxy to send an upstreamHostthat the HTTP app accepts forserver.host(with the default loopback configuration,127.0.0.1:8179); forwarding the public hostname unchanged can produce421 Invalid Host header. Keep bearer authentication and HTTPS on. A localclaude_desktop_config.jsonusescommand/argsfor local stdio processes and does not support remote HTTP endpoints.Setup and auth: in Claude (Pro/Max: Customize > Connectors > + Add > Add custom connector; Team/Enterprise owners: Organization settings > Connectors), enter the public endpoint. Under Request headers, set
AuthorizationtoBearer <your-token>, matchingserver.auth.bearer_tokeninconfig.yaml. See Anthropic's custom connectors guide.
Other MCP clients
Any client that starts a stdio MCP server from a command, or connects to a Streamable HTTP endpoint, can use knowledge-rag. The installation guide has the exact JSON for each of these:
Client | Where the server entry goes |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Antigravity |
|
VS Code (Copilot) |
|
opencode |
|
{
"mcpServers": {
"knowledge-rag": {
"command": "npx",
"args": ["-y", "knowledge-rag"],
"env": { "KNOWLEDGE_RAG_DIR": "~/knowledge-rag" }
}
}
}One writer per data directory. Over stdio, each MCP client starts and owns its own knowledge-rag process. Do not run a second writer against the same data_dir while that client is open: on Windows, two writers corrupted the ChromaDB HNSW segment (#216). Add "KNOWLEDGE_RAG_SINGLE_INSTANCE": "1" to the client's env block as a safety net, or share one HTTP server. Running CLI commands safely: docs/single-instance.md.
Keep data_dir out of cloud-sync folders. OneDrive (including OneDrive - <tenant>), iCloud Drive, Dropbox, Google Drive, Box, pCloud, MEGAsync, Nextcloud/ownCloud and Sync hold handles on the live index while they upload it. That races with ChromaDB's HNSW memory maps and SQLite WAL writes and can crash the process (0xC0000005 on Windows, SIGBUS elsewhere); startup auto-repair then moves the index to data/backups/auto-repair-* and you reindex from scratch. Since v4.11.0, startup stops with exit code 78 (EX_CONFIG) when data_dir resolves under one of these providers. Use a local path such as %LOCALAPPDATA%\knowledge-rag\data on Windows or ~/.local/share/knowledge-rag/data on Linux and macOS, or set paths.allow_cloud_sync: true to accept the risk.
All install methods, GPU setup and troubleshooting for each client: docs/INSTALLATION.md.
The 13 MCP tools
Tool | What it does |
| Hybrid BM25 + vector search with cross-encoder reranking; filters by category, folders ( |
| Returns the full content of one indexed file |
| Finds documents similar to an indexed file |
| Reports MRR@5 and Recall@5 for your own query → expected file pairs |
| Lists indexed documents, 100 per page by default (up to 200 with |
| Lists categories, derived from folder paths, with document counts |
| Document and chunk counts, embedding model, BM25 status, cache hit rate, watcher status, HNSW self-recall probe |
| Saves text as a file under |
| Replaces a document's content and re-indexes it |
| Removes a document's chunks from the index, and optionally the file |
| Fetches an http(s) page, strips the HTML, saves it as Markdown with a provenance marker and indexes it |
| Incremental by default; |
| Reports the progress of a background reindex |
Each result carries source (the file path), chunk_index and, in snippet mode, match_offset (a character offset into the content), so citations point to a file and chunk, not a line number. score is normalized per query, so the top result is always 1.0 and min_score filters relative to the other results; compare reranker_score, the raw cross-encoder score, across queries. Parameters, return shapes and examples: docs/API.md.
Agent skills
The 13 tools tell an agent what it can do; they do not tell it when to search. The skills/ folder adds ten MIT-licensed skills for Claude Code that make the agent check your index first, cite what it used and keep the index current. Other agents can use the same instructions as rules or system prompts (skills/README.md).
Skill | Kind | What it changes |
Foundation | Searches the corpus before answering technical questions | |
Foundation | Cites the source file and chunk for every claim taken from the corpus | |
Foundation | Probes what is indexed at the start of a session | |
Workflow | Search, read the best document in full, then find similar ones | |
Workflow | Goes to the web only when the local corpus comes back empty or insufficient | |
Workflow | Looks up prior fixes and runbooks before debugging an error | |
Workflow | Checks ADRs, standards and similar files before commenting on a change | |
Maintenance | Indexes decisions and fixes back into the corpus | |
Maintenance | Measures MRR@5 and Recall@5 after ingestion or configuration changes | |
Domain | Consults MITRE ATT&CK, CVE and runbook notes first on security tasks |
Each skill installs as ~/.claude/skills/<skill-name>/SKILL.md (or .claude/skills/<skill-name>/SKILL.md for one project):
# Node.js 22.20+: choose the skills and agents interactively; -g installs for all projects
npx skills add lyonzin/knowledge-rag -g
# Without Node (Linux, macOS, WSL, Git Bash): all ten skills into ~/.claude/skills
curl -fsSL https://raw.githubusercontent.com/lyonzin/knowledge-rag/master/skills/install.sh | bashinstall.sh also takes --project, --target <path>, --only rag-check-first,rag-cite-sources, --dry-run, --list and --help. Restart Claude Code after installing. Skill chains and per-client setup: skills/CATALOG.md, skills/README.md.
How knowledge-rag compares to other RAG projects
As of 2026-11-06. 🗸 default: built in and on by default. 🗸 opt-in: built in, off until you enable it. 🗸: available, default state not compared. component: a library piece you assemble yourself. ✗: not built in, meaning absent from the code, needing an external provider (local embeddings column), or not found in code or docs; ✗ manual: you start it yourself. Words in parentheses name the mechanism.
Project (stars, license) | MCP server | MCP client | Hybrid | Rerank | Auto re-index | Local emb. |
knowledge-rag (301, MIT) | 🗸 13 tools | ✗ | 🗸 default (+FTS5 opt-in) | 🗸 default | 🗸 default | 🗸 |
Dify (160.5k, Dify license) | 🗸 | 🗸 | 🗸 | 🗸 opt-in | ✗ manual sync | ✗ |
Open WebUI (157.9k, Open WebUI license) | ✗ | 🗸 | 🗸 opt-in | 🗸 opt-in | ✗ manual (add-on) | 🗸 |
Langflow (156.4k, MIT) | 🗸 | 🗸 | component | component | component (Schedule Trigger) | component |
LangChain (149.1k, MIT) | ✗ | 🗸 | component | component | component (indexing API) | component |
RAGFlow (93.7k, Apache-2.0) | 🗸 | 🗸 | 🗸 default | 🗸 opt-in | 🗸 connectors | ✗ |
AnythingLLM (68.0k, MIT) | ✗ | 🗸 | ✗ | 🗸 opt-in | 🗸 opt-in (beta, per file, hourly) | 🗸 |
Serviette, ex pathwaycom/llm-app (58.7k, MIT) | ✗ | ✗ | 🗸 opt-in | 🗸 opt-in | 🗸 default | 🗸 |
PrivateGPT (57.6k, Apache-2.0) | ✗ | 🗸 | 🗸 opt-in (Qdrant) | ✗ | 🗸 opt-in (CLI --watch) | ✗ |
LlamaIndex (52.8k, MIT) | ✗ | 🗸 | component | component | component (refresh_ref_docs) | ✗ |
LightRAG (40.6k, MIT) | ✗ | ✗ | ✗ | 🗸 opt-in (API) | ✗ manual scan | ✗ |
Quivr 2 (39.6k, MIT) | 🗸 | ✗ | 🗸 | 🗸 opt-in (paid service) | 🗸 scheduled feeds | 🗸 |
Khoj (38.0k, AGPL-3.0) | ✗ | 🗸 | ✗ | 🗸 opt-in | 🗸 via clients, every 10 min | 🗸 |
GraphRAG (36.6k, MIT) | ✗ | ✗ | ✗ | ✗ | ✗ manual (graphrag update) | ✗ |
Onyx (33.3k, MIT CE + EE) | 🗸 | 🗸 | 🗸 default | ✗ removed in 2026 | 🗸 connectors | 🗸 |
FastGPT (30,000, FastGPT license) | 🗸 | 🗸 | 🗸 | 🗸 with a rerank model | 🗸 opt-in (daily sync) | ✗ |
Project | Type | Needs for first answer | Formats |
knowledge-rag | MCP server | pip + MCP client | 33 (+2 opt-in), code/IaC; no OCR |
Dify | platform | Docker (Postgres, Redis, Weaviate…) + model | PDF, Office, CSV, MD, HTML, EML, EPUB |
Open WebUI | chat app | pip/Docker + Ollama/API | PDF, Office, EPUB, CSV, HTML, MD |
Langflow | builder | pip/Docker + provider key | TXT, MD, CSV, JSON, HTML, PDF, DOCX… |
LangChain | library | code + provider | loaders |
RAGFlow | engine + UI | Docker (Elasticsearch, MySQL, MinIO, Kvrocks, NATS), 16 GB + model | Office, PDF, scans, web |
AnythingLLM | desktop/Docker app | installer (built-in LLM) | PDF, TXT, DOCX… |
Serviette | RAG server | pip + Pathway licence key | text, Office, PDF, scans |
PrivateGPT | API server | LLM + embedding servers | PDF, DOCX, PPT/X, EPUB, IPYNB, images, audio |
LlamaIndex | library | code + OPENAI_API_KEY | ~20 incl. images, MP3/4 |
LightRAG | graph lib + server | LLM + embedding providers | TXT, MD, PDF, DOCX |
Quivr 2 | HTTP engine | Docker (Postgres, object store) | PDF plugin, RSS, mail |
Khoj | app | Docker (pgvector, SearxNG…) + LLM | PDF, MD, Org, Word, Notion |
GraphRAG | library/CLI | OpenAI/Azure key | TXT, CSV, JSON |
Onyx | enterprise app | Docker (~12 containers: OpenSearch, Postgres, Redis…) + LLM | PDF, DOCX, PPTX, XLSX, EML, EPUB, HTML, TXT, MD, JSON, YAML, XML, CSV, SQL, PNG, JPG, WebP |
FastGPT | platform | Docker (MongoDB, PgVector, AI Proxy) + LLM + embedding | TXT, MD, HTML, PDF, Office, CSV |
Notes: Serviette was renamed from pathwaycom/llm-app and inherited its stars. The LlamaIndex README says its focus moved to LlamaParse. Quivr was repurposed as a content-stream search engine. The GraphRAG README says it is in maintenance mode. PrivateGPT's changelog lists a SentenceTransformer reranker (#1810) that the current code no longer contains.
Where knowledge-rag differs. It is the only row with hybrid search and cross-encoder reranking both on by default, and the only MCP server in the table that answers without Docker, a database server or a model key. Auto re-index is on by default only in knowledge-rag and Serviette, and Serviette ships no MCP server; everywhere else it takes a connector, a client, a setting, assembly or a manual run. It is code-first: 23 of its 33 default file types are code or infrastructure files. The license is plain MIT.
Where others are stronger. Multi-user scale: Postgres, OpenSearch and Elasticsearch stacks against one writer on an embedded ChromaDB. Web UIs and visual builders: knowledge-rag has no UI and does not generate answers; the MCP client's LLM does. Connectors, OCR, images and audio, and graph RAG. Evidence and reach: knowledge-rag's published quality check is a 12-question smoke test (Recall@5 1.0) and it has 301 stars. This table compares features, not retrieval quality.
Feature checklists are not benchmarks. Before you choose, measure what your deployment needs on comparable hardware:
Decision | What to verify |
Local or remote processing | Where models run, which client receives content, which features need network access |
Retrieval quality | Expected-source queries on your corpus, including its languages and identifiers |
Performance | Cold start, indexing, uncached queries, memory peaks and concurrent use |
Operations | Authentication, metrics exposure, backups, recovery and who owns the single writer |
Extensibility | Supported parsers, model profiles and the public MCP contract |
Results this project measured against an older version of itself, such as the audit, are not speed comparisons with other RAG projects.
knowledge-rag:
mcp_server/config.py,mcp_server/server.pyDify: github.com/langgenius/dify (
docker/.env.example,api/controllers/mcp/mcp.py,api/core/tools/mcp_tool/provider.py,api/core/rag/extractor/extract_processor.py; re-index:api/services/knowledge/document_sync.pysyncs on request only, andapi/schedule/has no document sync job); indexing methods docsOpen WebUI: github.com/open-webui/open-webui (
backend/open_webui/config.py); github.com/open-webui/docs (docs/features/extensibility/mcp.mdx,docs/features/workspace/knowledge.mdx)Langflow: MCP client docs, quickstart, github.com/langflow-ai/langflow (
src/lfx/src/lfx/utils/schemas.py; hybrid:src/bundles/datastax/src/lfx_datastax/components/datastax/astradb_vectorstore.py; rerank:src/bundles/cohere/src/lfx_cohere/components/cohere/cohere_rerank.py; re-index:src/lfx/src/lfx/components/triggers/schedule_trigger.py)LangChain: MCP docs; github.com/langchain-ai/langchain (
libs/langchain/langchain_classic/retrievers/ensemble.py,document_compressors/cross_encoder_rerank.py; re-index:libs/core/langchain_core/indexing/api.py)RAGFlow: github.com/infiniflow/ragflow (README,
docs/develop/mcp/overview.md,docs/guides/dataset/retrieval_testing.md,docker/.env)AnythingLLM: github.com/Mintplex-Labs/anything-llm (README,
frontend/src/pages/WorkspaceSettings/VectorDatabase/VectorSearchMode/index.jsx); anythingllm-docspages/beta-preview/active-features/live-document-sync.mdxServiette: github.com/pathwaycom/serviette
PrivateGPT: github.com/zylon-ai/private-gpt (README,
fern/docs/pages/api-guide/ingestion.mdx; hybrid:settings.yaml,qdrant.hybrid_search: false; rerank:CHANGELOG.md(#1810), with no reranker in the current code)LlamaIndex: starter example; github.com/run-llama/llama_index (
llama-index-core/llama_index/core/readers/file/base.py;module_guides/mcp/llamaindex_mcp.md; re-index:llama-index-core/llama_index/core/indices/base.py)LightRAG: github.com/HKUDS/LightRAG (
docs/LightRAG-API-Server.md,lightrag/parser/registry.py)Quivr: github.com/The-Vibe-Company/quivr (README,
docs-site/run-quivr/rerank-with-jev.mdx; local embeddings:deploy/cpu/embedding_server.py,docs-site/run-quivr/choose-an-embedding-model.mdx)Khoj: github.com/khoj-ai/khoj (
docker-compose.yml,src/khoj/database/models/__init__.py,src/khoj/search_type/text_search.py,src/khoj/processor/tools/mcp.py,src/interface/desktop/main.js)GraphRAG: github.com/microsoft/graphrag (README,
docs/get_started.md; re-index:pyproject.toml(graphrag update),docs/config/yaml.md(update_output_storage))Onyx: github.com/onyx-dot-app/onyx (README,
deployment/docker_compose/docker-compose.yml,backend/shared_configs/configs.py,backend/onyx/configs/chat_configs.py,backend/alembic/versions/78ebc66946a0_remove_reranking_from_search_settings.py; formats:backend/onyx/file_processing/file_types.py)FastGPT: github.com/labring/FastGPT (re-index:
packages/service/core/dataset/datasetSync/index.ts,packages/web/i18n/en/dataset.json), Docker deployment docs
Built for production
Each capability says whether it is on by default and links to the test, document or release note that backs it. Opt-in features do nothing until you set their key in config.yaml or the environment variable shown.
Security
Capability | Default | Enable / tune | Proof |
Listens on loopback only | On |
| |
Bearer token on HTTP transports | Opt-in |
| |
Client paths kept inside | On | — | |
Fence on fetched web content | On | — | |
Rate limit, one window per process | Opt-in |
| |
Refuses a cloud-synced | On |
| |
Bandit, Semgrep, pip-audit, Gitleaks, dependency review, Socket | Every PR | — | |
CodeQL | Master and weekly | — | |
PyPI Trusted Publishing, npm provenance | Every release | — | |
OpenSSF Best Practices | Passing | — |
Observability
Capability | Default | Enable / tune | Proof |
| On (HTTP) | — | |
Prometheus metrics on a separate port | Opt-in (HTTP) |
| |
Structured JSON logs | Opt-in |
| |
Public benchmark dashboard | Every push to master | — |
Scale and performance
Capability | Default | Enable / tune | Proof |
One HTTP server for many clients | Opt-in |
| |
ChromaDB WAL journal | Auto (HTTP) | — | |
BM25 over an inverted index | On | — | |
Cross-encoder rerank, fused-order fallback | On |
| |
FTS5 fast path for identifiers | Opt-in |
| |
NVIDIA CUDA with CPU fallback | Auto |
| |
Windows AMD DirectML, experimental | Opt-in |
| |
Embedding batch size per provider | Auto |
| |
Query cache, cleared on writes | On | — | |
Background reindex with progress | On | — | |
Staging rebuild while the index serves | On | — |
Reliability
Capability | Default | Enable / tune | Proof |
Single-instance lock | Auto (HTTP) |
| |
Startup probe, auto-repair, 3 backups kept | On | — | |
Index kept if | On | — | |
File watcher, 10 s quiet period | On |
| |
Rollback on handled publication failures | On | — | |
1,500+ tests on 9 OS × Python cells, 80% floor | Every PR | — | |
MCP tool contract and API surface vs master | Every PR | — | |
Legacy configs and call shapes | Every PR | — | |
Performance gate, 10% | Every PR | — | |
Chaos tests, 3 failure scenarios | Nightly | — | |
50,000-call soak, stub embeddings | Nightly | — | |
Mutation testing of lock and preflight | Nightly | — | |
Full suite three times for flaky tests | Nightly | — |
Compliance: the project holds no LGPD, GDPR or HIPAA certification. Local indexing can help with data-locality requirements, but the MCP client sends the results it retrieves to its own model provider as part of the conversation.
Bearer token: compared in constant time (
hmac.compare_digest). A missing or wrong token gets401withWWW-Authenticate: Bearer realm="knowledge-rag". Health probes answer without it. stdio has no token: the client owns the process. There is no built-in TLS, so put a reverse proxy (Caddy, Nginx) in front of anything that leaves loopback.Rate limit: one sliding window for the whole process, shared by every client:
requests_per_minuteplusburst(defaults 60 and 10) calls per 60 seconds. It is not per client.Metrics: only with HTTP transports, on
server.metrics.port(default 9179). The endpoint binds0.0.0.0with no authentication, so firewall it. It exposes per-tool calls, errors and durations plus FTS5 fast-path counters.Paths: the six tools that accept a path resolve it inside
documents_dirand reject traversal, escaping symlinks, NUL bytes and NTFS alternate data streams (CWE-22, CWE-59).Fetched content:
add_from_urlneutralizes known model control tokens and stores a provenance marker with the page. That limits prompt injection; it does not prevent it, so treat retrieved text as untrusted (SECURITY.md). The tool fetches whatever http(s) URL it receives, private network addresses included, and follows redirects; on a shared server, decide who may call it.Network use: the first model download contacts Hugging Face; set
HF_HUB_OFFLINE=1once the models are cached.Health payload:
GET /healthreturnsstatus,version,uptime_secondsand query-cache statistics on the MCP port.Single instance: HTTP transports turn the lock on automatically; for stdio clients, add
KNOWLEDGE_RAG_SINGLE_INSTANCE=1to the client'senvblock. A second process on the samedata_dirthen exits with code 75.Index safety: a full rebuild fills a staging collection and swaps it in after validation; handled failures roll back. Startup retries a failing probe 3 times before moving the index to
data/backups/auto-repair-*, keeping the 3 newest. Recovery steps: docs/reindex-operations.md.Dependencies:
requirements.txtandpyproject.tomldeclare version ranges, not pins. For a reproducible deployment, resolve once and record the tested environment.CI gates: every pull request runs 34 GitHub Actions checks. The performance gate fails a benchmark only when every branch run is more than 10% slower than every master run. Nightly jobs open issues instead of blocking merges; mutation testing is exploratory and never fails the run.
Disclosure: private security advisories, acknowledged within 48 hours, initial assessment within 5 business days, 90-day coordinated disclosure (SECURITY.md).
Configuration in 30 seconds
knowledge-rag init # copies config.example.yaml, the presets and an empty documents/
cp presets/general.yaml config.yaml # or cybersecurity, developer, research, multilingual
# drop your files into documents/, restart, ask the agentSettings live in config.yaml inside KNOWLEDGE_RAG_DIR. Every key is optional; these are the defaults:
paths:
documents_dir: "./documents"
data_dir: "./data" # local disk only, see the cloud-sync warning
models_cache_dir: "./models_cache"
documents:
chunking:
chunk_size: 1000
chunk_overlap: 200
models:
embedding:
profile: "custom" # "compact" | "quality" | "multilingual" | "custom"
model: "BAAI/bge-small-en-v1.5" # used when profile is "custom"
dimensions: 384
gpu: "auto" # "auto" | "true" | "false" | "directml"
reranker:
enabled: true
model: "Xenova/ms-marco-MiniLM-L-6-v2"
search:
default_results: 5
max_results: 100
lexical_fast_path:
enabled: false # SQLite FTS5 for identifier-like queries
server:
transport: "stdio" # "stdio" | "streamable-http" | "sse"
host: "127.0.0.1"
port: 8179Profile | Embedding model | Dimensions |
|
| 384 |
|
| 1024 |
|
| 1024 |
|
|
|
Changing the embedding model or its prefixes needs a full reindex. GPU: auto tries NVIDIA CUDA on the first embedding and falls back to CPU; the [gpu] extra targets CUDA 12. directml is the experimental Windows AMD mode and needs models.embedding.device_id (GPU setup).
Presets are complete config.yaml files (knowledge-rag init copies them):
Preset | For | Categories | Routing keywords | Query expansions | File types enabled |
Red and blue team, CTF, threat hunting, incident response | 8 | 128 | 69 | 14 | |
Design docs, ADRs, runbooks, APIs, code | 9 | 137 | 64 | 16 | |
Papers, lab notebooks, datasets | 9 | 80 | 40 | 8 | |
Anything else: no categories, routing or expansions | 0 | 0 | 0 | 4 | |
Non-English corpora, | 0 | 0 | 0 | 4 |
The presets list their own documents.supported_formats, so they index fewer file types than the defaults: general and multilingual index only .md, .txt, .pdf and .docx. Every field, every default and tuning recipes: docs/CONFIGURATION.md.
35 file formats
Without a config.yaml, 33 file types are indexed. The MetaTrader extensions .mq4 and .mqh are opt-in. The shipped config.example.yaml enables 29 (it leaves out .xlsx, .pptx, .ipynb and .csv), and each preset enables its own list. Chunking is fixed-size (1,000 characters, 200 overlap) for every format except Markdown.
Format | Match | How it is parsed | Default |
Markdown |
| Splits at | Yes |
Plain text |
| Fixed-size chunks | Yes |
| PyMuPDF text extraction, or an explicit page-marked UTF-8 extraction (below); no OCR | Yes | |
Word |
| python-docx, headings kept as Markdown | Yes |
Excel |
| openpyxl, sheet by sheet | Yes |
PowerPoint |
| python-pptx, slide by slide | Yes |
Jupyter Notebook |
| Markdown and code cells only; outputs and base64 skipped | Yes |
JSON |
| Structure-aware, flattened key-value text | Yes |
CSV |
| Header and rows as text | Yes |
XML |
| Root element and namespace metadata | Yes |
Python |
| Function and class names as metadata | Yes |
C |
| Functions, structs and includes as metadata | Yes |
C/C++ header |
| Function declarations and structs as metadata | Yes |
C++ |
| Classes, structs and includes as metadata | Yes |
JavaScript |
| Functions, classes and imports (ESM and CJS) as metadata | Yes |
React JSX |
| Same as JavaScript | Yes |
TypeScript |
| Functions, classes, interfaces, enums and imports as metadata | Yes |
React TSX |
| Same as TypeScript | Yes |
Go |
| Functions, structs and imports as metadata | Yes |
Rust |
| Functions, structs, enums, traits and | Yes |
Kotlin |
| Functions (including class members) and classes as metadata | Yes |
YAML |
| Kubernetes | Yes |
YAML |
| Same as | Yes |
HuJSON |
| JSON with comments and trailing commas (for example Tailscale ACLs) | Yes |
CUE |
| Package and imports as metadata | Yes |
Protocol Buffers |
| Services, messages and RPCs as metadata | Yes |
Rego |
| OPA policies: package and imports as metadata | Yes |
SQL |
| Table names and statement types as metadata | Yes |
Shell |
| Function names as metadata | Yes |
jq |
| Indexed as a shell-style script | Yes |
Dockerfile |
| Plain text, matched by exact file name | Yes |
Makefile |
| Plain text, matched by exact file name | Yes |
Tiltfile |
| Starlark: | Yes |
MQL4 source |
| Code parser | Opt-in |
MQL4 header |
| Code parser | Opt-in |
A file with a .pdf extension can also hold an explicit text extraction: the first line must be [Page N] with a positive page number, followed by non-empty UTF-8 text. An optional UTF-8 BOM and tab/CR/LF whitespace are accepted. Recognition is limited to 4 MiB, rejects other C0/C1 control characters and DEL, and never treats a file with PDF magic bytes in its first 1 KiB as text. Accepted extractions keep their source path and are marked content_format=extracted_text and page_count_source=markers; the marker count does not prove the original PDF's page count. Binary PDFs keep the native parser and its error messages, and invalid or oversized text lookalikes remain errors.
To enable an opt-in format, list it in documents.supported_formats. The list replaces the default, so include every type you want:
documents:
supported_formats: [".md", ".pdf", ".mq4", ".mqh"]Per-format notes: docs/CONFIGURATION.md.
FAQ
Indexing, embeddings and search run on your machine. Three things use the network: the first model download from Hugging Face, add_from_url when you call it, and your MCP client, which sends the results it retrieves to its model provider as part of the conversation.
Yes, once the models are in models_cache/. Start it once with network access, or copy a populated models_cache/ from another machine, then set HF_HUB_OFFLINE=1. The audit measurements above ran in that mode.
Those are building blocks you assemble in code. knowledge-rag is a finished MCP server: hybrid search, reranking and folder watching behind 13 tools, configured with a YAML file. See the comparison.
No. CPU is the default and the fallback. NVIDIA CUDA speeds up embedding (13.7 s against 0.8 s for the first indexing in the audit workload); on Windows, AMD GPUs can opt into experimental DirectML. See docs/gpu-setup.md.
Not while the server runs: the watcher picks up changes after 10 seconds without new ones. Changes made while it was stopped are indexed by the next change or by calling reindex_documents() with no arguments.
Yes. Run one Streamable HTTP server and point every client at it. Do not run two writers against the same data_dir.
The default model is English-trained, yet it found the expected source for all 6 Portuguese test questions (MRR@5 0.792) in the audit. The multilingual profile uses intfloat/multilingual-e5-large; on the 60-question diagnostic it found 36 expected sources against 37 for the default, so measure on your own corpus before switching.
Call evaluate_retrieval with your own pairs of query and expected file; it returns MRR@5, Recall@5 and per-query hits. Use reranker_score, not score, to compare results across queries, because score is rescaled so that each query's top result is 1.0.
Any client that can start a stdio MCP server from a command, or connect to a Streamable HTTP endpoint, can use it. The repository has written setup for Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity, VS Code and opencode.
Documentation
Document | Contents |
Install methods (npx, installer, pip, source, Docker, SSE/HTTP), client configurations, GPU acceleration | |
All 13 MCP tools: parameters, return shapes, examples | |
Every | |
Components, query and ingestion flow, memory and concurrency boundaries, hybrid weights | |
Folder filters, evaluation method, quality limits | |
Common problems and their fixes | |
When and how to enable lexical retrieval | |
Staging rebuilds, resume, checkpoints, recovery | |
Who runs the server, running CLI commands safely | |
CUDA runtime compatibility, CPU fallback, AMD and macOS limits | |
Embedding profiles, multilingual, zero-downtime rebuild | |
Reproducible workloads, measured results, validation limits | |
Independent review findings, retrieval diagnostics, model comparison | |
Threat model, disclosure channel and timelines | |
Development, testing, pull request process | |
Release notes since v1.0.0 |
Recent releases
v5.0.0 (2026-11-05): breaking
list_documentsnow returns 100 documents per page by default (up to 200 withlimit); call it again withoffsetuntil you reachtotal. Also: an empty or missingdocuments_dirno longer clears the index, search snippets start at the match,add_from_urlstops overwriting other pages, and failing tests now block merges.v4.11.1 (2026-10-25): fresh installs start again, Windows state writes retry through brief file locks, and the Docker image adds
linux/arm64.v4.11.0 (2026-10-04): startup refuses a
data_dirinside cloud-sync folders.v4.10.0 (2026-10-04): indexing reliability, bounded memory,
include_folders/exclude_folderssearch scopes and opt-in Windows DirectML.v4.9.0 to v4.9.2 (2026-09): 15 more file types, watcher and index resilience, and a fix for the reindex loop on Windows stdio clients.
Full history, including the v4.8 releases: CHANGELOG.md.
Community and support
Report a bug: open an issue
Ask a question: GitHub Discussions
Report a vulnerability: private security advisory
Contribute: CONTRIBUTING.md
Security reports are acknowledged within 48 hours (SECURITY.md).
License
MIT. You may use, modify and redistribute knowledge-rag, including in commercial products, under its terms. There is no paid edition.
Acknowledgments
Built on these open-source projects:
Model Context Protocol: the protocol and its Python SDK
ChromaDB: embedded vector database
FastEmbed: ONNX embeddings and reranking without PyTorch
Hugging Face: model hosting, including the
Xenova/ms-marco-MiniLM-L-6-v2cross-encoderBAAI: the
bge-small-en-v1.5embedding model
Community contributors: @Hohlas, @eeshsaxena, Sergey Khokhlov, and everyone who filed issues or pull requests (all contributors).
Available Tools
13 toolsadd_documentA
Add a new document to the knowledge base from raw text content.
Mutating — writes a file to disk and indexes it immediately. No auth required.
Args: content: Full text content of the document (markdown supported) filepath: Relative path within documents directory (e.g., "security/new-technique.md"). The subdirectory should match the category. category: Category stored with the document (default: general). Any name is accepted, but search_knowledge() filters only by configured categories (category_mappings values, keyword_routes keys, general), and update_document() or re-indexing the file detects it again from the path through category_mappings. list_categories() shows the categories in use.
Returns: JSON string with indexing results (filepath, chunks created, status).
Usage: Use to add new documents from text content. Use add_from_url() instead when the source is a web page. Use update_document() to replace content of an existing file. The document is immediately searchable after this call — no manual reindex needed.
Inputs: content (required), filepath (required), category. Returns: result
add_from_urlA
Fetch content from a URL, convert to markdown, and add to the knowledge base.
Mutating — makes an outbound HTTP request (requires internet access), strips HTML, converts to markdown, saves to disk, and indexes immediately.
Args: url: Full URL to fetch (https:// required). The page must be publicly accessible. category: Category stored with the document and the folder it is saved in; default: general. Being part of the path, it must stay inside documents_dir: a value such as ../outside returns a "Filepath rejected" error. Any other name is accepted, but search_knowledge() filters only by configured categories (category_mappings values, keyword_routes keys, general), and update_document() or re-indexing the file detects it again from the path through category_mappings. list_categories() shows the categories in use. title: Optional document title. Auto-detected from the page's tag if omitted.
Returns: JSON string with indexing results (filepath, category, chunks added, status). The page is saved as /.md, or as -<first 8 hex characters of the URL's SHA-256>.md (then 16, then the full digest) when a file not saved from this URL already has the shorter name. Use the returned filepath instead of building the path.
Usage: Use to ingest web content (writeups, blog posts, documentation pages) directly by URL. Use add_document() instead when you already have the text content. The document is immediately searchable after this call — no manual reindex needed.
Inputs: url (required), title, category. Returns: result
evaluate_retrievalA
Evaluate search quality by testing whether search_knowledge() retrieves expected documents.
Read-only. Runs multiple search queries internally. No side effects on the index.
Args: test_cases: JSON string array of test cases. Each item requires "query" (search string) and "expected_filepath" (path of the document that should appear in top-5 results). Example: [{"query": "suid exploit", "expected_filepath": "security/suid.md"}]
Returns: JSON string with MRR@5 (Mean Reciprocal Rank), Recall@5, and per-query hit/miss breakdown. MRR@5 above 0.7 indicates good retrieval quality.
Usage: Use to audit search quality after bulk document ingestion, a model change or a reindex. Each case runs as one top-5 search with the defaults of search_knowledge() (hybrid_alpha 0.3, search_method auto, no category or folder filter), so the figures describe what a client gets when it passes no options; this tool takes no search options. Use get_index_stats() for system health checks instead. Use search_knowledge() for actual document retrieval — this tool is for quality measurement only.
Inputs: test_cases (required). Returns: result
get_documentA
Get the full content of a specific document by filepath.
Read-only. No side effects.
Args: filepath: Relative path to the document within the documents directory (e.g., "security/technique.md"). Must be an indexed file — use search_knowledge() to find the filepath by topic first, or browse list_documents(), which returns one page at a time (see its offset).
Returns: JSON string with full document content and metadata (filepath, category, size).
Usage: Use when you need the complete text of a known file — search_knowledge() returns chunks, not full docs. Use search_knowledge() first to find the filepath if unknown. Use list_documents() to browse files by category, one page at a time.
Inputs: filepath (required). Returns: result
get_index_statsA
Get statistics and health metrics for the knowledge base index.
Read-only. No side effects.
Returns: JSON string with system metrics: total documents, total chunks, embedding model name, BM25 status, query cache hit rate, file watcher status, a self_recall probe (fraction of sampled chunks returned as top-1 by their own stored vector; a value below 1.0 means the HNSW index misses some chunks — see search.ef_search in config.example.yaml), and hnsw_ef_search (the value ChromaDB actually applies to the live collection; it can lag behind search.ef_search until a full rebuild).
Usage: Use for system health checks — inspecting embedding runtime status, checking index population, or monitoring cache efficiency. This does not load the embedding model or initialize BM25. Use list_categories() for per-category document counts instead. Use evaluate_retrieval() to measure actual search quality with test queries.
Inputs: no named parameters. Returns: result
get_reindex_statusA
Get the current status of a background reindex operation.
Lightweight — does not compute full index statistics. Use this to poll progress after calling reindex_documents().
Returns: JSON string with reindex status. When active: operation name, progress (processed/total), percent complete, indexed/skipped/errors counts, and start time. When inactive: active=false, plus last_result or last_error from the most recent completed reindex. When the last run had errors, last_result includes failed_files (deduped [{"path", "reason"}, ...], capped at 100) and failed_files_truncated, so you can see exactly which files failed and why. A failed full_rebuild surfaces in last_error, whose message lists the first failing paths, and the partial last_result still carries the failed_files list.
Usage: Call repeatedly after reindex_documents() to monitor progress. When reindex.active becomes false, the operation is complete. Use get_index_stats() for full index health metrics.
Inputs: no named parameters. Returns: result
list_categoriesA
List all document categories with their document counts.
Read-only. No side effects. Reflects the live index state.
Returns: JSON string with category names, document counts per category, and total document count.
Usage: Use before filtering search_knowledge() or list_documents() by category to see which categories exist and how many documents each contains; search_knowledge() still rejects a listed name that is not configured, such as one stored by add_document(). Use get_index_stats() instead for broader system health metrics (model name, cache hit rate, BM25 status).
Inputs: no named parameters. Returns: result
list_documentsA
List indexed documents one page at a time, optionally filtered by category.
Read-only. No side effects.
Args: category: Optional category filter, matched exactly against each document's category; an empty string, like omitting it, lists every document, and a category without documents returns an empty page (total 0). Call list_categories() to see the categories that hold documents. limit: Maximum number of documents to return (default: 100, max: 200). offset: Number of matching documents to skip (default: 0). For the next page, call again with offset + count until offset reaches total.
Returns: JSON string with total (documents matching the filter), offset, limit, count (documents in this page) and the filepaths, categories, and metadata of this page, ordered by filepath.
Usage: Use to browse what's in the index, one page at a time; to see every document, call again with offset + count until offset reaches total. Use list_categories() first to see which categories hold documents. Use search_knowledge() when you want to find documents by topic rather than browsing the full list. Use get_document() to read a specific file once you have its filepath.
Inputs: limit, offset, category. Returns: result
reindex_documentsA
Index or reindex all documents in the knowledge base (runs in background).
No flags — incremental pass: index new or changed files, skip unchanged
ones, prune deleted sources. Use after filesystem edits outside
add_document/update_document.
force — smart reindex: re-embed every file, unchanged ones included,
and rebuild BM25. Slow on a large corpus; use after changing the
query/passage prefixes or chunking settings.
full_rebuild — nuclear rebuild (delete + re-embed). Use only after
embedding-model change or index corruption. Mutually exclusive with resume.
resume — pick up an interrupted smart reindex from
data/reindex_checkpoint.json. Falls back to a fresh smart run silently
if the checkpoint is missing/corrupt/drifted (v4.8.0 Fase 4).
Returns a JSON envelope. Poll get_reindex_status() until
reindex.active becomes false. Add/update/URL tools already auto-index —
use these flags only for the recovery/rebuild scenarios above.
Inputs: force, resume, full_rebuild. Returns: result
remove_documentA
Remove a document from the knowledge base index.
Mutating — removes index entries. If delete_file=True, also permanently deletes the file from disk (irreversible, cannot be undone).
Args: filepath: Path to the document file. Must be an indexed document — list_documents() lists indexed paths, one page at a time. delete_file: If True, permanently deletes the file from disk in addition to removing from the index (default: False).
Returns: JSON string with removal results (filepath, status).
Usage: Use to unindex a document while keeping the file on disk (default). Set delete_file=True only for permanent removal. Use update_document() to replace content instead of removing. Use reindex_documents(force=True) if you deleted the file manually on disk outside of this tool.
Inputs: filepath (required), delete_file. Returns: result
search_knowledgeA
Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking.
Read-only. No side effects.
Args:
query: Search query text (1–3 keywords recommended; phrase queries also work)
max_results: Maximum number of results (default: 5, capped by search.max_results).
category: Optional category filter. Accepts the categories the server is configured with
(category_mappings values and keyword_routes keys) plus general; an empty string, like
omitting it, searches every category, and any other value returns an error that lists
the valid ones. Call list_categories() first to see which categories hold documents and
how many.
hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact
technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only
(best for conceptual or natural-language queries).
min_score: Minimum score (0.0–1.0) a result needs to be returned; default 0.0 returns all
results. Scores are min-max normalized per query over its candidates: the best scores 1.0
and the weakest 0.0, while a single candidate or candidates that all tie score 1.0. On the
hybrid path (results labeled hybrid, semantic or keyword) the candidates are the returned
results, so any min_score above 0 drops at least the weakest one unless all tie; fts5
results are BM25 scores normalized over up to max(3 * max_results, 20) hits, so even the
weakest returned one can score well above 0.0. It is not an absolute relevance bar.
snippet_mode: When true (default), truncates content to ~500 characters from the start of the
matching chunk, at a natural break point, and adds a content_length field with the full
size. Use get_document() to fetch full content when needed. Set to false to return the full
content, which can include adjacent chunks; match_offset, when present, is where the match starts.
search_method: Dispatch selector (v4.8.2+). One of "auto" (router picks FTS5 fast-path
for lexical queries when enabled, hybrid otherwise), "hybrid" (force hybrid path —
kill switch for suspected router misclassification), or "fts5" (force FTS5 fast-path
— debug/testing; errors out when the feature is disabled or the index is not ready).
Default "auto" preserves pre-v4.8.2 behavior byte-for-byte when the fast-path is
disabled in config.
include_folders: Optional list of directories relative to documents_dir, recursively included
before candidate selection (e.g. ["manuals/product-a", "runbooks"]). Omit for all folders.
exclude_folders: Optional recursive directory exclusions, applied before candidate selection.
Exclusions override inclusions. Paths use / or , have exact component boundaries,
and cannot be absolute, contain '..', or resolve outside documents_dir. Maximum 32 each.
Returns: JSON string with results including content chunks, source filepath, relevance score, and search method used. Returns chunks, not full document content.
Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when you already have a reference document and want more like it. Prefer get_document() when you already know the exact filepath and need the full content.
Inputs: query (required), category, min_score, max_results, +5 more. Returns: result
search_similarA
Find documents semantically similar to a given reference document.
Read-only. No side effects. Uses the document's embedding for similarity comparison.
Args: filepath: Path to the reference document (must already be indexed — list_documents() lists indexed paths, one page at a time). E.g., "security/technique.md" max_results: Number of similar documents to return (default: 5, max: 20)
Returns: JSON string with list of similar document filepaths and similarity scores (0.0–1.0).
Usage: Use when you have a specific document and want to discover thematically related ones. Use search_knowledge() instead when you have a text query rather than a reference document. The reference document must be indexed; list_documents() lists indexed paths one page at a time.
Inputs: filepath (required), max_results. Returns: result
update_documentA
Update the content of an existing document in the knowledge base.
Mutating — overwrites the file on disk and re-indexes immediately. Old chunks are removed and replaced with new ones. Full content replacement, not a patch. The category is detected again from the path through category_mappings (general when none matches), so a category stored by add_document() or add_from_url() is not kept.
Args: filepath: Full or relative path to the document file. Must be an already-indexed file — list_documents() lists indexed paths, one page at a time. content: New full-text content to replace the existing content entirely
Returns: JSON string with update results (old chunk count, new chunk count, status).
Usage: Use to replace a document's content completely. Use add_document() to create a new file instead. Use remove_document() to delete without replacing. Changes are immediately searchable — no manual reindex needed.
Inputs: content (required), filepath (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose, and the descriptions actively cross-reference siblings to prevent misselection (e.g., evaluate_retrieval vs search_knowledge vs get_index_stats, search_similar vs search_knowledge vs get_document). The read/ingest/maintenance split is unambiguous: search, retrieve, list, add, update, remove, reindex, status, stats, categories, evaluation.
Every tool follows a consistent snake_case verb_noun pattern: search_knowledge, get_document, add_document, update_document, remove_document, add_from_url, list_categories, list_documents, get_index_stats, get_reindex_status, evaluate_retrieval, search_similar. No mixed conventions or vague single-word names.
13 tools is well within the 3-15 sweet spot for a RAG knowledge-base server. Each tool covers a distinct operation (search, similar, fetch, list, add text, add URL, update, remove, reindex, status, stats, categories, evaluation) with no filler.
Full lifecycle coverage: ingest (add_document, add_from_url), read (get_document), browse (list_documents, list_categories), mutate (update_document, remove_document), discover (search_knowledge, search_similar), and operational tooling (reindex_documents with recovery modes, get_reindex_status, get_index_stats, evaluate_retrieval). No obvious dead ends for the stated domain.
Maintenance
Related MCP Connectors
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseAqualityDmaintenancePersistent memory for Claude Code. Automatically indexes every conversation and provides production-grade hybrid search (BM25 + vectors + reranker) via MCP tools. 100% local, zero config, zero API keys, zero invoice.1650 npm8MIT
- AlicenseAqualityBmaintenanceNexus-MCP is a local MCP server for coding agents. Hybrid code search and a call graph for 10 languages give the agent the right code in one call, so it reads less. No API key, no telemetry, MIT. * 95% fewer tokens to reach the right file * About 9× faster search than Grep and Read * Live Claude Code runs on 11 repos: cost per task lower on 8 of 115175 PyPIMIT
- AlicenseAqualityCmaintenanceSemantic vector DB as an MCP server for Claude Code — SQLite + FTS5 + local ONNX embeddings. Gives Claude persistent, searchable project knowledge across conversations.12MIT
- FlicenseNot gradedqualityDmaintenanceA lightweight RAG (Retrieval-Augmented Generation) system for Claude Code that enables semantic search over local markdown documents via MCP tools, saving tokens and time.64-