Hermes Agent + Honcho

How Hermes Agent uses Honcho for persistent cross-session memory and user modeling

Hermes Agent is an open-source AI agent from Nous Research with tool-calling, terminal access, a skills system, and multi-platform deployment (Telegram, Discord, Slack, WhatsApp). Honcho gives Hermes persistent cross-session memory and user modeling.

Honcho plugs into Hermes as a memory provider plugin, hermes-plugin-honcho, maintained by Plastic Labs in the Honcho repository. It is listed in the Hermes plugin catalog. Its README is the full reference for configuration and CLI commands.

Installation

hermes plugins install honcho
hermes memory setup honcho

hermes memory setup honcho walks you through connecting to Honcho with OAuth sign-in, a device code, or an API key from app.honcho.dev.

Honcho used to ship inside Hermes. If you set it up before it moved to the catalog, hermes update installs the plugin for you and keeps your existing config.

What Honcho provides

Honcho acts as a long-term memory and user-model layer alongside Hermes’ built-in memory files (MEMORY.md and USER.md).

It gives Hermes three capabilities:

1. Prompt-time context injection — durable context about a user loaded into the prompt before generating a response.
2. Cross-session continuity — recall of stable preferences, project history, and working context across conversations.
3. Durable writeback — stable facts learned during a conversation stored back for future turns.

These sit alongside Hermes’ local session history. Session history remembers the current conversation. Honcho remembers what should still matter later.

Dual-peer architecture

Both the user and the AI agent have peer representations in Honcho:

• User peer: observed from user messages. Learns preferences, goals, communication style.
• AI peer: observed from assistant messages. Builds the agent’s knowledge representation.

Both representations are injected into the user message at API-call time (not the system prompt, which keeps prompt caching intact), giving Hermes awareness of both who it’s talking to and what it knows.

Available tools

The plugin exposes five Honcho tools to the agent. Each takes an optional peer argument (user or ai, default user):

Tool	What it does
honcho_profile	Fast peer card retrieval (no LLM). Returns curated key facts about the peer.
honcho_search	Hybrid semantic and keyword search over past messages. Returns ranked excerpts.
honcho_context	Full session context: summary, representation, peer card, and recent messages (no LLM).
honcho_reasoning	Dialectic Q&A powered by Honcho’s LLM. Synthesizes an answer from memory.
honcho_conclude	Writes, lists, searches, or deletes durable conclusions about the peer.

Tools are hidden when recallMode is context.

Running Honcho locally with Hermes

Follow the Self-Hosting Guide to get Honcho running locally. Once it’s up, point Hermes at your instance:

hermes memory setup honcho  # choose self-hosted, enter http://localhost:8000 as the base URL

Or manually create/edit the config file (checked in order: $HERMES_HOME/honcho.json > ~/.hermes/honcho.json > ~/.honcho/config.json):

{
  "baseUrl": "http://localhost:8000",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "your-name",
      "workspace": "hermes"
    }
  }
}

For the full list of config fields (recallMode, writeFrequency, sessionStrategy, dialecticReasoningLevel, etc.), see the plugin README.

Verifying the integration

1. Check status

hermes honcho status

This should show Honcho as enabled with your workspace and peer names, followed by Connection... OK. If it also prints Peer data unavailable, the connection works but reading peer data failed.

2. Store a fact and recall it across sessions

In one conversation, tell Hermes something specific:

My favorite programming language is Rust and I always use dark mode.

Start a new session (different thread, new CLI invocation, or a different platform). Ask:

What do you know about my preferences?

If Hermes mentions Rust and dark mode without being told again, cross-session memory is working. The deriver processed your messages, extracted observations, and the dialectic recalled them.

3. Test tool calling directly

Ask Hermes to use a specific Honcho tool:

Use your honcho_search tool to find anything you know about me.

If Hermes calls the tool and returns results, the full tool pipeline (API connection, vector search, embedding) is functional.

Configuration options

Field	Default	Description
recallMode	hybrid	hybrid (auto-inject + tools), context (inject only), tools (tools only)
writeFrequency	async	async, turn, session, or integer N
sessionStrategy	per-directory	per-directory, per-repo, per-session, global
dialecticReasoningLevel	low	minimal, low, medium, high, max
reasoningHeuristic	true	Raise the auto-injected dialectic’s reasoning level for longer queries, up to reasoningLevelCap
dialecticDynamic	true	Let the agent pick the reasoning level per call to honcho_reasoning
messageMaxChars	25000	Max chars per message (chunked if exceeded)

Reporting issues

File plugin bugs and feature requests with the Hermes plugin issue template. If the problem still happens with Honcho disabled, report it to Hermes Agent instead.

Next steps

Plugin README

Full configuration reference, CLI commands, and how the plugin works.

Plugin Source

hermes-plugin-honcho in the Honcho repository.

Honcho Architecture

Peers, sessions, and how reasoning works.

Self-Hosting Guide

Full local environment setup, provider configuration, and troubleshooting.