tomevault-io Paper Reference Assistant (CLI)
Entry point skill. Use papi CLI first; MCP RAG tools only when CLI is insufficient.
For specialized workflows, invoke dedicated skills:
/papi-ask— RAG queries requiring synthesis/papi-verify— verify code against paper/papi-compare— compare papers for decision/papi-ground— ground responses with citations/papi-curate— create project notes
Setup
papi path # DB location (default ~/.paperpipe/; override via PAPER_DB_PATH)
papi list # available papers
papi list | grep -i "keyword" # check if paper exists before searching
When NOT to Use MCP RAG
- Paper name known →
papi show <paper> -l summary - Exact term search →
papi search --rg "term" - Checking equations →
papi show <paper> -l eq - Only use RAG when above methods fail or semantic matching required
Decision Tree
| Question | Tool |
|---|---|
| "What does paper X say about Y?" | papi show X -l summary, then papi search --rg "Y" |
| "Does my code match the paper?" | /papi-verify skill |
| "Which paper mentions X?" | papi search --rg "X" first, then leann_search() if no hits |
| "Compare approaches across papers" | /papi-compare skill or papi ask |
| "Need citable quote with page number" | retrieve_chunks() (PQA MCP) |
| "Cross-paper synthesis" | papi ask "..." |
Search Commands
papi search --rg "query" # literal text match (fast, no LLM) — NOT regex by default!
papi search --rg --regex "pattern" # regex patterns (add --regex explicitly)
papi search "query" # ranked BM25
papi search --hybrid "query" # ranked + exact boost
papi search "query" -p paper1,paper2 # limit search to specific papers
papi ask "question" # PaperQA2 RAG
papi ask "question" --backend leann # LEANN RAG
papi notes {name} # open/print implementation notes
Search Escalation (cheapest first)
papi search --rg "X"— exact text, fast, no LLMpapi search "X"— ranked BM25 (requirespapi index --backend searchfirst)papi search --hybrid "X"— ranked + exact boostleann_search()— semantic search, returns file paths for follow-upretrieve_chunks()— formal citations (DOI, page numbers)papi ask "..."— full RAG synthesis
MCP Tool Selection (when papi CLI insufficient)
| Tool | Speed | Output | Best For |
|---|---|---|---|
leann_search(index_name, query, top_k) |
Fast | Snippets + file paths | Exploration, finding which paper to dig into |
retrieve_chunks(query, index_name, k) |
Slower | Chunks + formal citations | Verification, citing specific claims |
papi ask "..." |
Slowest | Synthesized answer | Cross-paper questions, "what does literature say" |
- Check available indexes:
leann_list()orlist_pqa_indexes() - Embedding priority: Voyage AI → Google/Gemini → OpenAI → Ollama
Adding Papers
papi add 2303.13476 # arXiv ID
papi add https://arxiv.org/abs/... # URL
papi add 2303.13476 1706.03762 "Attention Is All You Need" # multiple at once (mixed sources OK)
papi add --pdf /path/to.pdf # local PDF
papi add --pdf "https://..." # PDF from URL
papi add --from-file papers.bib # bulk import
Per-Paper Files
Located at {db}/papers/{name}/: equations.md, summary.md, source.tex, notes.md, paper.pdf, figures/.
If agent can't read ~/.paperpipe/, export to repo: papi export <papers...> --level equations --to ./paper-context/
Use --figures to include extracted figures in export.
See references/commands.md for full command reference and per-file details.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.