内容
# 本地数据库
**指向你的数据。立即搜索 - 从终端，或从你已经使用的任何AI助手。** 笔记，规格，PDF，Word/Excel/PowerPoint文档，EPUB，书签页面 - 只需一次`localdb index`，混合（关键词+语义）搜索即可返回引用的，精确到字节的摘录，毫秒级。 一个二进制文件，无需Python，无需Docker，无需云，无需守护进程即可搜索，无需API密钥。 参见[与其他工具的比较](#比较其他工具)。
长期目标更大：一个私有的，可信赖的替代品 - 你的知识通过你信任的人发现的内容丰富，每次跳转都有出处。 其基础从第一天就建立好了：内容寻址文档，每个区块的出处，存储作为第一类可共享单元。 参见[VISION.md](VISION.md)。
**状态：v0.1.0 预发布。** 混合搜索使用默认的本地模型（`pplx-embed-context-v1-0.6b`，默认为CPU上的ONNX； Apple Silicon macOS上的CoreML ANE/GPU自动启用）；第一次`localdb index`或`localdb search`下载约706 MB来自HuggingFace（无需API密钥）。 HTTP守护进程从与CLI相同的统一数据库中读取和写入；通过`POST /v1/jobs`进行摄取目前是一个空操作。 参见下面的[诚实状态](#诚实状态)。
**许可证：** [AGPL-3.0-or-later](LICENSE).
## 比较其他工具
本地数据库用于从命令行或AI助手进行个人知识搜索，无需云依赖，无需守护进程即可搜索，并且只需安装一个二进制文件 - 无需Python解释器，虚拟环境或Docker Compose栈。 它是代理优先而非聊天优先：CLI和MCP服务器是主要界面，通过Codex，Claude Code，Claude Desktop和Hermes Agent进行实践验证，使用云（Anthropic，OpenAI，DeepSeek）和本地（Gemma）模型提供商。 它已经索引了不仅仅是“你的笔记”：Markdown，纯文本，HTML，PDF，Office文档（DOCX/PPTX/XLSX/XLS/CSV）和EPUB，所有这些都在进程中提取 - 计划下一次连接Notion，电子邮件，聊天和转录。
它故意狭隘 - “做好一件事”：一个可验证的检索原语（索引，搜索，引用），而不是一个全能的聊天应用或团队平台。 这使得其API稳定 enough，以便在其上构建其他东西 - 第二大脑UI或代理自己的实时草稿搜索。 知识图层，MCP管理源/存储的工具以及最终的Web UI都已列入路线图，与此同时 - 更远的是联邦：搜索由你信任的人共享的数据集，比任何一个人单独收集的都要大。 没有被调查的竞争对手解决这个问题。 参见[docs/comparison.md](docs/comparison.md)以获取完整的调查报告，与八个相邻项目进行比较，包括本地数据库落后的地方（无GUI，仅限单节点，MCP只读，无知识图谱 - 参见其“本地数据库落后的地方”部分）。
| 项目 | 单个二进制文件，无运行时 | 无外部服务 | 混合BM25+向量 | 原生MCP服务器 | 结构化引用 |
|---|:---:|:---:|:---:|:---:|:---:|
| **本地数据库** | ✅ | ✅ | ✅ | ✅ | ✅ |
| [GPT4All](https://www.nomic.ai/gpt4all) (LocalDocs) | ✅ | ✅ | ❌ | ❌ | ❌ |
| [Khoj](https://khoj.dev) | ❌ | ⚠️ | ❌ | ❌ | ❌ |
| [Basic Memory](https://basicmemory.com) | ❌ | ✅ | ✅ | ✅ | ❌ |
GPT4All是最常见的比较点（似乎实际上停滞不前 - 13个月以上无提交或发布）；Khoj是最受欢迎的积极维护的自托管替代品（Python，需要`pip`/`uv`/Docker）；Basic Memory是 closest的架构对等 - 原生MCP，本地优先，混合搜索 - 但用读写笔记编辑替换了本地数据库的只读引用库模型，并且仅限于Markdown（无PDF/Office摄取）。 完整的详细信息，来源和注意事项（包括`⚠️`部分标记）都在[docs/comparison.md](docs/comparison.md)。
## 功能亮点
- **可引用的混合搜索** - BM25 + 密集向量（RRF融合）返回结构化的`Citation`对象：文件URI，标题路径，精确文本片段，字节跨度，内容哈希，每个组件的分数和完整的文档元数据。 每个结果都是可验证的。
- **文档元数据** - 从前言中提取的`DocumentMetadata`（Dublin Core：标题，创建者，日期，描述...），并在每个引用上携带，以便代理可以正确地归因来源。
- **本地文件和URL** - `localdb source add ~/notes`或`localdb source add https://example.com/page`；增量重新索引跳过未更改的内容。
- **嵌入式优先** - `localdb search`在进程中打开存储；无需运行任何其他进程。 MCP服务器也以相同的方式工作。
- **MCP服务器** - `localdb mcp`向任何MCP-capable AI助手公开三个只读工具（`search`，`list_stores`，`get_document`）。 连接一次，永久搜索。
- **多个存储** - 每个存储都是隔离的；查询一个或所有存储，使用`--store`。
- **上下文感知密集搜索** - 默认的嵌入器（`pplx-embed-context-v1-0.6b`）是来自Perplexity AI的延迟块模型，它在整个文档的上下文中编码每个块，产生强大的检索质量。 存储为二进制量化的128字节向量（Hamming / IVF_FLAT），在没有GPU的情况下保持索引大小小和搜索速度快。 在Apple Silicon macOS上，二进制文件在Neural Engine / GPU上运行模型通过CoreML自动运行 - 无需`--features`标志。 默认的`local`提供程序在运行时自动选择CoreML，并在否则情况下回落到ONNX（CPU）；两者产生的索引可互换。 模型是公共的MIT版本，因此无需API密钥或许可点击。 替代方案：任何OpenAI兼容的嵌入端点，包括通过llama.cpp或MLX（Apple Silicon，SSD支持的KV缓存）的本地私有模型。
- **libsql后端**：带有DiskANN向量索引和FTS5全文搜索的嵌入式数据库，无需单独的服务器。
- **`--json` everywhere** - 每个命令的机器可读输出。
- **`localdb status`** - 显示索引存储和守护进程状态一目了然。
## 安装
### 从源代码（今天有效）
需要Rust工具链（**Linux：1.82或更高版本；macOS：1.85或更高版本**，因为CoreML是在macOS上自动构建的）。 通过[rustup](https://rustup.rs/)安装。
```bash
git clone https://github.com/dokterbob/localdb
cd localdb
cargo install --path localdb
localdb --version
```
在Apple Silicon macOS上，CoreML（ANE/GPU）加速功能会自动构建 - 无需`--features`标志。 默认的`local`嵌入提供程序在运行时自动选择CoreML，并在否则情况下回落到ONNX（CPU）；由任一后端构建的索引都可查询。
### 预构建的tarballs
| 平台 | Tarball后缀 | 备注 |
|---|---|---|
| macOS Apple Silicon | `aarch64-apple-darwin` | 核心ML（ANE/GPU）内置 - 运行时自动选择 |
| Linux x86_64 | `x86_64-unknown-linux-gnu` | ONNX CPU |
| Linux arm64 | `aarch64-unknown-linux-gnu` | ONNX CPU |
从[Releases](https://github.com/dokterbob/localdb/releases)页面下载并安装：
```bash
# 将VERSION和PLATFORM替换为上表中的值
VERSION=0.1.0
PLATFORM=aarch64-apple-darwin # 或 x86_64-unknown-linux-gnu / aarch64-unknown-linux-gnu
curl -L "https://github.com/dokterbob/localdb/releases/download/v${VERSION}/localdb-v${VERSION}-${PLATFORM}.tar.gz" \
| tar -xz -C /usr/local/bin --strip-components=1 "localdb-v${VERSION}-${PLATFORM}/localdb"
localdb --version
```
参见[docs/release-engineering.md](docs/release-engineering.md)以获取完整的管道详细信息和如何进行发布。
## 60秒快速入门
```bash
# 1. 创建配置文件
localdb init
# 2. 创建存储
localdb store add notes
# 3. 添加源 - 本地目录和/或URL
localdb source add ~/notes --store notes
localdb source add https://example.com/page --store notes # 可选
# 4. 索引
localdb index --store notes
# 5. 检查索引内容
localdb status
# 6. 搜索
localdb search "rust如何处理错误" --store notes
```
步骤6的示例输出（路径显示来自一次从头开始的运行）：
```
1. file:///private/tmp/.../notes/rust-error-handling.md > Rust中的错误处理
Rust中的错误处理
Rust使用Result类型处理可恢复错误，使用panic!处理不可恢复错误。问题-
2. file:///private/tmp/.../notes/meeting.txt
会议 2026-06-02：决定采用互惠秩融合来组合密集和稀疏检索结果。 Aardvark c
3. file:///private/tmp/.../notes/lancedb-notes.md > LanceDB笔记
LanceDB笔记
LanceDB是一个建立在Lance列式格式上的嵌入式向量数据库。它支持混合搜索组合
```
添加`--json`以获取具有块ID，文档ID，来源哈希，每个组件的分数和文档`metadata`字段（标题，创建者，日期等）的结构化`Citation`对象：
```bash
localdb search "混合搜索" --store notes --json
```
## MCP连接
```bash
claude mcp add localdb -- localdb mcp
```
这将`localdb`注册为stdio上的本地MCP服务器。公开了三个只读工具：`search`（返回Citation JSON的混合搜索），`list_stores`（存储名称，文档计数，块计数）和`get_document`（通过文档ID获取完整文档文本和元数据）。
连接后，任何MCP-capable AI助手都可以调用`search`针对索引存储，并返回具有源URI，标题路径和文档元数据的引用摘录 - 基于您文件中的实际段落。
参见[docs/mcp.md](docs/mcp.md)以获取完整的工具模式和示例调用。
## 实验性HTTP守护进程
```bash
localdb serve # 默认绑定到http://127.0.0.1:7700
```
守护进程公开了一个REST API。 它是**实验性的**：通过`POST /v1/jobs`的摄取目前是一个空操作。 守护进程读取和写入与CLI相同的统一数据库，因此CLI索引的数据对它可见。 参见[docs/http-api.md](docs/http-api.md)以获取端点参考和已知限制。
## 诚实状态
| 区域 | 今天的实际情况 |
|---|---|
| 搜索排名 | 混合BM25 + 密集（RRF融合）。 默认嵌入器是`pplx-embed-context-v1-0.6b`（本地ONNX，~706 MB下载后首次使用）。 |
| 嵌入模型 | 在首次`localdb index`或`localdb search`时，从公共HuggingFace仓库`perplexity-ai/pplx-embed-context-v1-0.6b`自动下载。 无需API密钥。 |
| 嵌入后端 | 默认提供程序`local`在CPU上运行ONNX。 在Apple Silicon macOS（Rust ≥1.85）上，macOS二进制文件默认包含CoreML，并在运行时自动选择ANE/GPU后端，否则回落到ONNX。 CoreML/ONNX索引可互换。 强制后端使用`local-coreml` / `local-onnx`。 |
| HTTP守护进程 | 实验性预览。 通过POST /v1/jobs的摄取是一个空操作；读取和写入统一数据库。 |
| YAML声明的存储 | 出现在`store list`中但**无法索引**（`localdb index`仅解析运行时存储）。 使用`localdb store add` + `localdb source add`代替。 |
| CLI同时守护进程运行 | CLI和守护进程可以同时运行。 SQLite WAL和busy_timeout序列化并发写入。 |
文档同步：旧的已知空白项已在代码中解决，并在`docs/architecture.md`中反映。
设计理念和计划行为位于[specs/](specs/)目录中。
## 文档
| 文档 | 内容 |
|---|---|
| [docs/install.md](docs/install.md) | 完整的安装选项，平台说明，shell补全 |
| [docs/comparison.md](docs/comparison.md) | 与GPT4All，Khoj，Basic Memory和其他5个相邻项目的比较 |
| [docs/release-engineering.md](docs/release-engineering.md) | 发布管道，二进制目标，MSRV，如何发布 |
| [docs/quickstart.md](docs/quickstart.md) | 带有真实输出的注释端到端演练 |
| [docs/configuration.md](docs/configuration.md) | YAML配置模式，路径，存储/源选项 |
| [docs/cli.md](docs/cli.md) | 所有命令和标志，退出代码，错误消息 |
| [docs/http-api.md](docs/http-api.md) | REST端点参考，请求/响应形状，限制 |
| [docs/mcp.md](docs/mcp.md) | MCP工具模式，stdio线协议，示例调用 |
| [docs/architecture.md](docs/architecture.md) | 货物布局，存储，搜索管道概述 |
| [specs/01-architecture.md](specs/01-architecture.md) | 工作区布局，嵌入式优先过程模型，存储特征 |
| [specs/02-domain-model.md](specs/02-domain-model.md) | 存储，源，文档，块，块，引用；内容寻址ID |
| [specs/03-config.md](specs/03-config.md) | YAML模式，每个存储的索引策略，配置与运行时状态分离 |
| [specs/04-search-pipeline.md](specs/04-search-pipeline.md) | 摄取，块，嵌入，BM25+密集RRF |
| [specs/05-surfaces.md](specs/05-surfaces.md) | CLI命令树，REST API，MCP工具，错误分类 |
| [specs/06-roadmap.md](specs/06-roadmap.md) | 阶段排序，联合，包装 |
| [VISION.md](VISION.md) | 长期方向：对等存储共享 |
| [skills/localdb/SKILL.md](skills/localdb/SKILL.md) | localdb-aware AI助手的代理技能定义 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发设置，测试门，贡献指南 |
| [docs/design-decisions.md](docs/design-decisions.md) | 带有选项和建议的开放设计问题 |
## 许可证
[AGPL-3.0-or-later](LICENSE). 参见许可证文件以获取完整条款。
