Terminal Knowledge Base

Локальная база знаний, ориентированная на терминал, для управления PDF-файлами, заметками Markdown и доказательствами при написании научных работ. Она не зависит от Obsidian или Zotero, и работать с ней можно напрямую через CLI, скрипты и MCP-агентов.

Возможности

• Полнотекстовый поиск SQLite FTS5 с поддержкой китайского и английского языков

• Постраничный разбор PDF с возвратом citekey, номера страницы и исходного фрагмента

• Рекурсивный импорт заметок Markdown с сохранением стабильного citekey

• Каталог файлов библиографии BibTeX и исследовательских черновиков

• JSON-RPC over stdio MCP server, который можно подключать к терминальным агентам вроде Codex

• Необязательный векторный индекс LanceDB + Sentence Transformers

• Все индексы и результаты анализа — локальные восстанавливаемые файлы

Related MCP server: search-docs

Требования к окружению

• Linux/macOS

• Python 3.11+

• pdftotext, pdfinfo, pdftoppm (рекомендуется установить poppler)

Для базового полнотекстового поиска не требуются дополнительные зависимости Python. Рекомендуется использовать виртуальное окружение Python 3.12 и uv.

uv python install 3.12
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .

Необязательные зависимости:

# 向量检索（CPU 环境）
uv pip install --python .venv/bin/python lancedb sentence-transformers

# 更复杂的 PDF 版面、表格和公式解析
uv pip install --python .venv/bin/python docling

Для видеокарт, отличных от под управлением NVIDIA:

uv pip install --python .venv/bin/python \
  torch==2.6.0+cpu \
  --index-url https://download.pytorch.org/whl/cpu

Быстрый старт

./kb init
./kb add ~/Books/paper.pdf --title "Paper title" --author "Doe, Jane" --year 2024
./kb add ~/notes/method.md --title "Method notes"
./kb index --all
./kb search "retrieval augmented generation" --limit 5

Часто используемые команды:

./kb status
./kb doctor
./kb show <citekey> --page 2
./kb passage --citekey <citekey> --page 2
./kb cite <citekey> --page 2
./kb page-image <citekey> 2 --dpi 150

Формат цитирования: [@citekey, p. 2].

Импорт существующей директории

kb add добавляет файлы по одному. Для пакетного импорта можно использовать shell:

find ~/Books/final -type f \( -iname '*.pdf' -o -iname '*.md' \) -print0 |
  while IFS= read -r -d '' file; do
    ./kb add "$file"
  done
./kb index --all --force

Подключение MCP-агента

serve-mcp передаёт JSON-RPC через stdin/stdout, дополнительный MCP SDK не требует:

[mcp_servers.terminal_kb]
command = "/absolute/path/to/knowledge-base/kb"
args = ["--root", "/absolute/path/to/knowledge-base", "serve-mcp"]

Предоставляемые инструменты:

• search_library: поиск доказательств в PDF и Markdown

• get_passage: получение точного фрагмента с номером страницы

• get_document: просмотр метаданных и статуса документа

• get_page_image: рендер страницы PDF для проверки формул, таблиц и изображений

• find_evidence: поиск доказательств по утверждению

• index_status: просмотр статуся индекса

Векторный поиск

Векторный индекс — это необязательная функция, которая включается в .kb/config.toml:

enable_vectors = true
embedding_model = "BAAI/bge-small-zh-v1.5"

Затем пересоберите:

./kb index --all --force

При первом запуске модель загружается с Hugging Face.

Проверка

./kb doctor
.venv/bin/python -m unittest discover -s tests -v