Your current stack

What research-hub gives you first

Zotero + Obsidian

Paper search, Zotero metadata, Markdown notes, tags, Obsidian Bases dashboards

Obsidian + NotebookLM

Local PDF/DOCX/MD/TXT ingest, cluster dashboards, NotebookLM bundles and briefs

Zotero + NotebookLM

Zotero-backed paper selection, namespaced tags, NotebookLM upload/generate/download

Zotero + Obsidian + NotebookLM

Full loop: discover -> ingest -> organize -> brief -> answer -> maintain

No accounts yet

Sample dashboard and local smoke tests before connecting anything

What you can do

Zotero alone

NotebookLM alone

Generic RAG

Obsidian-Zotero plugin

research-hub

Search arXiv + Semantic Scholar in one command

No

No

DIY

No

Yes

Ingest into Zotero and Obsidian and NotebookLM

No

No

DIY

Partial

Yes

AI brief from your collection

No

Manual

DIY

No

Yes

Cached canonical answers

No

No

Re-fetches

No

Yes

Structured memory layer

No

No

Usually chunks

No

Yes

Direct AI-agent control via MCP

No

No

DIY

No

Yes

Live dashboard with action buttons

No

No

No

No

Yes

Per-cluster Obsidian Bases dashboard

No

No

No

No

Yes

No OpenAI/Anthropic API key required

n/a

Yes

Usually no

n/a

Yes

Local-first vault you own

Partial

No

Depends

Yes

Yes

Goal

Accounts needed

Commands

Preview the dashboard only

None

pip install research-hub-pipeline then research-hub dashboard --sample

Try a demo vault

None

pip install research-hub-pipeline then research-hub init --sample

Work from local PDFs/DOCX/Markdown

Obsidian optional

pip install "research-hub-pipeline[import,secrets]" then research-hub setup --persona analyst

Zotero + Obsidian, no browser automation

Zotero

pip install "research-hub-pipeline[secrets]" then research-hub setup --skip-login

Full Zotero + Obsidian + NotebookLM loop

Zotero + Google

pip install "research-hub-pipeline[playwright,secrets]" then research-hub setup

Autonomous agent bootstrap

Existing vault or target folder

python -m research_hub setup --autonomous --vault ./vault --persona agent

Item

Needed when

How to handle it

Python 3.10+

Always

Use the same Python that runs pip install research-hub-pipeline

Zotero API key + library ID

Zotero-backed paper ingestion

Set ZOTERO_API_KEY and ZOTERO_LIBRARY_ID, then run research-hub doctor

Obsidian vault

Markdown note workflow

Point setup at a folder you can open in Obsidian; it is still plain Markdown

NotebookLM browser login

NotebookLM upload/generate/download

Run research-hub notebooklm login --auto-detect; Google OAuth still requires a visible human sign-in

LLM CLI for relevance judging

research-hub auto default path

Install claude, codex, gemini, opencode, aichat, cursor, configure a custom adapter, or pass --no-fit-check

AI-host integration

Claude/Codex/Cursor/Gemini/OpenClaw/etc.

Use MCP/REST for tool-calling hosts; use research-hub install --platform ... only for verified skill installer targets

Name

Required

Purpose

ZOTERO_API_KEY

yes

Zotero web API auth, required for paper ingestion

ZOTERO_LIBRARY_ID

yes

Zotero library identifier

SEMANTIC_SCHOLAR_API_KEY

no

Uses an S2 API key and defaults to a conservative ~1 request/sec throttle

SEMANTIC_SCHOLAR_RPS

no

Optional S2 request-rate override; leave unset unless your key has a different quota

TAVILY_API_KEY

no

Web search backend (alternative to DDG)

BRAVE_API_KEY

no

Web search backend (alternative to DDG)

Persona

Best for

Install extra

Researcher

STEM papers, DOI/arXiv, Zotero-first workflows

[playwright,secrets]

Humanities

books, quotes, URL-only sources, Zotero + Obsidian

[playwright,secrets]

Analyst

industry research, local PDFs/reports, no Zotero required

[import,secrets]

Internal KM

lab/company knowledge bases, mixed file types

[import,secrets]

Layer

Best for

Current status

MCP / REST

Claude Desktop, Claude Code, Cursor, Continue.dev, Cline, Roo Code, VS Code Copilot, OpenClaw, and other tool-calling hosts

Host-agnostic; configure the MCP server or call the REST API

Installed SKILL.md files

Claude Code, Codex, Cursor, Gemini

Built-in installer targets via research-hub install --platform ...

Manual SKILL.md loading

Hermes, OpenClaw, other agents with skill/rules directories

Copy or reference the bundled skill directories manually; not release-verified as installer targets

Tag

Meaning

research-hub

Ingested through this pipeline

cluster/<slug>

Which research cluster the paper belongs to

category/<arxiv-code>

arXiv category like cs.AI or econ.GN

type/<publication-type>

Review, JournalArticle, etc. from Semantic Scholar

src/<backend>

Search backend that discovered it: arxiv, semantic_scholar, crossref, zotero

Capability

Command or MCP tool

Notes

One-shot setup

research-hub setup

init + install + optional NotebookLM login + guided sample run

Lazy research pipeline

research-hub auto "topic" / auto_research_topic

Search, ingest, bundle, upload, generate, download

Authenticity quarantine review

research-hub quarantine list / show <id> / restore <id>

Inspect and optionally restore papers the authenticity gate rejected (with the failing layer + reason)

Plan before running

research-hub plan "intent" / plan_research_workflow

Suggests field, cluster slug, and max papers

Zotero hygiene

research-hub zotero backfill --tags --notes [--apply]

Fills missing tags and notes on legacy items

Cluster cascade delete

research-hub clusters delete <slug> [--apply --force]

Preview impact on Obsidian, Zotero, dedup, memory, and crystals

No-NotebookLM smoke test

research-hub auto "topic" --no-nlm

Validates search and vault ingest without browser automation

Local file ingest

research-hub import-folder <folder> --cluster <slug>

PDF, DOCX, MD, TXT, URL

Ad-hoc cluster Q&A

research-hub ask <cluster> "question" / ask_cluster_notebooklm

Top-level CLI takes cluster first, then question

NotebookLM operations

research-hub notebooklm upload --cluster <slug>

Browser automation with persistent Chrome

Pre-computed crystals

research-hub crystal emit --cluster <slug>

Canonical answers cached as Markdown

Structured memory

research-hub memory emit --cluster <slug>

Entities, claims, methods

Live dashboard

research-hub serve --dashboard

HTTP dashboard with action buttons

Sample preview

research-hub dashboard --sample

Temporary bundled vault, no accounts

Lazy maintenance

research-hub tidy

Doctor, dedup, bases refresh, cleanup preview

Garbage collection

research-hub cleanup --all --apply

Bundles, debug logs, stale artifacts

Cluster repair

research-hub clusters rebind --emit then --apply

Rebinds orphaned notes

Obsidian Bases

research-hub bases emit --cluster <slug>

Generated .base dashboard

Web search

research-hub websearch "query" / web_search

Tavily, Brave, Google CSE, DDG fallback

Symptom

Cause

Fix

research-hub init reports Chrome warnings

Chrome is missing or patchright cannot find it

Install Chrome, then run research-hub doctor

research-hub notebooklm login opens a browser but Google blocks login

New-device or bot challenge

Complete the visible browser sign-in and phone challenge

research-hub auto finds 0 papers / empty vault

Topic too narrow OR papers were quarantined by the authenticity gate (unresolved DOI, failed integrity, or relevance-unjudged)

Re-run with --max-papers 20 / rephrase; run research-hub quarantine list to see rejected papers + reasons

research-hub auto stops before searching: "no relevance judge on PATH"

Fail-closed relevance check and no supported LLM CLI found

Install a judge CLI, or re-run with --no-fit-check to skip relevance judging

NotebookLM upload or generate fails

NotebookLM UI changed or login expired

Run research-hub notebooklm login --auto-detect; then resume with research-hub notebooklm bundle/upload/generate/download --cluster <slug>

notebooklm upload worked yesterday and now fails on auth

Google's __Secure-1PSIDTS / PSIDRTS cookies expire roughly every 3.5h; notebooklm keepalive cannot refresh them server-side

Re-run research-hub notebooklm login --auto-detect — the browser opens, the cookies refresh on sign-in, the session saves automatically (no terminal interaction). Takes < 1 minute

auto --with-crystals cannot find an LLM CLI

No supported LLM CLI is on PATH

Install one, configure a custom adapter, or use crystal emit and crystal apply manually

Claude Desktop cannot see the MCP server

MCP config is in the wrong file or host was not restarted

Check the host config path and restart Claude Desktop

init reports Zotero warnings but you do not use Zotero

Persona expects Zotero

Re-run research-hub setup --persona analyst or --persona internal

research-hub clusters delete refuses to delete

Cluster has papers, notes, or Zotero items

Re-run with --apply --force after reviewing the cascade preview

research-hub auto errors "cluster already has N papers"

Cluster is non-empty and you ran auto --cluster <slug> without a flag

Add --append to add more, or --force to overwrite

Zotero items miss research-hub tags or notes

Items were created before v0.61 or pipeline failed mid-run

research-hub zotero backfill --tags --notes --apply

Limitation

What's actually happening

What to do

IEEE Xplore PDFs / URLs are blocked by anti-bot

IEEE returns an "Unable to Load Page" HTML stub to direct fetches. paper attach-pdfs can now route configured publisher PDF URLs through your institution's EZproxy and fall back to the direct URL if the proxy fails.

Configure ezproxy_url_template, run research-hub ezproxy login once, then re-run paper attach-pdfs. See EZproxy PDF access. Without EZproxy, manually attach the PDF through institutional access or skip the source.

NotebookLM session expires ~every 3.5h

Google's short-lived __Secure-1PSIDTS / PSIDRTS cookies are not refreshable by background polling. notebooklm keepalive exists but cannot rotate them server-side.

Re-run research-hub notebooklm login --auto-detect when a run reports an auth failure — < 1 minute, no terminal interaction.

The no-LLM BM25 gate is designed to catch blatant cross-field contamination (e.g. pure hydrology with zero AI in an LLM cluster). It cannot tell "AI-agents-in-general" from "AI-agents-in-water-resources" — both score similarly on a lexical-only metric, so the gate is recall-biased and keeps both.

For topic-specific subset filtering, use the default LLM-judge path (drop --no-llm-fit-check). The LLM-judge layer is what's designed to make semantic relevance calls.

Cluster-overview LLM auto-fill writes English headings even when the scaffold is Chinese

topic.py writes Chinese section headings (## 核心問題, ## 範圍定義, …) for the empty scaffold, but apply_overview re-renders the file with English headings (## Core Question, ## Scope, …) when the LLM fills it in.

Cosmetic — content is correct. If you prefer Chinese headings on the filled overview, hand-curate the section names after the first auto-fill (the markers ensure subsequent runs preserve your edits).

(CLI is opt-out)

Programmatic callers — tests, library users — get with_pdfs=False by default so the PDF-attach network round-trips don't fire silently. The CLI hands in True from BooleanOptionalAction.

If you call auto_pipeline() directly and want PDFs attached, pass with_pdfs=True explicitly. CLI users get the default-on behaviour automatically; use --no-with-pdfs to opt out.

Slow / blocked publisher URLs sometimes poison the NotebookLM bundle

Some publishers (Wiley paywalls, Frontiers oddly-routed PDFs, IEEE) return either a thin stub or an HTML error page that the bundle ladder admits because the URL pre-check passed. Downstream NotebookLM grounds on the stub instead of the paper.

Run auto and inspect the [warn] N source(s) look like they did not ingest content block. Replace the listed URLs with PDFs uploaded to the NotebookLM web UI for those papers.