Hermes Agent Integration Guide

Plug-and-play persistent memory for Hermes Agent. Add one MCP server and your agent remembers everything across sessions, platforms, and conversations.

Overview

Hermes Agent is an AI agent framework that supports the Model Context Protocol (MCP) for extensible tool use. AgentRecall provides a memory MCP server that automatically stores and retrieves contextual information — preferences, corrections, facts, and temporal events — so your Hermes agent carries knowledge forward between sessions.

The integration is a single YAML config change and a restart. No code modifications needed.

Prerequisites

Python 3.10 or later installed on your system.
Hermes Agent installed and operational (hermes --version should work).
An AgentRecall account with an active API key (ark_...).

Installation

Install the AgentRecall MCP server package globally:

pip install agentrecall-mcp

Important

Hermes Agent uses its own virtual environment. If the binary is not on the PATH that Hermes sees at runtime, the MCP server will fail to launch. See the troubleshooting section below.

Setup

Open your Hermes configuration file and add the MCP server block:

"comment"># Edit the config file\nvim ~/.hermes/config.yaml

Add the following section to your config:

"keyword">mcp_servers:\n  agentrecall:\n    command: "agentrecall-mcp"\n    env:\n      AGENTRECALL_API_KEY: "ark_YOUR_KEY"\n      AGENTRECALL_AGENT_ID: "hermes-agent"

Replace ark_YOUR_KEY with the API key from your AgentRecall dashboard. The AGENTRECALL_AGENT_ID value determines the namespace for all stored memories.

Restart Hermes

Apply the configuration by restarting the Hermes gateway:

hermes gateway restart

This shuts down the current session, reloads config.yaml, and spawns the MCP servers defined in the configuration.

Verify Installation

Check that the MCP server is registered:

hermes mcp list

You should see `agentrecall` listed with a healthy status.

You can also verify it works end-to-end by asking your agent:

"comment"># In a Hermes conversation:\n"Search my memories for my preferred editor"

If the agent returns results (or says it found nothing yet), the integration is working.

Configuration Reference

All configuration is passed as environment variables to the MCP server process. Set them in the env block of your config.

Variable	Description	Required	Default
AGENTRECALL_API_KEY	Your AgentRecall API key (ark_...)	Yes	—
AGENTRECALL_AGENT_ID	Agent identifier (e.g. hermes-agent)	Yes	hermes
AGENTRECALL_BASE_URL	Custom API endpoint	No	https://api.agentrecall.com
AGENTRECALL_LOG_LEVEL	Logging verbosity	No	info

Use Cases

Session Memory

Continue conversations exactly where you left off. The agent recalls what you discussed, decisions you made, and tasks that are still pending.

Preference Tracking

Over time the agent learns your coding style, communication preferences, tool choices, and workflows — applying them without being asked.

Multi-Platform Context

Interact with Hermes from your CLI, Telegram, Discord, or Slack and the memory is shared. Context flows seamlessly between platforms.

Troubleshooting

Venv Mismatch — Most Common Issue

Hermes Agent runs inside its own Python virtual environment. If you installed agentrecall-mcp with your system Python, Hermes won't find the binary.

Solution A: Install inside Hermes's venv:

"comment"># Find Hermes venv location\nhermes venv path\n\n# Install into it\n$(hermes venv path)/bin/pip install agentrecall-mcp

Solution B

Use an absolute path in your config.yaml so Hermes doesn't need the binary on PATH:

"keyword">mcp_servers:\n  agentrecall:\n    command: "/path/to/agentrecall-mcp"\n    env:\n      AGENTRECALL_API_KEY: "ark_YOUR_KEY"\n      AGENTRECALL_AGENT_ID: "hermes-agent"

Orphaned MCP Server Processes

If Hermes restarts abruptly (crash, force-kill), the old MCP server process may remain running. This can cause port conflicts or stale connections.

Cleanup:

"comment"># Find orphaned agentrecall processes\nps aux | grep agentrecall-mcp\n\n# Kill them\nps aux | grep agentrecall-mcp | grep -v grep | awk '{print $2}' | xargs kill

Updating the Server

When a new version of agentrecall-mcp is released:

"comment"># Update globally\npip install --upgrade agentrecall-mcp\n\n# Or update inside Hermes venv\n$(hermes venv path)/bin/pip install --upgrade agentrecall-mcp\n\n# Restart to pick up the new version\nhermes gateway restart