> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent + Honcho

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

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source AI agent from [Nous Research](https://nousresearch.com) 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`](https://github.com/plastic-labs/honcho/tree/main/hermes-plugin-honcho), maintained by Plastic Labs in the Honcho repository. It is listed in the Hermes plugin catalog. Its [README](https://github.com/plastic-labs/honcho/tree/main/hermes-plugin-honcho#readme) is the full reference for configuration and CLI commands.

## Installation

```bash theme={null}
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](https://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](https://honcho.dev/docs/v3/contributing/self-hosting.md) to get Honcho running locally. Once it's up, point Hermes at your instance:

```bash theme={null}
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`):

```json theme={null}
{
  "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](https://github.com/plastic-labs/honcho/tree/main/hermes-plugin-honcho#full-configuration-reference).

## Verifying the integration

### 1. Check status

```bash theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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](https://github.com/plastic-labs/honcho/issues/new?template=6-hermes.yml). If the problem still happens with Honcho disabled, report it to [Hermes Agent](https://github.com/NousResearch/hermes-agent/issues) instead.

## Next steps

> [card] [Plugin README](https://github.com/plastic-labs/honcho/tree/main/hermes-plugin-honcho#readme)
>
> Full configuration reference, CLI commands, and how the plugin works.

> [card] [Plugin Source](https://github.com/plastic-labs/honcho/tree/main/hermes-plugin-honcho)
>
> `hermes-plugin-honcho` in the Honcho repository.

> [card] [Honcho Architecture](https://honcho.dev/docs/v3/documentation/core-concepts/architecture.md)
>
> Peers, sessions, and how reasoning works.

> [card] [Self-Hosting Guide](https://honcho.dev/docs/v3/contributing/self-hosting.md)
>
> Full local environment setup, provider configuration, and troubleshooting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.