[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
Changelog
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-ivfwith FAISS IndexIVFFlat + DirectMap.Hashtable. - IVF supports in-place
add_vectorsandremove_idswithout full rebuild. leann buildis 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_buildMCP tool: build or incrementally update indexes directly from Claude Code. - Added
leann_statusMCP tool: inspect index details (backend, embedding model, chunk/file count, size). leann_searchnow uses--jsonoutput with file paths always included, formatted as markdown code blocks.- Fixed
float32JSON serialization bug inleann search --json. - Cleaned up MCP tool descriptions (concise, no emoji).
2026-03-05: Documentation — roadmap, vision, and dev guidelines
- Rewrote
docs/roadmap.mdwith 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 FAISSivfbackend. Registered as backend nameflashlib_ivf; install viauv sync --extra flashlib-ivforpip install leann-backend-flashlib-ivf. Shares thenlist/nproberecall knobs with theivfbackend, 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-headflashlib_ivf(GPU) vsivf(FAISS, CPU) at matchednlistacross annprobesweep (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.mdgains aflashlib_ivfsection.
2026-07-27: Bounded leann list index discovery
- Bound App-format metadata discovery to a configurable directory depth;
leann listdefaults to depth 5 and accepts--max-depthfor deeper projects. - Prune common dependency, virtual-environment, cache, and system directories during discovery.
- Preserve discovery of registered CLI-format and App-format projects without recursively scanning an entire home directory.
2026-07-29: CI build matrix — Python 3.14 wheels for macOS/Linux (#385)
leann-backend-hnswandleann-backend-diskann0.3.7 only shipped acp314wheel forwin_amd64(the CI build matrix had awindows-2022/ Python 3.14 row but no equivalent for macOS or Linux), and neither package setrequires-python. Resolvers on Python 3.14 (macOS/Linux) selected the release anyway and then failed with a confusing "only has wheels forwin_amd64" error instead of a clear incompatibility message.- Extended
.github/workflows/build-reusable.yml's build matrix with Python 3.14 rows forubuntu-22.04,ubuntu-22.04-arm,macos-14,macos-15, andmacos-26, matching the Windows coverage.macos-15-intel(x86_64) is intentionally excluded, consistent with its existing Python 3.13 exclusion — PyTorch (aleann-coredependency) publishes nomacosx x86_64wheel for either version. - A
requires-pythonupper bound was considered instead but rejected: the bound applies uniformly across platforms, so it would have also blocked the already-working Windowscp314installs. Completing the wheel matrix is the correct fix; the next 0.3.8 patch release will carry fullcp314coverage once CI confirms the new platforms build cleanly.
2026-09-06: Restore CLI parsing after duplicate index command registration
- Remove the seven duplicate index command parsers and handlers introduced by #269 after #285 had already supplied them. This fixes
argparse.ArgumentError: conflicting subparser: index-browser, which prevented every CLI command, including help, from running. - Retain the #285 command interface (
--max-count,--index-name,--no-recompute), application readers, and shared builder; native indexing and standalone wheel reader packaging are unchanged.
2026-09-06: Preserve mixed-script words in BM25 search
- Keep Latin words and numbers separate from adjacent Chinese, Japanese, and Korean n-grams when building SQLite FTS5 indexes and parsing keyword queries. For example,
Python数据库SQLcan be retrieved byPython,SQL, or a mixed-script query. - Existing BM25 artifacts remain readable. Rebuild indexes containing mixed-script text to regenerate tokens that were previously joined at script boundaries.
2026-10-12: Parallel Search MCP web reader (#433)
- Added
apps/parallel_data: anonymous Parallel Search MCP search/fetch (no API key) exported as Markdown named<url-slug>-<hash>.mdforleann build. - Added
apps/parallel_rag.py: one-command web search → chunk → index → ask, keeping each chunk's title and source URL.
2026-10-12: Fit chunk sizes to the embedding model's sequence limit
leann buildnow caps--doc-chunk-size/--code-chunk-sizeat 70% of the embedding model's sequence limit. Previously the macOS default modelall-MiniLM-L6-v2(reads 256 tokens) got 512-token code chunks, so ~43% of indexed code text was never embedded. Onleann-coresources, code retrieval MRR@10 rose from 0.30 to 0.54 (18 queries, realleann buildindexes).get_model_token_limit()readsmax_seq_lengthfrom Hugging Face sentence-transformers repos instead of assuming 2048 tokens for them.create_text_chunks(max_tokens_per_chunk=...)now only shrinkschunk_size; it previously replaced it, growing 256-token chunks to ~1700 for unknown models.- Existing indexes are unchanged; rebuild with
--forceto re-chunk with the new sizes.
2026-10-23: Refuse to load a custom encoder as a vanilla BertModel
jinaai/jina-embeddings-v2-base-code(and any encoder that declares its architecture throughconfig.auto_mapwhile keepingmodel_type="bert") was being loaded withouttrust_remote_code. Transformers silently built a plainBertModelinstead, discarded every weight it could not map, randomly initialised ~70 tensors (all 12 layers' feed-forward and output LayerNorm weights, plus position embeddings), and returned one constant vector for every input. Nothing raised: the index built, search returned results, and the ranking was noise. Measured on an 8-chunk retrieval probe, pairwise chunk cosine similarity was 1.0000 (mean and max) and recall@1 was 0.000; with the model's own code loaded, cosine fell to 0.064 mean / 0.239 max and recall@1 reached 1.000.embedding_compute.pynow checksconfig.auto_mapbefore loading and raises with the model name and the fix, rather than producing a degenerate index. Opt in withLEANN_TRUST_REMOTE_CODE=1; it stays off by default becausetrust_remote_codeexecutes arbitrary Python from the model repository, which matches the existing default inchat.py.- The flag is now threaded through all five
SentenceTransformer(...)call sites in the loader cascade and included in the model cache key. benchmarks/contextbench/scripts/batch_run_random.pyexecutes tasks again. The block had been commented out, and the commented code unpacked four values fromrun_single_task, which has since returned five (patch, latency_seconds, agent_seconds, traj_data, usage) — so uncommenting it would have failed on the unpack. The restored block matchesbatch_run_selected.py, which was already on the current contract, and recordsagent_secondsandlatency_secondsin each result row.