kb-rag — Local literature RAG with passage-level provenance

English | Chinese

kb-rag is a local literature knowledge base for DSH (DeepSeek Harness) and any MCP-capable agent. It indexes PDFs and Zotero libraries into a single SQLite file, then answers questions with passages rather than paraphrases: every result carries its section, physical PDF page, and a clickable DOI — and every in-text citation in the retrieved passage can be traced back to the referenced work, including whether that work is already in your library.

The npm package dsh-kb-rag is published from npm-package/ in this repository. It is not affiliated with other repositories that share the name dsh-kb-rag.

Indexing, embedding, and reranking all run locally. There is no API cost and no upload.

<a href="#quick-start"><strong>Quick Start</strong></a> · <a href="#three-deployment-shapes"><strong>Deployment shapes</strong></a> · <a href="#tool-reference"><strong>Tool reference</strong></a> · <a href="#documentation"><strong>Documentation</strong></a> · <a href="#measured-performance"><strong>Measured performance</strong></a>

What the output looks like

A single kb_rag call returns evidence in this form. The tool renders its interface in Chinese today, so the block below is that output translated; the in-library marker it prints appears here as [in-library]:

**Knowledge base sources Top-2**
deep · reranked with BAAI/bge-reranker-base · cache hit

1. [Chemical vapour deposition of graphene on copper substrates](https://doi.org/10.5555/12345678) — Author A; Author B · 2024 · Carbon · Results · p.4
> graphene domains nucleate on the copper surface and coalesce into a continuous film ... at a growth rate of ~2 um/min
citations from this evidence ([in-library] = already held, searchable)
  · [Ref 4] Author C, et al. Carbon 48, 1234 (2010)
    [in-library] [Nucleation and growth of graphene on transition metals](https://doi.org/10.5555/12345684) (Author C · 2010 · Carbon) (this evidence's Ref 4) · [open in Zotero](zotero://open-pdf/library/items/EXAMPLEKEY1)
  · 3 further citations collapsed (Ref 6-8); use the numbers to fetch them

**Related work**
- [A Practical Guide to Raman Spectroscopy of Graphene] — Author G et al. · 2020 (same author, related topic)

The full walkthrough, including the agent's answer and the follow-up that resolves a page number, is in docs/OUTPUT-FORMAT.md. The example uses neutral placeholder data: authors, journals, and DOIs are fictional.

Positioning

Retrieval is table stakes; the question is how far a result sits from the original evidence. kb-rag returns a location rather than a summary: section, physical PDF page, clickable DOI, and the citation chain behind the passage.

Three deliberate trade-offs define the project:

…