Hermes Agent + Honcho

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. For setup, configuration, and CLI commands, see the Hermes Agent Honcho docs.

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:

Prompt-time context injection — durable context about a user loaded into the prompt before generating a response.
Cross-session continuity — recall of stable preferences, project history, and working context across conversations.
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 system prompt, giving Hermes awareness of both who it’s talking to and what it knows.

Available tools

Hermes exposes four Honcho tools to the agent:

Tool	What it does
`honcho_profile`	Fast peer card retrieval (no LLM). Returns curated key facts about the user.
`honcho_search`	Semantic search over memory. Returns raw excerpts ranked by relevance.
`honcho_context`	Dialectic Q&A powered by Honcho’s LLM. Synthesizes answers from conversation history.
`honcho_conclude`	Writes durable facts to Honcho when the user states preferences, corrections, or important context.

Two memory layers

When Honcho is enabled, Hermes operates with two layer memory by default (hybrid): Local session history — the immediate transcript for the current chat, thread, or CLI session. Use it for recent turns, short-lived task context, and follow-up questions. Honcho memory — the semantic, cross-session layer. Use it for user preferences, durable project facts, cross-session continuity, and synthesized peer context.

Running Honcho locally with Hermes

If you want to point Hermes at a local Honcho instance instead of the hosted API:

Docker (quickest)

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp .env.template .env
cp docker-compose.yml.example docker-compose.yml

Edit .env:

OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/honcho
AUTH_USE_AUTH=false

docker compose up -d
curl http://localhost:8000/health

Manual

git clone https://github.com/plastic-labs/honcho.git
cd honcho
uv sync
cp .env.template .env

Edit .env with a local or cloud Postgres connection string and API keys, then:

uv run alembic upgrade head
uv run fastapi dev src/main.py

Then update ~/.honcho/config.json to point at your local instance:

{
  "apiKey": "not-needed-with-auth-disabled",
  "baseUrl": "http://localhost:8000",
  "hosts": {
    "hermes": {
      "workspace": "hermes",
      "peerName": "your-name",
      "aiPeer": "hermes",
      "memoryMode": "hybrid",
      "enabled": true
    }
  }
}

The baseUrl field overrides the default hosted API. With AUTH_USE_AUTH=false on the server, the apiKey value is ignored but the field must still be present. See the full self-hosting guide for database options, cloud setup, and troubleshooting.

Verifying the integration

Steps to test the integration via CLI and agentically by speaking to Hermes agent in natural language.

1. Check configuration

hermes honcho status

2. Test cross-session recall

In one conversation:

Remember that my test phrase is velvet circuit.

In a fresh conversation (different thread, new CLI session):

What is my test phrase?

If Hermes recalls “velvet circuit” after short-term context is gone, Honcho is working.

3. Test writeback

Tell Hermes a preference:

Remember that I prefer terse answers.

Wait briefly if writes are asynchronous. Open a fresh conversation:

How should you respond to me?

If Hermes answers with the stored preference, writeback is functioning.

Session strategy

Scope	When to use
Per-Session	A honcho session starts fresh each time a new Hermes session is created. Hermes remembers the user across sessions.
Per Directory	One honcho session per project directory. Context is scoped to each directory. Coding/project memory scoped to each repository/workspace.
Global (per user)	Continuity across all chats, threads, and projects. One honcho session globally for the user and Hermes agent.

Next steps