Terminal Knowledge Base

Ein rein terminalbasiertes lokales Wissensarchiv zur Verwaltung von PDFs, Markdown-Notizen und Belegen für das wissenschaftliche Schreiben. Es ist nicht auf Obsidian oder Zotero angewiesen und kann direkt über die CLI, Skripte und MCP-Agenten verwendet werden.

Merkmale

• SQLite-FTS5-Volltextsuche, unterstützt Chinesisch und Englisch

• PDF wird seitenweise geparst und liefert citekey, Seitenzahl und Originalausschnitt

• Markdown-Notizen werden rekursiv importiert; stabile Citekeys bleiben erhalten

• BibTeX-Bibliografiedateien und Verzeichnisse für Forschungsentwürfe

• JSON-RPC over stdio MCP Server, an Terminal-Agenten wie Codex anbindbar

• Optionale Vektorindizierung mit LanceDB + Sentence Transformers

• Alle Indizes und Parsing-Ergebnisse sind lokale, neu aufbaubare Dateien

Related MCP server: search-docs

Systemanforderungen

• Linux/macOS

• Python 3.11+

• pdftotext, pdfinfo, pdftoppm (die Installation von poppler wird empfohlen)

Die grundlegende Volltextsuche benötigt keine zusätzlichen Python-Abhängigkeiten. Empfohlen werden eine virtuelle Python-3.12-Umgebung und uv.

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

Optionale Abhängigkeiten:

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

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

Für Nicht-NVIDIA-GPUs:

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

Schnellstart

./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

Häufig verwendete Befehle:

./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

Das Zitierformat für wissenschaftliche Arbeiten lautet: [@citekey, p. 2].

Vorhandene Verzeichnisse importieren

kb add kann Dateien einzeln hinzufügen. Für Massenimporte kann eine Shell verwendet werden:

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-Agent-Anbindung

serve-mcp verwendet stdin/stdout für die JSON-RPC-Übertragung und benötigt kein zusätzliches MCP SDK:

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

Die bereitgestellten Werkzeuge:

• search_library: durchsucht PDF- und Markdown-Belege

• get_passage: liefert einen exakten Auszug mit Seitenzahl

• get_document: zeigt Metadaten und Status von Dokumenten

• get_page_image: rendert PDF-Seiten zur Überprüfung von Formeln, Tabellen und Grafiken

• find_evidence: sucht Belege zu einer These

• index_status: zeigt den Indexstatus

Vektorsuche

Die Vektorindizierung ist eine optionale Funktion und wird in .kb/config.toml aktiviert:

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

Anschließend neu erzeugen:

./kb index --all --force

Beim ersten Lauf wird das Modell von Hugging Face heruntergeladen.

Verifikation

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