papi

// CLI reference for paperpipe (papi). Use BEFORE MCP RAG tools. For listing, searching, showing, adding papers.

$ git log --oneline --stat

stars:8

forks:2

updated:March 1, 2026

SKILL.mdreadonly

SKILL.md Frontmatter

namepapi

descriptionThis skill should be used when the user wants to interact with their paper database — listing papers, searching content, showing paper details, adding papers, or exporting context. Matches queries like "search papers for X", "add this arXiv paper", "show equations from paper Y", "what papers do I have". Prefer CLI over MCP RAG tools for direct lookups.

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 LLM
papi search "X" — ranked BM25 (requires papi index --backend search first)
papi search --hybrid "X" — ranked + exact boost
leann_search() — semantic search, returns file paths for follow-up
retrieve_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() or list_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.