Skip to content
Back to search

ZotSeek

AI semantic search for Zotero, with a built-in MCP server for AI agents (Claude Code, Codex). Find papers by meaning. 100% local and private.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/introfini/ZotSeek with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/introfini/ZotSeek'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/introfini--zotseek/badge.svg)](/listings/introfini--zotseek)

HTML

<a href="/listings/introfini--zotseek"><img src="/api/listings/introfini--zotseek/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For Users

**Requirements:** Zotero 8.0 or newer (Zotero 9 and Zotero 10 supported).

1. Download the latest `zotseek-X.Y.Z.xpi` from the [Releases page](https://github.com/introfini/ZotSeek/releases/latest). 2. In Zotero, open **Tools → Plugins**. 3. Click the gear icon (⚙️) in the top-right and choose **Install Plugin From File…** 4. Select the downloaded `.xpi` file. 5. Restart Zotero when prompted.

After installation, ZotSeek is ready to use — open **Zotero → Settings → ZotSeek** to configure it, then right-click a collection and choose **ZotSeek → "Update Entire Library"** to build your index.

**Updating:** ZotSeek checks for updates automatically. New releases are delivered through Zotero's built-in plugin update mechanism, so you'll be notified when a new version is available.

For Developers

# Clone the repository
git clone https://github.com/introfini/ZotSeek
cd zotseek

# Install dependencies (includes zotero-plugin-toolkit for stable progress windows)
npm install

# Build the plugin
npm run build

# Create extension proxy file (macOS)
echo "$(pwd)/build" > ~/Library/Application\ Support/Zotero/Profiles/*.default/extensions/zotseek@zotero.org

# Restart Zotero with debug console
open -a Zotero --args -purgecaches -ZoteroDebugText -jsconsole

Building a Distributable XPI

npm run release

The interactive release script bumps the version, syncs `manifest.json` and `update.json`, rebuilds, and packages `zotseek-X.Y.Z.xpi` at the project root.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 935 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ZotSeek | AI-Powered Semantic Search & MCP Server for Zotero
  2. Find similar papers by **meaning**, not just keywords. 100% local, no data leaves your machine. Now with a built-in **MCP server** for AI agents.
  3. > **Status:** ✅ Stable release · Zotero 8, 9 & 10 · Transformers.js running locally
  4. >
  5. > **New:** 🤖 **MCP server built in** — Claude Code, Codex, and any MCP client can search your library and cite papers with links that open straight to the matched PDF page. Fully local, read-only, opt-in. [Set it up in one line →](docs/MCP.md)
  6. >
  7. > **New from the same author:** 🔎 [**citefact**](https://github.com/hearthresearch/citefact) — audit your manuscript against your Zotero library: citations exist, quotes are verbatim, claims are supported.
  8. ![ZotSeek Search Dialog](docs/images/search-dialog-by-section-hover.png)
  9. ---
  10. ## Features
  11. - 🔒 **100% Local** - No data sent to cloud, works completely offline
  12. - 🧠 **True Semantic Search** - Find papers by meaning, not just keywords
  13. - 🤖 **AI Agent Access (MCP)** - Let Claude Code and other MCP clients search your library, fully local and opt-in ([docs](docs/MCP.md))
  14. - 🔍 **Find Similar Documents** - Right-click any paper → discover related research
  15. - 📖 **Search from PDF Selection** - Select text while reading → right-click → find documents about that concept
  16. - 🔎 **Natural Language Search** - Search with queries like "machine learning in healthcare"
  17. - 🔀 **Multi-Query Search** - Combine up to 4 queries with AND/OR logic to find topic intersections
  18. - 📝 **Your Notes, Searched Too** - Optionally index the text of notes attached to an item, so what you wrote is findable alongside the paper itself; off by default, and existing items are back-filled on demand
  19. - 🕘 **Recent Searches** - The search window remembers your last 10 queries, so you can go back to a phrasing that worked; clear the list from the dropdown at any time
  20. - 🔗 **Hybrid Search** - Combines AI and keyword search, with the keyword half reading PDF text and note content, not just titles and tags
  21. - ⚡ **Lightning Fast** - Searches complete in <100ms
  22. - 📑 **Section-Aware** - See where each match came from (Abstract, Methods, Results, or one of your notes)
  23. - 📄 **Matched-Passage Preview** - Hover a result to read the exact passage that matched, with query terms highlighted
  24. - 📍 **Passage-Level Location** - Jump to exact page & paragraph in Full Document mode
  25. - ✅ **Multi-Select in Results** - Select multiple search results, right-click to add to collections
  26. - 📁 **Save Results as Collection** - One click saves the full result set into a new Zotero collection so you can revisit the list later without re-running the search
  27. - 🧩 **Selectable Embedding Models** - Choose from 4 curated local models, including multilingual options; non-bundled models download once from Hugging Face to your machine
  28. - 🖥️ **Local Inference Server (optional)** - Serve the embedding model from LM Studio, Ollama, llama.cpp or vLLM on the same machine for native GPU speed: OpenAI-compatible API, localhost only
  29. - 🔄 **Auto-Index** - Automatically index new papers when you add them to your library
  30. - 👥 **Group Libraries (opt-in)** - Extend indexing and search to your Zotero group libraries with the Index scope setting
  31. - 🗑️ **Auto-Cleanup** - Embeddings automatically removed when items are deleted or trashed
  32. - 🚫 **Tag-Based Exclusion** - Tag items with `zotseek-exclude` to skip them during indexing
  33. - 📊 **Indexing Status Column** - "ZotSeek" column in the item list shows whether each paper is fully indexed, partially indexed (chunk limit hit), out of date, excluded, or not indexed
  34. - ⏸️ **Pause & Cancel** - Pause or cancel long-running indexing operations at any time
  35. - 💾 **Crash-Resilient** - Checkpoint saving every 10 items, **auto-resume on next startup** if a bulk run was interrupted, worker recovery on sleep/wake, skips problematic chunks automatically
  36. - 🔌 **Plugin API** - Other Zotero plugins can [call ZotSeek's search programmatically](docs/API.md)
  37. - ⚙️ **Configurable** - Customize via Zotero Settings → ZotSeek (also accessible from search dialog)
  38. - 🌐 **Localized** - UI available in English and Chinese (zh-CN)
  39. ---
  40. ## Privacy & Security
  41. ZotSeek is designed with privacy as a core principle:
  42. | Aspect | Guarantee |
  43. |--------|-----------|
  44. | **AI Model** | Default model bundled (~130MB); optional models download once from Hugging Face on demand — no API keys, no subscription |
  45. | **Processing** | All AI inference runs locally on your CPU/GPU |
  46. | **Your Papers** | Only indexes items from your local Zotero library |
  47. | **Network** | Zero network requests for search or indexing, unless you opt into a local inference server (see below) |
  48. | **Storage** | Embeddings saved locally in `zotseek.sqlite` in your Zotero data folder |
  49. | **Offline** | Works completely offline after installation (or after the optional inference server has started) |
  50. **What this means:**
  51. - Your research never leaves your machine
  52. - No cloud services, no API keys, no subscriptions
  53. - No telemetry or usage tracking
  54. - Uninstalling the plugin removes all ZotSeek data
  55. **Optional local inference server:** the default is the fully in-process engine described above, which makes no network requests at all. If you choose to add a local inference server (LM Studio, Ollama, llama.cpp or vLLM), the guarantee shifts from "no network code exists" to "network code provably cannot leave the machine": every request is validated at request time against an allow-list of `127.0.0.1`, `localhost` and `[::1]`, there is no preference to override this, redirects to a non-loopback address are refused rather than followed, and cloud or remote endpoints are unsupported by design. This is opt-in and off by default.
  56. ---
  57. ## More Screenshots
  58. <details>
  59. <summary>Click to expand</summary>
  60. ### Notes in Search Results
  61. Notes are searched alongside abstracts and PDF text. The Section column says where each
  62. match came from, and a note has no page to point at.
  63. ![Search results including notes](docs/images/search-dialog-notes.png)
  64. ### Recent Searches
  65. Click the empty search box to bring back a query you ran earlier.
  66. ![Recent searches dropdown](docs/images/search-history.png)
  67. ### Find Similar Documents
  68. ![Find Similar Results](docs/images/find-similar.png)
  69. ### Context Menu
  70. ![Context Menu](docs/images/context-menu.png)
  71. ### PDF Selection Context Menu
  72. ![PDF Find Related](docs/images/context-menu-pdf-find-similar.png)
  73. ### Settings Panel
  74. ![Settings Panel](docs/images/settings.png)
  75. ### Indexing Progress
  76. ![Indexing Progress](docs/images/progress.png)
  77. </details>
  78. ---
  79. ## How It Works
  80. ### The Big Picture
  81. ```mermaid
  82. flowchart TD
  83. subgraph INDEX["1️⃣ INDEX"]
  84. A[📄 Paper] --> B[🤖 AI Model] --> C[768 numbers]
  85. end
  86. subgraph SEARCH["2️⃣ SEARCH"]
  87. D[🔍 Query] --> E[Query → 768 numbers]
  88. E --> F{Compare all papers}
  89. F --> G[📊 Ranked results]
  90. end
  91. C -.->|stored| F
  92. ```
  93. **How it works:** Each paper becomes 768 numbers capturing its meaning. To search, we convert your query to numbers and find papers with similar numbers.
  94. ### Step-by-Step Process
  95. #### 1️⃣ Indexing Your Library
  96. When you use "Index Current Collection" or "Update Entire Library":
  97. ```
  98. For each paper:
  99. 1. Extract title + abstract (Abstract mode)
  100. — OR —
  101. Extract PDF text page-by-page with exact page numbers (Full Document mode)
  102. 2. Split into paragraphs, filter out References/Bibliography
  103. 3. Send to local AI model (nomic-embed-text-v1.5)
  104. 4. Model outputs 768 numbers per chunk (the "embedding")
  105. 5. Save embeddings + location metadata to local database (zotseek.sqlite)
  106. ```
  107. **Time:** ~3 seconds per chunk
  108. #### 2️⃣ Finding Similar Documents
  109. When you right-click → "Find Similar Documents":
  110. ```
  111. 1. Load the selected paper's embedding
  112. 2. Compare against all indexed papers (cached in memory)
  113. 3. Rank by semantic similarity
  114. 4. Show top results
  115. ```
  116. **Time:** ~70ms (with cache)
  117. ---
  118. ## Hybrid Search
  119. The plugin combines **semantic search** (AI embeddings) with **Zotero's keyword search** using **Reciprocal Rank Fusion (RRF)** for optimal results.
  120. ### Search Modes
  121. | Mode | Best For | How It Works |
  122. |------|----------|--------------|
  123. | 🔗 **Hybrid** (Recommended) | Most searches | Combines semantic + keyword results |
  124. | 🧠 **Semantic Only** | Conceptual queries | Finds related papers by meaning |
  125. | 🔤 **Keyword Only** | Author/year searches, exact phrases | Zotero's own search over titles, authors, years, tags, PDF text and notes; a match inside a PDF or a note is credited to the paper it belongs to |
  126. ### Why Hybrid Search?
  127. | Query Type | Pure Semantic | Pure Keyword | Hybrid |
  128. |------------|---------------|--------------|--------|
  129. | "trust in AI" | ✅ Great | ❌ Poor | ✅ Great |
  130. | "Smith 2023" | ❌ Poor | ✅ Great | ✅ Great |
  131. | "RLHF" | ⚠️ Maybe | ✅ Exact only | ✅ Both |
  132. ### Result Indicators
  133. | Icon | Meaning |
  134. |------|---------|
  135. | 🔗 | Found by BOTH semantic and keyword (high confidence) |
  136. | 🧠 | Found by semantic search only (conceptually related) |
  137. | 🔤 | Found by keyword search only (exact match) |
  138. ### Section-Aware Results
  139. The **Source** column shows where the match came from:
  140. | Source | What it means |
  141. |--------|---------------|
  142. | Abstract | Title + Abstract |
  143. | Methods | Introduction, Background, Methods |
  144. | Results | Results, Discussion, Conclusions |
  145. | Content | Generic (sections not detected) |
  146. | Note | A note attached to the item, when note indexing is on |
  147. A note has no page, so a Note result leaves the Location column empty and opens the note
  148. itself rather than jumping into the PDF.
  149. ### Matched-Passage Preview
  150. Hover any result row to see a tooltip with the exact passage that matched your query, along with its location (page & paragraph), section type, and match score. This lets you judge whether a result is relevant without opening the paper. In **Keyword** and **Hybrid** searches the query terms are highlighted inside the passage, and the preview is centered on the first match so the relevant text is always in view. (Pure semantic search has no literal terms to highlight, so the passage is shown without highlighting.)
  151. ### Result Granularity (Full Document Mode)
  152. When using **Full Document** indexing mode, you can toggle between two result views:
  153. | Mode | Results | Best For |
  154. |------|---------|----------|
  155. | **By Section** (default) | 1 result per paper, best matching section, with the location of that match | Overview of matching papers |
  156. | **By Location** | Every matching paragraph with exact page & paragraph | Finding specific passages |
  157. **By Section** - Aggregates all chunks per paper and shows the highest-scoring match. The **Location** column shows where that best match was found (page & paragraph), so you get one diverse result per paper without losing the exact location:
  158. ![By Section Mode](docs/images/search-dialog-by-section-hover.png)
  159. **By Location** - Returns every matching paragraph individually with its own score:
  160. ![By Location Mode](docs/images/search-dialog-by-location.png)
  161. In **By Location** mode, clicking a result opens the PDF to the exact page where the match was found.
  162. ### Multi-Query Search
  163. Combine up to 4 search queries to find papers at the intersection of multiple topics:
  164. 1. Click the **"+"** button next to the search field to add more queries
  165. 2. Choose **AND** or **OR** to combine results
  166. 3. For AND mode, select a combination formula
  167. | Operator | Behavior | Best For |
  168. |----------|----------|----------|
  169. | **AND** | Papers must match ALL queries | Finding topic intersections |
  170. | **OR** | Papers can match ANY query | Broadening search with synonyms |
  171. | AND Formula | How It Works | Use When |
  172. |-------------|--------------|----------|
  173. | **Minimum** (default) | Uses lowest score across queries | You want strict intersection |
  174. | **Product** | Geometric mean of scores | Balanced relevance across all queries |
  175. | **Average** | Arithmetic mean of scores | More lenient matching |
  176. **Example:** Search for papers about "machine learning" AND "healthcare" AND "ethics" to find AI ethics papers specifically in the medical domain.
  177. **Match column with multiple queries:** Shows combined score plus individual per-query scores:
  178. - `73% (77|73|68)` = 73% combined, with 77% for Q1, 73% for Q2, 68% for Q3
  179. For technical details, see [docs/SEARCH_ARCHITECTURE.md](docs/SEARCH_ARCHITECTURE.md).
  180. ### Recent Searches
  181. Semantic search rewards rephrasing, and the phrasing that finally worked is easy to lose. The search window keeps the last 10 queries you actually ran:
  182. 1. Click the empty search field (or press the Down arrow while it's empty) to see them, newest first
  183. 2. Pick one to put it back in the box and run it again
  184. 3. Choose **Clear search history** in the same dropdown to forget all of them
  185. Only the text of the main search box is kept, in a preference, so the list survives a restart. Running a query you have run before moves it back to the top instead of listing it twice, and a search you never ran (text you typed and then deleted) never enters the list.
  186. ---
  187. ## Indexing Modes
  188. | Mode | What Gets Indexed | Best For |
  189. |------|-------------------|----------|
  190. | **Abstract** | Title + Abstract | Fast indexing, quick setup |
  191. | **Full Document** (default) | PDF content split by sections | Deep content search, better results |
  192. Configure via **Zotero → Settings → ZotSeek**.
  193. ### Library Scope (Group Libraries)
  194. By default, ZotSeek indexes only **My Library**. If you use Zotero group libraries, the **Index scope** setting (under Auto-Indexing) lets you include them:
  195. | Scope | What Gets Indexed |
  196. |-------|-------------------|
  197. | **My Library** (default) | Your personal library only |
  198. | **All libraries** | Personal library + every group library |
  199. The scope applies to both the bulk **Update Index** action and background auto-indexing. Once indexed, group items show up in search results like any other paper, with links that open them in the right library. Searches over MCP/REST can also be limited to a single library with the `library_key` parameter (see [docs/MCP.md](docs/MCP.md)).
  200. ### How Full Document Mode Works
  201. For papers with PDFs, the chunker:
  202. 1. Extracts text page-by-page with exact page numbers
  203. 2. Splits each page into paragraphs
  204. 3. Prepends title to each chunk for context
  205. 4. **Automatically filters out References/Bibliography sections**
  206. When searching, if *any* chunk matches your query, the paper ranks highly (MaxSim aggregation in "By Section" mode).
  207. ### References Filtering
  208. The chunker automatically detects and excludes bibliography sections:
  209. - Detects headers: "References", "Bibliography", "Works Cited", "Literature Cited"
  210. - Recognizes citation patterns: `[1]`, `Smith, J. (2021).`, DOI links
  211. - Stops indexing once references section is detected
  212. This keeps your search results focused on the actual content of papers.
  213. ### Chunk Size Trade-offs
  214. The `maxTokens` setting controls how text is split for embedding. It's a **ceiling, not a target** — chunks are split at paragraph boundaries and may be smaller.
  215. | Chunk Size | Speed | Search Behavior |
  216. |------------|-------|-----------------|
  217. | **500-800** | Fast (~0.5s/chunk) | Higher precision, finds specific passages |
  218. | **2000** | Moderate (~3s/chunk) | Balanced (default) |
  219. | **4000+** | Slow | Higher recall, finds broad topics |
  220. **Default:** 2000 tokens. Firefox 140+ handles larger chunks efficiently.
  221. **Recommendations:**
  222. - Large libraries with full-paper indexing: use defaults
  223. - Finding specific methodologies: try 500-600
  224. - Broad topic discovery: try 2000-3000
  225. For detailed chunking documentation, see [docs/SEARCH_ARCHITECTURE.md](docs/SEARCH_ARCHITECTURE.md#chunking-strategy).
  226. ### Indexing Status Column
  227. ZotSeek adds a "ZotSeek" column to the Zotero item list so you can see at a glance how each paper has been indexed. The first time you install this version the column appears automatically; you can hide or reorder it from the column-header menu like any other Zotero column.
  228. | Glyph | Meaning |
  229. |-------|---------|
  230. | `✓` | Fully indexed |
  231. | `◐` | Partial — the paper hit the *Max Chunks per Paper* limit and only part of its content is in the index. Raise the limit or switch to Abstract mode to capture the full text. |
  232. | `↻` | Out of date — the item was modified after it was indexed. Re-index to refresh. |
  233. | `⊘` | Excluded — the item carries the `zotseek-exclude` tag. |
  234. | *(empty)* | Not indexed. |
  235. After indexing, a one-line summary in the progress window also warns when any paper hit the chunk limit, and the same warning is written to the debug log per affected paper.
  236. ### Indexing Child Notes
  237. Enable **"Also index child notes"** in Settings to make the text of notes attached to an item searchable alongside its abstract or full text. This includes notes created by [Better Notes](https://github.com/windingwind/zotero-better-notes), since it stores its content in the same note field Zotero itself uses. A note's text is added to its parent item, not indexed as a separate result.
  238. - **Off by default, and turning it on does not re-index anything by itself.** Items indexed from then on include their notes. Items that are already in the index keep exactly what they have until you run **"Add Note Text to Existing Items"** (below), or until you edit each note individually.
  239. - **Works in both modes.** This setting is independent of Abstract/Full Document mode; it adds note text on top of whichever mode is active.
  240. - **Not indexed:** standalone notes (notes not attached to any item), comments on PDF annotations, and images inside a note — every embedding model ZotSeek ships is text-only. Text surrounding an image is still indexed; only the image itself is skipped. Annotation comments are still found by Hybrid and Keyword search, which match their exact words: the result shows the comment and opens the PDF on that annotation.
  241. - **Editing a note** re-indexes its parent after a quiet period (default 60 seconds, adjustable via **"Delay before re-indexing an edited note"**) — but only while **"Automatically index new items"** is also enabled. With auto-indexing off, edited notes are picked up the next time you run Update Index by hand.
  242. - **Trashing a note** removes its text from the index the same way. Permanently erasing a note (bypassing the trash) leaves nothing to resolve back to its parent, so that removal only takes effect on the next manual Update Index.
  243. - **Turning the setting back off does not remove note text that is already indexed.** It only stops new note text from going in. Notes already in the index stay searchable until those items are re-indexed from scratch: remove them from the index and index them again, or clear and rebuild the whole index from Settings. If you put something in a note that you would rather not have indexed, switching the setting off is not enough on its own.
  244. #### Adding Notes to Items That Are Already Indexed
  245. **"Add Note Text to Existing Items"**, in the item context menu's ZotSeek submenu next to the other indexing commands, adds note text to items that already have an entry in the index. Nothing else does: **Update Entire Library** skips anything already indexed, whatever changed about it, so without this action the setting would only ever apply to items indexed after you switched it on.
  246. - **What it picks up:** items that are **already indexed**, and that have at least one note which is not in the trash. Items that are not indexed yet are left alone, since **Update Entire Library** covers those, notes included.
  247. - **Scope:** your personal library, or every library, following the same **Index scope** setting as Update Entire Library.
  248. - **Cost:** existing embeddings are reused, so only the note text goes to the model. In Full Document mode each candidate PDF is still read again to confirm the rest of the item has not changed, so the run is much faster than re-indexing from scratch but not instant.
  249. - **Interruptions:** pause, cancel and resume-after-a-crash behave exactly as they do for Update Entire Library.
  250. - **If the setting is off**, the action stops and asks you to turn it on first; there would be no note text to add.
  251. - **Running it again is safe.** Items whose notes are already indexed are left untouched rather than rewritten, and are reported as such at the end of the run.
  252. ---
  253. ## Choose Your Embedding Model
  254. ZotSeek ships with a curated set of local embedding models. The default model is bundled and works immediately; other models download once from Hugging Face and are then available offline.
  255. Go to **Zotero → Settings → ZotSeek → Embedding Model** to pick the model that fits your library.
  256. | Model | Dims | Multilingual | Approx. size | When to use |
  257. |-------|------|-------------|--------------|-------------|
  258. | **nomic-embed-text-v1.5** *(default, bundled)* | 768 | No | ~130 MB | English or mostly-English libraries. Strong all-around retrieval quality, no download needed. |
  259. | **paraphrase-multilingual-MiniLM-L12-v2** | 384 | Yes | ~135 MB | Smaller and faster; good for hardware-constrained machines or mixed-language collections where speed matters more than top accuracy. |
  260. | **multilingual-e5-base** | 768 | Yes | ~110 MB | Balanced multilingual quality at the same 768-dimension space as the default. Good first choice for non-English libraries. |
  261. | **BGE-M3** | 1024 | Yes | ~570 MB | Highest-quality multilingual retrieval in the set. Worth the extra size for large, mixed-language collections where accuracy is paramount. |
  262. **Privacy:** models are downloaded once from Hugging Face directly to your Zotero profile directory. No library content is ever sent anywhere — inference runs entirely on your machine.
  263. **Coverage indicator:** below the model selector, Settings shows "N of M items searchable with the active model." When any items are missing coverage, an **Index remaining N** button appears. Clicking it indexes those items in the background while you continue working; the button shows "Indexing in the background..." and disables itself while the run is active.
  264. **Three ways to index with a model (all preserve other models' embeddings):**
  265. 1. The prompt shown immediately after you switch to a new model.
  266. 2. The **Index remaining** button on the coverage line in Settings.
  267. 3. The toolbar or right-click → ZotSeek → **Update Entire Library** action — now model-aware, it backfills items not yet covered by the active model rather than reporting "already indexed."
  268. **Switching models:** switching to a different model triggers a background re-index for items that have not yet been indexed with the new model. Items indexed with other models retain their embeddings — switching back is instant.
  269. **Manage downloaded models:** a "Manage downloaded models" panel in Settings shows per-model index statistics (items, chunks, and embedding storage) and lets you delete models you no longer need (this also removes that model's embeddings from the database). The built-in model and whichever model is currently active cannot be removed; each shows an inline reason ("Built-in" / "Active") with a tooltip explaining why.
  270. ---
  271. ## Using a Local Inference Server
  272. If you have a GPU, running the embedding model in a dedicated inference server (LM Studio, Ollama, llama.cpp or vLLM) is faster than the built-in WASM engine, which runs on CPU inside Zotero. This is entirely optional: the default remains the fully in-process engine, and ZotSeek never talks to anything off this machine.
  273. **Setup with LM Studio:**
  274. 1. In LM Studio, load an embedding model (e.g. an embedding-capable GGUF) and start the local server. Note the port shown (typically `1234`).
  275. 2. In Zotero, go to **Settings → ZotSeek → Local inference server** and enter the server URL, e.g. `http://127.0.0.1:1234`.
  276. 3. Click **Test connection**. ZotSeek lists the models the server currently has loaded.
  277. 4. Pick a model from the dropdown. ZotSeek sends a test embedding request and reports the dimensions it returns.
  278. 5. Click **Add model**. The model now appears in the main **Embedding Model** picker alongside the bundled and Hugging Face models.
  279. 6. Select it in the model picker to make it the active model.
  280. **Setup with Ollama:**
  281. 1. Pull an embedding model, e.g. `ollama pull nomic-embed-text`. Ollama serves its OpenAI-compatible API on port `11434` by default.
  282. 2. In **Settings → ZotSeek → Local inference server**, enter `http://127.0.0.1:11434`.
  283. 3. Follow the same Test connection → pick model → Add model steps as above.
  284. The same flow works with llama.cpp's server (`llama-server`) and vLLM, since both also expose an OpenAI-compatible `/v1/embeddings` endpoint on localhost.
  285. **Re-indexing note:** a server-hosted model is a separate index from the built-in models, even for the same model name: indexing runs once per model, and previous indexes are kept. Switching between a server model and a built-in model does not require re-indexing again later, since both are retained side by side.
  286. **API key note:** if your server requires an API key, ZotSeek stores it in plain text in the Zotero profile preferences, sends it only to the loopback server you configured, and never logs it.
  287. **Choosing a model and task prefixes:**
  288. Pick a dedicated embedding model. The server's model list includes every model it has loaded, including chat models, and ZotSeek cannot tell the two apart from the API alone, so it warns you when a selected model's name does not look like an embedding model. Running a chat model as your embedding model produces poor search results.
  289. Some embedding models were trained to expect a short prefix before the text, different for queries versus documents (a "task prefix"). Using the correct prefix helps the model separate what you are searching for from what you indexed.
  290. | Model family | Query prefix | Document prefix |
  291. |--------------|--------------|------------------|
  292. | Nomic | `search_query: ` | `search_document: ` |
  293. | E5 | `query: ` | `passage: ` |
  294. | Most others (BGE, MiniLM, GTE) | none | none |
  295. ZotSeek pre-fills these prefixes automatically when it recognizes the model family from its name. If you are using a model that is not listed here, check the model card on Hugging Face for a prefix requirement, and leave the fields empty if the card does not mention one.
  296. Using the wrong prefixes does not produce an error. Search will simply run and quietly return lower-quality results.
  297. ---
  298. ## The AI Model
  299. ### nomic-embed-text-v1.5
  300. | Property | Value |
  301. |----------|-------|
  302. | **Name** | [nomic-ai/nomic-embed-text-v1.5](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5) |
  303. | **Size** | 131 MB (quantized) |
  304. | **Dimensions** | 768 (Matryoshka - can truncate to 256/128) |
  305. | **Context Window** | 8192 tokens |
  306. | **Speed** | ~3 seconds per chunk |
  307. | **Quality** | Outperforms OpenAI text-embedding-3-small on MTEB |
  308. | **Special Feature** | Instruction-aware prefixes for queries vs documents |
  309. ### Why This Model?
  310. - ✅ **Superior retrieval quality** - Outperforms OpenAI text-embedding-3-small and jina-v2 on MTEB benchmarks
  311. - ✅ **8K context window** - Most papers fit in 1-3 chunks (vs 10-20 with 512-token models)
  312. - ✅ **Instruction-aware** - Uses `search_document:` for indexing and `search_query:` for queries
  313. - ✅ **Matryoshka embeddings** - 768 dims can be truncated to 256/128 with minimal quality loss
  314. - ✅ **Fully open** - Open weights, open training data, reproducible
  315. - ✅ **Works in Zotero** - Compatible with Transformers.js v3 via wasmPaths configuration
  316. ### How Embeddings Work
  317. The model converts text into 768 numbers that capture semantic meaning:
  318. ```
  319. "Machine learning for medical diagnosis" → [0.023, -0.045, 0.012, ...]
  320. "AI in healthcare applications" → [0.021, -0.048, 0.015, ...] ← Similar!
  321. "Organic chemistry synthesis" → [-0.089, 0.034, 0.067, ...] ← Different!
  322. ```
  323. Papers with **similar meanings** have **similar numbers**, even if they use different words.
  324. ---
  325. ## Architecture
  326. ### System Overview
  327. ```mermaid
  328. flowchart LR
  329. subgraph Main["Main Thread"]
  330. A[Plugin] <--> B[(SQLite)]
  331. A <--> C[Search]
  332. end
  333. subgraph Worker["ChromeWorker"]
  334. D[Transformers.js]
  335. E[nomic-embed-v1.5]
  336. end
  337. A -->|text| Worker
  338. Worker -->|embeddings| A
  339. ```
  340. ### Why ChromeWorker?
  341. Transformers.js can't run directly in Zotero's main thread because:
  342. - Missing browser globals (`self`, `navigator`, `indexedDB`)
  343. - Cache API crashes Zotero
  344. - Would block UI during model inference
  345. **Solution:** Run in a separate ChromeWorker thread with special configuration.
  346. ### Data Storage
  347. Embeddings are stored in a **separate SQLite database** (`zotseek.sqlite`) attached to Zotero's connection:
  348. - **Location:** `<Zotero Data Directory>/zotseek.sqlite`
  349. - **Size:** ~15KB per paper (abstract mode), ~150KB per paper (full document mode)
  350. - **Benefits:** O(1) indexed lookups, in-memory caching, atomic updates, clean uninstall
  351. The SQLite backend uses the **ATTACH DATABASE** pattern (inspired by Better BibTeX):
  352. - **Separate file** - Keeps Zotero's main database clean and unbloated
  353. - **Smart caching** - Pre-normalized Float32Arrays cached in memory after first search
  354. - **Reliable queries** - Uses `columnQueryAsync()` and `valueQueryAsync()` for robust data retrieval
  355. - **Clean uninstall** - Database file automatically removed when plugin is uninstalled
  356. ### Copying the database between machines
  357. ZotSeek stores its embeddings in `zotseek.sqlite` inside your Zotero data directory. The file is local and is not synced by Zotero's built-in sync.
  358. > **If your Zotero data folder is on a network drive or NAS:** downloadable embedding models are kept next to Zotero's profile instead, not in the data folder, because reading a few hundred megabytes of model weights over a network share can stall indexing. Models downloaded by earlier versions still work from the old location, but if you are on network storage it is worth removing and re-downloading them from **Settings → ZotSeek → Models** so they end up local.
  359. If you use Zotero on multiple machines and want to avoid re-indexing your library on each one, you can copy the file manually:
  360. 1. Quit Zotero on both machines.
  361. 2. Find your Zotero data directory (Preferences → Advanced → Files and Folders).
  362. 3. Copy `zotseek.sqlite` from one machine to the other.
  363. 4. Start Zotero on the destination machine.
  364. The plugin identifies items by Zotero's stable item keys (the same identifiers visible in the Zotero web API), so the database works correctly regardless of which machine indexed the items.
  365. Notes:
  366. - Both Zotero libraries must be in sync — items not yet present on the destination will appear as "unresolved embeddings" in Preferences → Database Health until sync completes.
  367. - The file can be large (hundreds of MB for libraries with full-document indexing). It is not designed to be cloud-synced continuously.
  368. - Group libraries are supported via stable group IDs assigned by Zotero's server.
  369. ---
  370. ## Cosine Similarity
  371. The math behind "how similar are two papers":
  372. $$\text{similarity} = \frac{A \cdot B}{\|A\| \times \|B\|}$$
  373. Where:
  374. - **A · B** = sum of (a[i] × b[i]) for all 768 dimensions
  375. - **‖A‖** = sqrt(sum of a[i]²)
  376. - **‖B‖** = sqrt(sum of b[i]²)
  377. **Result:** 0.0 (completely different) to 1.0 (identical)
  378. **Interpretation:**
  379. - 0.9+ = Very similar (probably same topic)
  380. - 0.7-0.9 = Related topics
  381. - 0.5-0.7 = Loosely related
  382. - <0.5 = Different topics
  383. ---
  384. ## Use with AI Agents (MCP)
  385. ZotSeek can let **Claude Code** and other MCP clients search your library semantically, so an agent can find relevant papers and cite them with links that open straight to the right page in Zotero. Each result carries `zotero://` deep links: one opens the item, one opens its PDF at the exact page that matched your query.
  386. **What this enables** — real workflows from a thesis-writing session:
  387. - *"Find me a citable definition of human-AI collaboration"* → the agent searches the library, proposes three candidate papers with the matched passages, and links each one so it opens in Zotero at the relevant page.
  388. - Mark claims in a draft with `[citation needed]` → the agent hunts your library for sources that actually support each claim and flags the ones nothing supports.
  389. - *"A reviewer says these statements are too strong — what evidence do I have?"* → the agent cross-checks the argument against what you have actually collected, paper by paper.
  390. It runs entirely on your machine and is **opt-in** (off by default). Enable it in **Settings → ZotSeek → AI Agent Access**, make sure Zotero's local HTTP server is allowed (**Settings → Advanced**), then connect Claude Code with:
  391. ```bash
  392. claude mcp add --transport http --scope user zotseek http://localhost:23119/zotseek/mcp
  393. ```
  394. The same searches are also available as plain REST endpoints for scripts. Everything is read-only — nothing can modify your library or index. See [docs/MCP.md](docs/MCP.md) for the full setup, tool reference, REST API, and security notes.
  395. Once the manuscript is written, the complementary tool [citefact](https://github.com/hearthresearch/citefact) closes the loop: point it at the same Zotero collection and it audits the finished draft — citations exist, quotes are verbatim, and each source actually supports the claim citing it.
  396. ---
  397. ## Built with ZotSeek
  398. Independent projects built on ZotSeek's local API:
  399. - **[Wordbot](https://github.com/Addy-ad/wordbot)** by [@Addy-ad](https://github.com/Addy-ad) — a Microsoft Word add-in for researchers. It converts LLM output into native Word formatting (tables, equations, code blocks, headings) and grounds it in your library: it runs semantic searches through ZotSeek, then writes text with inline citations that Zotero's own Word plugin recognises, so you can build a unified bibliography from them. Runs entirely offline against a local LLM server. Windows and macOS. See the author's [introduction and demo](https://github.com/introfini/ZotSeek/discussions/46) for what it looks like in use and which edition to pick.
  400. These are third-party projects, maintained by their authors and released under their own licences (Wordbot is non-commercial). Please report problems with them on their own issue trackers.
  401. ---
  402. ## Installation
  403. ### For Users
  404. **Requirements:** Zotero 8.0 or newer (Zotero 9 and Zotero 10 supported).
  405. 1. Download the latest `zotseek-X.Y.Z.xpi` from the [Releases page](https://github.com/introfini/ZotSeek/releases/latest).
  406. 2. In Zotero, open **Tools → Plugins**.
  407. 3. Click the gear icon (⚙️) in the top-right and choose **Install Plugin From File…**
  408. 4. Select the downloaded `.xpi` file.
  409. 5. Restart Zotero when prompted.
  410. After installation, ZotSeek is ready to use — open **Zotero → Settings → ZotSeek** to configure it, then right-click a collection and choose **ZotSeek → "Update Entire Library"** to build your index.
  411. **Updating:** ZotSeek checks for updates automatically. New releases are delivered through Zotero's built-in plugin update mechanism, so you'll be notified when a new version is available.
  412. ### For Developers
  413. ```bash
  414. # Clone the repository
  415. git clone https://github.com/introfini/ZotSeek
  416. cd zotseek
  417. # Install dependencies (includes zotero-plugin-toolkit for stable progress windows)
  418. npm install
  419. # Build the plugin
  420. npm run build
  421. # Create extension proxy file (macOS)
  422. echo "$(pwd)/build" > ~/Library/Application\ Support/Zotero/Profiles/*.default/extensions/zotseek@zotero.org
  423. # Restart Zotero with debug console
  424. open -a Zotero --args -purgecaches -ZoteroDebugText -jsconsole
  425. ```
  426. ### Building a Distributable XPI
  427. ```bash
  428. npm run release
  429. ```
  430. The interactive release script bumps the version, syncs `manifest.json` and `update.json`, rebuilds, and packages `zotseek-X.Y.Z.xpi` at the project root.
  431. ---
  432. ## Usage
  433. ### Index Your Library
  434. 1. Right-click on a collection → **ZotSeek → "Index Current Collection"**. Subcollections
  435. are included. On Zotero 10 you can select several collections first and index them in
  436. one pass; items filed in more than one of them are indexed once. The same command is
  437. also in the ZotSeek submenu you get by right-clicking a paper, where it indexes the
  438. collection selected on the left.
  439. 2. Or use **"Update Entire Library"** to index all items
  440. 3. A progress window will appear showing:
  441. - Current item being processed
  442. - Progress percentage
  443. - Estimated time remaining (ETA)
  444. - Option to cancel at any time
  445. 4. Indexing speed: ~3 seconds per chunk
  446. **Automatic Compaction (Zotero 10+):**
  447. Re-indexing, switching models and purging orphans all leave free space inside
  448. ZotSeek's database file. Zotero 10 runs its own database maintenance after a few
  449. minutes of idle, and ZotSeek reclaims its space in the same window — but only when
  450. there is a meaningful amount to recover and no indexing is running. Turn it off under
  451. **Settings → ZotSeek → Integrations & Maintenance**, where the manual **Compact
  452. Database** button also lives.
  453. **Crash-Resilient Indexing:**
  454. - Progress is saved every 25 items (checkpoint saving)
  455. - If Zotero crashes or you need to stop, simply re-run "Update Index"
  456. - Already-indexed items are automatically skipped
  457. - No need to start over from scratch
  458. **Progress Window Features:**
  459. - ✅ AI model loaded status
  460. - ✅ Extraction progress (chunks from items)
  461. - 📊 Current paper being processed
  462. - 📈 Progress bar with percentage
  463. - ⏱️ ETA countdown
  464. - ⏸ Pause/resume button (pauses at batch boundaries, all progress saved)
  465. - ✕ Cancel button (shows quiet notification, no error alert)
  466. - 🪟 Hides while Zotero is minimized and reappears on restore (macOS)
  467. ### Find Similar Documents
  468. 1. Select any paper in your library
  469. 2. Right-click → **"Find Similar Documents"**
  470. 3. Results appear showing similarity percentages
  471. ### Save Results as Collection
  472. Every ZotSeek search result set can be saved into a Zotero collection so you can come back to the same list later without re-running the search:
  473. - In the search dialog, click **"Save Results as Collection"** in the footer to export every result.
  474. - Or right-click any subset of results and choose **Add to Collection → New collection...** to export just the selection.
  475. - The same button appears in the **Find Similar Documents** dialog.
  476. The modal pre-fills a sensible name (your query + today's date, e.g. `ZotSeek: "machine learning" · 2026-04-21`) that you can edit. A live status line shows `N items → My Library` so you know where the collection will land.
  477. New collections are created at the target library's root. If you want them in a specific subfolder, drag them from Zotero's sidebar after the export — faster and more flexible than a dropdown.
  478. When search results span multiple libraries (for example, your personal library and a group library), a Library dropdown appears so you can pick which library receives the new collection. Items in other libraries are reported as skipped in the confirmation status.
  479. ### Search from PDF Selection
  480. While reading a PDF, you can search for related documents based on selected text:
  481. 1. Open a PDF in Zotero's reader
  482. 2. Select a passage that describes a concept you want to explore
  483. 3. Right-click → **"Find Related Documents"**
  484. 4. ZotSeek opens with the selected text as the search query
  485. 5. Results show documents related to that concept (current document is excluded)
  486. This is useful for:
  487. - Exploring unfamiliar concepts while reading
  488. - Finding additional sources on a specific topic
  489. - Discovering related work mentioned in a paper
  490. ### Auto-Index New Papers
  491. ZotSeek can automatically index papers as you add them to your library:
  492. 1. Go to **Zotero → Settings → ZotSeek**
  493. 2. Enable **"Automatically index new items"**
  494. 3. Now when you add papers (via browser connector, drag & drop, etc.), they'll be indexed automatically
  495. **How it works:**
  496. - Detects when new items are added to your library
  497. - Waits for PDF attachments to arrive (with automatic retry)
  498. - Batches multiple items together with a configurable delay (default: 10 seconds)
  499. - Each new item resets the countdown, preventing indexing during bulk imports
  500. - Shows a brief progress indicator while indexing
  501. - Respects your indexing mode setting (Abstract or Full Document)
  502. **Configuring the delay:** Go to **Zotero Settings > ZotSeek** and adjust the **Auto-index delay** slider (1-300 seconds). Longer delays are useful when importing large batches via browser connector or RSS feeds.
  503. ### Managing the Index
  504. **Automatic cleanup:** When you delete or trash items in Zotero, their embeddings are automatically removed from the ZotSeek index. This prevents ghost search results and keeps the index clean — no action needed on your part.
  505. **Manual removal:** To remove specific items from the index without deleting them:
  506. 1. Select one or more items in Zotero
  507. 2. Right-click → **ZotSeek → "Remove from Index"**
  508. 3. A notification confirms how many items were removed
  509. This is useful when you want to re-index specific items (e.g., after updating a PDF), or to exclude items from search results without deleting them from your library.
  510. ### Excluding Items from Indexing
  511. You can prevent specific items from being indexed by tagging them:
  512. 1. Select one or more items in Zotero
  513. 2. Add the tag `zotseek-exclude` (or your custom tag name)
  514. 3. These items will be skipped during all indexing operations
  515. **Customizing the tag name:** Go to **Zotero → Settings → ZotSeek → Advanced Settings** and change the **Exclude tag** field. Leave it empty to disable tag-based exclusion.
  516. **Tip:** Use Zotero's advanced search (Edit → Advanced Search) to find items by title, type, collection, etc., then bulk-tag them. This is more flexible than regex-based filtering since it leverages Zotero's native search capabilities.
  517. ### ZotSeek Search Dialog
  518. 1. Click the **ZotSeek button** in the toolbar (🔍✨)
  519. 2. Or right-click → **ZotSeek → "Search Library..."**
  520. 3. Enter a natural language query (e.g., "machine learning for medical diagnosis")
  521. 4. **Optional:** Click "+" to add more queries (up to 4) and combine with AND/OR
  522. 5. View results ranked by semantic similarity
  523. 6. Double-click any result to open it in Zotero
  524. 7. Click **⚙ Settings** (bottom-left) to quickly access ZotSeek preferences
  525. ### Working with Multiple Search Results
  526. Select multiple items in the ZotSeek search results:
  527. 1. **Select multiple items:**
  528. - **Shift+click** to select a range of items
  529. - **Cmd+click** (Mac) or **Ctrl+click** (Windows/Linux) to toggle individual items
  530. 2. **Right-click** on the selection to open the context menu:
  531. - **Show in Library** - Selects all items in Zotero's main pane
  532. - **Add to Collection** - Add all selected items to any collection
  533. 3. Click **"Open Selected"** to select all items in the Zotero library (when multiple selected)
  534. ### View Debug Output
  535. Help → Debug Output Logging → View Output
  536. Look for `[ZotSeek]` entries.
  537. ---
  538. ## Configuration
  539. ### Settings Panel
  540. Access settings via **Zotero → Settings → ZotSeek** (or **Zotero → Preferences** on macOS).
  541. The settings panel allows you to configure:
  542. - **Indexing Mode**: Abstract only or Full Document
  543. - **Search Options**: Maximum results, and a minimum similarity threshold that applies to the AI half of the search; keyword matches are always returned, since a literal match is its own evidence
  544. - **Exclusion**: Exclude books, exclude by tag
  545. - **Actions**: Clear index, re-index library
  546. ### Preferences Reference
  547. Preferences are stored in Zotero's preferences system:
  548. **Search Settings:**
  549. | Preference | Default | Description |
  550. |------------|---------|-------------|
  551. | `zotseek.minSimilarityPercent` | `30` | Minimum similarity % for semantic matches; keyword matches are never filtered by it |
  552. | `zotseek.topK` | `20` | Maximum number of results |
  553. | `zotseek.autoIndex` | `false` | Automatically index new papers when added |
  554. | `zotseek.autoIndexDelay` | `10` | Seconds to wait after last item before auto-indexing (1-300) |
  555. | `zotseek.noteIndexDelay` | `60` | Seconds to wait after a note edit before re-indexing its parent (requires `zotseek.autoIndex`) |
  556. **Indexing Settings:**
  557. | Preference | Default | Description |
  558. |------------|---------|-------------|
  559. | `zotseek.indexingMode` | `"full"` | `"abstract"` or `"full"` |
  560. | `zotseek.indexNotes` | `false` | Also index the text of child notes attached to an item |
  561. | `zotseek.maxTokens` | `2000` | Max tokens per chunk |
  562. | `zotseek.maxChunksPerPaper` | `100` | Max chunks per paper |
  563. | `zotseek.excludeBooks` | `true` | Skip books during indexing |
  564. | `zotseek.excludeTag` | `"zotseek-exclude"` | Tag name to skip items during indexing (empty to disable) |
  565. **Hybrid Search Settings:**
  566. | Preference | Default | Description |
  567. |------------|---------|-------------|
  568. | `zotseek.hybridSearch.enabled` | `true` | Enable hybrid search |
  569. | `zotseek.hybridSearch.mode` | `"hybrid"` | `"hybrid"`, `"semantic"`, or `"keyword"` |
  570. | `zotseek.hybridSearch.semanticWeightPercent` | `50` | Semantic weight (0-100) |
  571. | `zotseek.hybridSearch.rrfK` | `60` | RRF constant |
  572. | `zotseek.hybridSearch.autoAdjustWeights` | `true` | Auto-adjust based on query |
  573. You can also access preferences via `about:config` (Help → Debug Output Logging → View Output, then navigate to `about:config`).
  574. ---
  575. ## Performance
  576. Tested on MacBook Pro M3:
  577. | Operation | Time |
  578. |-----------|------|
  579. | Model loading | ~1.5 seconds (bundled, 131MB) |
  580. | Index 1 chunk | ~3 seconds (optimized from ~45s) |
  581. | Index 10 papers (40 chunks) | ~2 minutes |
  582. | **First search** | ~130ms (loads cache) |
  583. | **Subsequent searches** | **~70ms** (uses cache) |
  584. | **Hybrid search** | ~70ms (with cache) |
  585. | Storage size | ~130 KB per 10 papers (full mode) |
  586. | Memory usage (cached) | +75MB for 1,000 papers |
  587. ### Performance Optimizations
  588. The plugin includes several performance optimizations:
  589. 1. **Tuned Chunk Size** - 2000 tokens (~3s/chunk) balances recall and speed while avoiding the O(n²) attention bottleneck
  590. 2. **In-Memory Caching** - Embeddings cached after first search
  591. 3. **Pre-normalized Vectors** - Float32Arrays normalized on load for fast dot product
  592. 4. **Parallel Searches** - Semantic and keyword searches run simultaneously
  593. 5. **Reliable SQLite Methods** - Uses `columnQueryAsync()` and `valueQueryAsync()`
  594. ### GPU Acceleration (Experimental)
  595. ZotSeek automatically detects and uses **WebGPU** for GPU-accelerated embeddings when available:
  596. | Backend | When Used | Speed |
  597. |---------|-----------|-------|
  598. | **WebGPU (GPU)** | If browser/Zotero supports WebGPU | Up to 10-20x faster |
  599. | **WASM (CPU)** | Fallback when WebGPU unavailable | ~3 seconds per chunk |
  600. **Current status (August 2026):**
  601. - Firefox 141 shipped WebGPU on **Windows only** (July 2025)
  602. - **macOS and Linux** WebGPU support is still in progress at Mozilla
  603. - Zotero 8, 9 and 10 all ship Firefox 140 ESR — one version before the first WebGPU build, so GPU acceleration is still gated on an upstream Firefox ESR bump
  604. **When will GPU work?** Once Zotero upgrades to a Firefox ESR with WebGPU support for your platform, GPU acceleration will automatically activate — no plugin update needed.
  605. **Check if GPU is being used:** Look for "Model loaded on GPU" or "Model loaded on CPU" in Zotero's debug console (Help → Debug Output Logging → View Output).
  606. Note: If WebGPU is unavailable or fails, the plugin automatically falls back to CPU without interruption.
  607. ---
  608. ## Limitations
  609. - **Default model is English-optimized** - The bundled nomic-embed-text-v1.5 is trained primarily on English text; switch to a multilingual model in Settings for non-English libraries (UI available in English and Chinese)
  610. - **Large plugin size** - ~131MB due to bundled AI model
  611. - **CPU only (for now)** - GPU acceleration ready but waiting for Zotero/Firefox WebGPU support
  612. - **Zotero 8 or newer required** - As of v1.12.0, Zotero 7 is no longer supported. Users on Zotero 7 should upgrade to Zotero 8 or later, or stay on ZotSeek v1.11.x.
  613. ---
  614. ## Comparison with OpenAI
  615. | Feature | This Plugin (Local) | OpenAI API |
  616. |---------|--------------------| -----------|
  617. | **Cost** | Free | ~$0.02 per 1K papers |
  618. | **Privacy** | 100% local | Data sent to OpenAI |
  619. | **Offline** | Yes (after model loads) | No |
  620. | **Quality** | Excellent (outperforms text-embedding-3-small) | Good |
  621. | **Speed** | ~70-130ms | ~100ms |
  622. | **Context** | 8192 tokens | 8191 tokens |
  623. ---
  624. ## Technical Details
  625. See the [docs/](docs/) folder for detailed documentation:
  626. - [**API.md**](docs/API.md) - Plugin API for integration with other Zotero plugins
  627. - [**SEARCH_ARCHITECTURE.md**](docs/SEARCH_ARCHITECTURE.md) - Hybrid search, RRF fusion, chunking strategy
  628. - [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) - Development guide, ChromeWorker + Transformers.js implementation
  629. - [**ROADMAP.md**](docs/ROADMAP.md) - Planned features and improvements
  630. - [**MCP.md**](docs/MCP.md) - Local MCP server and REST API for AI agents and scripts
  631. ---
  632. ## Changelog
  633. See [CHANGELOG.md](CHANGELOG.md) for version history.
  634. ## License
  635. MIT License - see [LICENSE](LICENSE)
  636. ---
  637. ## Related Projects
  638. - **[citefact](https://github.com/hearthresearch/citefact)** — CLI that audits a manuscript against the full text of its cited sources, straight from a Zotero collection. ZotSeek helps you *find* the right papers; citefact verifies the final draft actually *uses* them correctly. `uvx citefact check manuscript.md --zotero-collection "My Collection"`.
  639. ---
  640. ## Acknowledgments
  641. - [Transformers.js](https://huggingface.co/docs/transformers.js) by Hugging Face
  642. - [sentence-transformers](https://www.sbert.net/) for the embedding model
  643. - [Zotero](https://www.zotero.org/) for the amazing reference manager
  644. - [windingwind's Zotero Plugin Docs](https://windingwind.github.io/doc-for-zotero-plugin-dev/) for invaluable guidance
  645. ---
  646. *ZotSeek: AI-Powered Semantic Search for Zotero — Built by José Fernandes*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.