Semantic search over your Zotero library
Zoteus index actions, coverage limits, embedding providers, persistence and single-library scope. Advanced reference for configuring search.
For setup and common symptoms, start with search readiness. This page is the advanced reference. The full implementation and operations reference retains detailed diagnostics and implementation history.
Index actions
zotero_index action | Behaviour |
|---|---|
status | Read progress, stored item/passage counts, active embedder, coverage warnings, persistence errors and library version |
build | First build or resume persisted work, including missing vectors; respects the configured item cap |
update | Read changes since the recorded library version; can fall back to a full build when the backend or model changed |
refresh | Start over; repeats extraction and embedding work, potentially including API costs |
stop | Cancel the current job while preserving partial progress |
pause / resume | Persist a hold / clear the hold; resume does not itself start a build |
Builds run in the background. Poll status instead of repeatedly requesting builds. Default ZOTEUS_INDEX_MAX_ITEMS is 5000; a tool limit can lower but cannot raise that cap. Child notes and annotations are included by default. PDF body text is opt-in using fulltext:true or ZOTEUS_INDEX_FULLTEXT=true; the default ZOTEUS_INDEX_FULLTEXT_MAX_CHARS is 40000 per item. A value of 0 removes the text cap, with increased resource use. The source is text Zotero has extracted, not OCR or a complete disk crawl.
Ranking modes
zotero_semantic_search accepts q and mode: auto combines BM25 and vectors when available; keyword uses BM25; semantic requires vectors and an active query embedder. auto_build defaults to true and starts an initial background build when empty. A partially indexed library is only partially searchable.
Use zotero_search_items for exact metadata/filter discovery without a Zoteus index. Read a returned hit with zotero_get_fulltext for the passage and available locator; an index snippet is not a complete evidence check.
Embedding providers
ZOTEUS_EMBEDDINGS | Requirements and data path |
|---|---|
local (default setting) | Requires a separate @huggingface/transformers install and reachable dependency path; embeddings run on the server hosting Zoteus |
openai / gemini | API key configured by the operator; indexed text and queries sent to that provider, potentially billed separately |
off | Deliberate keyword-only ranking |
The desktop bundle omits the local dependency. Follow the supported installation path, then inspect embedderActive and embedderReason. Configuration alone does not establish working vectors. Local embeddings do not keep a cloud AI conversation local.
Storage and library scope
ZOTEUS_INDEX_BACKEND=auto selects SQLite on supported Node runtimes (Node 22.13+), otherwise the memory backend with JSON persistence. Indexes live under ZOTEUS_DATA_DIR; hosted multi-user mode scopes files by authenticated user.
One index file per library. A data directory holds one index file per library: the personal library keeps its file and each other library gets a sibling beside it. zotero_index action:"libraries" lists them, and zotero_semantic_search with libraries searches several at once, merging by rank and labelling each hit with its library. ZOTEUS_INDEX_MAX_OPEN (default 4) bounds how many indexes are open at once, not how many libraries can be indexed.
Configuration reference · Coverage troubleshooting · Missing PDFs