How to set up Honcho memory for Hermes Agent

Give Hermes Agent long-term memory with Honcho: install the plugin, connect your account, link your chat apps and the terminal, check it works and fix common problems.

Docs-backed6 min read · Reviewed Nov 9, 2026

What Honcho adds to Hermes

Disclosure: Honcho is a paid HermesWatcher partner. This guide is written from the official Honcho and Hermes Agent docs, plus details supplied by Plastic Labs, the company behind Honcho. The steps are the same whether or not you use HermesWatcher's link and code.

Honcho is an open-source memory plugin for Hermes Agent, made by Plastic Labs. It learns from your conversations in the background and gives Hermes a long-term picture of you, so you repeat yourself less, even in a brand-new chat.

It works alongside Hermes's built-in memory, not instead of it. Hermes keeps its two small files, MEMORY.md and USER.md (see how Hermes Agent memory works). Honcho adds a profile of you (your preferences, goals and how you work) and one of the agent, and Hermes can draw on them before it replies.

The memory lives in your Honcho account, not in one Hermes install. Your chat apps, the terminal and other agents can share it, as long as each one uses the same Honcho account and the same workspace, and is linked to the same person.

Watch it work (1:40): what Alex tells Hermes on Telegram comes back in a brand-new Hermes chat and in Claude Code, then a conclusion Honcho wrote, shown in the dashboard next to the Telegram message it came from. Real recordings with a demo user, Alex.

Is it worth setting up?

Honcho is most useful if:

  • You start a lot of new chats and are tired of explaining the same things again.
  • You talk to Hermes in more than one place, such as a chat app and the terminal, and want one memory across them.
  • You want to see, and correct, what your agent has learned about you.

You may not need it if MEMORY.md and USER.md already hold what matters to you, or if you don't want your messages sent to an outside service and don't want to run your own Honcho server. Hermes also runs only one external memory provider at a time.

The card below has HermesWatcher's partner link and code. The setup is the same if you go to app.honcho.dev (opens in a new tab) directly.

What you need

  • Hermes Agent installed, with a model provider configured. New to Hermes? Start with Install Hermes Agent.
  • A Honcho Cloud account at app.honcho.dev (opens in a new tab). New accounts get $5 in free credits, plus $5 more each month once you add a card. The code hermeswatcher gives new accounts $10 in credits. After that, Honcho Cloud is pay as you go.
  • Or your own Honcho server instead of an account. The core is open source and can be self-hosted. Honcho's Hermes guide (opens in a new tab) links the self-hosting steps.

If you chat with Hermes from an app, connect it first

Hermes can also run in chat apps such as Telegram, Discord, Slack and WhatsApp, through its messaging gateway. If you use one, connect it before you set up Honcho. With a gateway connected, Honcho's setup asks who talks to it, and that answer is what puts your chat app and terminal messages under one person. See all the ways to chat with Hermes to set one up, then come back.

Only use the terminal? Skip to the next step.

Install and connect Honcho

Install the plugin from the catalog, then run the memory setup for Honcho.

Terminal

hermes plugins install honcho
hermes memory setup honcho

The setup asks a series of questions. This guide covers the ones that matter here, and the defaults are fine for the rest. Cloud or local: pick cloud to use Honcho Cloud. For your own server, pick local, enter its address (for example http://localhost:8000) and its token, or leave the token blank if your server has auth turned off.

How to sign in: sign in to your Honcho account in the browser, use a device code (handy on a server with no browser: you approve the code on your phone or laptop), or paste an API key from the Honcho dashboard (opens in a new tab).

Your name and workspace: the setup asks for "Your name (user peer)", which defaults to your computer's username, and a "Workspace ID", which defaults to hermes. Enter the name you want Honcho to know you by.

Who talks to this gateway: pick [1] single peer (older versions call it just me) if you are the only person who messages your Hermes. With single peer, Honcho treats every person who talks to the gateway as you, which is what links your chat app and terminal messages. If other people message it too, pick one of the other options. The Hermes Agent Honcho docs (opens in a new tab) explain them. If no gateway is connected, the setup prints "No gateway platforms connected" and asks "Configure anyway? (y/N)". When it can't tell, it asks whether you run the gateway.

If the messaging gateway was already running as a background service, restart it so it loads Honcho. If you run hermes gateway run in the foreground instead, press Ctrl-C and run it again.

Terminal (only if the gateway service was already running)

hermes gateway restart

If you set up Honcho before it moved to the plugin catalog, run hermes update instead of installing it again. It installs the plugin and keeps your existing settings.

Your name in Honcho

The setup already asks for your name, so there's nothing extra to do here. Honcho calls each person a peer, and using the same name everywhere is what makes messages from the terminal land on the same person as messages from your chat apps. To change your name later:

Terminal (to change it later)

hermes honcho peer --user "Your Name"

Check it works

Run the status check. A working setup shows Honcho as enabled with your workspace and peer names, followed by Connection... OK. hermes memory status should also list Honcho as the active memory provider.

Terminal

hermes honcho status
hermes memory status

If the status check prints Peer data unavailable, the connection works but reading your profile failed.

Then test memory across chats. Tell Hermes something specific, such as the time of your daily standup. Give Honcho a little time to process it in the background. Then message Hermes from another app, or close Hermes and start it again from a different folder, and ask about it without repeating yourself. If the answer is right, cross-session memory is working.

You can also ask Hermes to use honcho_search to find something you said earlier. It should come back with matching messages.

See what Honcho learned

What Honcho writes are conclusions. Some are things you said outright. Others are reasoned from what you said: deductions, patterns across conversations and contradictions it noticed. Since Honcho 3.5, a conclusion drawn from something you said records the message it came from. Reasoned conclusions don't point to a single message, and conclusions made before 3.5 don't have one.

To look for yourself, open the Honcho dashboard (opens in a new tab), go to Explore, then your workspace (hermes by default), then Chat, and pick your name from the dropdown. Ask something like "What do you know about [your name] as a person?" Plastic Labs recommends choosing High in the reasoning dropdown.

Or ask Hermes: "What do you know about me?" With Honcho active, Hermes has these memory tools:

  • honcho_profile: a quick look at your profile card.
  • honcho_search: searches your past messages by meaning and by keyword.
  • honcho_context: a summary of what Honcho knows, plus recent messages.
  • honcho_reasoning: answers a question by reasoning over your memory.
  • honcho_conclude: adds, lists, searches or deletes saved conclusions, so you can remove anything you don't want kept.

Use the same memory everywhere

Chat apps share your memory with the terminal once you have picked single peer (just me in older versions) and use the same name everywhere. hermes honcho peer --user changes it if you need to.

Other agents can use the same memory too. Honcho has integrations for Claude Code, Codex, Cursor, OpenClaw and more. Sign them in to the same Honcho account, use the same name, and point them at the same workspace Hermes uses (hermes honcho status shows it). By default each tool gets its own workspace, so this step matters. Honcho's Claude Code guide (opens in a new tab) shows how to set a shared workspace.

Settings worth knowing

Honcho's settings live in honcho.json in your Hermes home (~/.hermes/honcho.json for the default profile). If that file doesn't exist, Hermes uses ~/.honcho/config.json instead. hermes honcho status shows the settings in use. You can start with the defaults. These are the ones you are most likely to change:

  • recallMode: hybrid (the default) adds memory to each reply automatically and gives Hermes the tools above. context adds memory only, and tools lets Hermes look things up only when it decides to. Show or change it with hermes honcho mode.
  • sessionStrategy: how conversations are grouped into sessions. The built-in default is per-directory, but on a new setup the wizard's default is per-session, which is also what Hermes's docs recommend for new users. Run hermes honcho strategy to see or change yours.
  • dialecticReasoningLevel: the starting effort Honcho uses when Hermes asks it a question, from minimal to max. The default is low, and Hermes can raise it for harder questions.
  • contextTokens: caps how much memory is added to each reply. There is no cap by default. Show or set it with hermes honcho tokens.

The full list of settings is in the Honcho plugin README (opens in a new tab).

If memory isn't working

  • hermes honcho isn't a command: those commands only appear once Honcho is the active memory provider. Run hermes memory setup honcho, then check with hermes memory status.
  • A new fact doesn't show up: give it a little time, since Honcho works in the background. Then ask again from another app, or after starting Hermes again from a different folder.
  • It works in the terminal but not in your chat app: the gateway may still be running with your old settings. Run hermes gateway restart. If you run hermes gateway run in the foreground, press Ctrl-C and run it again.
  • Your chat app and the terminal act like two different people: run hermes memory setup honcho again, pick single peer (just me in older versions), and check that hermes honcho peer shows the name you expect.
  • Honcho disappeared after an update: run hermes update, then hermes plugins list.
  • Still stuck: run hermes doctor and read any warnings. If the problem stays after hermes memory off, it's in Hermes rather than Honcho. Otherwise report it with the issue template linked from Honcho's Hermes guide (opens in a new tab).

Cost, privacy and turning it off

  • It isn't instant. Honcho processes conversations in the background, so a new fact can take a little while to show up.
  • Corrections don't overwrite. If you correct Hermes, Honcho records the correction as a newer conclusion. The old one can show for a while before cleanup removes it.
  • Cost: Honcho Cloud is pay as you go once your free credits are used, and higher reasoning levels cost more per question. Self-hosting is free, but you run the server and bring your own model provider API keys or a local model.
  • Where your data goes: with Honcho Cloud, Hermes sends your conversation turns, the conclusions drawn from them, and your peer and session IDs to Honcho's API (api.honcho.dev) under your API key, and Honcho stores and processes them on its servers. Honcho's privacy policy (opens in a new tab) explains how long it keeps data and which other services process it. Self-host Honcho if you want the data on your own server.
  • Turning it off: run hermes memory off. MEMORY.md and USER.md keep working either way. Hermes runs one external memory provider at a time, so to switch, run hermes memory setup and pick another.

Primary sources

Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher

Liked this guide?

Every Hermes Agent change that matters, explained in five minutes.

We'll only use your email to send the newsletter. Unsubscribe anytime. Privacy