Honcho Memory for Hermes

Honcho provides AI-native cross-session user modeling. It learns who the user is across conversations and gives every Hermes profile its own peer identity while sharing a unified view of the user.

When to Use

• Setting up Honcho (cloud or self-hosted)
• Troubleshooting memory not working / peers not syncing
• Creating multi-profile setups where each agent has its own Honcho peer
• Tuning observation, recall, dialectic depth, or write frequency settings
• Understanding what the 5 Honcho tools do and when to use them
• Configuring context budgets and session summary injection

Setup

Cloud (app.honcho.dev)

hermes honcho setup
# select "cloud", paste API key from https://app.honcho.dev

Self-hosted

hermes honcho setup
# select "local", enter base URL (e.g. http://localhost:8000)

See: https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes

Verify

hermes honcho status    # shows resolved config, connection test, peer info

Architecture

Base Context Injection

When Honcho injects context into the system prompt (in

hybrid

context

1. Session summary -- a short digest of the current session so far (placed first so the model has immediate conversational continuity)
2. User representation -- Honcho's accumulated model of the user (preferences, facts, patterns)
3. 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.

Cold / Warm Prompt Selection

Honcho automatically selects between two prompt strategies:

You do not need to configure this -- it is automatic based on session state.

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.

Observation

Each peer has two observation toggles that control what Honcho learns from:

observeMe

observeOthers

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:

"directional"

"unified"

Settings changed in the Honcho dashboard are synced back on session init -- server-side config wins over local defaults.

Sessions

Honcho sessions scope where messages and observations land. Strategy options:

per-directory

per-repo

per-session

global

Manual override:

hermes honcho map my-project-name

Recall Modes

How the agent accesses Honcho memory:

hybrid

context

tools

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.

contextCadence

1

dialecticCadence

2

injectionFrequency

every-turn

every-turn

first-turn

Higher cadence values fire the dialectic LLM less often.

dialecticCadence: 2

1

Depth (how many)

Controls how many rounds of dialectic reasoning Honcho performs per query.

dialecticDepth

1

dialecticDepthLevels

dialecticDepth: 2

dialecticDepthLevels

{
  "dialecticDepth": 3,
  "dialecticDepthLevels": ["low", "medium", "high"]
}

If

dialecticDepthLevels

dialecticReasoningLevel

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

Level (how hard)

Controls the intensity of each dialectic reasoning round.

dialecticReasoningLevel

low

minimal

low

medium

high

max

dialecticDynamic

true

true

reasoning_level

honcho_reasoning

false

dialecticReasoningLevel

Higher levels produce richer synthesis but cost more tokens on Honcho's backend.

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

1. Creates a

   hermes.coder

   host block in

   honcho.json

2. Sets

   aiPeer: "coder"

   (the profile name)
3. Inherits

   workspace

   ,

   peerName

   ,

   writeFrequency

   ,

   recallMode

   , etc. from default
4. 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

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 }
      }
    }
  }
}

Tools

The agent has 5 bidirectional Honcho tools (hidden in

context

honcho_profile

honcho_search

honcho_context

honcho_reasoning

honcho_conclude

peer: "ai"

honcho_profile

Read or update a peer card — curated key facts (name, role, preferences, communication style). Pass

card: [...]

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.

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.

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

minimal

low

medium

high

max

low

honcho_conclude

Write or delete a persistent conclusion about a peer. Pass

conclusion: "..."

delete_id: "..."

Bidirectional peer targeting

All 5 tools accept an optional

peer

• peer: "user"

  (default) — operates on the user peer

• peer: "ai"

  — operates on this profile's AI peer

• peer: "<explicit-id>"

  — 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

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)

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-correction

• honcho_reasoning query="How do I typically handle ambiguous requests?" peer="ai"

  — self-audit

• honcho_profile peer="ai"

  — review own identity card

When NOT to call tools

In

hybrid

context

• 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

Config Reference

Config file:

$HERMES_HOME/honcho.json

~/.honcho/config.json

Key settings

apiKey

baseUrl

peerName

aiPeer

workspace

recallMode

hybrid

hybrid

context

tools

observation

observeMe

observeOthers

writeFrequency

async

async

turn

session

sessionStrategy

per-directory

per-directory

per-repo

per-session

global

messageMaxChars

25000

Dialectic settings

dialecticReasoningLevel

low

minimal

low

medium

high

max

dialecticDynamic

true

false

dialecticDepth

1

dialecticDepthLevels

["low", "high"]

dialecticMaxInputChars

10000

Context budget and injection

contextTokens

injectionFrequency

every-turn

every-turn

first-turn

contextCadence

1

dialecticCadence

2

The

contextTokens

Memory-context sanitization

Honcho sanitizes the

memory-context

• 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

memory.provider: honcho

~/.hermes/config.yaml

Memory not persisting across sessions

Check

hermes honcho status

saveMessages: true

writeFrequency

session

Profile not getting its own peer

Use

--clone

hermes profile create <name> --clone

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

[continued]

Context injection too large

If you see warnings about context budget exceeded, lower

contextTokens

dialecticDepth

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.

CLI Commands

hermes honcho setup

hermes honcho status

hermes honcho enable

hermes honcho disable

hermes honcho peer

--user <name>

--ai <name>

--reasoning <level>

hermes honcho peers

hermes honcho mode

hybrid

context

tools

hermes honcho tokens

--context <N>

--dialectic <N>

hermes honcho sessions

hermes honcho map <name>

hermes honcho identity

hermes honcho sync

hermes honcho migrate

hermes memory setup

hermes memory status

hermes memory off