lit-monitor 0.11.0

A personal literature tracker that ranks new papers by semantic similarity to your Zotero library, extracts structured fields with an LLM, builds a knowledge graph, and writes to Obsidian.

lit-monitor for Zotero

Semantic literature discovery for researchers who live in Zotero.

lit-monitor tracks PubMed, arXiv, and Scopus on a schedule, ranks every new paper against your existing Zotero library, extracts structured fields with an LLM, and writes everything into your Obsidian vault — queryable from a browser, the terminal, or any AI client that speaks the Model Context Protocol (MCP).

Your library is the signal. Each candidate paper is scored by semantic similarity to embeddings of what you already keep in Zotero, so the feed adapts to whatever you read — papers close to your interests rank higher, papers in a different domain rank lower. Nothing in the pipeline is domain-specific: your Zotero library, a handful of search topics, and an optional free-text domain paragraph are the only inputs it needs.

The default configuration and some examples lean toward downstream biopharmaceutical process development — the domain the tool was originally developed against — but ready-made starting configs for other fields (ML research, climate science, and more) ship in config/examples/. See Installation.

Drive it from a localhost web UI (lit-monitor serve) for setup and day-to-day operation, or from the CLI (lit-monitor --help) for scripted work. Same pipeline either way.

Local-first, free by default. On the default configuration everything runs on your machine: your library is embedded and stored locally (Ollama + ChromaDB), with no per-call API costs. Only outbound paper searches reach PubMed, arXiv, and Scopus. Routing extraction or embeddings to a cloud provider (Anthropic, OpenAI, Vertex AI, Ollama Cloud) is opt-in.

Beta. lit-monitor is feature-complete and in active daily use, but still maturing toward 1.0 — interfaces and on-disk formats may change between releases, and you may hit rough edges. Bug reports and feedback are very welcome via GitHub Issues. Provided under the MIT License, without warranty (see License).

Features

• Topic search with library-relative ranking. Recurring searches across PubMed, arXiv, and Scopus, powered by a bundled copy of findpapers (see Acknowledgements). Each candidate is ranked by cosine similarity to embeddings of your Zotero library, computed locally via mxbai-embed-large (or any LiteLLM-compatible provider) against a per-machine ChromaDB store. Explicit search coverage for individual journal publishers is planned for a future release.
• Obsidian-native output. Every paper becomes a structured Markdown note with persist zones for your own annotations, two-phase LLM extraction, and a citation-graph rebuild path.
• Knowledge graph with an ask interface. A KuzuDB graph stores entities (topics, methods, materials, authors, journals, keywords) and ten typed relationships across the corpus. Ask questions in plain English from the CLI, HTTP, or MCP — for example, lit-monitor ask "what methods extend Carta 2009?". Answers are theme-aware when the library has been clustered.
• Three retrieval modes — vector (semantic), graph (entity-typed), and hybrid (reciprocal-rank fusion), selectable per command with --rag-mode {vector,graph,hybrid}.
• MCP server for AI clients. Twelve tools that Claude Desktop, Cursor, Continue, and any other MCP-capable agent can call to query the graph and vector index, including a read-only Cypher escape hatch with a safety guard.
• Notifications and flexible delivery. An OS notification when a discovery run finishes, a weekly Markdown digest, on-demand Markdown export, or a rich terminal table — configurable.
• Runs on any schedule. One-command install for launchd (macOS) or systemd user timers (Linux), plus ad-hoc runs from the dashboard.

For the scoring model and the design behind each signal, see How it works.

Requirements

• macOS or Linux (ARM Linux, including Raspberry Pi 4/5, works for cloud-Ollama configurations)
• Python 3.11+
• Ollama installed locally for embeddings (ollama pull mxbai-embed-large)
• A Zotero library (Better BibTeX optional)
• An Obsidian vault (full absolute path required)

Install

pip install lit-monitor        # or: uvx lit-monitor / pipx install lit-monitor
lit-monitor first-run

That's the whole install. lit-monitor first-run walks you through interactive setup and then launches the web UI. Ollama is a separate prerequisite for local embeddings (ollama pull mxbai-embed-large) — see Requirements.

For optional extras — [nlp] (BioBERT entity extraction) and [litellm] (multi-provider cloud LLM routing) — and the from-source / development install, see the Installation guide.

From source (development)

git clone https://github.com/max3925vats/lit-monitor.git
cd lit-monitor
./install.sh

The script installs uv if needed, creates a project-local .venv, resolves all dependencies, and seeds working configs from config/*.example.yaml.

Quickstart

Web UI

lit-monitor first-run   # interactive first-time setup, then launches the server
# or, once credentials are configured:
lit-monitor serve

Open http://127.0.0.1:8765/setup in any browser. An 8-step wizard covers credentials, paths, extraction config, topics, domain context, theme vocabulary, tracked researchers, and item routing, with live credential checks at each step. After setup, the dashboards take over. See the Web UI guide for every page.

CLI

lit-monitor check          # verify config + Ollama + Zotero connectivity
lit-monitor brain-build    # index your existing Zotero library (one-time)
lit-monitor run            # first discovery run
lit-monitor serve          # browse results at http://127.0.0.1:8765

Full command surface in the CLI reference. To configure credentials and YAML by hand instead of using the wizard, see Configuration.

Documentation

Guide	Covers
Installation	Install paths, optional extras, field-specific starter configs
How it works	Library-as-signal, score decomposition, clustering, domain extraction, trending, embeddings
Configuration	Three setup recipes, LLM and embedding providers, notifications, strict mode
CLI reference	Every day-to-day command
Web UI	Dashboard pages and the setup wizard
Integrations	MCP server and HTTP API
Development	Running tests and deployment

Glossary

A few terms used throughout the docs:

• Zotero — reference manager that holds your library of papers; lit-monitor reads it as the relevance signal.
• Obsidian — Markdown-based knowledge base; lit-monitor writes one note per paper into a vault (a folder of Markdown files).
• Embedding — a numeric vector representing a paper's text, so similarity can be measured by distance. Papers near your library's embeddings rank higher.
• Ollama — runs language and embedding models locally on your machine (no cloud account needed for the default setup).
• ChromaDB — the local vector database that stores paper embeddings.
• KuzuDB — the local graph database that stores entities (methods, authors, …) and their typed relationships.
• LiteLLM — an optional adapter to route LLM or embedding calls to cloud providers (OpenAI, Anthropic, Vertex AI) instead of local Ollama.
• MCP (Model Context Protocol) — an open standard that lets AI clients (Claude Desktop, Cursor, …) call external tools; lit-monitor ships an MCP server.
• Cypher — the query language for the knowledge graph; the ask and MCP surfaces translate plain English into read-only Cypher under the hood.
• brain-build — the one-time step that indexes your existing Zotero library into the embedding store and graph.
• RRF (reciprocal-rank fusion) — the method behind --rag-mode hybrid that blends vector and graph rankings into one ordered list.

Acknowledgements

Multi-source literature search is powered by findpapers by Jonatas Grosman (MIT License, © 2020). A copy is bundled under lit_monitor/_vendor/findpapers — with its license retained — so that pip install lit-monitor resolves cleanly without an upstream dependency conflict. The original project is gratefully acknowledged.

Explicit search coverage for individual journal publishers (beyond the sources findpapers provides) is planned for a future release.

License

MIT

This project bundles a copy of findpapers (MIT License) — see Acknowledgements and lit_monitor/_vendor/findpapers/LICENSE.