在本地索引 PDF 和 Markdown 文件，支持语义搜索和 AI 增强。https://t.co/YQpOntM6tU https://t.co/vjmJfc0yyF

---

joelhooks/pdf-brain

来源：https://github.com/joelhooks/pdf-brain

pdf-brain

本地 PDF 和 Markdown 知识库，支持语义搜索和 AI 增强。

同时支持 PDF 和 Markdown 文件 - 将研究论文、书籍、笔记、文档以及任何 .md 文件索引到统一、可搜索的知识库中。

`` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ PDF / MD │────▶│ Ollama │────▶│ Ollama │────▶│ libSQL │ │ (提取) │ │ (LLM) │ │ (嵌入) │ │ (向量) │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ pdf-parse llama3.2:3b mxbai-embed HNSW 索引

• markdown 增强 1024 维 余弦相似度 ``

功能特性

• PDF + Markdown - 用同一工作流索引 .pdf 和 .md 文件
• 本地优先 - 一切运行在本地机器上，无需 API 费用
• AI 增强 - LLM 提取标题、摘要、标签和概念
• SKOS 分类体系 - 通过层级概念组织文档
• 向量搜索 - 通过 Ollama 嵌入实现语义搜索
• 混合搜索 - 将向量相似度与全文搜索结合
• MCP 服务端 - 可与 Claude、Cursor 等 AI 助手配合使用

快速开始

注意：pdf-brain 以代理优先设计，默认输出单个 JSON 信封到 stdout。 使用 --format text 获取人类可读输出（及 TUI/进度渲染），或通过 pdf-brain capabilities 检查机器接口契约。

``bash

1. 安装（独立二进制，无需运行时）

curl -fsSL https://raw.githubusercontent.com/joelhooks/pdf-brain/main/scripts/install.sh | bash

2. 安装 Ollama（macOS）

brew install ollama

3. 拉取所需模型

ollama pull mxbai-embed-large # 嵌入（必需） ollama pull llama3.2:3b # 增强（可选但推荐）

4. 启动 Ollama

ollama serve

5. 初始化（创建数据库 + 种子分类体系）

pdf-brain init

6. 添加第一个文档

pdf-brain add ~/Documents/paper.pdf –enrich ``

安装

前置条件

Ollama 是嵌入必需的。LLM 模型可选但推荐用于增强。

``bash

macOS

brew install ollama

Linux

curl -fsSL https://ollama.com/install.sh | sh

Windows

从 https://ollama.com/download 下载

``

模型

``bash

必需：嵌入模型（1024 维）

ollama pull mxbai-embed-large

推荐：本地 LLM 用于增强

ollama pull llama3.2:3b

启动 Ollama 服务

ollama serve ``

安装 pdf-brain

``bash

独立二进制（无需运行时）

curl -fsSL https://raw.githubusercontent.com/joelhooks/pdf-brain/main/scripts/install.sh | bash

或者通过 npm

npm install -g pdf-brain ``

CLI 参考

代理输出（默认）

pdf-brain 针对代理工作流优化：默认 stdout 为机器可读格式。

• --format json|ndjson|text（默认：json）
• --pretty 美化打印 JSON
• --quiet（别名：--no-hints）省略 nextActions
• --log-level silent|error|info|debug（日志输出到 stderr）

运行时发现完整的命令/工具契约（包括 JSON Schema）：

bash pdf-brain capabilities

基本命令

``bash

检查 Ollama 状态

pdf-brain check

显示库统计信息

pdf-brain stats

初始化库（创建数据库、种子分类体系）

pdf-brain init ``

添加文档

``bash

添加 PDF

pdf-brain add /path/to/document.pdf

添加 Markdown 文件

pdf-brain add /path/to/notes.md

从 URL 添加（PDF 或 MD）

pdf-brain add https://example.com/paper.pdf pdf-brain add https://raw.githubusercontent.com/user/repo/main/README.md

手动添加标签

pdf-brain add document.pdf –tags “ai,agents,research”

使用 AI 增强（提取标题、摘要、概念）

pdf-brain add document.pdf –enrich pdf-brain add notes.md –enrich ``

搜索

``bash

语义搜索（使用嵌入）

pdf-brain search “context engineering patterns”

仅全文搜索（更快，无需嵌入）

pdf-brain search “context engineering” –fts

混合搜索（两者结合）

pdf-brain search “machine learning” –hybrid

限制结果数

pdf-brain search “query” –limit 5

扩展匹配结果周围上下文

pdf-brain search “query” –expand 500 ``

管理文档

``bash

列出所有文档

pdf-brain list

按标签列出

pdf-brain list –tag ai

获取文档详情

pdf-brain read “document-title”

删除文档

pdf-brain remove “document-title”

更新标签

pdf-brain tag “document-title” “new,tags,here” ``

分类体系命令

分类系统使用 SKOS（简单知识组织系统）进行层级概念组织。

``bash

列出所有概念

pdf-brain taxonomy list

显示概念树

pdf-brain taxonomy tree

显示某个概念下的子树

pdf-brain taxonomy tree programming

搜索概念

pdf-brain taxonomy search “machine learning”

添加新概念

pdf-brain taxonomy add ai/transformers –label “Transformers” –broader ai-ml

为文档分配概念

pdf-brain taxonomy assign “doc-id” “programming/typescript”

从 JSON 文件种子分类体系

pdf-brain taxonomy seed –file data/taxonomy.json ``

批量导入

递归导入包含 PDF 和/或 Markdown 文件的目录：

``bash

使用完整 LLM 增强导入目录

pdf-brain ingest ~/Documents/papers –enrich

导入 Obsidian 仓库或笔记文件夹

pdf-brain ingest ~/Documents/obsidian –enrich

导入多个目录（PDF、Markdown、混合）

pdf-brain ingest ~/papers ~/books ~/notes –enrich

使用手动标签

pdf-brain ingest ~/books –tags “books,reference”

仅自动标签（更快，基于启发式 + 轻量 LLM）

pdf-brain ingest ~/docs –auto-tag

仅处理前 N 个文件（用于测试）

pdf-brain ingest ~/papers –enrich –sample 10

禁用 TUI 以简化输出

pdf-brain ingest ~/papers –enrich –no-tui ``

支持的格式：

• .pdf - 研究论文、书籍、文档
• .md - 笔记、文档、Obsidian 仓库、README

增强

使用 --enrich 添加文档时，LLM 提取以下字段：

字段	描述
title	干净、格式正确的标题
author	作者姓名（如可检测）
summary	2-3 句摘要
documentType	book, paper, tutorial, guide, article 等
category	主要类别
tags	5-10 个描述性标签
concepts	从分类体系中匹配的概念
proposedConcepts	LLM 建议添加的新概念

LLM 提供者

通过配置系统支持多个提供者：

``bash

检查当前配置

pdf-brain config show

使用本地 Ollama（默认）

pdf-brain config set enrichment.provider ollama pdf-brain config set enrichment.model llama3.2:3b

使用 AI Gateway（Anthropic、OpenAI 等）

pdf-brain config set enrichment.provider gateway pdf-brain config set enrichment.model anthropic/claude-haiku-4-5 export AI_GATEWAY_API_KEY=your-key

提供者优先级：配置 > CLI 标志 > 自动检测

pdf-brain add paper.pdf –enrich # 使用配置 pdf-brain add paper.pdf –enrich –provider ollama # 覆盖 ``

增强回退

如果 LLM 增强失败（API 错误、速率限制、响应格式错误），pdf-brain 会自动回退到基于启发式的增强：

• 标题：从文件名清理得到
• 标签：从路径、文件名和内容关键词提取
• 类别：从目录结构推断

实际错误会记录下来，以便调试提供者问题。

分类体系

分类体系是一个层级概念系统，用于组织文档。它附带了一个入门分类体系，涵盖以下领域：

• 编程 - TypeScript、React、Next.js、测试、架构、DevOps、AI/ML
• 教育 - 教学设计、学习科学、课程创建、评估
• 商业 - 营销、文案、自举、产品、销售
• 设计 - 用户体验、视觉设计、系统思考、信息架构
• 元 - 生产力、笔记、知识管理、写作

扩展分类体系

在增强文档时，LLM 可能会提出新概念。这些概念会被保存供审查：

``bash

查看增强中提出的概念

pdf-brain taxonomy proposed

接受特定概念

pdf-brain taxonomy accept ai/rag –broader ai-ml

接受所有提出的概念

pdf-brain taxonomy accept –all

拒绝概念

pdf-brain taxonomy reject ai/rag

清除所有提议

pdf-brain taxonomy clear-proposed

手动添加概念

pdf-brain taxonomy add ai/rag –label “RAG” –broader ai-ml

或编辑 data/taxonomy.json 并重新种子

pdf-brain taxonomy seed –file data/taxonomy.json ``

自定义分类体系

创建自己的 taxonomy.json：

json { "concepts": [ { "id": "cooking", "prefLabel": "Cooking" }, { "id": "cooking/baking", "prefLabel": "Baking" }, { "id": "cooking/grilling", "prefLabel": "Grilling" } ], "hierarchy": [ { "conceptId": "cooking/baking", "broaderId": "cooking" }, { "conceptId": "cooking/grilling", "broaderId": "cooking" } ] }

bash pdf-brain taxonomy seed --file my-taxonomy.json

配置

配置文件

pdf-brain 将配置存储在 $PDF_LIBRARY_PATH/config.json：

``bash

显示所有配置

pdf-brain config show

获取特定值

pdf-brain config get enrichment.provider

设置值

pdf-brain config set enrichment.model anthropic/claude-haiku-4-5 ``

配置选项

json { "ollama": { "host": "http://localhost:11434" }, "embedding": { "provider": "ollama", "model": "mxbai-embed-large" }, "enrichment": { "provider": "gateway", "model": "anthropic/claude-haiku-4-5" }, "judge": { "provider": "gateway", "model": "anthropic/claude-haiku-4-5" } }

设置	默认值	描述
ollama.host	http://localhost:11434	Ollama API 端点
embedding.provider	ollama	嵌入提供者（仅 ollama）
embedding.model	mxbai-embed-large	嵌入模型（1024 维）
enrichment.provider	ollama	LLM 提供者：ollama 或 gateway
enrichment.model	llama3.2:3b	文档增强模型
judge.provider	ollama	概念去重提供者
judge.model	llama3.2:3b	判断重复概念的模型

环境变量

变量	默认值	描述
PDF_LIBRARY_PATH	~/Documents/.pdf-library	库存储位置
OLLAMA_HOST	http://localhost:11434	Ollama API 端点
AI_GATEWAY_API_KEY	-	AI Gateway 的 API 密钥
PDF_BRAIN_LOG_LEVEL	silent	stderr 日志详细程度
PDF_BRAIN_QUERY_EMBED_CACHE_SIZE	256	查询嵌入 LRU 缓存大小（0 表示禁用）

AI Gateway

对于云端 LLM 提供者（Anthropic、OpenAI 等），使用 AI Gateway：

``bash

设置你的 API 密钥

export AI_GATEWAY_API_KEY=your-key

配置使用 gateway

pdf-brain config set enrichment.provider gateway pdf-brain config set enrichment.model anthropic/claude-haiku-4-5

其他支持的模型：

- anthropic/claude-sonnet-4-20250514

- openai/gpt-4o-mini

- openai/gpt-4o

``

存储

~/Documents/.pdf-library/ ├── library.db # libSQL 数据库（向量、FTS、元数据、分类体系） ├── library.db-shm # 共享内存（WAL 模式） ├── library.db-wal # 预写日志 └── downloads/ # 从 URL 下载的 PDF

数据库大小

由于向量索引开销，数据库可能会变得很大。对于约 50 万个分块：

组件	大小	备注
文本内容	~180MB	实际分块文本
嵌入	~1.9GB	500k × 1024 维 × 4 字节
向量索引	~48GB	HNSW 邻居图（约 100KB/行）
FTS 索引	~200MB	全文搜索

*_idx_shadow 表存储 HNSW 邻居图，用于近似最近邻搜索。每行平均约 100KB。

libSQL 怪癖：SELECT COUNT(*) FROM embeddings 返回 0。始终对特定列计数：

sql SELECT COUNT(chunk_id) FROM embeddings -- 正确

工作原理

1. 提取 - 通过 pdf-parse 提取 PDF 文本，Markdown 直接解析
2. 增强（可选）- LLM 提取元数据，匹配分类体系概念
3. 分块 - 文本按约 512 token 分块，带重叠
4. 嵌入 - 每个分块通过 Ollama 嵌入（1024 维）
5. 存储 - libSQL 带向量索引（HNSW）+ FTS5
6. 搜索 - 查询嵌入后通过余弦相似度比较

MCP 集成

pdf-brain 作为 MCP 服务端供 AI 编程助手使用：

json { "mcpServers": { "pdf-brain": { "command": "npx", "args": ["pdf-brain", "mcp"] } } }

文档工具

工具	描述
pdf-brain_add	向库中添加 PDF/Markdown（支持 URL）
pdf-brain_batch_add	从目录批量导入
pdf-brain_search	统一的语义搜索（文档 + 概念）
pdf-brain_list	列出文档，可选按标签过滤
pdf-brain_read	获取文档详情和元数据
pdf-brain_remove	从库中删除文档
pdf-brain_tag	设置文档标签
pdf-brain_stats	库统计信息（文档、分块、嵌入）

分类体系工具

工具	描述
pdf-brain_taxonomy_list	列出所有概念（可选树状格式）
pdf-brain_taxonomy_tree	使用框线绘制可视化概念树
pdf-brain_taxonomy_add	向分类体系添加新概念
pdf-brain_taxonomy_assign	为文档分配概念
pdf-brain_taxonomy_search	按标签搜索概念
pdf-brain_taxonomy_seed	从 JSON 文件加载分类体系

配置工具

工具	描述
pdf-brain_config_show	显示所有配置
pdf-brain_config_get	获取特定配置值
pdf-brain_config_set	设置配置值

实用工具

工具	描述
pdf-brain_check	检查 Ollama 是否就绪
pdf-brain_repair	修复数据库完整性错误

故障排除

“Ollama not available”

``bash

检查 Ollama 是否运行

curl http://localhost:11434/api/tags

启动 Ollama

ollama serve

检查模型

ollama list ``

“Model not found”

``bash

拉取所需模型

ollama pull mxbai-embed-large ollama pull llama3.2:3b ``

“Database locked”

数据库使用 WAL 模式。如果看到锁定错误：

``bash

检查僵尸进程

lsof ~/Documents/.pdf-library/library.db*

强制检查点

sqlite3 ~/Documents/.pdf-library/library.db “PRAGMA wal_checkpoint(TRUNCATE);” ``

增强速度慢

增强是 CPU 密集型操作。对于大批量数据：

• 使用 --auto-tag 替代 --enrich 以获得更快处理
• 在夜间运行大型库的处理
• 考虑为 Ollama 启用 GPU 加速

开发

``bash

克隆

git clone https://github.com/joelhooks/pdf-brain cd pdf-brain

安装

bun install

运行 CLI

bun run src/cli.ts

运行测试

bun test

类型检查

bun run typecheck ``

许可证

MIT