Giving Hermes Agent Access to Your Own Files

This post assumes you already run Hermes Agent and are comfortable with its configuration. What it adds is the other half: a local document search server, so the agent can answer from your own files rather than only from what you paste into the session.

What we can and cannot vouch for

Stating this first, because setup instructions that quietly guess are worse than none.

We can vouch for the server side. LocalSynapse speaks MCP over stdio, exposes nine tools, and we measure its behaviour continuously — response shape, latency, what happens when a search finds nothing.

The Hermes specifics below come from its documentation, not from us running the two together. The config path, the key names and the reload command are as documented for Hermes Agent. If any of it has moved in a newer version, its documentation wins over this post — and we would appreciate being told.

The config entry

Hermes reads MCP servers from ~/.hermes/config.yaml under mcp_servers. LocalSynapse is a stdio server: one executable, invoked with the argument mcp.

mcp_servers:
  localsynapse:
    command: 'C:\Program Files\LocalSynapse\LocalSynapse.exe'
    args: ["mcp"]

On macOS:

mcp_servers:
  localsynapse:
    command: "/Applications/LocalSynapse.app/Contents/MacOS/LocalSynapse"
    args: ["mcp"]

Then /reload-mcp in a session to pick it up without restarting.

The Windows path deserves a note, because it is the most common way this fails silently. YAML treats a backslash as an escape character inside double-quoted strings. Use single quotes, as above, and the backslashes are taken literally. Forward slashes also work. Get this wrong and the config parses, the server never starts, and nothing tells you why.

The option that matters most here: tool filtering

Hermes supports per-server tool filtering, and with LocalSynapse it is worth using deliberately.

Here is why. Tool definitions are sent to the model on every turn, whether or not any tool gets called. LocalSynapse exposes nine, covering search, reading file contents, browsing the index, spreadsheets, mail threads, timelines and index maintenance. If your Hermes work only ever needs to search and read, the other seven are a fixed tax on every message in the session.

mcp_servers:
  localsynapse:
    command: 'C:\Program Files\LocalSynapse\LocalSynapse.exe'
    args: ["mcp"]
    tools:
      include: [search_files, get_file_content]

Include takes precedence over exclude, and both accept glob patterns as well as exact names. Our own measurement of the full tool list is about 5,500 characters; trimming to two tools removes most of that from every turn. If you later want the timeline or spreadsheet tools, add them and reload.

What the tools do

Enough to decide what to include:

• search_files — search inside documents by keyword or meaning. Returns documents with several passages each, plus a statement of how the query was read.
• get_file_content — read the extracted text of up to twenty indexed files in one call, by id.
• list_indexed_files — browse what is indexed, filtered by folder or extension.
• get_pipeline_status — check indexing coverage before trusting an empty result.
• get_email_thread — walk a mail conversation up and down the reply chain.
• get_spreadsheet — read a workbook as structure: cell coordinates, sheet names, merged ranges, declared types honoured.
• get_timeline and get_work_session — reconstruct what happened around a period or a stretch of work.
• preview_index_removal — show what would be removed from the index. A dry run, not an action.

What a search returns

Worth knowing before you write prompts against it, because the shape is not the usual list of snippets.

A result is a set of documents with passages under them — several excerpts per document, each carrying its position — rather than one truncated teaser per file. The caller states a purpose, and the response is sized for it: locating documents returns many with short excerpts, answering a question returns fewer with long ones. On our own test set that is roughly 176 characters of document text per result versus about 1,850.

Each response also carries a request block stating how the query was read — which terms ran, which were dropped as stop words, the expression that executed — and which axes were not constrained, with counts. If the interpretation did not hold up, that is said outright rather than dressed as a plausible list. For an agent that composes tool calls, this matters: it can correct a misread query and re-run instead of reasoning over the wrong material.

Verifying it works

Hermes does not document a status command for MCP servers, so verify by behaviour rather than by a green light.

1. Process list. With a Hermes session open, a LocalSynapse process should be running as a child of it.
2. Tool list. Ask the agent which tools it has. If your filtered set comes back by name, discovery worked.
3. A real search, then a search with no answer. Ask something that requires your files, then ask something your files genuinely do not contain. The second is the important one — a working setup says it found nothing, and a broken one lets the agent answer anyway from general knowledge in exactly the same tone.

Two practical notes

You do not need the desktop app open. Hermes launches the server itself; the LocalSynapse window is optional and closing it changes nothing for the agent.

Running Hermes and another client at once is fine. Each launches its own server process and each gets full search. Indexing is not duplicated — exactly one process maintains the index at a time. The cost to know about is memory: the semantic model loads per process that needs it, which is also why it is released as soon as there is nothing left to index.

If you get this working and something in the Hermes half of these instructions is out of date, please tell us. We would rather correct the post than leave someone following it into a config that quietly does nothing.