Hermes : terminology tools, library and microservice

Hermes is a SNOMED CT terminology server and command-line tool and library. It imports and indexes a distribution in under 5 minutes, with fantastic performance characteristics and has no runtime dependencies beyond a filesystem. No Docker, no Elasticsearch, no PostgreSQL.

It provides:

• fast full-text search with autocompletion, locale-aware synonyms and ECL constraints
• full Expression Constraint Language (ECL) v2.2 — query the ontology by structure, not just text
• inference and subsumption — "is this concept a type of X?" in microseconds
• cross-mapping to and from ICD-10, Read codes, OPCS and arbitrary reference sets
• SNOMED CT compositional grammar — parse, validate, render and normalize expressions
• OWL reasoning for post-coordinated expression classification, subsumption and normal forms
• a native Model Context Protocol (MCP) server with 29 tools for AI assistants
• a HTTP/JSON API for language-agnostic integration
• a HL7 FHIR R4 terminology server via hades — a generic, conformant FHIR terminology server built on hermes
• an embeddable JVM library for in-process use from Clojure, Java or any JVM language
• declarative codelist generation from ECL, ICD-10 and ATC codes

It is designed to work at every scale — from a developer or analyst's laptop, to a single instance serving thousands of concurrent users, to a horizontally scaled deployment behind an API gateway. The database requires no external services and can be shared across multiple instances via a single mounted volume. Updating to a new SNOMED release is a single command.

Hermes is widely used in production systems across the World. It is fully open source under the Eclipse Public License v2.0.

Quickstart

You need Java 17+ installed, or use Homebrew which installs Java automatically.

Note: Throughout this documentation, hermes refers to the Homebrew-installed command. If you downloaded the jar, use java -jar hermes.jar instead. If you're running from source, use clj -M:run. All three are equivalent.

Install

brew install wardle/tools/hermes

Or download the latest jar from GitHub releases, or run from source.

Download, import, index and compact

If your distribution supports automated download (UK via TRUD, or any MLDS member nation):

hermes --progress --db snomed.db install --dist uk.nhs/sct-monolith --api-key trud-api-key.txt --cache-dir /tmp/trud index compact

Or import a manually downloaded distribution:

hermes --db snomed.db import ~/Downloads/snomed-2024/ index compact

Run a HTTP server

hermes --db snomed.db --port 8080 serve

curl -s -H 'Accept-Language: en-GB' \
  'http://localhost:8080/v1/snomed/search?s=heart+attack&constraint=<64572001&maxHits=5' | jq .

Run an MCP server for AI assistants

hermes --db snomed.db mcp

Add to Claude Code:

claude mcp add --transport stdio --scope user hermes -- hermes --db /path/to/snomed.db mcp

Or add to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["--db", "/path/to/snomed.db", "mcp"]
    }
  }
}

See MCP documentation for details on the 29 available tools, guided prompts and built-in resources.

Performance

Measured on a MacBook Pro M1 (2021), single process, no external services.

Operation	In-process	HTTP (single)	HTTP (50 concurrent)
Concept lookup	0.82 us	59 us / 15,546 req/s	311 us / 86,167 req/s
Free-text search (10 hits)	141-184 us	292-378 us / 2,642-3,312 req/s	0.93 ms / 27,392 req/s
Subsumption test	13-69 us	81 us / 11,801 req/s	—

See benchmarks for full details.

Documentation

Guide	Description
Installation	Install methods, downloading distributions, building a database
HTTP API	Endpoint reference with examples
MCP server	AI integration — tools, prompts, resources and configuration
Search and ECL	Full-text search, autocompletion and Expression Constraint Language
ECL implementation status	Feature-by-feature ECL v2.2 (and v2.3) coverage — what works, what's planned, what isn't currently supported
Cross-mapping	Mapping to/from ICD-10, OPCS, reference sets and analytics
OWL reasoning	Post-coordinated expression classification and normal forms
REPL exploration	Interactive SNOMED CT exploration with the Clojure REPL
Library usage	Embedding hermes in JVM applications
Deployment	Containers, horizontal scaling and version management
Performance	Benchmarks and load testing
Development	Building, testing, linting and releasing

Use cases

I have embedded hermes into clinical systems, where it drives fast autocompletion — users start typing and the diagnosis, procedure, occupation or ethnicity pops up. They don't generally know they're using SNOMED CT. I use it to populate drop-down controls and for real-time decision support — e.g. does this patient have a type of motor neurone disease? — switching UI functionality on and off based on subsumption checks that return in microseconds.

Hermes is equally at home in data pipelines and large-scale population analytics. Because it has no external dependencies and runs read-only from a single database file, it can be embedded directly into batch or streaming jobs — an Apache Spark executor, a Kafka Streams processor, or a plain ETL script — without standing up a separate service. Every worker gets its own memory-mapped view of the same file; there is no shared server to become a bottleneck. I routinely use hermes to classify clinical records against SNOMED hierarchies, cross-map to ICD-10 for reporting, and build analytic cohorts from ECL expressions. A large number of my academic publications are a direct result of using SNOMED in this way.

For AI and LLM workflows, hermes runs as a local MCP server, giving models direct access to the full SNOMED ontology — search, subsumption, cross-mapping and ECL — without network round-trips or API keys.

Related projects

Project	Description
hades	Generic, conformant HL7 FHIR R4 terminology server built on hermes
codelists	Declarative codelist generation from ECL, ICD-10 and ATC codes
dmd	UK dictionary of medicines and devices
trud	UK reference data updates
deprivare	Socioeconomic deprivation data
clods	UK organisational data
nhspd	UK geographical data via the NHS postcode directory

Support

Raise an issue on GitHub, or more formal support options are available on request, including a fully-managed service.

Licence

Copyright (c) 2020-2026 Mark Wardle / Eldrix Ltd.

Distributed under the Eclipse Public License 2.0.

Hermes is listed on the SNOMED International Terminology Services page.

SNOMED CT data requires a separate licence — see SNOMED International or your national release centre.

Mark