pdf-brain

PDF 및 Markdown 통합 인덱싱

pdf-brain은 PDF와 Markdown 파일을 동일한 워크플로우로 인덱싱하여 하나의 통합된 지식 베이스에서 검색할 수 있도록 지원합니다. PDF 텍스트 추출에는 pdf-parse를 사용하고, Markdown은 직접 파싱합니다.

로컬 우선 AI enrichment

–enrich 플래그를 사용하면 Ollama 기반 LLM(기본값: llama3.2:3b)이 문서에서 제목, 저자, 요약, 문서 유형, 카테고리, 태그, 개념 등을 추출하여 메타데이터를 enrichment합니다. LLM 사용이 불가능할 경우 heuristic 기반 폴백 메커니즘이 작동합니다.

의미 검색 및 하이브리드 검색

텍스트는 ~512 토큰 청크로 분할되어 Ollama의 mxbai-embed-large 모델로 1024차원 벡터 임베딩을 생성하고, libSQL의 HNSW 벡터 인덱스에 저장됩니다. 사용자는 의미 검색(–hybrid), 전체 텍스트 검색(–fts), 또는 두 가지를 결합한 하이브리드 검색을 수행할 수 있습니다.

SKOS 기반 택소노미 시스템

pdf-brain은 SKOS(Simple Knowledge Organization System)를 기반으로 한 계층적 개념 체계를 제공하여 문서를 주제별로 분류하고 조직할 수 있습니다. 기본 택소노미에는 프로그래밍, 교육, 비즈니스, 디자인, 메타 카테고리가 포함되며, 사용자는 자신만의 택소노미를 정의하거나 LLM이 제안한 개념을 수락/거부할 수 있습니다.

MCP 서버 통합

pdf-brain은 MCP(Model Context Protocol) 서버로 작동하여 Claude, Cursor 등의 AI 코딩 어시스턴트와 연동할 수 있습니다. 이를 통해 AI가 사용자의 로컬 문서 라이브러리를 컨텍스트로 활용할 수 있습니다.

다운로드·설치 방법

pdf-brain은 독립 실행형 바이너리로 제공되며, 별도의 런타임이 필요하지 않습니다. 다음 명령어로 설치할 수 있습니다:

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

또는 npm을 통해 전역 설치도 가능합니다:

npm install -g pdf-brain

기본 사용법/명령어

설치 후 Ollama를 설치하고 필요한 모델을 pull해야 합니다. Ollama는 공식 웹사이트에서 Windows용 설치 프로그램을 다운로드할 수 있습니다.

필수 모델:

ollama pull mxbai-embed-large

선택적 enrichment 모델:

ollama pull llama3.2:3b

Ollama 서버를 시작합니다:

ollama serve

그런 다음 pdf-brain을 초기화하고 문서를 추가할 수 있습니다:

pdf-brain init
pdf-brain add ~/Documents/paper.pdf --enrich

기본적으로 pdf-brain은 에이전트 워크플로우에 최적화된 JSON 형태의 머신 리더블 출력을 내보냅니다. 사람이 읽기 쉬운 출력을 원한다면 –format text 플래그를 사용합니다.

이런 경우에 유용합니다

연구자나 학생이 다수의 PDF 논문과 Markdown 노트를 보유하고 있을 때, pdf-brain을 사용하면 파일을 폴더별로 나누어 관리하는 대신 내용 기반으로 의미 검색을 통해 원하는 정보를 빠르게 찾을 수 있습니다. 예를 들어 “맥락 공학 패턴”과 같은 개념을 검색하면 관련 논문과 노트의 내용을 의미적으로 유사도 기준으로 순위를 매겨 보여줍니다.

또한 AI 코딩 어시스턴트를 사용하는 개발자는 pdf-brain을 MCP 서버로 설정하여 자신의 로컬 문서 라이브러리를 AI의 컨텍스트로 제공할 수 있어, 코딩 중 관련 설계 문서나 연구 자료를 즉시 참조할 수 있습니다.

지원 환경·시스템 요구사항

pdf-brain은 Windows, macOS, Linux에서 실행 가능하며, 핵심 기능인 벡터 임베딩과 enrichment를 위해 Ollama가 필수입니다. enrichment용 LLM 모델은 선택 사항이지만 권장됩니다. 저장소는 기본적으로 ~/Documents/.pdf-library에 libSQL 데이터베이스와 다운로드된 PDF 파일을 저장합니다.

최신 버전·업데이트

현재 버전은 2.0.0이며, 공식 저장소의 README 및リリース 노트에서 업데이트 내역을 확인할 수 있습니다.

제한 사항·확인 사항

벡터 인덱스(HNSW)는 문서 청크 수가 증가함에 따라 디스크 공간을 크게 차지할 수 있습니다. 예를 들어 50만 개의 텍스트 청크에 대해 약 48GB의 벡터 인덱스 공간이 필요할 수 있습니다. 이는 약 100KB per row의 이웃 그래프 저장소 특성 때문입니다.

libSQL의 특성상 SELECT COUNT(*) FROM embeddings 쿼리는 0을 반환하므로, 정확한 임베딩 개수를 확인하려면 SELECT COUNT(chunk_id) FROM embeddings 와 같이 특정 컬럼을 기준으로 카운트해야 합니다.

FAQ

• pdf-brain은 무료인가요?

  네, pdf-brain은 MIT 라이선스 하에 배포되는 오픈소스 소프트웨어입니다.

• Windows에서 사용할 수 있나요?

  네, pdf-brain은 Windows를 지원하며, Ollama의 Windows용 설치 프로그램을 사용해 필수 의존성을 충족할 수 있습니다.

• 인터넷 연결이 필수인가요?

  아니요, pdf-brain은 로컬 우선 도구로 설계되어 Ollama 모델을 로컬에 pull하고 서버를 실행한 후에는 인터넷 연결 없이도 전체 기능을 사용할 수 있습니다. 단, 초기 모델 다운로드와 enrichment를 위한 LLM 제공자 설정 시에는 인터넷이 필요할 수 있습니다.