Hermes
A library and microservice implementing the health and care terminology SNOMED CT with support for cross-maps, inference, fast full-text search, autocompletion, compositional grammar and the expression constraint language.
Ask AI about Hermes
Powered by Claude Β· Grounded in docs
I know everything about Hermes. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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,
hermesrefers to the Homebrew-installed command. If you downloaded the jar, usejava -jar hermes.jarinstead. If you're running from source, useclj -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

