Hermes Medical Literature Search

A portable Agent Skill and deterministic CLI for reproducible medical-literature retrieval. It structures simple or compound PICO/PCC questions into AND-of-OR groups, creates transparent database-specific strategies, searches PubMed, PMC, OpenAlex, Semantic Scholar, and optionally Scopus, then preserves native and deduplicated MDR-ranked results.

This is the Agent Skill version of the article-search stage of medical-deep-research.

Install the skill

Hermes:

hermes skills tap add junhewk/hermes-medical-search
hermes skills install junhewk/hermes-medical-search/skills/medical-literature-search

Other Agent Skills-compatible clients can install the skills/medical-literature-search directory. The skill invokes the CLI from the matching GitHub release with uvx; no server remains running.

CLI development

uv sync --extra dev
uv run hermes-medical-search --help
uv run pytest

Configure NCBI_EMAIL for PubMed/PMC. Optional credentials are NCBI_API_KEY, OPENALEX_API_KEY, SEMANTIC_SCHOLAR_API_KEY (or S2_API_KEY), SCOPUS_API_KEY, and SCOPUS_INSTTOKEN. Secrets are read only by the CLI; configured values are stripped from provider errors before those errors reach a run artifact. uv run hermes-medical-search doctor --json reports what is configured and reachable.

Create a strategy:

uv run hermes-medical-search plan question.json --mode review --limit-per-source 100 --json
uv run hermes-medical-search approve runs/<run> --strategy-digest <sha256>
uv run hermes-medical-search preflight runs/<run>
uv run hermes-medical-search search runs/<run>

Review mode requires digest-bound strategy approval and a successful explicit preflight. Select database variants independently with repeatable --variant SOURCE=sensitivity|precision.

Quick mode defaults to 20 results per source and the previous three years:

uv run hermes-medical-search run question.json

The mdr-v2-grouped score in ranked-results.jsonl is a transparent prioritization heuristic. It is not GRADE, risk-of-bias assessment, evidence quality, or a systematic-review conclusion. Recency is scored against the strategy's creation date, so re-running or resuming a run reproduces the file exactly.