knowledge-rag 3.6.2__tar.gz → 3.8.0__tar.gz

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowledge-rag
-Version: 3.6.2
+Version: 3.8.0
 Summary: Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers.
 Project-URL: Homepage, https://github.com/lyonzin/knowledge-rag
 Project-URL: Repository, https://github.com/lyonzin/knowledge-rag
@@ -30,7 +30,7 @@ Requires-Dist: python-docx>=1.0.0
 Requires-Dist: python-pptx>=1.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rank-bm25>=0.2.2
-Requires-Dist: requests>=2.31.0
+Requires-Dist: requests>=2.33.0
 Requires-Dist: watchdog>=4.0.0
 Provides-Extra: gpu
 Requires-Dist: onnxruntime-gpu>=1.14.0; extra == 'gpu'
@@ -40,7 +40,9 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-3.5.2-blue.svg)
+[![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
+[![NPM](https://img.shields.io/npm/v/knowledge-rag)](https://www.npmjs.com/package/knowledge-rag)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/knowledge-rag?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/knowledge-rag)
 ![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)
@@ -48,7 +50,6 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/lyonzin/knowledge-rag/actions/workflows/ci.yml/badge.svg)](https://github.com/lyonzin/knowledge-rag/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/lyonzin/knowledge-rag/actions/workflows/security.yml/badge.svg)](https://github.com/lyonzin/knowledge-rag/actions/workflows/security.yml)
 [![Glama Score](https://glama.ai/mcp/servers/lyonzin/knowledge-rag/badges/score.svg)](https://glama.ai/mcp/servers/lyonzin/knowledge-rag)
-[![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
 
 ### Your docs, your machine, zero cloud. Claude Code searches them natively.
 
@@ -70,11 +71,21 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
-## What's New in v3.6.0
+## What's New in v3.8.0
+
+### Lazy-Loaded Embeddings — Cheaper Idle Processes
 
-### Multi-Language Code Parsing
+The FastEmbed ONNX model (~200MB resident) now loads on the **first query**, not at startup. Idle `knowledge-rag` processes are now genuinely cheap. Why this matters: MCP stdio is one-process-per-client by protocol — multiple Claude Code windows, Claude Desktop + IDE simultaneously, or review/approval flows that open extra connections all spawn their own processes. Before v3.8.0, every one of them paid the full embedding-model cost up front. Now only processes that actually serve queries load the model. Public API is unchanged.
 
-Language-aware extraction for **C**, **C++**, **JavaScript**, **TypeScript**, and **XML** — functions, classes, structs, interfaces, imports, and namespaces are captured as searchable metadata. Total supported formats: **20**.
+### Opt-In Single-Instance Guard
+
+For users who measured their setup and want a hard cap of one server per `data_dir`:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. **OFF by default** so multi-client MCP usage continues to work unchanged. Stale-PID recovery + SIGINT/SIGTERM cleanup wired correctly. Full guide in [docs/single-instance.md](docs/single-instance.md). Sample MCP config in [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ### 5 Ways to Install
 
@@ -90,6 +101,7 @@ All methods produce the same MCP server. See [Installation](#installation) for f
 
 ### Recent Highlights
 
+- **v3.8.0** — Lazy-load embeddings, opt-in single-instance guard, version sync across PyPI/NPM/Docker
 - **v3.6.0** — Multi-language code parsing (C/C++/JS/TS/XML), NPM wrapper, Docker image, automated release pipeline
 - **v3.5.2** — CUDA DLL auto-discovery from pip packages, graceful GPU→CPU fallback, explicit CPU provider (no CUDA noise when `gpu: false`), BASE_DIR resolution fix for editable installs
 - **v3.5.1** — Remove Python `<3.13` upper bound — 3.13 and 3.14 now supported
@@ -809,7 +821,7 @@ models:
     dimensions: 384
     gpu: false                         # Set true + pip install knowledge-rag[gpu]
   reranker:
-    enabled: true                      # Set false on low-resource machines
+    enabled: true                      # Falls back to RRF if model is unavailable
     model: "Xenova/ms-marco-MiniLM-L-6-v2"
     top_k_multiplier: 3               # Candidates fetched before reranking
 
@@ -896,6 +908,8 @@ For `.md` files, chunking splits at `##` and `###` header boundaries first. Sect
 | `models.reranker.model` | `Xenova/ms-marco-MiniLM-L-6-v2` | Reranker model |
 | `models.reranker.top_k_multiplier` | 3 | Fetch N*multiplier candidates for reranking |
 
+If the reranker model is not available locally and the machine cannot download it, search now falls back to the RRF order from hybrid semantic+BM25 retrieval. This keeps `search_knowledge` available offline, but result ordering may be less precise for ambiguous queries until the reranker model is cached.
+
 **Embedding model options** (fastest → most accurate):
 - `BAAI/bge-small-en-v1.5` — 384D, ~33MB (default)
 - `BAAI/bge-base-en-v1.5` — 768D, ~130MB
@@ -1026,6 +1040,31 @@ rm -rf models_cache
 # Then restart the MCP server
 ```
 
+### Reranker model download fails
+
+The reranker is lazy-loaded on the first query. If the model is not cached and the machine is offline, search continues without reranking and uses the RRF order from hybrid retrieval. To keep reranking enabled offline, run one query while online or pre-populate `models_cache/` on the target machine.
+
+You can still disable reranking explicitly in `config.yaml`:
+
+```yaml
+models:
+  reranker:
+    enabled: false
+```
+
+Disabling reranking reduces memory use and avoids first-query model loading. The tradeoff is lower ranking precision, especially when several chunks match the same terms but only one is the best answer.
+
+### ChromaDB index crashes on startup
+
+Native ChromaDB failures can terminate Python before normal exception handling runs. Startup now probes ChromaDB in a child process before initializing the MCP server. If the probe crashes, the active `chroma_db/` and `index_metadata.json` are moved to `data/backups/auto-repair-*`, and the next startup can rebuild a clean index.
+
+The same guarded behavior is available through either console script:
+
+```bash
+knowledge-rag
+knowledge-rag-guarded
+```
+
 ### Index is empty
 
 ```bash
@@ -1056,16 +1095,44 @@ pip install --upgrade knowledge-rag
 
 ### Slow first query
 
-The cross-encoder reranker model is lazy-loaded on the first query. This adds a one-time ~2-3 second delay for model download and loading. Subsequent queries are fast.
+The cross-encoder reranker model is lazy-loaded on the first query. This adds a one-time ~2-3 second delay for model download and loading. Subsequent queries are fast. If the model cannot be loaded, search falls back to RRF ordering and does not retry loading the reranker until the server restarts.
 
 ### Memory usage
 
-With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and reranker (~25MB) are loaded into memory. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+With ~200 documents, expect ~300-500MB RAM. The embedding model (~200MB ONNX runtime resident, lazy-loaded on first query since v3.8.0) and reranker (~25MB, lazy-loaded) are loaded into memory only when actually used. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+
+### Multiple MCP clients spawn duplicate servers
+
+MCP stdio is one process per client by protocol — multiple Claude Code windows, Claude Desktop + IDE, etc. each spawn their own `knowledge-rag` process. Since v3.8.0 idle processes are cheap (no embedding model loaded until first query). If you've measured and want a hard cap of one server per data directory, opt in:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. Default is OFF (multi-client friendly). Full guide: [docs/single-instance.md](docs/single-instance.md). Sample MCP config: [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ---
 
 ## Changelog
 
+### v3.8.0 (2026-05-10)
+
+- **NEW**: Lazy-load FastEmbed embedding model (~200MB ONNX runtime). Loads on first query instead of startup — idle `knowledge-rag` processes are now cheap, which matters when MCP stdio clients spawn parallel server processes (multiple Claude Code windows, Claude Desktop + IDE, etc.). Public API unchanged. (#32)
+- **NEW**: Opt-in single-instance guard via `KNOWLEDGE_RAG_SINGLE_INSTANCE=1` env var. **OFF by default** — multi-client MCP usage continues to work unchanged. When enabled, a second server process for the same `data_dir` exits with code 75 (`EX_TEMPFAIL`). Includes stale-PID recovery and SIGINT/SIGTERM handlers. See [docs/single-instance.md](docs/single-instance.md). (#33, original concept by @Hohlas in #31)
+- **NEW**: `examples/mcp-config-single-instance.json` — sample MCP client config for the opt-in guard.
+- **DOCS**: New `docs/single-instance.md` — when to use, when NOT to use, troubleshooting, full activation reference.
+- **DOCS**: README troubleshooting section for "Multiple MCP clients spawn duplicate servers" + memory-usage note for lazy embeddings.
+- **CHORE**: Sync version across `pyproject.toml`, `mcp_server/__init__.py`, and `npm/package.json` (was drifting since v3.5.x).
+- **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
+- **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
+
+### Unreleased
+
+- **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.
+- **FIX**: Reranker load failures now fall back to RRF ordering instead of failing `search_knowledge` on offline machines.
+- **FIX**: Virtualenv project-root detection now handles Python symlinks that resolve to the system interpreter.
+- **NEW**: `knowledge-rag-guarded` console script kept as an explicit guarded startup alias.
+
 ### v3.6.2 (2026-04-23)
 
 - **INFRA**: NPM provenance attestation (SLSA supply chain security), full README on npm page

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/README.md

@@ -2,7 +2,9 @@
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-3.5.2-blue.svg)
+[![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
+[![NPM](https://img.shields.io/npm/v/knowledge-rag)](https://www.npmjs.com/package/knowledge-rag)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/knowledge-rag?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/knowledge-rag)
 ![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)
@@ -10,7 +12,6 @@
 [![CI](https://github.com/lyonzin/knowledge-rag/actions/workflows/ci.yml/badge.svg)](https://github.com/lyonzin/knowledge-rag/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/lyonzin/knowledge-rag/actions/workflows/security.yml/badge.svg)](https://github.com/lyonzin/knowledge-rag/actions/workflows/security.yml)
 [![Glama Score](https://glama.ai/mcp/servers/lyonzin/knowledge-rag/badges/score.svg)](https://glama.ai/mcp/servers/lyonzin/knowledge-rag)
-[![PyPI](https://img.shields.io/pypi/v/knowledge-rag)](https://pypi.org/project/knowledge-rag/)
 
 ### Your docs, your machine, zero cloud. Claude Code searches them natively.
 
@@ -32,11 +33,21 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
-## What's New in v3.6.0
+## What's New in v3.8.0
+
+### Lazy-Loaded Embeddings — Cheaper Idle Processes
 
-### Multi-Language Code Parsing
+The FastEmbed ONNX model (~200MB resident) now loads on the **first query**, not at startup. Idle `knowledge-rag` processes are now genuinely cheap. Why this matters: MCP stdio is one-process-per-client by protocol — multiple Claude Code windows, Claude Desktop + IDE simultaneously, or review/approval flows that open extra connections all spawn their own processes. Before v3.8.0, every one of them paid the full embedding-model cost up front. Now only processes that actually serve queries load the model. Public API is unchanged.
 
-Language-aware extraction for **C**, **C++**, **JavaScript**, **TypeScript**, and **XML** — functions, classes, structs, interfaces, imports, and namespaces are captured as searchable metadata. Total supported formats: **20**.
+### Opt-In Single-Instance Guard
+
+For users who measured their setup and want a hard cap of one server per `data_dir`:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. **OFF by default** so multi-client MCP usage continues to work unchanged. Stale-PID recovery + SIGINT/SIGTERM cleanup wired correctly. Full guide in [docs/single-instance.md](docs/single-instance.md). Sample MCP config in [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ### 5 Ways to Install
 
@@ -52,6 +63,7 @@ All methods produce the same MCP server. See [Installation](#installation) for f
 
 ### Recent Highlights
 
+- **v3.8.0** — Lazy-load embeddings, opt-in single-instance guard, version sync across PyPI/NPM/Docker
 - **v3.6.0** — Multi-language code parsing (C/C++/JS/TS/XML), NPM wrapper, Docker image, automated release pipeline
 - **v3.5.2** — CUDA DLL auto-discovery from pip packages, graceful GPU→CPU fallback, explicit CPU provider (no CUDA noise when `gpu: false`), BASE_DIR resolution fix for editable installs
 - **v3.5.1** — Remove Python `<3.13` upper bound — 3.13 and 3.14 now supported
@@ -771,7 +783,7 @@ models:
     dimensions: 384
     gpu: false                         # Set true + pip install knowledge-rag[gpu]
   reranker:
-    enabled: true                      # Set false on low-resource machines
+    enabled: true                      # Falls back to RRF if model is unavailable
     model: "Xenova/ms-marco-MiniLM-L-6-v2"
     top_k_multiplier: 3               # Candidates fetched before reranking
 
@@ -858,6 +870,8 @@ For `.md` files, chunking splits at `##` and `###` header boundaries first. Sect
 | `models.reranker.model` | `Xenova/ms-marco-MiniLM-L-6-v2` | Reranker model |
 | `models.reranker.top_k_multiplier` | 3 | Fetch N*multiplier candidates for reranking |
 
+If the reranker model is not available locally and the machine cannot download it, search now falls back to the RRF order from hybrid semantic+BM25 retrieval. This keeps `search_knowledge` available offline, but result ordering may be less precise for ambiguous queries until the reranker model is cached.
+
 **Embedding model options** (fastest → most accurate):
 - `BAAI/bge-small-en-v1.5` — 384D, ~33MB (default)
 - `BAAI/bge-base-en-v1.5` — 768D, ~130MB
@@ -988,6 +1002,31 @@ rm -rf models_cache
 # Then restart the MCP server
 ```
 
+### Reranker model download fails
+
+The reranker is lazy-loaded on the first query. If the model is not cached and the machine is offline, search continues without reranking and uses the RRF order from hybrid retrieval. To keep reranking enabled offline, run one query while online or pre-populate `models_cache/` on the target machine.
+
+You can still disable reranking explicitly in `config.yaml`:
+
+```yaml
+models:
+  reranker:
+    enabled: false
+```
+
+Disabling reranking reduces memory use and avoids first-query model loading. The tradeoff is lower ranking precision, especially when several chunks match the same terms but only one is the best answer.
+
+### ChromaDB index crashes on startup
+
+Native ChromaDB failures can terminate Python before normal exception handling runs. Startup now probes ChromaDB in a child process before initializing the MCP server. If the probe crashes, the active `chroma_db/` and `index_metadata.json` are moved to `data/backups/auto-repair-*`, and the next startup can rebuild a clean index.
+
+The same guarded behavior is available through either console script:
+
+```bash
+knowledge-rag
+knowledge-rag-guarded
+```
+
 ### Index is empty
 
 ```bash
@@ -1018,16 +1057,44 @@ pip install --upgrade knowledge-rag
 
 ### Slow first query
 
-The cross-encoder reranker model is lazy-loaded on the first query. This adds a one-time ~2-3 second delay for model download and loading. Subsequent queries are fast.
+The cross-encoder reranker model is lazy-loaded on the first query. This adds a one-time ~2-3 second delay for model download and loading. Subsequent queries are fast. If the model cannot be loaded, search falls back to RRF ordering and does not retry loading the reranker until the server restarts.
 
 ### Memory usage
 
-With ~200 documents, expect ~300-500MB RAM. The embedding model (~50MB) and reranker (~25MB) are loaded into memory. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+With ~200 documents, expect ~300-500MB RAM. The embedding model (~200MB ONNX runtime resident, lazy-loaded on first query since v3.8.0) and reranker (~25MB, lazy-loaded) are loaded into memory only when actually used. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.
+
+### Multiple MCP clients spawn duplicate servers
+
+MCP stdio is one process per client by protocol — multiple Claude Code windows, Claude Desktop + IDE, etc. each spawn their own `knowledge-rag` process. Since v3.8.0 idle processes are cheap (no embedding model loaded until first query). If you've measured and want a hard cap of one server per data directory, opt in:
+
+```bash
+export KNOWLEDGE_RAG_SINGLE_INSTANCE=1
+```
+
+A second instance exits immediately with code 75. Default is OFF (multi-client friendly). Full guide: [docs/single-instance.md](docs/single-instance.md). Sample MCP config: [examples/mcp-config-single-instance.json](examples/mcp-config-single-instance.json).
 
 ---
 
 ## Changelog
 
+### v3.8.0 (2026-05-10)
+
+- **NEW**: Lazy-load FastEmbed embedding model (~200MB ONNX runtime). Loads on first query instead of startup — idle `knowledge-rag` processes are now cheap, which matters when MCP stdio clients spawn parallel server processes (multiple Claude Code windows, Claude Desktop + IDE, etc.). Public API unchanged. (#32)
+- **NEW**: Opt-in single-instance guard via `KNOWLEDGE_RAG_SINGLE_INSTANCE=1` env var. **OFF by default** — multi-client MCP usage continues to work unchanged. When enabled, a second server process for the same `data_dir` exits with code 75 (`EX_TEMPFAIL`). Includes stale-PID recovery and SIGINT/SIGTERM handlers. See [docs/single-instance.md](docs/single-instance.md). (#33, original concept by @Hohlas in #31)
+- **NEW**: `examples/mcp-config-single-instance.json` — sample MCP client config for the opt-in guard.
+- **DOCS**: New `docs/single-instance.md` — when to use, when NOT to use, troubleshooting, full activation reference.
+- **DOCS**: README troubleshooting section for "Multiple MCP clients spawn duplicate servers" + memory-usage note for lazy embeddings.
+- **CHORE**: Sync version across `pyproject.toml`, `mcp_server/__init__.py`, and `npm/package.json` (was drifting since v3.5.x).
+- **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
+- **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
+
+### Unreleased
+
+- **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.
+- **FIX**: Reranker load failures now fall back to RRF ordering instead of failing `search_knowledge` on offline machines.
+- **FIX**: Virtualenv project-root detection now handles Python symlinks that resolve to the system interpreter.
+- **NEW**: `knowledge-rag-guarded` console script kept as an explicit guarded startup alias.
+
 ### v3.6.2 (2026-04-23)
 
 - **INFRA**: NPM provenance attestation (SLSA supply chain security), full README on npm page

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/mcp_server/__init__.py

@@ -8,7 +8,7 @@ import sys  # noqa: I001
 _original_stdout = sys.stdout
 sys.stdout = sys.stderr
 
-__version__ = "3.5.2"
+__version__ = "3.8.0"
 __author__ = "Ailton Rocha (Lyon.)"
 
 from .config import Config  # noqa: E402

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/mcp_server/config.py

@@ -54,10 +54,11 @@ def _has_documents(path: Path) -> bool:
 
 def _venv_project_dir():
     """Detect project root from venv location (pip install from PyPI)."""
-    exe = Path(sys.executable).resolve()
-    for parent in exe.parents:
-        if parent.name in ("venv", ".venv", "env", ".env"):
-            return parent.parent
+    candidates = [Path(sys.prefix), Path(sys.executable), Path(sys.executable).resolve()]
+    for candidate in candidates:
+        for parent in (candidate, *candidate.parents):
+            if parent.name in ("venv", ".venv", "env", ".env"):
+                return parent.parent
     return None
 
 

knowledge_rag-3.8.0/mcp_server/guarded.py

@@ -0,0 +1,10 @@
+"""Backward-compatible guarded console entry point for knowledge-rag."""
+
+from __future__ import annotations
+
+from .server import main
+
+
+def guarded_main() -> None:
+    """Run the MCP server; server.main performs startup preflight."""
+    main()

knowledge_rag-3.8.0/mcp_server/instance_lock.py

@@ -0,0 +1,188 @@
+"""Optional single-instance guard for the MCP server process.
+
+Background
+----------
+MCP stdio servers are 1-process-per-client by protocol design. Multiple
+Claude Code windows, Claude Desktop + IDE running simultaneously, or clients
+that open extra internal connections during approval/review flows will all
+spawn additional `knowledge-rag` processes. Each process holds its own
+embedding model, ChromaDB client, BM25 state, and file watcher.
+
+Lazy-loading the embedding model (v3.8.0) reduces idle cost dramatically,
+but some users still want a hard cap of one process per data directory.
+This module provides that cap as an OPT-IN, never as a default.
+
+Activation
+----------
+Set the environment variable in your MCP client config:
+
+    KNOWLEDGE_RAG_SINGLE_INSTANCE=1     # also accepts: true, yes, on (case-insensitive)
+
+When unset (default), `single_instance_lock()` is a no-op and the server
+behaves exactly as it did before this module existed.
+
+When enabled, the server creates `<data_dir>/knowledge-rag.lock` containing
+its PID. A second process starting against the same `data_dir` will detect
+the live PID and exit with code 75 (EX_TEMPFAIL). Stale locks (PID gone)
+are cleaned up automatically.
+
+Cleanup is wired in three places so the lock does not outlive the process:
+1. Normal exit: contextmanager `finally` block removes the lock.
+2. SIGINT / SIGTERM: handlers remove the lock and re-raise the default action.
+3. Crash / SIGKILL: stale-PID detection on the next startup removes it.
+
+Authors
+-------
+- Concept and original guard: Sergey Khokhlov (@Hohlas) in PR #31
+- Reworked as opt-in + signal handlers + tests: Lyon. (knowledge-rag maintainer)
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .config import config
+
+LOCK_FILENAME = "knowledge-rag.lock"
+ALREADY_RUNNING_EXIT_CODE = 75  # EX_TEMPFAIL from sysexits.h
+ENV_VAR = "KNOWLEDGE_RAG_SINGLE_INSTANCE"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+class AlreadyRunningError(RuntimeError):
+    """Raised when another knowledge-rag server instance already holds the lock."""
+
+
+def single_instance_enabled() -> bool:
+    """Return True if the user opted into the single-instance guard.
+
+    Reads `KNOWLEDGE_RAG_SINGLE_INSTANCE`. Accepts ``1``, ``true``, ``yes``, ``on``
+    (case-insensitive, surrounding whitespace ignored). Anything else — including
+    unset, empty, ``0``, ``false`` — leaves the guard disabled.
+    """
+    raw = os.environ.get(ENV_VAR, "").strip().lower()
+    return raw in _TRUTHY
+
+
+def _pid_is_running(pid: int) -> bool:
+    """Return True if a process with PID appears to be alive."""
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but is owned by another user / has tighter ACLs
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _read_lock_pid(lock_path: Path) -> Optional[int]:
+    try:
+        raw = lock_path.read_text(encoding="utf-8").strip().splitlines()[0]
+        return int(raw)
+    except (IndexError, OSError, ValueError):
+        return None
+
+
+def _lock_path() -> Path:
+    return config.data_dir / LOCK_FILENAME
+
+
+def _remove_if_ours(lock_path: Path) -> None:
+    """Remove the lock file ONLY if it still references our PID."""
+    if _read_lock_pid(lock_path) == os.getpid():
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            # Best-effort; stale-PID check on next startup will recover
+            pass
+
+
+@contextmanager
+def single_instance_lock() -> Iterator[Optional[Path]]:
+    """Acquire the single-instance lock if opt-in flag is set.
+
+    No-op when ``KNOWLEDGE_RAG_SINGLE_INSTANCE`` is unset / falsy — yields ``None``
+    and the caller proceeds normally with no side effects on disk.
+
+    When enabled:
+      - Creates ``<data_dir>/knowledge-rag.lock`` containing this process's PID.
+      - Raises :class:`AlreadyRunningError` if another live PID already holds it.
+      - Recovers stale locks (PID no longer running).
+      - Registers SIGINT/SIGTERM handlers that remove the lock and re-raise.
+      - Removes the lock on normal exit via ``finally``.
+    """
+    if not single_instance_enabled():
+        yield None
+        return
+
+    config.data_dir.mkdir(parents=True, exist_ok=True)
+    lock_path = _lock_path()
+
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            pid = _read_lock_pid(lock_path)
+            if pid is not None and _pid_is_running(pid):
+                raise AlreadyRunningError(
+                    f"knowledge-rag MCP server is already running (pid {pid}). "
+                    f"Refusing to start a second instance because "
+                    f"{ENV_VAR} is enabled."
+                )
+            try:
+                lock_path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                raise AlreadyRunningError(f"Failed to clear stale lock {lock_path}: {exc}") from exc
+            continue
+
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(f"{os.getpid()}\n")
+        break
+
+    # Wire signal handlers so SIGINT/SIGTERM cleanup the lock before exit
+    previous_handlers: dict[int, object] = {}
+
+    def _signal_cleanup(signum: int, frame) -> None:
+        _remove_if_ours(lock_path)
+        # Restore original handler and re-raise so default action runs
+        prev = previous_handlers.get(signum, signal.SIG_DFL)
+        try:
+            signal.signal(signum, prev)  # type: ignore[arg-type]
+        except (ValueError, OSError):
+            pass
+        # Re-send the signal to ourselves so the original disposition fires
+        os.kill(os.getpid(), signum)
+
+    for sig_name in ("SIGINT", "SIGTERM"):
+        sig = getattr(signal, sig_name, None)
+        if sig is None:
+            continue
+        try:
+            previous_handlers[sig] = signal.getsignal(sig)
+            signal.signal(sig, _signal_cleanup)
+        except (ValueError, OSError):
+            # signal.signal raises if not on the main thread; tests may hit this
+            pass
+
+    try:
+        yield lock_path
+    finally:
+        _remove_if_ours(lock_path)
+        for sig, prev in previous_handlers.items():
+            try:
+                signal.signal(sig, prev)  # type: ignore[arg-type]
+            except (ValueError, OSError):
+                pass

knowledge_rag-3.8.0/mcp_server/preflight.py

@@ -0,0 +1,74 @@
+"""Startup preflight checks for persistent ChromaDB state."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .config import BASE_DIR, config
+
+
+def _backup_active_index(reason: str) -> Path:
+    """Move active ChromaDB state aside so the server can rebuild cleanly."""
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup_dir = config.data_dir / "backups" / f"auto-repair-{stamp}"
+    backup_dir.mkdir(parents=True, exist_ok=False)
+
+    if config.chroma_dir.exists():
+        shutil.move(str(config.chroma_dir), str(backup_dir / f"chroma_db.{reason}"))
+
+    metadata_file = config.data_dir / "index_metadata.json"
+    if metadata_file.exists():
+        shutil.move(str(metadata_file), str(backup_dir / f"index_metadata.{reason}.json"))
+
+    return backup_dir
+
+
+def _probe_chroma(timeout_seconds: int = 30) -> subprocess.CompletedProcess[str]:
+    """Check Chroma in a child process so native crashes do not kill MCP startup."""
+    code = r"""
+import chromadb
+
+from mcp_server.config import config
+
+if not config.chroma_dir.exists():
+    print("missing")
+    raise SystemExit(0)
+
+client = chromadb.PersistentClient(path=str(config.chroma_dir))
+collection = client.get_or_create_collection(name=config.collection_name)
+print(collection.count())
+"""
+    env = os.environ.copy()
+    env.setdefault("KNOWLEDGE_RAG_DIR", str(BASE_DIR))
+    return subprocess.run(
+        [sys.executable, "-c", code],
+        cwd=str(BASE_DIR),
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=timeout_seconds,
+        check=False,
+    )
+
+
+def run_preflight(timeout_seconds: int = 30) -> bool:
+    """Return True when active Chroma state was moved aside for repair."""
+    result = _probe_chroma(timeout_seconds=timeout_seconds)
+    if result.returncode == 0:
+        return False
+
+    reason = "segfault" if result.returncode in (-11, 139) else "failed"
+    backup_dir = _backup_active_index(reason)
+    print(
+        f"[RECOVERY] Chroma preflight failed with code {result.returncode}; moved active index to {backup_dir}",
+        file=sys.stderr,
+    )
+    if result.stderr:
+        print(result.stderr[-2000:], file=sys.stderr)
+    return True

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/mcp_server/server.py

@@ -136,6 +136,17 @@ class FastEmbedEmbeddings:
     Uses ONNX Runtime in-process for embedding generation.
     No external server required (replaces Ollama).
     Model: BAAI/bge-small-en-v1.5 (384-dim, MTEB score 62.x)
+
+    Lazy-loading (since v3.8.0):
+        The ONNX model (~200MB resident) is NOT loaded in __init__.
+        It loads on the first call to __call__/embed_query/embed_documents.
+        This makes idle MCP server processes cheap, which matters when
+        multiple stdio clients spawn parallel knowledge-rag processes
+        (e.g. multiple Claude Code windows). The CrossEncoderReranker
+        already follows this same pattern.
+
+        Thread-safe: load is guarded by a lock so concurrent first-callers
+        don't double-initialize the model.
     """
 
     @staticmethod
@@ -174,20 +185,34 @@ class FastEmbedEmbeddings:
     def __init__(self, model: str = None):
         self.model_name = model or config.embedding_model
         self._dim = config.embedding_dim
-        kwargs = {"model_name": self.model_name, "cache_dir": str(config.models_cache_dir)}
-        if config.gpu_acceleration:
-            self._setup_cuda_dll_paths()
-            kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
-            print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
-            try:
-                self._model = TextEmbedding(**kwargs)
-                print("[INFO] Embedding model loaded successfully [GPU]")
-            except (ValueError, RuntimeError) as e:
-                print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
-                kwargs["providers"] = ["CPUExecutionProvider"]
-                self._model = TextEmbedding(**kwargs)
-                print("[INFO] Embedding model loaded successfully [CPU fallback]")
-        else:
+        # Build kwargs once; defer the heavy TextEmbedding(**kwargs) call to first use.
+        self._init_kwargs = {"model_name": self.model_name, "cache_dir": str(config.models_cache_dir)}
+        self._gpu = bool(config.gpu_acceleration)
+        self._model: Optional[TextEmbedding] = None
+        self._load_lock = threading.Lock()
+
+    def _load_model(self) -> None:
+        """Load the ONNX model on demand. Idempotent and thread-safe."""
+        if self._model is not None:
+            return
+        with self._load_lock:
+            if self._model is not None:  # double-checked under the lock
+                return
+            kwargs = dict(self._init_kwargs)
+            if self._gpu:
+                self._setup_cuda_dll_paths()
+                kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+                print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
+                try:
+                    self._model = TextEmbedding(**kwargs)
+                    print("[INFO] Embedding model loaded successfully [GPU]")
+                    return
+                except (ValueError, RuntimeError) as e:
+                    print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
+                    kwargs["providers"] = ["CPUExecutionProvider"]
+                    self._model = TextEmbedding(**kwargs)
+                    print("[INFO] Embedding model loaded successfully [CPU fallback]")
+                    return
             kwargs["providers"] = ["CPUExecutionProvider"]
             print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D)...")
             self._model = TextEmbedding(**kwargs)
@@ -203,6 +228,7 @@ class FastEmbedEmbeddings:
         if not input:
             return []
 
+        self._load_model()
         try:
             embeddings = list(self._model.embed(input))
             return [emb.tolist() for emb in embeddings]
@@ -248,13 +274,22 @@ class CrossEncoderReranker:
     def __init__(self, model: str = None):
         self.model_name = model or config.reranker_model
         self._model = None  # Lazy init
+        self._load_failed = False
 
-    def _ensure_model(self):
+    def _ensure_model(self) -> bool:
         """Lazy initialization of cross-encoder model"""
+        if self._load_failed:
+            return False
         if self._model is None:
             print(f"[INFO] Loading reranker model: {self.model_name}...")
-            self._model = TextCrossEncoder(model_name=self.model_name, cache_dir=str(config.models_cache_dir))
-            print("[INFO] Reranker model loaded successfully")
+            try:
+                self._model = TextCrossEncoder(model_name=self.model_name, cache_dir=str(config.models_cache_dir))
+                print("[INFO] Reranker model loaded successfully")
+            except Exception as e:
+                self._load_failed = True
+                print(f"[WARN] Reranker unavailable, using RRF order: {e}")
+                return False
+        return True
 
     def rerank(self, query: str, documents: List[Dict[str, Any]], top_k: int = 5) -> List[Dict[str, Any]]:
         """
@@ -271,7 +306,8 @@ class CrossEncoderReranker:
         if not documents or not config.reranker_enabled:
             return documents[:top_k]
 
-        self._ensure_model()
+        if not self._ensure_model():
+            return documents[:top_k]
 
         texts = [doc.get("document", "") for doc in documents]
 
@@ -1924,44 +1960,58 @@ def main():
         _handle_init()
         return
 
-    orchestrator = get_orchestrator()
-
-    # Migration: check dimension mismatch AFTER full init (avoids segfault during __init__)
-    orchestrator._needs_rebuild = orchestrator._check_dimension_mismatch()
-    if orchestrator._needs_rebuild:
-        print("[MIGRATION] Running nuclear rebuild for embedding model change...")
-        try:
-            stats = orchestrator.nuclear_rebuild()
-            print(
-                f"[MIGRATION] Rebuild complete: {stats['indexed']} docs, "
-                f"{stats['chunks_added']} chunks in {stats.get('elapsed_seconds', '?')}s"
-            )
-        except Exception as e:
-            print(f"[ERROR] Migration failed: {e}")
-            print("[FALLBACK] Attempting regular index instead...")
-            stats = orchestrator.index_all(force=True)
-    elif orchestrator.collection.count() == 0:
-        print("[INFO] No documents indexed. Running initial indexing...")
-        stats = orchestrator.index_all()
-        print(f"[INFO] Indexed {stats['indexed']} documents with {stats['chunks_added']} chunks")
+    from .instance_lock import (
+        ALREADY_RUNNING_EXIT_CODE,
+        AlreadyRunningError,
+        single_instance_lock,
+    )
+    from .preflight import run_preflight
 
-    # Start file watcher for auto-reindex on document changes
     try:
-        watcher = DocumentWatcher(get_orchestrator, debounce_seconds=5.0)
-        observer = Observer()
-        observer.schedule(watcher, str(config.documents_dir), recursive=True)
-        observer.daemon = True
-        observer.start()
-        print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
-    except Exception as e:
-        print(f"[WARN] Failed to start file watcher: {e}")
-        print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
-
-    # Restore real stdout for MCP JSON-RPC, keep print() going to stderr
-    from . import _original_stdout
-
-    sys.stdout = _original_stdout
-    mcp.run()
+        with single_instance_lock():
+            run_preflight()
+
+            orchestrator = get_orchestrator()
+
+            # Migration: check dimension mismatch AFTER full init (avoids segfault during __init__)
+            orchestrator._needs_rebuild = orchestrator._check_dimension_mismatch()
+            if orchestrator._needs_rebuild:
+                print("[MIGRATION] Running nuclear rebuild for embedding model change...")
+                try:
+                    stats = orchestrator.nuclear_rebuild()
+                    print(
+                        f"[MIGRATION] Rebuild complete: {stats['indexed']} docs, "
+                        f"{stats['chunks_added']} chunks in {stats.get('elapsed_seconds', '?')}s"
+                    )
+                except Exception as e:
+                    print(f"[ERROR] Migration failed: {e}")
+                    print("[FALLBACK] Attempting regular index instead...")
+                    stats = orchestrator.index_all(force=True)
+            elif orchestrator.collection.count() == 0:
+                print("[INFO] No documents indexed. Running initial indexing...")
+                stats = orchestrator.index_all()
+                print(f"[INFO] Indexed {stats['indexed']} documents with {stats['chunks_added']} chunks")
+
+            # Start file watcher for auto-reindex on document changes
+            try:
+                watcher = DocumentWatcher(get_orchestrator, debounce_seconds=5.0)
+                observer = Observer()
+                observer.schedule(watcher, str(config.documents_dir), recursive=True)
+                observer.daemon = True
+                observer.start()
+                print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
+            except Exception as e:
+                print(f"[WARN] Failed to start file watcher: {e}")
+                print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
+
+            # Restore real stdout for MCP JSON-RPC, keep print() going to stderr
+            from . import _original_stdout
+
+            sys.stdout = _original_stdout
+            mcp.run()
+    except AlreadyRunningError as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        raise SystemExit(ALREADY_RUNNING_EXIT_CODE) from e
 
 
 if __name__ == "__main__":

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/npm/README.md

@@ -2,7 +2,7 @@
 
 # Knowledge RAG
 
-Local RAG system for Claude Code. Hybrid BM25 + semantic search with cross-encoder reranking. 12 MCP tools. Zero external servers. Everything runs on your machine.
+Local RAG system for Claude Code. Hybrid BM25 + semantic search with cross-encoder reranking. 12 MCP tools, 20 format parsers. Zero external servers. Everything runs on your machine.
 
 ## Quick Start
 

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowledge-rag"
-version = "3.6.2"
+version = "3.8.0"
 description = "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers."
 readme = "README.md"
 license = {text = "MIT"}
@@ -34,7 +34,7 @@ dependencies = [
     "fastembed[reranking]>=0.4.0",
     "mcp>=1.0.0",
     "rank-bm25>=0.2.2",
-    "requests>=2.31.0",
+    "requests>=2.33.0",
     "beautifulsoup4>=4.12.0",
     "python-docx>=1.0.0",
     "openpyxl>=3.1.0",
@@ -54,6 +54,7 @@ Changelog = "https://github.com/lyonzin/knowledge-rag/releases"
 
 [project.scripts]
 knowledge-rag = "mcp_server.server:main"
+knowledge-rag-guarded = "mcp_server.guarded:guarded_main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["mcp_server"]
@@ -94,6 +95,11 @@ exclude = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["."]
+# Limit retained tmp_path directories to avoid pytest's atexit cleanup race
+# on Windows (cleanup_numbered_dir + pathlib.glob "garbage-*" can fail when
+# many tmp dirs accumulate). Tests run isolated; we don't need history.
+tmp_path_retention_count = 1
+tmp_path_retention_policy = "failed"
 
 [tool.ruff]
 target-version = "py311"

{knowledge_rag-3.6.2 → knowledge_rag-3.8.0}/requirements.txt

@@ -1,6 +1,6 @@
 # Knowledge RAG System - Python Dependencies
 # ==========================================
-# Requires Python 3.11 or 3.12 (NOT 3.13+ due to onnxruntime)
+# Requires Python 3.11+ (3.11, 3.12, 3.13, 3.14 supported)
 
 # Vector Database (uses new PersistentClient API)
 chromadb>=1.4.0
@@ -19,7 +19,7 @@ mcp>=1.0.0
 rank-bm25>=0.2.2
 
 # URL content fetching (add_from_url tool)
-requests>=2.31.0
+requests>=2.33.0
 
 # HTML parsing (add_from_url tool)
 beautifulsoup4>=4.12.0
@@ -44,6 +44,6 @@ watchdog>=4.0.0
 # 2. Default embedding model: BAAI/bge-small-en-v1.5 (384-dim)
 #    Cached in ~/.cache/fastembed/
 #
-# 3. Python 3.13+ is NOT supported because chromadb
-#    depends on onnxruntime which has no 3.13 wheels
+# 3. Python 3.13+ is supported since v3.5.1
+#    (onnxruntime now ships wheels for 3.13 and 3.14)
 # ==========================================