retrievr

Guide

Add document search to Hermes

After this, Hermes can answer from your own documents and quote the page it read. The entry is YAML, so whitespace and quoting are part of the instruction.

1. Give Hermes the tool

Paste this into a session and let it work:

Fetch https://retrievr.io/install and follow it.

The sheet writes the key to ~/.config/retrievr/credentials — never printed — and the MCP server to ~/.config/retrievr/mcp.mjs.

2. Add the block to ~/.hermes/config.yaml

Hermes keeps MCP servers under mcp_servers, two spaces per level:

mcp_servers:
  retrievr:
    command: "node"
    args: ["/home/you/.config/retrievr/mcp.mjs"]

Three things that bite in YAML specifically. Quote "node" — it is harmless unquoted, but the habit is what saves a value that is not. Keep the path in flow-style brackets with double quotes, because a bare path with unusual characters ends a scalar early. And indent the two lines under retrievr: with spaces, not a tab: a tab is a parse error in YAML and the message will not say so in those words.

The path must be absolute. The arguments reach the process without a shell, so ~ is not expanded; echo $HOME prints the prefix.

The shape is checked against Hermes’s MCP documentation.

3. Check it loaded

Start a new Hermes session and ask what tools it has. retrievr should appear with five: retrievr_search, retrievr_documents, retrievr_upload, retrievr_upload_status and retrievr_delete_document.

4. Ask it something

Add a document from your library, then ask in plain language:

In the report, what does it say about the forecast?
Which of my documents mentions the deadline?

Each passage names its page and character range, so the quote can be checked. The service is always ready and answers in well under a second.

When the tool does not appear

A YAML file that fails to parse is ignored quietly, so the first check is that the block is real YAML rather than YAML-shaped: two spaces per level, no tabs anywhere, and mcp_servers at the top level rather than under another key.

The second is the path: an array of arguments reaches the process without a shell, so ~ is a literal character. And if you already had an mcp_servers block, the new one replaces it rather than merging — the other servers would go missing at the same moment, which is the clue.

What it costs

$0.01 per query, charged when it is accepted; uploading and indexing are free. The full price list, or the same guide for opencode or pi.