Skip to main content
Glama
terminal_kb

terminal_kb

by xuj1nfan

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: loci-mcp

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

Available Tools

6 tools
find_evidenceB

Find passages relevant to a claim; verify passages before citing.

Inputs: claim (required), limit.

get_documentC

Retrieve document metadata and index status.

Inputs: citekey (required).

get_page_imageB

Render a PDF page for visual verification of formulas, tables, and figures.

Inputs: page (required), citekey (required), dpi.

get_passageB

Retrieve an exact indexed passage with citekey and page metadata.

Inputs: page, citekey, chunk_id.

index_statusA

Show local catalog and index status.

Inputs: no named parameters.

search_libraryC

Search indexed PDF and Markdown evidence.

Inputs: query (required), limit, citekey.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 6 tools

    Disambiguation3/5

    get_passage, get_document, get_page_image, and index_status are clearly distinct, but search_library and find_evidence overlap heavily since both search the same evidence set for relevant passages. The descriptions add some differentiation, but an agent could still easily pick the wrong one for a general search.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern: search_library, get_passage, get_document, get_page_image, find_evidence. The exception is index_status, which is a noun phrase instead of something like get_index_status, but this is only a minor consistency break.

    Tool Count5/5

    Six tools form a tight, well-scoped set for an evidence-retrieval knowledge base. Each tool maps to a specific step in the workflow of searching, retrieving, and verifying evidence, with no unnecessary bloat.

    Completeness4/5

    The core research workflow is covered: search, retrieve passages, inspect page images, check metadata, and monitor index status. Notable gaps are full-document text retrieval and index/database management, but agents can still complete the primary evidence-checking task with the provided tools.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and MCP hosts to query locally indexed notes, docs, chat logs, and other files via hybrid vector/BM25 retrieval with section-level citations. Exposes tools, resources, and prompts for searching and asking over the indexed content.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI hosts and agents to search, ask, and retrieve cited sections from a locally indexed collection of notes, documents, PDFs, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and MCP-compatible hosts to search, ask, and retrieve section-level citations from scattered local notes, docs, PDFs, Word files, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.
      -