Skip to content

armgit / LEANN

Public Imported from GitHub
0

[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.

Merge remote-tracking branch 'origin/main' into feat/mcp-improvements

yichuan520030910320e3593feb199d
diff --cc docs/CHANGELOG.md
index 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.py
index 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 import
resolve_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.py
index 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 jso
import subprocess
import 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",