---
title: Persistent memory for Hermes Agent, on your own machine
slug: semurg-memory-for-hermes-agent
date: 2026-10-25
author: Semurg
section: how-to
tags: [hermes-agent, mcp, agents, memory, how-to]
summary: Give Hermes Agent a memory that outlives the session, on your own disk, with one entry in its MCP configuration, the token kept out of that file, and a check that needs no model.
status: published
covers: [route:POST /v1/mcp, route:GET /v1/memory/status, mcp:memory_status, mcp:memory_remember, mcp:memory_recall, mcp:memory_context, mcp:memory_relate, mcp:memory_forget, mcp:memory_document]
constants: [24.04]
---
> Tested with Hermes Agent `0.22.5`: Hermes' own MCP client connected to the node and listed every memory tool it serves. The [agents page](/agents#hermes) shows the release it last ran on.

Hermes Agent starts each session without what it learned in the last one. This guide adds a memory it asks instead of forgets: a Semurg
node on your own machine, which Hermes reaches over MCP through one entry in its configuration. Facts stay on your disk, come back cited to
where they were said, and are shared with every other agent on the node that uses the same scope.

> Diagram hermes-memory: Hermes Agent reads one MCP entry from its configuration and the token from its own environment file; it reaches your node, which keeps the memory in the scope you named on your own disk; a later session or another agent on the same scope reads it back, cited.

## What you need

- An Intel or AMD x86_64 machine with Ubuntu 24.04, on Linux directly or on Windows through WSL2. One node is free, with no licence key.
- Hermes on the same machine. Its installer needs `curl`, `git`, `ca-certificates`, `tar` and `xz-utils`; we test both in a fresh `ubuntu:24.04` container.

## Step one: install a node

On Ubuntu 24.04 (x86_64), with sudo:

```bash
curl -fsSL https://one.semurg.io/install | sudo bash
```

The [install page](/install) lists what the installer needs and what it changes. The installer ends by printing your API token, and the
node keeps a copy. Put it in a file only you can read, and have every new terminal load it:

```bash
mkdir -p ~/.config/semurg
(umask 077; sudo grep '^SEMURG_API_TOKEN=' /etc/semurg/semurg.env | cut -d= -f2- > ~/.config/semurg/token)
echo 'export SEMURG_API_TOKEN="$(cat ~/.config/semurg/token)"' >> ~/.bashrc
export SEMURG_API_TOKEN="$(cat ~/.config/semurg/token)"
```

## Step two: install Hermes Agent

Hermes installs itself with its own installer, the line the [agents page](/agents#hermes) shows:

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive
```

The `hermes` command lands in `~/.local/bin`.

## Step three: connect

Add this entry under `mcp_servers:` in `~/.hermes/config.yaml` (add the key itself if the file has none), exactly as the agents page shows
it. Change `default` to a scope of your own per project: agents that use the same scope share what they learn.

```yaml
mcp_servers:
  semurg:
    url: "http://127.0.0.1:4000/v1/mcp"
    headers:
      Authorization: "Bearer ${SEMURG_API_TOKEN}"
      X-Semurg-Scope: "default"
```

The file holds only a reference to the token. Hermes fills it in from its own environment file, `~/.hermes/.env`, when it connects. Put
the token there once, readable only by you:

```bash
(umask 077; echo "SEMURG_API_TOKEN=$(cat ~/.config/semurg/token)" >> ~/.hermes/.env)
chmod 600 ~/.hermes/.env
```

## Step four: check it, then use it

This check needs no model provider. It connects to the node with Hermes' own MCP client and lists what it finds:

```bash
hermes mcp test semurg
```

It should print `Connected` and the memory tools it discovered. Hermes then offers them to its model like its other tools, named
`mcp_semurg_memory_remember`, `mcp_semurg_memory_recall` and so on, so you can ask in plain words: "remember that we chose Postgres for
billing because of the audit log", and in a later session, "what did we decide about billing?". We have tested the connection,
not a conversation with a model.

To see from outside Hermes which of your scopes now hold facts, ask the node directly:

```bash
curl -sS http://127.0.0.1:4000/v1/memory/status \
  -H "Authorization: Bearer $SEMURG_API_TOKEN"
```

## The memory tools in Hermes

Hermes names each tool `mcp_semurg_` followed by the tool's own name, after the entry name `semurg`:

- `memory_status`: reports whether shared memory is on for this node and which of your scopes hold facts.
- `memory_remember`: stores entities, the relationships between them and the passages they came from, or plain text, with an optional source label and date.
- `memory_recall`: recalls what is stored about one named entity, its own facts first, each item cited.
- `memory_relate`: adds one typed relationship between two entities in a scope, creating an end that is not stored yet.
- `memory_context`: answers a question in plain words with cited items and a verdict on whether the store covers it.
- `memory_document`: takes a whole document (PDF with a text layer, Word, HTML or plain text) and stores it as cited passages in a scope.
- `memory_forget`: deletes one thing per call: an entity and everything that names it, one fact, one document, every document under a source label, or the whole scope. It is unreachable at once and not yet wiped from the disk.
- `memory_export`: reads everything a scope holds, one page per call: send each reply's `next` back as `cursor` until it is empty. The records are the entities, the facts with their dated sources and whether each is current or ended, and each stored document once; a forgotten passage is never exported.
- `memory_import`: stores the records `memory_export` produced into any scope, through the same writes `memory_remember` makes. A page sent twice stores nothing twice, and the reply names every record it skipped.

Every answer says its `state`: `answered`, `nothing_stored` (nothing stored matched, so the agent should say it does not know) or `could_not_judge`.

## Troubleshooting

- `hermes: command not found`: the installer puts Hermes in `~/.local/bin`. Add it to your path with `export PATH="$HOME/.local/bin:$PATH"`.
- Keep Hermes' home where its installer put it. With `HERMES_HOME` moved, Hermes builds a separate runtime, and `hermes --version` fails until that runtime is prepared.
- The test does not connect: check that `~/.hermes/.env` holds `SEMURG_API_TOKEN` for this node, and that the node answers with `curl -s http://127.0.0.1:4000/api/health`.
- `mcp_servers:` already has an entry named `semurg` with another address: edit that entry rather than adding a second one, and keep it indented two spaces under the key.

Use `127.0.0.1` rather than `localhost`: on Ubuntu `localhost` can resolve to the IPv6 address first, and the node listens on IPv4 loopback
only.

## Next

- The [agents page](/agents): the configuration for more agents, with the release each was last connected on.
- [Give your agent persistent memory with MCP in five minutes](/blog/agent-memory-mcp-five-minutes): the memory calls over plain HTTP too.
- [Connecting to Semurg over MCP](/blog/connect-over-mcp): the endpoint, the protocol versions it speaks and how a refusal comes back.
- If a step does not work, tell us on the [contact page](/contact), with the reply you got.