把 LEANN 接入 Claude Code，提供本地语义检索增强编码代理

方案简介

方案简介

这是一套以 LEANN 为检索核心、通过 MCP 接入 Claude Code 的本地语义搜索方案。LEANN 被定位为一种面向个人 AI 的向量数据库，能够索引和搜索大规模文档，并通过图结构选择性重计算减少嵌入存储。接入 Claude Code 后，它可以为编码代理提供语义检索能力，补足 Claude Code 原生偏基础的 grep 式关键词搜索。

方案适合希望在笔记本上搜索代码库、个人文档或其他本地知识，并希望保持隐私、避免云端成本的开发者。README 明确将其描述为与 Claude Code 兼容的 drop-in semantic search MCP service，因此目标不是改变既有编码代理工作流，而是为其增加智能检索能力。

亮点与能力

亮点与能力

• 语义代码检索：为 Claude Code 提供语义搜索 MCP 服务，不局限于关键词匹配。
• 本地隐私：数据保留在用户笔记本上，不依赖 OpenAI 或云端服务。
• 低存储占用：通过图结构选择性重计算，不必保存全部嵌入；README 宣称相比传统方案可减少 97% 存储。
• 大规模索引：可索引并搜索数百万份文档，也可用于代码库、邮件、浏览历史、聊天记录和代理记忆等数据。
• 可迁移知识库：知识库可以在设备之间转移，适合构建个人化、可携带的 AI 记忆。
• 编码代理增强：README 给出了与 BM25 对比的 ContextBench 评测，LEANN 在相关代码召回和覆盖率方面表现更高，同时使用更少 token。

组成与分工

组成与分工

• LEANN：负责建立向量索引、执行语义检索，并通过图结构选择性重计算降低嵌入存储开销。它是整个方案的检索引擎。
• MCP：作为 LEANN 与 Claude Code 之间的服务接入方式，使语义搜索能够被编码代理调用。
• Claude Code：作为使用侧的编码代理，消费 LEANN 提供的检索能力，把相关代码更早地放入探索和推理流程中。
• uv：负责创建虚拟环境并安装 LEANN，是 README 给出的安装工具。
• 本地文件与代码库：作为被索引的知识来源。README 明确列出 codebase、file system 以及多种个人数据作为可检索对象。

组合关系是：uv 完成运行环境安装，LEANN 建立本地检索能力，MCP 暴露服务接口，Claude Code 通过该接口进行语义搜索。

前置要求

前置要求

• 需要先安装 uv。README 提供了官方安装脚本。
• 需要能够执行 Git 操作，以克隆 LEANN 仓库。
• 需要准备本地代码库或其他文档数据，作为后续索引和检索对象。
• 如果在 Linux 上使用 CPU-only 方式，README 指定使用 cpu extra。
• 若从源码开发，还需要初始化 Git submodule；macOS 源码构建还要求 macOS 13.3 或更高版本。

安装 uv：

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

获取仓库并安装 PyPI 版本：

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

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

# CPU-only (Linux): use the `cpu` extra (e.g. `leann[cpu]`)

实施步骤

实施步骤

1. 安装 uv

在目标笔记本上执行 README 给出的安装脚本。安装完成后，使当前 shell 能够找到 uv。

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

2. 获取 LEANN 源码

克隆仓库并进入目录。这样既能安装 PyPI 包，也能访问仓库中的示例和 MCP 集成说明。

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

3. 创建环境并安装 LEANN

创建虚拟环境、激活环境，然后安装 LEANN。Linux CPU-only 场景按 README 的说明使用 cpu extra。

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

# CPU-only (Linux): use the `cpu` extra (e.g. `leann[cpu]`)

4. 接入 Claude Code

LEANN 的 Claude Code 集成位于 packages/leann-mcp/README.md。材料明确将其称为 easy setup，但当前提供的 README 片段没有展开具体 MCP 配置命令，因此应按该文件中的原始步骤完成服务注册，不自行改写配置格式。

5. 建立并使用索引

完成 MCP 接入后，使用 LEANN 对目标代码库或本地文档建立索引，再在 Claude Code 中发起需要代码理解、定位或语义查找的任务。索引对象和构建命令未出现在所给材料中，具体参数应以仓库完整文档为准。

使用与配置要点

使用与配置要点

• 检索对象：可以面向 codebase、文件系统、邮件、浏览历史、聊天历史、代理记忆以及 Slack 等 live data；其中 Claude Code 集成的直接目标是改善代码库检索。
• 使用方式：保持 Claude Code 原有工作流，通过 MCP 让代理获得语义搜索，而不是继续只依赖基础关键词扫描。
• 验证方向：可以观察 Claude Code 是否能够通过 LEANN 找到语义相关、但未必包含完全相同关键词的代码；README 的评测方式还包括相关代码召回率、探索后的覆盖率和 token 使用量。
• 隐私检查：该方案的设计目标是数据留在本机，不使用 OpenAI 或云端服务；部署时应将索引和原始数据放在自己的设备上。
• 容量验证：README 给出的规模示例是 6000 万文本片段约需 6GB，而传统方案为 201GB；实际占用仍应根据数据和配置测量。
• 迁移使用：LEANN 支持以较低成本在设备之间转移整个知识库，适合把个人 AI 记忆随设备携带。

注意事项与常见问题

注意事项与常见问题

• Linux 安装失败：如果后续执行 leann build 时出现 Security Violation [pathsec.open]: refusing multiply-linked file，README 建议使用 UV_LINK_MODE=copy 重新安装，原因是 uv 默认的硬链接安装会触发 llama-index 搭载的 nltk 加固文件加载器问题。
• 源码构建的 macOS 要求：DiskANN 要求 macOS 13.3 或更高版本。
• GPU 状态：README 的调查文本明确询问用户是否希望后续获得 GPU Acceleration，不能据此把 GPU 加速当作当前方案的既有能力。
• 评测边界：ContextBench 结果是 30 个 SWE-Bench Pro 任务上的宏平均标注指标；更好的上下文访问并不保证问题一定被解决。
• MCP 配置需看专门文档：当前材料只给出 packages/leann-mcp/README.md 的入口，没有提供完整配置文件内容或启动命令，因此不应凭空补写。
• 社区支持：遇到邀请链接失效或集成问题时，README 建议加入 Slack，或在 GitHub 上提交 issue。

优缺点

• ✓ 本地运行，数据不离开电脑
• ✓ 相比传统方案少占97%存储

出处

本方案挖掘自开源项目 StarTrail-org/LEANN，方案内容与实施命令均来自其 README 原文。