Terminal Knowledge Base

A terminal-only local knowledge base for managing PDFs, Markdown notes, and evidence for paper writing. It does not rely on Obsidian or Zotero and can be used directly through the CLI, scripts, and MCP agents.

Features

• SQLite FTS5 full-text search, supporting Chinese and English

• PDFs parsed page by page, returning citekey, page numbers, and original text passages

• Recursive import of Markdown notes, preserving stable citekeys

• BibTeX bibliography files and research draft directories

• JSON-RPC over stdio MCP server, connectable to terminal agents such as Codex

• Optional LanceDB + Sentence Transformers vector indexes

• All indexes and parse results are local, rebuildable files

Related MCP server: search-docs

Environment Requirements

• Linux/macOS

• Python 3.11+

• pdftotext, pdfinfo, pdftoppm (installing poppler is recommended)

Basic full-text search requires no additional Python dependencies. A Python 3.12 virtual environment with uv is recommended.

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

Optional dependencies:

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

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

Non-NVIDIA GPUs:

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

Quick Start

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

Common commands:

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

The paper citation format is: [@citekey, p. 2].

Importing Existing Directories

kb add adds files one at a time. For batch imports, you can use the 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 Agent Integration

serve-mcp uses stdin/stdout for JSON-RPC transport and requires no additional MCP SDK:

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

The tools provided include:

• search_library: search PDF and Markdown evidence

• get_passage: fetch a precise passage with its page number

• get_document: view document metadata and status

• get_page_image: render PDF pages to verify formulas, tables, and figures

• find_evidence: find evidence by claim

• index_status: view indexing status

Vector Retrieval

The vector index is an optional feature, enabled in .kb/config.toml:

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

Then rebuild:

./kb index --all --force

The first run downloads the model from Hugging Face.

Verification

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