knowledge-rag 4.9.1__tar.gz → 4.9.2__tar.gz

{knowledge_rag-4.9.1 → knowledge_rag-4.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: knowledge-rag
-Version: 4.9.1
+Version: 4.9.2
 Summary: Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 13 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
@@ -636,6 +636,8 @@ Native MCP
 
 **Complete client configuration guide with JSON schemas per client:** [docs/INSTALLATION.md#use-with-other-mcp-clients →](docs/INSTALLATION.md#use-with-other-mcp-clients)
 
+> ⚠️ **Operating model — read once.** Your MCP client (Claude Desktop, Code, Cursor, etc.) **spawns and owns the knowledge-rag server process**. Do **NOT** also run `knowledge-rag` in a terminal while your MCP client is open — two writer processes against the same `data_dir` corrupt the ChromaDB HNSW segment on Windows (see [issue #216](https://github.com/lyonzin/knowledge-rag/issues/216)). Recommended baseline: add `"KNOWLEDGE_RAG_SINGLE_INSTANCE": "1"` to the `env` block of your MCP config as a safety net. Full explanation + how to run CLI commands safely: [docs/single-instance.md](docs/single-instance.md).
+
 ---
 
 ## ⚙️ Configuration in 30 seconds

{knowledge_rag-4.9.1 → knowledge_rag-4.9.2}/README.md

@@ -588,6 +588,8 @@ Native MCP
 
 **Complete client configuration guide with JSON schemas per client:** [docs/INSTALLATION.md#use-with-other-mcp-clients →](docs/INSTALLATION.md#use-with-other-mcp-clients)
 
+> ⚠️ **Operating model — read once.** Your MCP client (Claude Desktop, Code, Cursor, etc.) **spawns and owns the knowledge-rag server process**. Do **NOT** also run `knowledge-rag` in a terminal while your MCP client is open — two writer processes against the same `data_dir` corrupt the ChromaDB HNSW segment on Windows (see [issue #216](https://github.com/lyonzin/knowledge-rag/issues/216)). Recommended baseline: add `"KNOWLEDGE_RAG_SINGLE_INSTANCE": "1"` to the `env` block of your MCP config as a safety net. Full explanation + how to run CLI commands safely: [docs/single-instance.md](docs/single-instance.md).
+
 ---
 
 ## ⚙️ Configuration in 30 seconds

{knowledge_rag-4.9.1 → knowledge_rag-4.9.2}/mcp_server/__init__.py

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

{knowledge_rag-4.9.1 → knowledge_rag-4.9.2}/mcp_server/preflight.py

@@ -49,17 +49,43 @@ def _backup_active_index(reason: str) -> Path:
     fallback copy+rmtree path in shutil.move leaks a partial copy in
     backups/ AND a partially deleted live chroma_db/ when another process
     holds a segment file open (WinError 32).
+
+    The two moves (metadata JSON + chroma_db dir) must be all-or-nothing.
+    If we moved chroma_db first and metadata failed (antivirus scanning
+    the JSON, brief file lock), restart would find `chroma_db` gone but
+    `index_metadata.json` still live — incremental reindex would then
+    read the orphan metadata, mark every doc as "already indexed", and
+    silently produce an empty collection. To prevent that, metadata is
+    moved first (small file, low lock probability) and chroma_db is
+    wrapped in try/except that rolls the metadata rename back before
+    re-raising. Restart then sees the pristine pre-quarantine state
+    and re-runs preflight 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():
-        os.rename(str(config.chroma_dir), str(backup_dir / f"chroma_db.{reason}"))
-
     metadata_file = config.data_dir / "index_metadata.json"
+    metadata_backup = backup_dir / f"index_metadata.{reason}.json"
+    metadata_moved = False
     if metadata_file.exists():
-        os.rename(str(metadata_file), str(backup_dir / f"index_metadata.{reason}.json"))
+        os.rename(str(metadata_file), str(metadata_backup))
+        metadata_moved = True
+
+    if config.chroma_dir.exists():
+        try:
+            os.rename(str(config.chroma_dir), str(backup_dir / f"chroma_db.{reason}"))
+        except OSError:
+            if metadata_moved:
+                # Rollback the metadata move so the two files stay consistent.
+                # If the rollback itself fails (unlikely — dst dir is fresh)
+                # we still re-raise the original OSError so the caller can
+                # exit cleanly instead of leaving the system in a wedged state.
+                try:
+                    os.rename(str(metadata_backup), str(metadata_file))
+                except OSError:
+                    pass
+            raise
 
     return backup_dir
 

{knowledge_rag-4.9.1 → knowledge_rag-4.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowledge-rag"
-version = "4.9.1"
+version = "4.9.2"
 description = "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 13 MCP Tools + 20 Format Parsers. Zero external servers."
 readme = "README.md"
 license = {text = "MIT"}