Connect Hermes

This page is for your own Hermes Agent install — not the Companion Hermes app from the Hub app store.

The Companion app does not fork Hermes. It builds on the official Hermes Agent image and layers a terminal UI and setup flow on top, so everything below works against a stock install.

Before you start

You need two API keys and the addresses of both servers.

<hub-url> and <memory-url> below are your two servers’ base URLs — everything before /api/mcp. Neither has a port you can assume, so take both from the Hub dashboard if you are unsure: Hub, Memory.

Add the servers

Hermes has a command for this, and it is the better path: it tests each server before you commit to it, and it keeps your key out of config.yaml. Editing the file by hand still works and is documented below — the result is the same shape either way.

With hermes mcp add

hermes mcp add hub       --url "<hub-url>/api/mcp"     --auth header
hermes mcp add ci_server --url "<memory-url>/api/mcp"  --auth header

The name is the config key, so choose it deliberately: it is what hermes mcp test and hermes mcp remove take afterwards, and it decides the environment variable name below. hub and ci_server match the rest of this page.

Each run asks whether the server needs authentication, takes the key, then connects:

Does this server require authentication? [Y/n]: y
API key / Bearer token:
✓ Saved to ~/.hermes/.env as MCP_HUB_API_KEY

Connecting to 'hub'...
✓ Connected! Found 76 tool(s) from 'hub':
  ...
Enable all 76 tools? [Y/n/select]:

Read the tool count before answering. That number is the check the scope trap describes, arriving at the one moment it is cheap to act on. A memory server reporting zero tools has a key without the Intents scope.

What it writes

mcp_servers:
  hub:
    url: "<hub-url>/api/mcp"
    headers:
      Authorization: Bearer ${MCP_HUB_API_KEY}
    enabled: true

Your key is not in there. It goes to $HERMES_HOME/.env — ~/.hermes/.env, or %LOCALAPPDATA%\hermes\.env on native Windows — and config.yaml only references it. On macOS and Linux that file is written at mode 0600; on Windows POSIX modes do not apply, and it inherits the ACLs of your local app-data directory, which are user-private by default. The variable is MCP_ + the server name uppercased + _API_KEY, so hub gives MCP_HUB_API_KEY and ci_server gives MCP_CI_SERVER_API_KEY.

That split is the main reason to prefer this over hand-editing. config.yaml is the file that gets screenshotted, pasted into a support thread, and synced between machines; a bearer token written inline goes everywhere it goes.

Raise the memory timeout by hand

One line the command cannot write, because there is no flag for it — --connect-timeout sets a different thing. Add it to the memory server:

mcp_servers:
  ci_server:
    timeout: 600

It is deliberate: recall over a large memory store can take longer than the default allows, and the resulting failure looks like a broken server rather than a slow one. Hermes’ default is 300 seconds, so only a value above that actually buys you headroom — setting a smaller number makes the timeout you were trying to avoid more likely. There is no need to set connect_timeout; its default of 60 is already right for these servers.

Or edit config.yaml yourself

Hermes is configured through config.yaml, in $HERMES_HOME — ~/.hermes/config.yaml on a stock macOS, Linux or WSL2 install, %LOCALAPPDATA%\hermes\config.yaml on native Windows. Both servers go under mcp_servers:

mcp_servers:
  hub:
    url: "<hub-url>/api/mcp"
    headers:
      Authorization: "Bearer <hub-key>"
  ci_server:
    url: "<memory-url>/api/mcp"
    headers:
      Authorization: "Bearer <memory-key>"
    timeout: 600

This puts both keys in config.yaml in the clear. To keep the indirection the command gives you, write Bearer ${MCP_HUB_API_KEY} here and put the key in ~/.hermes/.env yourself — the variable name is yours to choose when you do it this way.

Restart and verify

Testing 'ci_server'...
Transport: HTTP → https://memory.example.com/api/mcp
  Authorization: Bear***f3a1
✓ Connected (92ms)
✓ Tools discovered: 3

Which side of WSL are you installing into?

Skip this unless you are on Windows. Hermes supports both a native Windows install and a WSL2 one, and they are separate installations with separate homes:

Everything on this page — the plugin directory, config.yaml, .env — belongs to whichever one runs your agent. A ~ typed in PowerShell resolves to C:\Users\<you>, which a WSL2 Hermes will never scan; a ~ typed inside the distro is its own Linux home, which a native Hermes will never scan. If you are not sure which you have, run hermes --version in each and see which answers.

First-class memory

Everything above gives your agent memory it can call. Hermes also has a native memory provider interface, separate from MCP, and that is what produces passive capture and injected context — conversations recorded without anyone calling a tool.

The provider is published as @companionintelligence/hermes-memory. Nothing about it requires Node or npm: the npm registry is used purely as versioned tarball hosting, and Hermes discovers providers by scanning a directory. You can do this instead of the MCP sections above if passive memory is all you want.

The official way

rm -rf ~/.hermes/plugins/companionintelligence
mkdir -p ~/.hermes/plugins/companionintelligence
curl -fL https://registry.npmjs.org/@companionintelligence/hermes-memory/-/hermes-memory-2026.8.3.tgz \
  | tar -xz -C ~/.hermes/plugins/companionintelligence --strip-components=1

$dst = "${env:LOCALAPPDATA}\hermes\plugins\companionintelligence"
if (Test-Path $dst) { Remove-Item -Recurse -Force $dst }
New-Item -ItemType Directory -Force $dst | Out-Null
curl.exe -fL https://registry.npmjs.org/@companionintelligence/hermes-memory/-/hermes-memory-2026.8.3.tgz -o "$env:TEMP\hermes-memory.tgz"
tar.exe -xzf "$env:TEMP\hermes-memory.tgz" -C $dst --strip-components=1
Remove-Item "$env:TEMP\hermes-memory.tgz"

hermes memory setup

hermes memory status

The cihub connect way

If you are working on the Hub host itself:

cihub connect hermes --memory-url "<memory-url>" --memory-key "<memory-key>"

It probes the server first — the key as well as the address, unlike the wizard’s own check — then fetches and unpacks the pinned version for you. Memory credentials still stay with the wizard, which owns them, so you finish with hermes memory setup. Add --dry-run to see what it would do and write nothing.

Adding --hub-url and --hub-key registers the Hub MCP server in config.yaml for you, as the mcp_servers.hub block, so you can skip Add the servers for that one. Start a new Hermes session afterwards — mcp_servers is read at startup.

Note that it writes the key inline rather than as the ${MCP_HUB_API_KEY} reference hermes mcp add produces. If you would rather your token stayed out of config.yaml, use hermes mcp add for the Hub server and let cihub connect handle only the plugin.

It configures the machine it runs on. If Hermes lives elsewhere, use the official way there.

When memory does not accumulate

The wizard did not list companionintelligence. The files are not where Hermes scans, and there are two ways to land there. On native Windows, the usual one is the directory: $HERMES_HOME is %LOCALAPPDATA%\hermes, not ~/.hermes, so an extraction into the latter succeeds and is never seen — as is one done on the Windows side for a Hermes that lives in WSL2, or vice versa. Otherwise check $HERMES_HOME/plugins/companionintelligence/__init__.py exists at all: --strip-components=1 is what puts the files at the top of that directory rather than one level down.

Run hermes memory status — or print the home Hermes resolves, using the tab for the shell you are in:

hermes --version && echo "[$HERMES_HOME]"

hermes --version; "[$env:HERMES_HOME]"

Brackets so an unset value is visibly empty. An empty [] — from the form above that matches your shell — means the platform default is in use: %LOCALAPPDATA%\hermes on native Windows, ~/.hermes everywhere else.

The wizard printed Nothing was saved. The connection test failed, and the wizard refused to save a configuration it had just proved does not work. The message names the cause: a connection refused, a 401, or an unexpected status.

Setup succeeded, nothing accumulates. First: configuration is read at startup, so start a new session. If a new session still captures nothing, suspect the key — wrong, missing the Memory scope, or minted Read-only. The wizard’s check cannot catch any of those, and the provider fails silently rather than break your session, so re-run hermes memory setup with a re-checked key.

Turning it off. hermes memory off clears memory.provider and returns you to built-in memory. That alone is enough; the /plugins page does not gate this plugin.