How yichuan-w/leann works
Project type and purpose
• LEANN is a full‐stack, open-source vector database and RAG (Retrieval-Augmented Generation) toolkit written in Python with C++/CMake backends.
• Purpose: Provide a lightweight, on-device vector index (HNSW, DiskANN) that stores only a pruned graph and recomputes embeddings on-demand, enabling semantic search and chat over personal data (files, emails, browser history, code, WeChat, etc.) with minimal storage.
File structure
Top-level directories:
• apps/ – Sample RAG applications (document_rag, email_rag, browser_rag, wechat_rag, code_rag)
• packages/
– leann-core/ Core Python library: API (Builder, Searcher, Chat), CLI entry point, registry, metadata filter
– leann-backend-hnsw/ HNSW graph backend (C++ code, embedding server, CSR conversion)
– leann-backend-diskann/ DiskANN backend (third-party DiskANN integration, embedding server)
– leann-mcp/ MCP glue for Claude Code integration
– wechat-exporter/ Helper for exporting WeChat histories
• scripts/ CI & release scripts
• benchmarks/ Performance & storage comparison scripts
• docs/ Guides, architecture overview, configuration
• tests/ Unit & integration tests
Other: README.md, pyproject.toml, .github/workflows for CI.
README for additional insights
• Architecture section describes:
• Graph-based selective recomputation
• High-degree preserving pruning
• Two-level search, dynamic batching
• Technology stack: Python 3.9–3.13, ZeroMQ/Protobuf servers, optional MKL/OpenBLAS, uv CLI, LLM providers (OpenAI, Ollama, HuggingFace).
a. Main components
1. Frontend/CLI & Sample Apps
• CLI (leann command)
• apps/*.py scripts for different data sources
2. Core Library (leann-core)
• LeannBuilder, LeannSearcher, LeannChat
• Registry & plugin loader for backends
• Metadata filter, interface definitions
3. Backends (HNSW, DiskANN)
• Embedding servers (ZeroMQ gRPC, Protobuf)
• Graph storage (CSR files, pruned graph)
• Search algorithms (two-level traversal)
4. Storage
• Index files (.leann/indexes/…)
• Pruned graph + metadata JSON
5. External Services
• Embedding providers (OpenAI API, Ollama, HuggingFace)
• LLM for chat (same providers)
• Data exporters (Apple Mail, Chrome profile, WeChatTweak)
b. Relationships & data flows
• CLI / apps invoke Core API →
• Core API calls Builder/Searcher →
• Builder loads data (documents, emails, browser history, etc.) → chunking & metadata →
• Calls embedding server or remote embedding provider →
• Builds pruned graph → writes index files
• Searcher: loads graph → on query, traverses graph → fetches missing embeddings via recomputation →
• Returns nearest neighbors → Chat wraps results + sends to LLM provider → returns response
c. Architectural patterns & principles
• Plugin architecture for backends (searcher_base, registry)
• Separation of concerns:
– Data ingestion (apps)
– Index building & searching (core)
– Storage (files)
– Compute (local embedding server vs external API)
• Resource efficiency: graph recomputation, CSR storage
d. Key technologies & libraries
• Python packages: leann-core, click (CLI), ZeroMQ, Protobuf
• C++/CMake backends: DiskANN, HNSW implementations
• LLM/embedding: OpenAI, HuggingFace, Ollama
• Build tooling: uv, pyproject.toml
Essential details
• Plugin registry, metadata filtering, AST chunking component in code_rag
• Optional paths (HNSW vs DiskANN) side by side
• How MCP integration plugs into Claude Code via leann-mcp