Terminal Knowledge Base

Una base de conocimiento local orientada exclusivamente a la terminal, para gestionar PDF, notas Markdown y pruebas para la escritura de artículos. No depende de Obsidian ni Zotero; puede utilizarse directamente mediante CLI, scripts y agentes MCP.

Características

• Búsqueda de texto completo SQLite FTS5, compatible con chino e inglés

• Analiza el PDF página a página, conservando citekey, número de página y el fragmento original

• Importación recursiva de notas Markdown, manteniendo un citekey estable

• Directorio de archivos bibliográficos BibTeX y borradores de investigación

• Servidor MCP JSON-RPC sobre stdio, conectable a agentes de terminal como Codex

• Índice vectorial opcional con LanceDB + Sentence Transformers

• Todos los índices y resultados de análisis son archivos reconstruibles localmente

Related MCP server: search-docs

Requisitos de entorno

• Linux/macOS

• Python 3.11+

• pdftotext, pdfinfo, pdftoppm (se recomienda instalar poppler)

La búsqueda de texto completo básica no requiere dependencias Python adicionales. Se recomienda un entorno virtual de Python 3.12 y uv.

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

Dependencias opcionales:

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

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

Para GPU que no sean NVIDIA:

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

Inicio rápido

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

Comandos frecuentes:

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

El formato de cita académica es: [@citekey, p. 2].

Importar un directorio existente

kb add permite añadir archivos uno a uno. Para importaciones masivas puede usar el 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

Conexión con el agente MCP

serve-mcp utiliza stdin/stdout para transportar JSON-RPC sin necesidad de un SDK MCP adicional:

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

Las herramientas incluidas:

• search_library: busca evidencia en PDF y Markdown

• get_passage: obtiene fragmentos exactos con el número de página

• get_document: ver los metadatos y el estado del documento

• get_page_image: representar una página de PDF para revisar fórmulas, tablas y gráficos

• find_evidence: encuentra evidencia según una afirmación

• index_status: consulta el estado del índice

Búsqueda vectorial

El índice vectorial es una característica opcional que se habilita en .kb/config.toml:

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

A continuación hay que reconstruirlo:

./kb index --all --force

La primera ejecución descarga el modelo desde Hugging Face.

Verificación

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