[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
Merge remote-tracking branch 'origin/main' into feat/mcp-improvements
yichuan520030910320e3593feb199d
diff --cc docs/CHANGELOG.mdindex f92cb73,2030b8e..2ce4387--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@@ -1,27 -1,20 +1,42 @@@# Changelog- All notable changes to LEANN are documented here. Append-only, newest entries at the bottom.-- Format: `## YYYY-MM-DD: <short summary>` followed by bullet points.+ Append-only log of major changes to LEANN (new features, breaking changes, important+ fixes). Newest entries at the bottom.+## 2026-03-05: IVF backend incremental update support++- Added `leann-backend-ivf` with FAISS IndexIVFFlat + DirectMap.Hashtable.+- IVF supports in-place `add_vectors` and `remove_ids` without full rebuild.+- `leann build` is now idempotent: re-running on an existing index does incremental update (add new, remove deleted, re-index modified files).+- Fixed incremental build chunking inconsistency and shared metadata dict bug.+- Fixed IVF incremental update duplicate chunks from stale `passages.jsonl`.++## 2026-03-05: MCP server v2 — build, status, and structured search++- Added `leann_build` MCP tool: build or incrementally update indexes directly from Claude Code.+- Added `leann_status` MCP tool: inspect index details (backend, embedding model, chunk/file count, size).+- `leann_search` now uses `--json` output with file paths always included, formatted as markdown code blocks.+- Fixed `float32` JSON serialization bug in `leann search --json`.+- Cleaned up MCP tool descriptions (concise, no emoji).++## 2026-03-05: Documentation — roadmap, vision, and dev guidelines++- Rewrote `docs/roadmap.md` with current P0/P1 priorities from GitHub issue #237.+- Added `docs/ultimate_goal.md` — long-term vision (personal data platform, best code retrieval MCP, multimodal, local-first).+- Added self-contained documentation principle and dev doc maintenance rules to `CLAUDE.md`.+++ ## 2026-06-02: GPU FlashLib IVF backend (`flashlib_ivf`)++ - Add `leann-backend-flashlib-ivf`, a GPU IVF-Flat (inverted file) approximate-NN+ backend built on FlashLib (`flash_ivf_flat`, Triton/CuteDSL) — the GPU counterpart+ of the FAISS `ivf` backend. Registered as backend name `flashlib_ivf`; install via+ `uv sync --extra flashlib-ivf` or `pip install leann-backend-flashlib-ivf`. Shares+ the `nlist`/`nprobe` recall knobs with the `ivf` backend, so the two are drop-in+ comparable. Requires a CUDA GPU at build (k-means) and search.+ - Add `benchmarks/flashlib_ivf_vs_faiss_ivf.py`: head-to-head `flashlib_ivf` (GPU) vs+ `ivf` (FAISS, CPU) at matched `nlist` across an `nprobe` sweep (build time,+ single-query latency, batched throughput, recall@k vs exact ground truth). On an+ NVIDIA H200 at 1M x 768 vectors (nlist=4096, 8 CPU threads): ~13x faster build and,+ at nprobe=32, ~6.5x lower single-query latency / ~75x higher batched throughput at+ comparable recall (GPU latency stays ~flat while CPU grows linearly with nprobe).+ - Docs: `docs/flashlib_backend_guide.md` gains a `flashlib_ivf` section.diff --cc packages/leann-core/src/leann/cli.pyindex 2f4b583,5aa486c..405cf2c--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@@ -26,31 -28,9 +28,31 @@@ from .settings importresolve_openai_api_key,resolve_openai_base_url,)- from .sync import FileSynchronizer+ from .sync import DEFAULT_INDEX_EXTENSIONS, FileSynchronizer, parse_include_extensions+def _default_embedding_model() -> str:+ """Pick a sensible default embedding model based on platform.++ | Platform | Default model |+ |------------|------------------------------------------------|+ | NVIDIA GPU | BAAI/bge-base-en-v1.5 |+ | macOS | sentence-transformers/all-MiniLM-L6-v2 |+ | Other/CPU | sentence-transformers/all-MiniLM-L6-v2 |+ """++ try:+ import torch++ if torch.cuda.is_available():+ return "BAAI/bge-base-en-v1.5"+ except ImportError:+ pass++ # macOS (MPS or CPU) and all other platforms: lightweight model+ return "sentence-transformers/all-MiniLM-L6-v2"++def _normalize_path(path: str) -> str:"""Return absolute path string for consistent keys."""if not path:diff --cc packages/leann-core/src/leann/mcp.pyindex c3d1e79,c2f88be..f0b6017--- a/packages/leann-core/src/leann/mcp.py+++ b/packages/leann-core/src/leann/mcp.py@@@ -4,314 -5,24 +5,326 @@@ import jsoimport subprocessimport sys+ _base_dir: str | None = None+++ def _leann_cmd() -> list[str]:+ """Build the base command for invoking ``leann`` CLI.++ Using ``sys.executable -m leann`` guarantees we find the CLI even when+ the ``leann`` console-script is not on PATH (common on Windows when+ launched by mcp-proxy or other service wrappers).+ """+ return [sys.executable, "-m", "leann"]++def _run_leann(*args, timeout=120):+ """Run a leann CLI command and return (returncode, stdout, stderr)."""+ result = subprocess.run(+ ["leann", *args],+ capture_output=True,+ text=True,+ timeout=timeout,+ )+ return result.returncode, result.stdout, result.stderr+++def _make_result(request_id, content_text):+ return {+ "jsonrpc": "2.0",+ "id": request_id,+ "result": {"content": [{"type": "text", "text": content_text}]},+ }+++def _make_error(request_id, message):+ return {+ "jsonrpc": "2.0",+ "id": request_id,+ "error": {"code": -1, "message": message},+ }+++TOOLS = [+ {+ "name": "leann_search",+ "description": (+ "Semantic code search across an indexed codebase. Returns matching code "+ "chunks with file paths, scores, and surrounding context.\n\n"+ "Use this to find relevant code before making changes — understand existing "+ "patterns, locate implementations, and discover related files.\n\n"+ "Examples: 'authentication middleware', 'database connection pooling', "+ "'error handling in API routes', 'how are embeddings computed'"+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name of the LEANN index to search. Use leann_list to see available indexes.",+ },+ "query": {+ "type": "string",+ "description": "Natural language or technical search query.",+ },+ "top_k": {+ "type": "integer",+ "default": 5,+ "minimum": 1,+ "maximum": 20,+ "description": "Number of results to return (default 5).",+ },+ "complexity": {+ "type": "integer",+ "default": 32,+ "minimum": 16,+ "maximum": 128,+ "description": "Search precision level (default 32, use 64+ for thorough search).",+ },+ },+ "required": ["index_name", "query"],+ },+ },+ {+ "name": "leann_list",+ "description": "List all available LEANN indexes across projects. Shows index names, status, size, and location.",+ "inputSchema": {"type": "object", "properties": {}},+ },+ {+ "name": "leann_build",+ "description": (+ "Build or incrementally update a LEANN index for a codebase. "+ "If the index already exists, only new/modified/deleted files are processed "+ "(incremental update). Use this to keep the index current after code changes.\n\n"+ "Provide file paths or directories to index. For git repos, pass the output "+ "of 'git ls-files' as individual paths."+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name for the index (e.g., 'my-project'). Defaults to current directory name if omitted.",+ },+ "docs": {+ "type": "array",+ "items": {"type": "string"},+ "description": "List of file paths or directories to index.",+ },+ "backend_name": {+ "type": "string",+ "enum": ["hnsw", "ivf"],+ "default": "ivf",+ "description": "Index backend. 'ivf' supports incremental updates (recommended). 'hnsw' is faster for search but limited incremental support.",+ },+ "force": {+ "type": "boolean",+ "default": False,+ "description": "Force full rebuild instead of incremental update.",+ },+ },+ "required": ["docs"],+ },+ },+ {+ "name": "leann_status",+ "description": (+ "Show detailed status of a LEANN index: backend type, embedding model, "+ "number of chunks, file count, index size, and whether the index is up to date."+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name of the index to inspect.",+ },+ },+ "required": ["index_name"],+ },+ },+]+++def handle_search(request_id, args):+ index_name = args.get("index_name", "")+ query = args.get("query", "")+ if not index_name or not query:+ return _make_result(request_id, "Error: Both index_name and query are required.")++ top_k = args.get("top_k", 5)+ complexity = args.get("complexity", 32)++ rc, stdout, stderr = _run_leann(+ "search",+ index_name,+ query,+ f"--top-k={top_k}",+ f"--complexity={complexity}",+ "--json",+ "--show-metadata",+ "--non-interactive",+ )++ if rc != 0:+ return _make_result(request_id, f"Search failed: {stderr.strip()}")++ # Parse JSON results and format for code context+ try:+ results = json.loads(stdout)+ except json.JSONDecodeError:+ # Fallback to raw output if --json isn't available+ return _make_result(+ request_id, stdout if stdout.strip() else f"Search failed: {stderr.strip()}"+ )++ if not results:+ return _make_result(request_id, f"No results found for '{query}'.")++ formatted = []+ for i, r in enumerate(results, 1):+ meta = r.get("metadata", {})+ file_path = meta.get("file_path") or meta.get("source", "unknown")+ score = r.get("score", 0)+ text = r.get("text", "").strip()+ formatted.append(f"### Result {i} — {file_path} (score: {score:.3f})\n```\n{text}\n```")++ header = f"Found {len(results)} results for '{query}':\n"+ return _make_result(request_id, header + "\n\n".join(formatted))+++def handle_list(request_id):+ rc, stdout, stderr = _run_leann("list")+ if rc != 0:+ return _make_result(request_id, f"Error listing indexes: {stderr.strip()}")+ return _make_result(request_id, stdout)+++def handle_build(request_id, args):+ docs = args.get("docs", [])+ if not docs:+ return _make_result(+ request_id, "Error: 'docs' parameter is required (list of file paths or directories)."+ )++ cmd = ["build"]++ index_name = args.get("index_name")+ if index_name:+ cmd.append(index_name)++ cmd.extend(["--docs", *docs])++ backend = args.get("backend_name", "ivf")+ cmd.extend([f"--backend-name={backend}"])++ if args.get("force", False):+ cmd.append("--force")++ # Auto-detect embedding model from existing index to ensure incremental+ # updates use the same model (avoids mismatch with CLI default).+ if index_name:+ import json as _json+ from pathlib import Path++ meta_path = Path.cwd() / ".leann" / "indexes" / index_name / "documents.leann.meta.json"+ if meta_path.exists():+ try:+ with open(meta_path, encoding="utf-8") as f:+ meta = _json.load(f)+ existing_model = meta.get("embedding_model")+ existing_mode = meta.get("embedding_mode")+ if existing_model:+ cmd.extend([f"--embedding-model={existing_model}"])+ if existing_mode:+ cmd.extend([f"--embedding-mode={existing_mode}"])+ except (OSError, ValueError):+ pass++ rc, stdout, stderr = _run_leann(*cmd, timeout=600)++ if rc != 0:+ return _make_result(request_id, f"Build failed:\n{stderr.strip()}\n{stdout.strip()}")++ return _make_result(request_id, stdout if stdout.strip() else "Build completed successfully.")+++def handle_status(request_id, args):+ index_name = args.get("index_name", "")+ if not index_name:+ return _make_result(request_id, "Error: index_name is required.")++ from pathlib import Path++ # Check standard location+ leann_dir = Path.cwd() / ".leann" / "indexes" / index_name+ meta_path = leann_dir / "documents.leann.meta.json"+ passages_path = leann_dir / "documents.leann.passages.jsonl"++ if not meta_path.exists():+ return _make_result(request_id, f"Index '{index_name}' not found at {leann_dir}")++ try:+ with open(meta_path) as f:+ meta = json.load(f)+ except Exception as e:+ return _make_result(request_id, f"Error reading index metadata: {e}")++ # Count passages+ num_chunks = 0+ file_paths = set()+ if passages_path.exists():+ with open(passages_path) as f:+ for line in f:+ line = line.strip()+ if not line:+ continue+ num_chunks += 1+ try:+ passage = json.loads(line)+ meta = passage.get("metadata", {})+ fp = meta.get("file_path") or meta.get("source", "")+ if fp:+ file_paths.add(fp)+ except json.JSONDecodeError:+ pass++ # Calculate total index size+ total_size = 0+ if leann_dir.exists():+ for f in leann_dir.iterdir():+ if f.is_file():+ total_size += f.stat().st_size++ size_mb = total_size / (1024 * 1024)++ backend = meta.get("backend_name", "unknown")+ embedding_model = meta.get("embedding_model", "unknown")+ embedding_mode = meta.get("embedding_mode", "unknown")+ dimensions = meta.get("dimensions", "unknown")++ status_lines = [+ f"Index: {index_name}",+ f"Backend: {backend}",+ f"Embedding: {embedding_model} ({embedding_mode})",+ f"Dimensions: {dimensions}",+ f"Chunks: {num_chunks}",+ f"Files indexed: {len(file_paths)}",+ f"Size: {size_mb:.1f} MB",+ f"Location: {leann_dir}",+ ]++ return _make_result(request_id, "\n".join(status_lines))++def handle_request(request):- if request.get("method") == "initialize":+ method = request.get("method")+ request_id = request.get("id")++ if method == "initialize":return {"jsonrpc": "2.0",- "id": request.get("id"),+ "id": request_id,"result": {"capabilities": {"tools": {}},"protocolVersion": "2024-11-05",