Honcho Memory for Hermes Agent: Setup, Peers, and Dialectic Tuning
Configure and troubleshoot Honcho memory for Hermes.
Written by Neura Market from the official Hermes Agent documentation for Honcho. Commands, paths, and version numbers are reproduced from the source unchanged.
Read the official documentationHoncho is a cross-session user modeling service from Plastic Labs that plugs into Hermes Agent as a memory provider. It watches conversations, builds a picture of the person you are, and gives each Hermes profile its own AI peer identity while keeping one shared view of the user. Reach for this guide when you are wiring Honcho up for the first time, when memory has stopped syncing, or when you need to tune how often and how deeply the dialectic engine runs.
What it does
Honcho sits between Hermes and its conversations. Instead of treating each session as an isolated transcript, it records messages as interactions between peers and accumulates a representation of the user over time. That representation, plus a per-profile AI peer card and a short session summary, can be injected into the system prompt before each turn. The agent also gets five tools it can call to read or write memory directly.
The practical effect is continuity. A new session does not start from zero: the model can be handed a digest of what came before, a model of who it is talking to, and an identity card for its own profile. You choose how much of that happens automatically versus on demand through the recall mode.
Before you start
Honcho is an optional skill, installed on demand rather than bundled by default. The skill lives at optional-skills/autonomous-ai-agents/honcho, is version 2.0.0, authored by Hermes Agent, and released under the MIT license. It runs on linux, macos, and windows.
You need a Honcho account on the cloud service at app.honcho.dev, or a self-hosted Honcho instance you can reach over HTTP. The provider itself is a plugin-catalog memory provider, so it has to be installed once per machine. Homes that were upgraded from a release that bundled Honcho already have it.
Setup
Install the plugin
hermes plugins install honcho
This pulls the Honcho memory provider into your Hermes installation. Run it once per machine; you do not repeat it for every profile.
Cloud (app.honcho.dev)
hermes memory setup honcho
# select "cloud", paste API key from https://app.honcho.dev
The wizard asks you to pick cloud, then prompts for the API key you generated in the Honcho dashboard.
Self-hosted
hermes memory setup honcho
# select "local", enter base URL (e.g. http://localhost:8000)
Choose local and supply the base URL where your Honcho instance is listening. The upstream integration guide for running Honcho locally with Hermes is at https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes.
Verify
hermes honcho status # shows resolved config, connection test, peer info
Run this after either path. It reports the configuration Hermes resolved, tests the connection, and shows peer information for the active profile. If something is wrong, this is the first place to look.
Architecture
Base Context Injection
When Honcho injects context into the system prompt (in hybrid or context recall modes), it assembles the base context block in this order:
- Session summary -- a short digest of the current session so far (placed first so the model has immediate conversational continuity)
- User representation -- Honcho's accumulated model of the user (preferences, facts, patterns)
- AI peer card -- the identity card for this Hermes profile's AI peer
The session summary is generated automatically by Honcho at the start of each turn (when a prior session exists). It gives the model a warm start without replaying full history.
Order matters here. The summary goes first because conversational continuity is the most immediate need; the representation and card follow as background. Honcho generates the summary at the start of each turn when a prior session exists, so the model gets a warm start without the full transcript being replayed.
Cold / Warm Prompt Selection
Honcho automatically selects between two prompt strategies:
| Condition | Strategy | What happens |
|---|---|---|
| No prior session or empty representation | Cold start | Lightweight intro prompt; skips summary injection; encourages the model to learn about the user |
| Existing representation and/or session history | Warm start | Full base context injection (summary → representation → card); richer system prompt |
You do not need to configure this -- it is automatic based on session state.
There is no switch to flip. On a fresh peer with nothing learned yet, Honcho keeps the prompt light and nudges the model to ask questions. Once there is history or a representation, it switches to the fuller injection.
Peers
Honcho models conversations as interactions between peers. Hermes creates two peers per session:
- User peer (
peerName): represents the human. Honcho builds a user representation from observed messages. - AI peer (
aiPeer): represents this Hermes instance. Each profile gets its own AI peer so agents develop independent views.
The split is what makes multi-profile setups work. Every profile shares the user peer's accumulated knowledge but keeps its own AI peer, so two agents can hold different self-models without stepping on each other.
Observation
Each peer has two observation toggles that control what Honcho learns from:
| Toggle | What it does |
|---|---|
observeMe | Peer's own messages are observed (builds self-representation) |
observeOthers | Other peers' messages are observed (builds cross-peer understanding) |
Default: all four toggles on (full bidirectional observation).
Configure per-peer in honcho.json:
{
"observation": {
"user": { "observeMe": true, "observeOthers": true },
"ai": { "observeMe": true, "observeOthers": true }
}
}
Or use the shorthand presets:
| Preset | User | AI | Use case |
|---|---|---|---|
"directional" (default) | me:on, others:on | me:on, others:on | Multi-agent, full memory |
"unified" | me:on, others:off | me:off, others:on | Single agent, user-only modeling |
Settings changed in the Honcho dashboard are synced back on session init -- server-side config wins over local defaults.
If you only want the agent to model the user and not itself, unified is the preset to pick. If you want full memory across multiple agents, leave it on directional. Remember that dashboard changes override local defaults at session start, so editing honcho.json alone will not stick if the server has a different value.
Sessions
Honcho sessions scope where messages and observations land. Strategy options:
| Strategy | Behavior |
|---|---|
per-directory (default) | One session per working directory |
per-repo | One session per git repository root |
per-session | New Honcho session each Hermes run |
global | Single session across all directories |
Manual override: hermes honcho map my-project-name
per-directory is a sensible default for project work: each directory gets its own thread. per-repo collapses subdirectories under the same git root. per-session is the most isolated, and global the most shared. Use the map command when you want a directory to report under a specific session name.
Recall Modes
How the agent accesses Honcho memory:
| Mode | Auto-inject context? | Tools available? | Use case |
|---|---|---|---|
hybrid (default) | Yes | Yes | Agent decides when to use tools vs auto context |
context | Yes | No (hidden) | Minimal token cost, no tool calls |
tools | No | Yes | Agent controls all memory access explicitly |
hybrid gives the agent both automatic context and the option to call tools. context hides the tools and relies entirely on injection, which keeps token cost down. tools turns off injection and makes the agent ask for everything, which is the most explicit and the most expensive in tool calls.
Three Orthogonal Knobs
Honcho's dialectic behavior is controlled by three independent dimensions. Each can be tuned without affecting the others:
Cadence (when)
Controls how often dialectic and context calls happen.
| Key | Default | Description |
|---|---|---|
contextCadence | 1 | Min turns between context API calls |
dialecticCadence | 2 | Min turns between dialectic API calls. Recommended 1, 5 |
injectionFrequency | every-turn | every-turn or first-turn for base context injection |
Higher cadence values fire the dialectic LLM less often. dialecticCadence: 2 means the engine fires every other turn. Setting it to 1 fires every turn.
Cadence is your cost dial. If you are burning tokens on repeated synthesis, raise dialecticCadence toward 5. If you need the freshest possible context every turn, drop it to 1 and accept the cost.
Depth (how many)
Controls how many rounds of dialectic reasoning Honcho performs per query.
| Key | Default | Range | Description |
|---|---|---|---|
dialecticDepth | 1 | 1-3 | Number of dialectic reasoning rounds per query |
dialecticDepthLevels | -- | array | Optional per-depth-round level overrides (see below) |
dialecticDepth: 2 means Honcho runs two rounds of dialectic synthesis. The first round produces an initial answer; the second refines it.
dialecticDepthLevels lets you set the reasoning level for each round independently:
{
"dialecticDepth": 3,
"dialecticDepthLevels": ["low", "medium", "high"]
}
If dialecticDepthLevels is omitted, rounds use proportional levels derived from dialecticReasoningLevel (the base):
| Depth | Pass levels |
|---|---|
| 1 | [base] |
| 2 | [minimal, base] |
| 3 | [minimal, base, low] |
This keeps earlier passes cheap while using full depth on the final synthesis.
Depth at session start. The session-start prewarm runs the full configured dialecticDepth in the background before turn 1. A single-pass prewarm on a cold peer often returns thin output, multi-pass depth runs the audit/reconcile cycle before the user ever speaks. Turn 1 consumes the prewarm result directly; if prewarm hasn't landed in time, turn 1 falls back to a synchronous call with a bounded timeout.
Depth is the quality dial. Two rounds means an initial answer and a refinement; three means an extra pass. The prewarm behavior is worth knowing: on a cold peer, a single pass tends to produce thin output, so raising depth gives the background job more to work with before the first message arrives.
Level (how hard)
Controls the intensity of each dialectic reasoning round.
| Key | Default | Description |
|---|---|---|
dialecticReasoningLevel | low | minimal, low, medium, high, max |
dialecticDynamic | true | When true, the model can pass reasoning_level to honcho_reasoning to override the default per-call. false = always use dialecticReasoningLevel, model overrides ignored |
Higher levels produce richer synthesis but cost more tokens on Honcho's backend.
Level is the per-round intensity. With dialecticDynamic on, the model can ask for a different level on a specific honcho_reasoning call; with it off, the configured level is fixed and overrides are ignored.
Multi-Profile Setup
Each Hermes profile gets its own Honcho AI peer while sharing the same workspace (user context). This means:
- All profiles see the same user representation
- Each profile builds its own AI identity and observations
- Conclusions written by one profile are visible to others via the shared workspace
Create a profile with Honcho peer
hermes profile create coder --clone
# creates host block hermes.coder, AI peer "coder", inherits config from default
What --clone does for Honcho:
- Creates a
hermes.coderhost block inhoncho.json - Sets
aiPeer: "coder"(the profile name) - Inherits
workspace,peerName,writeFrequency,recallMode, etc. from default - Eagerly creates the peer in Honcho so it exists before first message
Backfill existing profiles
hermes honcho sync # creates host blocks for all profiles that don't have one yet
If you already have profiles that predate Honcho, sync fills in the missing host blocks. Run it once after enabling the provider.
Per-profile config
Override any setting in the host block:
{
"hosts": {
"hermes.coder": {
"aiPeer": "coder",
"recallMode": "tools",
"dialecticDepth": 2,
"observation": {
"user": { "observeMe": true, "observeOthers": false },
"ai": { "observeMe": true, "observeOthers": true }
}
}
}
}
Host blocks let one profile differ from another without touching the defaults. A coding profile might use tools recall and shallower depth; a research profile might use hybrid and deeper synthesis.
Tools
The agent has 5 bidirectional Honcho tools (hidden in context recall mode):
| Tool | LLM call? | Cost | Use when |
|---|---|---|---|
honcho_profile | No | minimal | Quick factual snapshot at conversation start or for fast name/role/pref lookups |
honcho_search | No | low | Fetch specific past facts to reason over yourself, raw excerpts, no synthesis |
honcho_context | No | low | Full session context snapshot: summary, representation, card, recent messages |
honcho_reasoning | Yes | medium, high | Natural language question synthesized by Honcho's dialectic engine |
honcho_conclude | No | minimal | Write or delete a persistent fact; pass peer: "ai" for AI self-knowledge |
honcho_profile
Read or update a peer card, curated key facts (name, role, preferences, communication style). Pass card: [...] to update; omit to read. No LLM call.
The card is the cheapest thing to check. It is curated rather than synthesized, so it is fast and predictable.
honcho_search
Semantic search over stored context for a specific peer. Returns raw excerpts ranked by relevance, no synthesis. Default 800 tokens, max 2000. Good when you need specific past facts to reason over yourself rather than a synthesized answer.
Use search when you want the raw material and plan to do the reasoning in the main model. It is cheaper than honcho_reasoning because no backend LLM is involved.
honcho_context
Full session context snapshot from Honcho, session summary, peer representation, peer card, and recent messages. No LLM call. Use when you want to see everything Honcho knows about the current session and peer in one shot.
This is the diagnostic tool. If you are unsure what the agent already has, pull the full snapshot before deciding whether to search or reason.
honcho_reasoning
Natural language question answered by Honcho's dialectic reasoning engine (LLM call on Honcho's backend). Higher cost, higher quality. Pass reasoning_level to control depth: minimal (fast/cheap) → low → medium → high → max (thorough). Omit to use the configured default (low). Use for synthesized understanding of the user's patterns, goals, or current state.
This is the expensive tool. Reserve it for questions that need synthesis rather than lookup.
honcho_conclude
Write or delete a persistent conclusion about a peer. Pass conclusion: "..." to create. Pass delete_id: "..." to remove a conclusion (for PII removal, Honcho self-heals incorrect conclusions over time, so deletion is only needed for PII). You MUST pass exactly one of the two.
Deletion is not the normal correction path. Honcho revises wrong conclusions on its own; delete only when the content is personally identifying and must go.
Bidirectional peer targeting
All 5 tools accept an optional peer parameter:
peer: "user"(default), operates on the user peerpeer: "ai", operates on this profile's AI peerpeer: "", any peer ID in the workspace
Examples:
honcho_profile # read user's card
honcho_profile peer="ai" # read AI peer's card
honcho_reasoning query="What does this user care about most?"
honcho_reasoning query="What are my interaction patterns?" peer="ai" reasoning_level="medium"
honcho_conclude conclusion="Prefers terse answers"
honcho_conclude conclusion="I tend to over-explain code" peer="ai"
honcho_conclude delete_id="abc123" # PII removal
Agent Usage Patterns
Guidelines for Hermes when Honcho memory is active.
On conversation start
1. honcho_profile → fast warmup, no LLM cost
2. If context looks thin → honcho_context (full snapshot, still no LLM)
3. If deep synthesis needed → honcho_reasoning (LLM call, use sparingly)
Do NOT call honcho_reasoning on every turn. Auto-injection already handles ongoing context refresh. Use the reasoning tool only when you genuinely need synthesized insight the base context doesn't provide.
The escalation ladder is deliberate: start with the free card, move to the free snapshot, and only then pay for synthesis.
When the user shares something to remember
honcho_conclude conclusion="<specific, actionable fact>"
Good conclusions: "Prefers code examples over prose explanations", "Working on a Rust async project through April 2026" Bad conclusions: "User said something about Rust" (too vague), "User seems technical" (already in representation)
Specificity is the whole game. A conclusion should be something the model could act on later, and it should not duplicate what the representation already captures.
When the user asks about past context / you need to recall specifics
honcho_search query="<topic>" → fast, no LLM, good for specific facts
honcho_context → full snapshot with summary + messages
honcho_reasoning query="<question>" → synthesized answer, use when search isn't enough
When to use peer: "ai"
Use AI peer targeting to build and query the agent's own self-knowledge:
honcho_conclude conclusion="I tend to be verbose when explaining architecture" peer="ai", self-correctionhoncho_reasoning query="How do I typically handle ambiguous requests?" peer="ai", self-audithoncho_profile peer="ai", review own identity card
Self-modeling is the feature that distinguishes Honcho from a simple transcript store. The AI peer can accumulate its own notes and be queried about them later.
When NOT to call tools
In hybrid and context modes, base context (user representation + card + session summary) is auto-injected before every turn. Do not re-fetch what was already injected. Call tools only when:
- You need something the injected context doesn't have
- The user explicitly asks you to recall or check memory
- You're writing a conclusion about something new
Cadence awareness
honcho_reasoning on the tool side shares the same cost as auto-injection dialectic. After an explicit tool call, the auto-injection cadence resets, avoiding double-charging the same turn.
Config Reference
Config file: $HERMES_HOME/honcho.json (profile-local) or ~/.honcho/config.json (global).
Key settings
| Key | Default | Description |
|---|---|---|
apiKey | -- | API key (get one) |
baseUrl | -- | Base URL for self-hosted Honcho |
peerName | -- | User peer identity |
aiPeer | host key | AI peer identity |
workspace | host key | Shared workspace ID |
recallMode | hybrid | hybrid, context, or tools |
observation | all on | Per-peer observeMe/observeOthers booleans |
writeFrequency | async | async, turn, session, or integer N |
sessionStrategy | per-directory | per-directory, per-repo, per-session, global |
messageMaxChars | 25000 | Max chars per message (chunked if exceeded) |
Dialectic settings
| Key | Default | Description |
|---|---|---|
dialecticReasoningLevel | low | minimal, low, medium, high, max |
dialecticDynamic | true | Auto-bump reasoning by query complexity. false = fixed level |
dialecticDepth | 1 | Number of dialectic rounds per query (1-3) |
dialecticDepthLevels | -- | Optional array of per-round levels, e.g. ["low", "high"] |
dialecticMaxInputChars | 10000 | Max chars for dialectic query input |
Context budget and injection
| Key | Default | Description |
|---|---|---|
contextTokens | uncapped | Max tokens for the combined base context injection (summary + representation + card). Opt-in cap, omit to leave uncapped, set to an integer to bound injection size. |
injectionFrequency | every-turn | every-turn or first-turn |
contextCadence | 1 | Min turns between context API calls |
dialecticCadence | 2 | Min turns between dialectic LLM calls (recommended 1, 5) |
The contextTokens budget is enforced at injection time. If the session summary + representation + card exceed the budget, Honcho trims the summary first, then the representation, preserving the card. This prevents context blowup in long sessions.
The trimming order is the important detail: the card survives last because it is the most compact and curated piece. If you set a budget, expect the summary to shrink first.
Memory-context sanitization
Honcho sanitizes the memory-context block before injection to prevent prompt injection and malformed content:
- Strips XML/HTML tags from user-authored conclusions
- Normalizes whitespace and control characters
- Truncates individual conclusions that exceed
messageMaxChars - Escapes delimiter sequences that could break the system prompt structure
This fix addresses edge cases where raw user conclusions containing markup or special characters could corrupt the injected context block.
Troubleshooting
"Honcho not configured"
Run hermes honcho setup. Ensure memory.provider: honcho is in ~/.hermes/config.yaml.
Memory not persisting across sessions
Check hermes honcho status -- verify saveMessages: true and writeFrequency isn't session (which only writes on exit).
Profile not getting its own peer
Use --clone when creating: hermes profile create --clone. For existing profiles: hermes honcho sync.
Observation changes in dashboard not reflected
Observation config is synced from the server on each session init. Start a new session after changing settings in the Honcho UI.
Messages truncated
Messages over messageMaxChars (default 25k) are automatically chunked with [continued] markers. If you're hitting this often, check if tool results or skill content is inflating message size.
Context injection too large
If you see warnings about context budget exceeded, lower contextTokens or reduce dialecticDepth. The session summary is trimmed first when the budget is tight.
Session summary missing
Session summary requires at least one prior turn in the current Honcho session. On cold start (new session, no history), the summary is omitted and Honcho uses the cold-start prompt strategy instead.
When not to use it
The source does not list explicit exclusions, but the recall modes make the trade-offs clear. If you want zero tool calls and minimal token cost, context mode hides the tools and relies on injection alone. If you want the agent to control every memory access explicitly, tools mode turns off auto-injection. If you do not want an external memory provider at all, hermes memory off disables it. And if you only need user modeling without the agent modeling itself, the unified observation preset is the lighter choice.
Limits and gotchas
- Server-side observation settings win over local defaults at session init. Editing
honcho.jsonwill not override a dashboard change until the next session. honcho_concluderequires exactly one ofconclusionordelete_id. Passing both or neither is invalid.- Deletion is for PII removal only. Honcho self-heals incorrect conclusions over time.
honcho_reasoningcosts more than the other tools because it makes an LLM call on Honcho's backend. Do not call it every turn.- In
hybridandcontextmodes, base context is already injected. Re-fetching it with tools wastes tokens. writeFrequency: sessiononly writes on exit, which is a common cause of memory appearing not to persist.- Messages over
messageMaxCharsare chunked with[continued]markers. Frequent chunking usually means tool results or skill content are inflating message size. - A context budget warning means the summary plus representation plus card exceeded
contextTokens. Lower the budget or reducedialecticDepth; the summary is trimmed first. - Session summaries require at least one prior turn in the current Honcho session. On a cold start there is no summary, and the cold-start prompt strategy is used instead.
CLI Commands
| Command | Description |
|---|---|
hermes honcho setup | Interactive setup wizard (cloud/local, identity, observation, recall, sessions) |
hermes honcho status | Show resolved config, connection test, peer info for active profile |
hermes honcho enable | Enable Honcho for the active profile (creates host block if needed) |
hermes honcho disable | Disable Honcho for the active profile |
hermes honcho peer | Show or update peer names (--user , --ai , --reasoning ) |
hermes honcho peers | Show peer identities across all profiles |
hermes honcho mode | Show or set recall mode (hybrid, context, tools) |
hermes honcho tokens | Show or set token budgets (--context , --dialectic ) |
hermes honcho sessions | List known directory-to-session-name mappings |
hermes honcho map | Map current working directory to a Honcho session name |
hermes honcho identity | Seed AI peer identity or show both peer representations |
hermes honcho sync | Create host blocks for all Hermes profiles that don't have one yet |
hermes honcho migrate | Step-by-step migration guide from OpenClaw native memory to Hermes + Honcho |
hermes memory setup | Generic memory provider picker (selecting "honcho" runs the same wizard) |
hermes memory status | Show active memory provider and config |
hermes memory off | Disable external memory provider |
What pairs with this
The source lists one related skill: hermes-agent. That is the natural companion, since Honcho is a memory layer for Hermes itself and most of the configuration lives in Hermes profiles and honcho.json. If you are migrating from OpenClaw's native memory, the hermes honcho migrate command walks through the transition step by step.