LEANN

https://github.com/yichuan-w/leann
Admin
LEANN is a vector database that enables personal AI by transforming laptops into RAG systems,...
Tokens:51,117
Snippets:749
Trust Score:9.2
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Setup Environment for Example

Source: https://github.com/yichuan-w/leann/blob/main/docs/metadata_filtering.md

Commands to set up a Python virtual environment and activate it for running the Leann example.

```bash
# Don't forget to set up the environment
uv venv
source .venv/bin/activate
```

--------------------------------

### Quick Install (pip)

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Installs the LEANN package using pip. This is the quickest way to get started if you don't need to build from source.

```bash
pip install leann
```

--------------------------------

### Setup FinanceBench Benchmark

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/financebench/README.md

Downloads Q&A examples, financial PDFs, and builds a LEANN index. Verifies setup with a test query. Use --backend to specify alternative backends like diskann.

```bash
cd benchmarks/financebench
python setup_financebench.py
```

```bash
python setup_financebench.py --backend diskann
```

```bash
python setup_financebench.py --embedding-model facebook/contriever
```

--------------------------------

### Development Setup (from source) - Ubuntu/Debian

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Installs LEANN from source on Ubuntu/Debian systems. Requires installing uv, git submodules, and several apt packages before syncing dependencies.

```bash
# Install uv first (required package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

git submodule update --init --recursive

# Ubuntu/Debian
sudo apt-get install libomp-dev libboost-all-dev protobuf-compiler \
    libabsl-dev libmkl-full-dev libaio-dev libzmq3-dev
uv sync
```

--------------------------------

### Quick Install LEANN from PyPI

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs LEANN using uv after cloning the repository. It sets up a virtual environment and installs the package.

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

--------------------------------

### Development Setup (from source) - Windows

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Installs LEANN from source on Windows. Requires VS 2022 Build Tools, vcpkg, chocolatey, and specific vcpkg installations before syncing dependencies. Environment variables for CMAKE_PREFIX_PATH, PKG_CONFIG_PATH, and OPENBLAS_LIB must be set.

```bash
# Install uv first (required package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

git submodule update --init --recursive

# Windows (requires VS 2022 Build Tools with C++ workload, vcpkg, chocolatey)
choco install cmake swig pkgconfiglite nuget.commandline -y
vcpkg install zeromq:x64-windows openblas:x64-windows lapack:x64-windows boost-program-options:x64-windows protobuf:x64-windows
# Set CMAKE_PREFIX_PATH, PKG_CONFIG_PATH, OPENBLAS_LIB to vcpkg paths (see README)
uv sync --extra diskann
```

--------------------------------

### Development Setup (from source) - macOS

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Installs LEANN from source on macOS. Requires installing uv, git submodules, and several Homebrew packages before syncing dependencies.

```bash
# Install uv first (required package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

git submodule update --init --recursive

# macOS
brew install libomp boost protobuf zeromq pkgconf
uv sync
```

--------------------------------

### Install LEANN Core

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/contextbench/README.md

Installs the LEANN core package using uv.

```bash
uv tool install leann-core --with leann
```

--------------------------------

### Installing and Serving Ollama on Linux

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Install the Ollama service on a Linux system using a script and then start the service manually. This allows for local LLM execution, enhancing privacy.

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service manually
ollama serve &
```

--------------------------------

### Configure LAION Benchmark Setup Options

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/laion/README.md

Configures setup parameters for the LAION benchmark, including sample count, query count, index path, and backend.

```bash
python setup_laion.py \
  --num-samples 10000 \
  --num-queries 200 \
  --index-path data/laion_index.leann \
  --backend hnsw
```

--------------------------------

### Install Pre-commit Linting Tools

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs the tools required for pre-commit linting using uv.

```bash
uv sync --group lint
```

--------------------------------

### Install Test Tools

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Installs testing tools for the project using uv.

```bash
uv sync --group test
```

--------------------------------

### Build LEANN from Source - Initial Setup

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Initial steps for building LEANN from source, including cloning the repository and updating submodules.

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

--------------------------------

### RAG Examples with Thinking Budget

Source: https://github.com/yichuan-w/leann/blob/main/docs/THINKING_BUDGET_FEATURE.md

Shows how to apply the `--thinking-budget` parameter in RAG examples for different LLM backends and models.

```bash
python apps/email_rag.py --llm ollama --llm-model gpt-oss:20b --thinking-budget high
```

```bash
python apps/document_rag.py --llm openai --llm-model o3 --thinking-budget medium
```

--------------------------------

### Install LEANN and Add Claude MCP Integration

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Install LEANN globally and configure it for Claude MCP integration. This setup is required for using LEANN with Claude Code.

```bash
uv tool install leann-core --with leann
claude mcp add --scope user leann-server -- leann_mcp
```

--------------------------------

### Example: Index Business Documents

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Shows how to build an index for a directory containing business reports.

```bash
# Index business documents
python -m apps.colqwen_rag build --pdfs ~/Documents/Reports/ --index reports
```

--------------------------------

### Default LEANN Installation

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann/README.md

Installs LEANN with default HNSW, DiskANN, and IVF backends. Use this for a standard setup.

```bash
uv pip install leann
```

--------------------------------

### Check LEANN Installation

Source: https://github.com/yichuan-w/leann/blob/main/skills/leann-memory/instructions.md

Verify if LEANN is installed on your system. If not, install it using pip.

```bash
which leann
```

```bash
pip install leann-core
```

--------------------------------

### Install uv Package Installer

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs the uv package installer using a curl script. This is a prerequisite for setting up the development environment.

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

--------------------------------

### Install huggingface-hub

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/data/README.md

Install the huggingface-hub library to download datasets. This is a prerequisite for downloading the LEANN-RAG evaluation data.

```bash
pip install huggingface-hub
```

--------------------------------

### Install mitmproxy

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/contextbench/README.md

Installs mitmproxy in a separate virtual environment for HTTP trace recording.

```bash
python3.11 -m venv .mitmproxy-venv
.mitmproxy-venv/bin/python -m pip install mitmproxy
```

--------------------------------

### Install Test Tools

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs only the necessary tools for running tests using uv, without installing project runtime dependencies.

```bash
# Install test tools only (no project runtime)
uv sync --group test
```

--------------------------------

### Start MCP Server and Run LEANN

Source: https://github.com/yichuan-w/leann/blob/main/docs/slack-setup-guide.md

Demonstrates how to start the MCP server in one terminal and then run the LEANN integration in another. This ensures the MCP server is running and accessible before LEANN attempts to connect.

```bash
# Terminal 1: Start MCP server
slack-mcp-server

# Terminal 2: Run LEANN (it will connect to the running server)
python -m apps.slack_rag --mcp-server "slack-mcp-server" --channels general --query "test"
```

--------------------------------

### Basic Usage Examples for Thinking Budget

Source: https://github.com/yichuan-w/leann/blob/main/docs/THINKING_BUDGET_FEATURE.md

Provides examples of using the thinking budget feature with the LEANN CLI for different reasoning effort levels and LLM providers.

```bash
# High reasoning effort for complex questions
leann ask my-index --llm ollama --model gpt-oss:20b --thinking-budget high
```

```bash
# Medium reasoning for balanced performance
leann ask my-index --llm openai --model gpt-4o --thinking-budget medium
```

```bash
# Low reasoning for fast responses
leann ask my-index --llm ollama --model gpt-oss:20b --thinking-budget low
```

--------------------------------

### Create and Activate Python Environment

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/contextbench/README.md

Sets up a Python virtual environment and installs project dependencies.

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r contextbench_official_repo/requirements.txt
pip install -r requirements-run.txt
```

--------------------------------

### Install LEANN IVF Backend

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-ivf/README.md

Install the leann-backend-ivf package using uv or pip. Ensure faiss-cpu is available.

```bash
uv sync --package leann-backend-ivf
# or
pip install leann-backend-ivf
```

--------------------------------

### Run Document RAG Example

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Execute a basic document retrieval augmented generation (RAG) query using default data. This is a good starting point for validating your approach.

```bash
python -m apps.document_rag --query "What techniques does LEANN use?"
```

--------------------------------

### Install Ubuntu/Debian System Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs required system dependencies for Leann development on Ubuntu/Debian systems using apt-get.

```bash
sudo apt-get install libomp-dev libboost-all-dev protobuf-compiler \
                        libabsl-dev libmkl-full-dev libaio-dev libzmq3-dev
```

--------------------------------

### Install Slack MCP Server via npm

Source: https://github.com/yichuan-w/leann/blob/main/docs/slack-setup-guide.md

Install the slack-mcp-server package globally or locally using npm.

```bash
# Install globally
npm install -g slack-mcp-server

# Or install locally
npm install slack-mcp-server
```

--------------------------------

### RAG Examples with Thinking Budget

Source: https://github.com/yichuan-w/leann/blob/main/docs/THINKING_BUDGET_FEATURE.md

Demonstrates the usage of the thinking budget parameter within RAG examples for email and document processing.

```bash
# Email RAG with high reasoning
python apps/email_rag.py --llm ollama --llm-model gpt-oss:20b --thinking-budget high
```

```bash
# Document RAG with medium reasoning
python apps/document_rag.py --llm openai --llm-model gpt-4o --thinking-budget medium
```

--------------------------------

### Install LEANN Core

Source: https://github.com/yichuan-w/leann/blob/main/docs/openclaw-setup.md

Install the LEANN core library using pip or uv tool. This is the first step to integrating LEANN with OpenClaw.

```bash
pip install leann-core
# or
uv tool install leann-core --with leann
```

--------------------------------

### Quick Start: Add LEANN Locally and Build Index

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann-mcp/README.md

Adds the LEANN MCP server locally for the current folder and builds an index for the project. Replace 'my-project' with your project's name.

```bash
# Add locally if you did not add it globally (current folder only; default if --scope is omitted)
claude mcp add leann-server -- leann_mcp

# Build an index for your project (change to your actual path)
# See the advanced examples below for more ways to configure indexing
# Set the index name (replace 'my-project' with your own)
leann build my-project --docs $(git ls-files)

# Start Claude Code
claude
```

--------------------------------

### OpenAI LLM Configuration

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Example of configuring the OpenAI LLM with a specific reasoning model and thinking budget.

```bash
python apps/document_rag.py --query "What are the main techniques LEANN explores?" \
  --index-dir hnswbuild --backend hnsw \
  --llm openai --llm-model o3 --thinking-budget medium
```

--------------------------------

### Activate LEANN Virtual Environment and Check Help

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Activate the LEANN virtual environment and verify the CLI installation by checking the help command.

```bash
source .venv/bin/activate
leann --help
```

--------------------------------

### Install LM Studio SDK (Optional)

Source: https://github.com/yichuan-w/leann/blob/main/docs/faq.md

Install the @lmstudio/sdk package globally using npm. This is optional but provides benefits like automatic context length detection for LM Studio models.

```bash
npm install -g @lmstudio/sdk
```

--------------------------------

### Clone LEANN Repository and Setup

Source: https://github.com/yichuan-w/leann/blob/main/docs/ast_chunking_guide.md

Clones the LEANN repository and initializes its git submodules. This is the first step for developers working from source.

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

--------------------------------

### Start Ollama Service

Source: https://github.com/yichuan-w/leann/blob/main/docs/slack-setup-guide.md

Start the Ollama service either manually or as a background service using Homebrew.

```bash
# Start Ollama as a service
brew services start ollama

# Or start manually
ollama serve
```

--------------------------------

### Setup LAION Benchmark Data

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/laion/README.md

Sets up the benchmark by creating dummy data, generating embeddings, building a LEANN index, and preparing evaluation queries.

```bash
cd benchmarks/laion
python setup_laion.py --num-samples 10000 --num-queries 200
```

--------------------------------

### Document RAG Example

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Runs the Document RAG application to perform a query on documents. This is the easiest example to test.

```python
python -m apps.document_rag --query "What is LEANN?"
```

--------------------------------

### Install Test Dependencies with uv

Source: https://github.com/yichuan-w/leann/blob/main/tests/README.md

Installs only the test dependencies using uv's group feature.

```bash
uv sync --only-group test
```

--------------------------------

### Install macOS System Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs necessary system dependencies for Leann development on macOS using Homebrew.

```bash
brew install llvm libomp boost protobuf zeromq pkgconf
```

--------------------------------

### Install LEANN and OpenClaw Skill

Source: https://github.com/yichuan-w/leann/blob/main/skills/leann-memory/README.md

Install the LEANN core library and the OpenClaw skill using pip and clawhub. Alternatively, manually copy the skill directory.

```bash
pip install leann-core

clawhub install leann-team/leann-memory

# Or manually: copy this directory to ~/.openclaw/workspace/skills/leann-memory/
```

--------------------------------

### Troubleshooting Import Errors

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Commands to ensure all necessary dependencies are installed and to check the PyTorch installation.

```bash
# Ensure all dependencies installed
uv pip install colpali_engine pdf2image pillow matplotlib qwen_vl_utils einops seaborn

# Check PyTorch installation
python -c "import torch; print(torch.__version__)"
```

--------------------------------

### Install LEANN with AST Chunking Support

Source: https://github.com/yichuan-w/leann/blob/main/docs/ast_chunking_guide.md

Installs LEANN in editable mode, including its vendored AST chunking submodule. Use this for development from source.

```bash
uv pip install -e "."
```

--------------------------------

### Install Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Installs necessary Python packages and Poppler for PDF processing on macOS.

```bash
uv pip install colpali_engine pdf2image pillow matplotlib qwen_vl_utils einops seaborn
brew install poppler  # macOS only, for PDF processing
```

--------------------------------

### LEANN Watch Command Example Output

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Example output from the `leann watch` command, illustrating how file changes (modified, added, removed) are reported.

```bash
=== Changes since last checkpoint ===
modified (1):
  - /path/to/file.py
```

--------------------------------

### Ollama LLM Configuration

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Example of configuring the Ollama LLM with a specific reasoning model and thinking budget.

```bash
python apps/document_rag.py --query "What are the main techniques LEANN explores?" \
  --index-dir hnswbuild --backend hnsw \
  --llm ollama --llm-model gpt-oss:20b --thinking-budget high
```

--------------------------------

### Example: Index and Search Research Papers

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Demonstrates indexing a collection of research papers and then searching them for specific questions about AI models.

```bash
# Index your research papers
python -m apps.colqwen_rag build --pdfs ~/Papers/AI/ --index ai_papers

# Ask research questions
python -m apps.colqwen_rag search ai_papers "What are the limitations of transformer models?"
python -m apps.colqwen_rag search ai_papers "How does BERT compare to GPT?"
```

--------------------------------

### LEANN Quick Start: Building and Searching an Index

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann/README.md

Demonstrates how to build a vector index using LeannBuilder and then search it with LeannSearcher. Supports incremental updates with 'ivf' backend.

```python
from leann import LeannBuilder, LeannSearcher, LeannChat
from pathlib import Path
INDEX_PATH = str(Path("./").resolve() / "demo.leann")

# Build an index (choose backend: "hnsw", "diskann", or "ivf" for incremental updates)
builder = LeannBuilder(backend_name="hnsw")  # or "diskann" / "ivf"
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)
```

--------------------------------

### Install Git Pre-commit Hooks

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Installs the git pre-commit hooks to enforce code quality checks before each commit.

```bash
pre-commit install
```

--------------------------------

### Install LEANN Core and Backend

Source: https://github.com/yichuan-w/leann/blob/main/demo.ipynb

Installs the necessary LEANN packages. Use `--no-deps` to avoid dependency conflicts, especially in Colab environments. Sets the LEANN log level to INFO for detailed output.

```python
# install this if you are using colab
! uv pip install leann-core leann-backend-hnsw --no-deps
! uv pip install leann --no-deps
# For Colab environment, we need to set some environment variables
import os

os.environ["LEANN_LOG_LEVEL"] = "INFO"  # Enable more detailed logging
```

--------------------------------

### Build with Document Prompt Template

Source: https://github.com/yichuan-w/leann/blob/main/docs/faq.md

Example of building documentation using a specific prompt template for task-specific embedding models like EmbeddingGemma. Ensure the template format is correct for document processing.

```bash
leann build my-docs --embedding-prompt-template "title: none | text: "
```

--------------------------------

### Install LEANN CLI Globally

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Install the LEANN CLI globally using 'uv tool' to make it accessible from any directory without activating a virtual environment. This is necessary for Claude Code integration.

```bash
uv tool install leann-core --with leann


leann --help
```

--------------------------------

### Run Document RAG with a Query

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Activate the virtual environment and run the document RAG application with a specific query. This is the easiest example to run.

```bash
source .venv/bin/activate
python -m apps.document_rag --query "What are the main techniques LEANN explores?"
```

--------------------------------

### Build LEANN from Source - Windows Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs Windows dependencies for building LEANN from source using Chocolatey and vcpkg.

```powershell
# Install toolchain (if not already present)
choco install cmake swig pkgconfiglite nuget.commandline -y

# Install C++ dependencies via vcpkg
vcpkg install zeromq:x64-windows openblas:x64-windows lapack:x64-windows \
  boost-program-options:x64-windows protobuf:x64-windows
```

--------------------------------

### Code RAG Example

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Runs the Code RAG application to perform a query on a codebase. This example demonstrates codebase search with AST-aware chunking.

```python
python -m apps.code_rag --repo-dir ./src --query "How does search work?"
```

--------------------------------

### Build LEANN from Source - Linux (RHEL/CentOS Stream/etc.) Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs Linux (RHEL/CentOS Stream/etc.) dependencies for building LEANN from source, including optional MKL for DiskANN.

```bash
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y libomp-devel boost-devel protobuf-compiler protobuf-devel \
  abseil-cpp-devel libaio-devel zeromq-devel pkgconf-pkg-config

# For MKL in DiskANN
sudo dnf install -y intel-oneapi-mkl intel-oneapi-mkl-devel \
  intel-oneapi-openmp || sudo dnf install -y intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh

uv sync --extra diskann
```

--------------------------------

### Install WeChat Exporter CLI

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Install the WeChat exporter tool using Homebrew or manually. This is a prerequisite for using the WeChat RAG functionality.

```bash
brew install sunnyyoung/repo/wechattweak-cli
```

```bash
sudo packages/wechat-exporter/wechattweak-cli install
```

--------------------------------

### Example: Multi-faceted Questions

Source: https://github.com/yichuan-w/leann/blob/main/docs/react_agent.md

Use the ReAct agent for questions requiring information from multiple sources. The agent will perform sequential searches to gather and compare data before answering.

```bash
leann react docs-index "What are the differences between HNSW and DiskANN backends, and when should I use each?"
```

--------------------------------

### LEANN CPU-Only Installation (Linux)

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann/README.md

Installs a CPU-only version of LEANN on Linux, specifying PyTorch CPU wheels and a custom index strategy. Useful for environments without GPU support.

```bash
uv pip install \
  --default-index https://download.pytorch.org/whl/cpu \
  --index https://pypi.org/simple \
  --index-strategy first-index \
  "leann[cpu]"
```

--------------------------------

### Install LEANN ClawHub Skill

Source: https://github.com/yichuan-w/leann/blob/main/docs/openclaw-setup.md

Install the LEANN memory skill via ClawHub. This enables the agent to call 'leann search' using shell commands.

```bash
clawhub install leann-team/leann-memory
```

--------------------------------

### Using MLX for Embedding on Apple Silicon

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Example of configuring MLX for embedding on Apple Silicon, noting potential performance trade-offs.

```bash
--embedding-mode mlx --embedding-model mlx-community/Qwen3-Embedding-0.6B-8bit
```

--------------------------------

### Minimal MLX Demo

Source: https://github.com/yichuan-w/leann/blob/main/docs/features.md

A minimal example demonstrating the use of MLX for ultra-fast recompute/build with quantized embedding models.

```python
import mlx.core as mx

def mlx_demo():
    # Example usage of MLX for quantized embedding models
    # This is a placeholder for the actual MLX integration code
    print("MLX demo running...")

if __name__ == "__main__":
    mlx_demo()
```

--------------------------------

### Clone LEANN Repository

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Clones the LEANN GitHub repository and navigates into the project directory. This is the first step for both quick install and building from source.

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

--------------------------------

### Example: Complex Reasoning

Source: https://github.com/yichuan-w/leann/blob/main/docs/react_agent.md

Leverage the ReAct agent for questions that demand complex reasoning and synthesis of information over multiple steps.

```bash
leann react research-index "What are the performance characteristics of different indexing strategies?"
```

--------------------------------

### Run Slack MCP Server with npx

Source: https://github.com/yichuan-w/leann/blob/main/docs/slack-setup-guide.md

Execute the slack-mcp-server directly using npx without prior installation.

```bash
# Use directly without installation
npx slack-mcp-server
```

--------------------------------

### Build LEANN from Source - Linux (Arch Linux) Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs Linux (Arch Linux) dependencies for building LEANN from source, including optional MKL for DiskANN.

```bash
sudo pacman -Syu && sudo pacman -S --needed base-devel cmake pkgconf git gcc \
  boost boost-libs protobuf abseil-cpp libaio zeromq

# For MKL in DiskANN
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin && makepkg -si
paru -S intel-oneapi-mkl intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh

uv sync --extra diskann
```

--------------------------------

### Complete Grep Search Example

Source: https://github.com/yichuan-w/leann/blob/main/docs/grep_search.md

A comprehensive Python script demonstrating LEANN's grep search for finding functions and errors, including initialization and result iteration.

```python
#!/usr/bin/env python3
"""
Grep Search Example
Demonstrates grep search for exact text matching.
"""

from leann.api import LeannSearcher

def demonstrate_grep_search():
    # Initialize searcher
    searcher = LeannSearcher("my_index")

    print("=== Function Search ===")
    functions = searcher.search("def __init__", use_grep=True, top_k=5)
    for i, result in enumerate(functions, 1):
        print(f"{i}. Score: {result.score}")
        print(f"   Preview: {result.text[:60]}...")
        print()

    print("=== Error Search ===")
    errors = searcher.search("FileNotFoundError", use_grep=True, top_k=3)
    for result in errors:
        print(f"Content: {result.text.strip()}")
        print("-" * 40)

if __name__ == "__main__":
    demonstrate_grep_search()
```

--------------------------------

### Interactive Chat CLI

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Starts an interactive chat session with a built LEANN index, allowing for multi-turn conversations.

```bash
leann ask my-docs --interactive
```

--------------------------------

### Quick Start: Build, Search, and Chat with LEANN

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Demonstrates the basic usage of LEANN for building a vector index, performing searches, and engaging in chat interactions with indexed data. Requires LEANN library and specified LLM configuration.

```python
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)
```

--------------------------------

### Build LEANN from Source - macOS Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs macOS dependencies for building LEANN from source, including DiskANN support.

```bash
brew install libomp boost protobuf zeromq pkgconf
uv sync --extra diskann
```

--------------------------------

### Basic Usage: Build, Search, and Ask

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Demonstrates the fundamental commands for building a document index, searching with text queries, and engaging in interactive Q&A.

```bash
# Build index from PDFs
python -m apps.colqwen_rag build --pdfs ./my_papers/ --index research_papers

# Search with text queries
python -m apps.colqwen_rag search research_papers "How does attention mechanism work?"

# Interactive Q&A
python -m apps.colqwen_rag ask research_papers --interactive
```

--------------------------------

### LEANN Quick Start: Chat with Data

Source: https://github.com/yichuan-w/leann/blob/main/packages/leann/README.md

Shows how to use LeannChat to ask questions against your indexed data, configured with a Hugging Face model. Specify 'top_k' for relevance.

```python
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)
```

--------------------------------

### Run Local PDF Multi-Vector Example

Source: https://github.com/yichuan-w/leann/blob/main/apps/multimodal/vision-based-pdf-multi-vector/README.md

Converts a local PDF to page images, builds a HNSW index, and performs searches. Assumes the script is run from the 'apps/multimodal/vision-based-pdf-multi-vector' directory. Downloads a sample PDF if not present.

```bash
cd apps/multimodal/vision-based-pdf-multi-vector
# If you don't have the sample PDF locally, download it (ignored by Git)
mkdir -p pdfs
curl -L -o pdfs/2004.12832v2.pdf https://arxiv.org/pdf/2004.12832.pdf
ls pdfs/2004.12832v2.pdf
# Ensure output dir exists
mkdir -p pages
python multi-vector-leann-paper-example.py
```

--------------------------------

### Build LEANN from Source - Linux (Ubuntu/Debian) Dependencies

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Installs Linux (Ubuntu/Debian) dependencies for building LEANN from source, including DiskANN support. Note potential issues with older Ubuntu versions.

```bash
sudo apt-get update && sudo apt-get install -y \
  libomp-dev libboost-all-dev protobuf-compiler libzmq3-dev \
  pkg-config libabsl-dev libaio-dev libprotobuf-dev \
  libmkl-full-dev

uv sync --extra diskann
```

--------------------------------

### Install Poppler for pdf2image

Source: https://github.com/yichuan-w/leann/blob/main/apps/multimodal/vision-based-pdf-multi-vector/README.md

Installs the Poppler utility using Homebrew, which is required by the pdf2image library for PDF processing. Verifies the installation by checking the pdfinfo version.

```bash
brew install poppler
which pdfinfo && pdfinfo -v
```

--------------------------------

### Example: Iterative Research

Source: https://github.com/yichuan-w/leann/blob/main/docs/react_agent.md

Employ the ReAct agent for questions that benefit from multiple search iterations and query refinement. The agent adapts its search strategy based on intermediate results.

```bash
leann react codebase-index "How does the embedding computation work and what optimizations are used?"
```

--------------------------------

### LAION Benchmark Directory Structure

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/laion/README.md

Outlines the file and directory structure for the LAION benchmark, including setup scripts, evaluation scripts, data files, and the LEANN index.

```text
benchmarks/laion/
├── setup_laion.py           # Setup script
├── evaluate_laion.py        # Evaluation script
├── README.md               # This file
└── data/                   # Generated data
    ├── laion_images/       # Image files (placeholder)
    ├── laion_metadata.jsonl # Image metadata
    ├── laion_passages.jsonl # LEANN passages
    ├── laion_embeddings.npy # CLIP embeddings
    ├── evaluation_queries.jsonl # Evaluation queries
    └── laion_index.leann/  # LEANN index files
```

--------------------------------

### Build LEANN Repo with OpenAI Embeddings

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Build the LEANN repository using OpenAI embeddings, specifying models, prompt templates, and API details. This example is for development purposes.

```bash
source "$LEANN_PATH/.venv/bin/activate" && \
leann build --docs $(git ls-files | grep -Ev '\.(png|jpg|jpeg|gif|yml|yaml|sh|pdf|JPG)$') --embedding-mode openai \
--embedding-model text-embedding-embeddinggemma-300m-qat \
--embedding-prompt-template "title: none | text: " \
--query-prompt-template "task: search result | query: " \
--embedding-api-key local-dev-key \
--embedding-api-base http://localhost:1234/v1 \
--doc-chunk-size 1024 --doc-chunk-overlap 100 \
--code-chunk-size 1024 --code-chunk-overlap 100 \
--ast-chunk-size 1024 --ast-chunk-overlap 100 \
--force --use-ast-chunking --no-compact --no-recompute
```

--------------------------------

### Search with Query Prompt Template

Source: https://github.com/yichuan-w/leann/blob/main/docs/faq.md

Example of searching using a specific prompt template for task-specific embedding models like EmbeddingGemma. Ensure the template format is correct for query processing.

```bash
leann search my-docs --query "your question" --embedding-prompt-template "task: search result | query: "
```

--------------------------------

### Performance Tip: Use ColQwen2 and Save Page Images

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Configuration options for optimizing performance by selecting the ColQwen2 model and saving page images for reuse.

```bash
# Use ColQwen2 for latest features
--model colqwen2

# Save page images for reuse
--pages-dir ./cached_pages/
```

--------------------------------

### Install Ollama using Homebrew

Source: https://github.com/yichuan-w/leann/blob/main/docs/slack-setup-guide.md

Install Ollama on macOS using Homebrew. Alternatively, download from the official website.

```bash
# Install Ollama using Homebrew (macOS)
brew install ollama

# Or download from https://ollama.ai/
```

--------------------------------

### Prepare Repositories with LEANN

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/contextbench/README.md

Prepares repositories and LEANN indexes. Ensure you are in the 'scripts' directory.

```bash
cd scripts
WORK_ROOT=contextbench_work_dir_claude python prepare_repos_with_leann.py
```

--------------------------------

### Build Leann from Source (Ubuntu/Debian)

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Builds Leann from source on Ubuntu/Debian systems by synchronizing packages with uv.

```bash
# Ubuntu/Debian
uv sync
```

--------------------------------

### Troubleshooting PDF Conversion on macOS

Source: https://github.com/yichuan-w/leann/blob/main/docs/COLQWEN_GUIDE.md

Commands to install Poppler and verify its installation for resolving PDF conversion issues on macOS.

```bash
# Install poppler
brew install poppler
which pdfinfo && pdfinfo -v
```

--------------------------------

### Metadata Filter Examples: Comparison Operators

Source: https://github.com/yichuan-w/leann/blob/main/docs/metadata_filtering.md

Provides examples of using comparison operators like '==', '!=', '<', '<=', '>', '>=' for filtering metadata fields.

```python
# Examples
{"chapter": {"==": 1}}           # Exactly chapter 1
{"page": {">": 100}}            # Pages after 100
{"rating": {">=": 4.0}}         # Rating 4.0 or higher
{"word_count": {"<": 500}}      # Short passages
```

--------------------------------

### LEANN CLI with Thinking Budget

Source: https://github.com/yichuan-w/leann/blob/main/docs/THINKING_BUDGET_FEATURE.md

Demonstrates how to use the `--thinking-budget` parameter with the LEANN CLI for Ollama models.

```bash
leann ask my-index --llm ollama --model gpt-oss:20b --thinking-budget high
```

--------------------------------

### Run Similarity Map and Answer Demo

Source: https://github.com/yichuan-w/leann/blob/main/apps/multimodal/vision-based-pdf-multi-vector/README.md

Executes the demo that generates similarity maps and optionally answers questions using Qwen-VL. It can use a default Hugging Face dataset or local PDF pages. Assumes the script is run from the 'apps/multimodal/vision-based-pdf-multi-vector' directory.

```bash
cd apps/multimodal/vision-based-pdf-multi-vector
python multi-vector-leann-similarity-map.py
```

--------------------------------

### Query with Local LM Studio via OpenAI API

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Use the 'leann ask' command to query an index, connecting to a local LM Studio instance that exposes an OpenAI-compatible API. Specify the API base URL and a placeholder API key.

```bash
# Query using a local LM Studio instance via OpenAI-compatible API
leann ask my-notes \
  --llm openai \
  --llm-model qwen3:8b \
  --api-base http://localhost:1234/v1 \
  --api-key local-dev-key
```

--------------------------------

### Install Python Dependencies with uv

Source: https://github.com/yichuan-w/leann/blob/main/apps/multimodal/vision-based-pdf-multi-vector/README.md

Installs necessary Python packages using uv, including colpali_engine, pdf2image, and others for image processing and model utilities. Ensure Python 3.9+ is used.

```bash
uv pip install \
  colpali_engine \
  pdf2image \
  pillow \
  matplotlib qwen_vl_utils \
  einops \
  seaborn
```

--------------------------------

### LEANN Search JSON Output Example

Source: https://github.com/yichuan-w/leann/blob/main/skills/leann-memory/instructions.md

Example of the JSON output format for LEANN search results. Each object contains an ID, relevance score, text content, and metadata including file path and source.

```json
[
  {
    "id": "a1b2c3",
    "score": 0.847,
    "text": "The user decided to use PostgreSQL for the project database...",
    "metadata": {
      "file_path": "/home/user/.openclaw/workspace/memory/2026-02-15.md",
      "source": "memory/2026-02-15.md"
    }
  }
]
```

--------------------------------

### Troubleshoot LEANN PATH Issue

Source: https://github.com/yichuan-w/leann/blob/main/docs/openclaw-setup.md

If 'leann: command not found' error occurs, ensure LEANN is on your system's PATH. If installed via 'uv tool install', run 'uv tool update-shell' and restart the terminal.

```bash
uv tool update-shell
```

--------------------------------

### Clone Leann Repository and Initialize Submodules

Source: https://github.com/yichuan-w/leann/blob/main/docs/CONTRIBUTING.md

Clones the Leann repository and updates its submodules. Navigates into the cloned directory.

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

--------------------------------

### Using Ollama for Embedding

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Example of configuring Ollama for embedding generation, with a note on discovering models.

```bash
--embedding-mode ollama --embedding-model nomic-embed-text
```

--------------------------------

### LEANN Build Command Reference

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Reference for the `leann build` command, detailing its syntax and available options for index creation.

```bash
leann build INDEX_NAME --docs DIRECTORY|FILE [DIRECTORY|FILE ...] [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 / --no-compact     Use compact storage (default: true). Must be `no-compact` for `no-recompute` build.
  --recompute / --no-recompute Enable recomputation (default: true)
```

--------------------------------

### Limiting Dataset Size for Testing

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Example of limiting the number of items processed for faster testing during embedding.

```bash
--max-items 1000  # Process first 1k items only
```

--------------------------------

### List Indexes CLI

Source: https://github.com/yichuan-w/leann/blob/main/CLAUDE.md

Lists all available LEANN indexes on the system.

```bash
leann list
```

--------------------------------

### Basic Command Line Usage

Source: https://github.com/yichuan-w/leann/blob/main/docs/react_agent.md

Execute the ReAct agent from the command line with a specified index and question. You can also customize LLM settings like the provider, model, and iteration limits.

```bash
leann react <index_name> "your question"
```

```bash
leann react my-index "What are the main features discussed?" \
  --llm ollama \
  --model qwen3:8b \
  --max-iterations 5 \
  --top-k 5
```

--------------------------------

### Metadata Filter Examples: Boolean Operators

Source: https://github.com/yichuan-w/leann/blob/main/docs/metadata_filtering.md

Illustrates the usage of boolean operators 'is_true' and 'is_false' for filtering fields based on their truthiness.

```python
# Examples
{"is_published": {"is_true": True}}     # Published content
{"is_draft": {"is_false": False}}       # Not drafts
```

--------------------------------

### Run Multimodal Generation with Qwen2.5-VL

Source: https://github.com/yichuan-w/leann/blob/main/benchmarks/laion/README.md

Executes the multimodal generation stage of the benchmark using the specified Qwen2.5-VL model.

```bash
python evaluate_laion.py --index data/laion_index.leann --stage 5 --model-name Qwen/Qwen2.5-VL-7B-Instruct
```

--------------------------------

### Build ColQwen Index from PDFs

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Build a search index from a directory of PDF files using the ColQwen RAG application.

```bash
python -m apps.colqwen_rag build --pdfs ./my_papers/ --index research_papers
```

--------------------------------

### Add Metadata During Indexing

Source: https://github.com/yichuan-w/leann/blob/main/README.md

Example of adding text with associated metadata during the indexing process. Metadata can include file extensions and lines of code.

```python
# Add metadata during indexing
builder.add_text(
    "def authenticate_user(token): ...",
    metadata={"file_extension": ".py", "lines_of_code": 25}
)
```

--------------------------------

### Global CLI with AST Support

Source: https://github.com/yichuan-w/leann/blob/main/docs/ast_chunking_guide.md

Builds a code index using the global LEANN CLI with AST chunking enabled. Suitable for project-wide indexing.

```bash
leann build my-code-index --docs ./src --use-ast-chunking
```

--------------------------------

### Chat with LEANN using Retrieved Results

Source: https://github.com/yichuan-w/leann/blob/main/demo.ipynb

Sets up a LeannChat instance with a specified language model configuration (Hugging Face model Qwen/Qwen3-0.6B). It then asks a question, leveraging the retrieved documents to generate a response.

```python
from leann.api import LeannChat

llm_config = {
    "type": "hf",
    "model": "Qwen/Qwen3-0.6B",
}

chat = LeannChat(index_path=INDEX_PATH, llm_config=llm_config)
response = chat.ask(
    "Compare the two retrieved programming languages and tell me their advantages.",
    top_k=2,
    llm_kwargs={"max_tokens": 128},
)
response
```

--------------------------------

### Metadata Filter Examples: String Operators

Source: https://github.com/yichuan-w/leann/blob/main/docs/metadata_filtering.md

Shows how to use string operators 'contains', 'starts_with', and 'ends_with' for filtering text-based metadata fields.

```python
# Examples
{"title": {"contains": "alice"}}        # Title contains "alice"
{"filename": {"ends_with": ".py"}}      # Python files
{"author": {"starts_with": "Dr."}}      # Authors with "Dr." prefix
```

--------------------------------

### Build with OpenAI Embeddings

Source: https://github.com/yichuan-w/leann/blob/main/docs/configuration-guide.md

Build an index using OpenAI embeddings for a fast setup with no local GPU requirements. Ensure your OPENAI_API_KEY is exported.

```bash
export OPENAI_API_KEY=sk-...
```

```bash
# Build with OpenAI embeddings
leann build my-index \
  --embedding-mode openai \
  --embedding-model text-embedding-3-small
```

--------------------------------

### Handle Grep Command Not Found Error

Source: https://github.com/yichuan-w/leann/blob/main/docs/grep_search.md

Shows the error message when the grep command is not found and provides installation instructions for different operating systems.

```text
RuntimeError: grep command not found. Please install grep or use semantic search.
```
Tokens:
Raw