Leann – Claude Code–compatible semantic search with 97% smaller vector index

3 months ago 2

The smallest vector index in the world. RAG Everything with LEANN!

LEANN is an innovative vector database that democratizes personal AI. Transform your laptop into a powerful RAG system that can index and search through millions of documents while using 97% less storage than traditional solutions without accuracy loss.

LEANN achieves this through graph-based selective recomputation with high-degree preserving pruning, computing embeddings on-demand instead of storing them all. Illustration Fig → | Paper →

Ready to RAG Everything? Transform your laptop into a personal AI assistant that can semantic search your file system, emails, browser history, chat history, codebase* , or external knowledge bases (i.e., 60M documents) - all on your laptop, with zero cloud costs and complete privacy.

* Claude Code only supports basic grep-style keyword search. LEANN is a drop-in semantic search MCP service fully compatible with Claude Code, unlocking intelligent retrieval without changing your workflow.

The numbers speak for themselves: Index 60 million text chunks in just 6GB instead of 201GB. From emails to browser history, everything fits on your laptop. See detailed benchmarks for different applications below ↓

🔒 Privacy: Your data never leaves your laptop. No OpenAI, no cloud, no "terms of service".

🪶 Lightweight: Graph-based recomputation eliminates heavy embedding storage, while smart graph pruning and CSR format minimize graph storage overhead. Always less storage, less memory usage!

📦 Portable: Transfer your entire knowledge base between devices (even with others) with minimal cost - your personal AI memory travels with you.

📈 Scalability: Handle messy personal data that would crash traditional vector DBs, easily managing your growing personalized data and agent generated memory!

✨ No Accuracy Loss: Maintain the same search quality as heavyweight solutions while using 97% less storage.

📦 Prerequisites: Install uv

Install uv first if you don't have it. Typically, you can install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository to access all examples and try amazing applications,

git clone https://github.com/yichuan-w/LEANN.git leann cd leann

and install LEANN from PyPI to run them immediately:

uv venv source .venv/bin/activate uv pip install leann

🔧 Build from Source (Recommended for development)

git clone https://github.com/yichuan-w/LEANN.git leann cd leann git submodule update --init --recursive

macOS:

brew install llvm libomp boost protobuf zeromq pkgconf CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ uv sync

Linux:

sudo apt-get install libomp-dev libboost-all-dev protobuf-compiler libabsl-dev libmkl-full-dev libaio-dev libzmq3-dev uv sync

Our declarative API makes RAG as easy as writing a config file.

Check out demo.ipynb or

from leann import LeannBuilder, LeannSearcher, LeannChat from pathlib import Path INDEX_PATH = str(Path("./").resolve() / "demo.leann") # Build an index builder = LeannBuilder(backend_name="hnsw") builder.add_text("LEANN saves 97% storage compared to traditional vector databases.") builder.add_text("Tung Tung Tung Sahur called—they need their banana‑crocodile hybrid back") builder.build_index(INDEX_PATH) # Search searcher = LeannSearcher(INDEX_PATH) results = searcher.search("fantastical AI-generated creatures", top_k=1) # Chat with your data chat = LeannChat(INDEX_PATH, llm_config={"type": "hf", "model": "Qwen/Qwen3-0.6B"}) response = chat.ask("How much storage does LEANN save?", top_k=1)

LEANN supports RAG on various data sources including documents (.pdf, .txt, .md), Apple Mail, Google Search History, WeChat, and more.

LEANN supports multiple LLM providers for text generation (OpenAI API, HuggingFace, Ollama).

🔑 OpenAI API Setup (Default)

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

🔧 Ollama Setup (Recommended for full privacy)

macOS:

First, download Ollama for macOS.

# Pull a lightweight model (recommended for consumer hardware) ollama pull llama3.2:1b

Linux:

# Install Ollama curl -fsSL https://ollama.ai/install.sh | sh # Start Ollama service manually ollama serve & # Pull a lightweight model (recommended for consumer hardware) ollama pull llama3.2:1b

LEANN provides flexible parameters for embedding models, search strategies, and data processing to fit your specific needs.

📚 Need configuration best practices? Check our Configuration Guide for detailed optimization tips, model selection advice, and solutions to common issues like slow embeddings or poor search quality.

📋 Click to expand: Common Parameters (Available in All Examples)

All RAG examples share these common parameters. Interactive mode is available in all examples - simply run without --query to start a continuous Q&A session where you can ask multiple questions. Type 'quit' to exit.

# Core Parameters (General preprocessing for all examples) --index-dir DIR # Directory to store the index (default: current directory) --query "YOUR QUESTION" # Single query mode. Omit for interactive chat (type 'quit' to exit), and now you can play with your index interactively --max-items N # Limit data preprocessing (default: -1, process all data) --force-rebuild # Force rebuild index even if it exists # Embedding Parameters --embedding-model MODEL # e.g., facebook/contriever, text-embedding-3-small or mlx-community/multilingual-e5-base-mlx --embedding-mode MODE # sentence-transformers, openai, or mlx # LLM Parameters (Text generation models) --llm TYPE # LLM backend: openai, ollama, or hf (default: openai) --llm-model MODEL # Model name (default: gpt-4o) e.g., gpt-4o-mini, llama3.2:1b, Qwen/Qwen2.5-1.5B-Instruct --thinking-budget LEVEL # Thinking budget for reasoning models: low/medium/high (supported by o3, o3-mini, GPT-Oss:20b, and other reasoning models) # Search Parameters --top-k N # Number of results to retrieve (default: 20) --search-complexity N # Search complexity for graph traversal (default: 32) # Chunking Parameters --chunk-size N # Size of text chunks (default varies by source: 256 for most, 192 for WeChat) --chunk-overlap N # Overlap between chunks (default varies: 25-128 depending on source) # Index Building Parameters --backend-name NAME # Backend to use: hnsw or diskann (default: hnsw) --graph-degree N # Graph degree for index construction (default: 32) --build-complexity N # Build complexity for index construction (default: 64) --no-compact # Disable compact index storage (compact storage IS enabled to save storage by default) --no-recompute # Disable embedding recomputation (recomputation IS enabled to save storage by default)

📄 Personal Data Manager: Process Any Documents (.pdf, .txt, .md)!

Ask questions directly about your personal PDFs, documents, and any directory containing your files!

The example below asks a question about summarizing our paper (uses default data in data/, which is a directory with diverse data sources: two papers, Pride and Prejudice, and a Technical report about LLM in Huawei in Chinese), and this is the easiest example to run here:

source .venv/bin/activate # Don't forget to activate the virtual environment python -m apps.document_rag --query "What are the main techniques LEANN explores?"

📋 Click to expand: Document-Specific Arguments

--data-dir DIR # Directory containing documents to process (default: data) --file-types .ext .ext # Filter by specific file types (optional - all LlamaIndex supported types if omitted)

# Process all documents with larger chunks for academic papers python -m apps.document_rag --data-dir "~/Documents/Papers" --chunk-size 1024 # Filter only markdown and Python files with smaller chunks python -m apps.document_rag --data-dir "./docs" --chunk-size 256 --file-types .md .py

📧 Your Personal Email Secretary: RAG on Apple Mail!

Note: The examples below currently support macOS only. Windows support coming soon.

Before running the example below, you need to grant full disk access to your terminal/VS Code in System Preferences → Privacy & Security → Full Disk Access.

python -m apps.email_rag --query "What's the food I ordered by DoorDash or Uber Eats mostly?"

780K email chunks → 78MB storage. Finally, search your email like you search Google.

📋 Click to expand: Email-Specific Arguments

--mail-path PATH # Path to specific mail directory (auto-detects if omitted) --include-html # Include HTML content in processing (useful for newsletters)

# Search work emails from a specific account python -m apps.email_rag --mail-path "~/Library/Mail/V10/WORK_ACCOUNT" # Find all receipts and order confirmations (includes HTML) python -m apps.email_rag --query "receipt order confirmation invoice" --include-html

📋 Click to expand: Example queries you can try

Once the index is built, you can ask questions like:

"Find emails from my boss about deadlines"
"What did John say about the project timeline?"
"Show me emails about travel expenses"

🔍 Time Machine for the Web: RAG Your Entire Chrome Browser History!

python -m apps.browser_rag --query "Tell me my browser history about machine learning?"

38K browser entries → 6MB storage. Your browser history becomes your personal search engine.

📋 Click to expand: Browser-Specific Arguments

--chrome-profile PATH # Path to Chrome profile directory (auto-detects if omitted)

# Search academic research from your browsing history python -m apps.browser_rag --query "arxiv papers machine learning transformer architecture" # Track competitor analysis across work profile python -m apps.browser_rag --chrome-profile "~/Library/Application Support/Google/Chrome/Work Profile" --max-items 5000

📋 Click to expand: How to find your Chrome profile

The default Chrome profile path is configured for a typical macOS setup. If you need to find your specific Chrome profile:

Open Terminal
Run: ls ~/Library/Application\ Support/Google/Chrome/
Look for folders like "Default", "Profile 1", "Profile 2", etc.
Use the full path as your --chrome-profile argument

Common Chrome profile locations:

macOS: ~/Library/Application Support/Google/Chrome/Default
Linux: ~/.config/google-chrome/Default

💬 Click to expand: Example queries you can try

Once the index is built, you can ask questions like:

"What websites did I visit about machine learning?"
"Find my search history about programming"
"What YouTube videos did I watch recently?"
"Show me websites I visited about travel planning"

💬 WeChat Detective: Unlock Your Golden Memories!

python -m apps.wechat_rag --query "Show me all group chats about weekend plans"

400K messages → 64MB storage Search years of chat history in any language.

🔧 Click to expand: Installation Requirements

First, you need to install the WeChat exporter,

brew install sunnyyoung/repo/wechattweak-cli

or install it manually (if you have issues with Homebrew):

sudo packages/wechat-exporter/wechattweak-cli install

Troubleshooting:

Installation issues: Check the WeChatTweak-CLI issues page
Export errors: If you encounter the error below, try restarting WeChat
Failed to export WeChat data. Please ensure WeChat is running and WeChatTweak is installed. Failed to find or export WeChat data. Exiting.

📋 Click to expand: WeChat-Specific Arguments

--export-dir DIR # Directory to store exported WeChat data (default: wechat_export_direct) --force-export # Force re-export even if data exists

# Search for travel plans discussed in group chats python -m apps.wechat_rag --query "travel plans" --max-items 10000 # Re-export and search recent chats (useful after new messages) python -m apps.wechat_rag --force-export --query "work schedule"

💬 Click to expand: Example queries you can try

Once the index is built, you can ask questions like:

"我想买魔术师约翰逊的球衣，给我一些对应聊天记录?" (Chinese: Show me chat records about buying Magic Johnson's jersey)

🚀 Claude Code Integration: Transform Your Development Workflow!

The future of code assistance is here. Transform your development workflow with LEANN's native MCP integration for Claude Code. Index your entire codebase and get intelligent code assistance directly in your IDE.

Key features:

🔍 Semantic code search across your entire project
📚 Context-aware assistance for debugging and development
🚀 Zero-config setup with automatic language detection

# Install LEANN globally for MCP integration uv tool install leann-core # Setup is automatic - just start using Claude Code!

Try our fully agentic pipeline with auto query rewriting, semantic search planning, and more:

Ready to supercharge your coding? Complete Setup Guide →

🖥️ Command Line Interface

LEANN includes a powerful CLI for document processing and search. Perfect for quick document indexing and interactive chat.

If you followed the Quick Start, leann is already installed in your virtual environment:

source .venv/bin/activate leann --help

To make it globally available:

# Install the LEANN CLI globally using uv tool uv tool install leann # Now you can use leann from anywhere without activating venv leann --help

Note: Global installation is required for Claude Code integration. The leann_mcp server depends on the globally available leann command.

# build from a specific directory, and my_docs is the index name leann build my-docs --docs ./your_documents # Search your documents leann search my-docs "machine learning concepts" # Interactive chat with your documents leann ask my-docs --interactive # List all your indexes leann list

Key CLI features:

Auto-detects document formats (PDF, TXT, MD, DOCX)
Smart text chunking with overlap
Multiple LLM providers (Ollama, OpenAI, HuggingFace)
Organized index storage in ~/.leann/indexes/
Support for advanced search parameters

📋 Click to expand: Complete CLI Reference

Build Command:

leann build INDEX_NAME --docs DIRECTORY [OPTIONS] Options: --backend {hnsw,diskann} Backend to use (default: hnsw) --embedding-model MODEL Embedding model (default: facebook/contriever) --graph-degree N Graph degree (default: 32) --complexity N Build complexity (default: 64) --force Force rebuild existing index --compact Use compact storage (default: true) --recompute Enable recomputation (default: true)

Search Command:

leann search INDEX_NAME QUERY [OPTIONS] Options: --top-k N Number of results (default: 5) --complexity N Search complexity (default: 64) --recompute-embeddings Use recomputation for highest accuracy --pruning-strategy {global,local,proportional}

Ask Command:

leann ask INDEX_NAME [OPTIONS] Options: --llm {ollama,openai,hf} LLM provider (default: ollama) --model MODEL Model name (default: qwen3:8b) --interactive Interactive chat mode --top-k N Retrieval count (default: 20)

🏗️ Architecture & How It Works

The magic: Most vector DBs store every single embedding (expensive). LEANN stores a pruned graph structure (cheap) and recomputes embeddings only when needed (fast).

Core techniques:

Graph-based selective recomputation: Only compute embeddings for nodes in the search path
High-degree preserving pruning: Keep important "hub" nodes while removing redundant connections
Dynamic batching: Efficiently batch embedding computations for GPU utilization
Two-level search: Smart graph traversal that prioritizes promising nodes

Backends: HNSW (default) for most use cases, with optional DiskANN support for billion-scale datasets.

Simple Example: Compare LEANN vs FAISS →

System DPR (2.1M) Wiki (60M) Chat (400K) Email (780K) Browser (38K)

Traditional vector database (e.g., FAISS)	3.8 GB	201 GB	1.8 GB	2.4 GB	130 MB
LEANN	324 MB	6 GB	64 MB	79 MB	6.4 MB
Savings	91%	97%	97%	97%	95%

uv pip install -e ".[dev]" # Install dev dependencies python benchmarks/run_evaluation.py # Will auto-download evaluation data and run benchmarks

The evaluation script downloads data automatically on first run. The last three results were tested with partial personal data, and you can reproduce them with your own data!

If you find Leann useful, please cite:

LEANN: A Low-Storage Vector Index

@misc{wang2025leannlowstoragevectorindex, title={LEANN: A Low-Storage Vector Index}, author={Yichuan Wang and Shu Liu and Zhifei Li and Yongji Wu and Ziming Mao and Yilong Zhao and Xiao Yan and Zhiying Xu and Yang Zhou and Ion Stoica and Sewon Min and Matei Zaharia and Joseph E. Gonzalez}, year={2025}, eprint={2506.08276}, archivePrefix={arXiv}, primaryClass={cs.DB}, url={https://arxiv.org/abs/2506.08276}, }

MIT License - see LICENSE for details.

Core Contributors: Yichuan Wang & Zhifei Li.

We welcome more contributors! Feel free to open issues or submit PRs.

This work is done at Berkeley Sky Computing Lab.

⭐ Star us on GitHub if Leann is useful for your research or applications!

Made with ❤️ by the Leann team

Read Entire Article