Honcho is an AI-native memory system that provides persistent cross-session user modeling. The integration enables Hermes to build a deepening representation of users and contexts across conversations by reasoning about exchanges after they happen, supplementing or replacing local file-based memory (MEMORY.md, USER.md).
In the current version of Hermes, Honcho is integrated into the unified Memory Provider Plugin system website/docs/user-guide/features/memory-providers.md9-11 This allows Honcho to be selected as the primary memory provider via the hermes memory setup wizard or manual configuration website/docs/user-guide/features/memory-providers.md14-26
Honcho configuration is managed through a resolution chain that prioritizes instance-local settings over global ones. The HonchoClientConfig class in plugins/memory/honcho/client.py resolves these settings, allowing for isolated Hermes profiles to maintain distinct Honcho identities. It reads from multiple config sources, prioritizing:
$HERMES_HOME/honcho.json plugins/memory/honcho/client.py109-111~/.hermes/honcho.json plugins/memory/honcho/client.py114-116~/.honcho/config.json plugins/memory/honcho/client.py118HONCHO_API_KEY, HONCHO_ENVIRONMENT, HONCHO_BASE_URL plugins/memory/honcho/client.py6-7The active host key is derived from the active Hermes profile (e.g., hermes_<profile>) using profile_host_key() and resolve_active_host() plugins/memory/honcho/client.py38-43 plugins/memory/honcho/client.py56-91
Sources: plugins/memory/honcho/client.py38-43 plugins/memory/honcho/client.py56-91 plugins/memory/honcho/client.py99-118
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | False | Explicit enable/disable toggle for the Honcho provider plugins/memory/honcho/client.py238 |
api_key | str | None | Honcho API key for authentication plugins/memory/honcho/client.py230 |
workspace | str | "hermes" | Logical container of shared context and sessions plugins/memory/honcho/client.py229 |
peer_name | str | None | Identity of the user peer (human) plugins/memory/honcho/client.py235 |
ai_peer | str | "hermes" | Identity of this Hermes AI agent peer plugins/memory/honcho/client.py236 |
write_frequency | str or int | "async" | Controls when conversation turns are flushed plugins/memory/honcho/client.py242 |
recall_mode | str | "hybrid" | Memory retrieval modes: hybrid, context, or tools plugins/memory/honcho/client.py263 |
context_cadence | int | 1 | Minimum turns between fetching base context plugins/memory/honcho/client.py264 |
dialectic_cadence | int | 2 | Minimum turns between dialectic reasoning LLM calls plugins/memory/honcho/client.py265 |
dialectic_depth | int | 1 | Number of reasoning passes (1-3) plugins/memory/honcho/client.py266 |
Sources: plugins/memory/honcho/client.py121-273 website/docs/user-guide/features/memory-providers.md82-104
HonchoSessionManager orchestrates conversation sessions within Honcho’s AI-native memory. It maintains a local cache of HonchoSession objects that represent the session state, including message history. Sessions correspond to conversation contexts such as chat channels or projects plugins/memory/honcho/session.py28-43 plugins/memory/honcho/session.py71-106
HonchoSession via add_message() plugins/memory/honcho/session.py45-55"channel:chat_id" plugins/memory/honcho/session.py36-39_get_or_create_honcho_session(), which configures the session with peer identities plugins/memory/honcho/session.py181-205user_observe_me, user_observe_others, ai_observe_me, and ai_observe_others settings plugins/memory/honcho/session.py132-135user_peer_aliases and runtime_peer_prefix to map platform-native IDs (Telegram, Discord) to stable Honcho peers plugins/memory/honcho/cli.py50-51Sources: plugins/memory/honcho/session.py28-68 plugins/memory/honcho/session.py103-105 plugins/memory/honcho/session.py165-179 plugins/memory/honcho/session.py181-205
Honcho supports multiple write frequency modes to control how and when conversation turn data is flushed to the persistent memory backend website/docs/user-guide/features/memory-providers.md96
_async_writer_loop. Non-blocking for the main agent loop plugins/memory/honcho/session.py146-153_turn_counter plugins/memory/honcho/session.py111The async thread consumes message batches from the queue and calls add_messages() on the Honcho SDK. This prevents blocking the main conversation logic on network latency plugins/memory/honcho/session.py146-153
Sources: plugins/memory/honcho/session.py45-55 plugins/memory/honcho/session.py109-111 plugins/memory/honcho/session.py146-153 website/docs/user-guide/features/memory-providers.md96
Honcho exposes a set of memory provider tools through the HonchoMemoryProvider interface plugins/memory/honcho/__init__.py7-8
| Tool Name | Description | Code Reference |
|---|---|---|
honcho_profile | Retrieve or update a peer card (curated list of facts: preferences, patterns). | PROFILE_SCHEMA plugins/memory/honcho/__init__.py36-61 |
honcho_search | Semantic search over stored context; returns raw excerpts ranked by relevance. | SEARCH_SCHEMA plugins/memory/honcho/__init__.py68-99 |
honcho_reasoning | Dialectic reasoning response: asks natural language questions to get synthesized insights using Honcho LLM. | REASONING_SCHEMA plugins/memory/honcho/__init__.py101-152 |
honcho_context | Retrieve full session context snapshot (summary, representation, card, messages). | CONTEXT_SCHEMA plugins/memory/honcho/__init__.py154-177 |
honcho_conclude | Create or delete persistent factual conclusions about a peer. | CONCLUDE_SCHEMA plugins/memory/honcho/__init__.py179-207 |
Sources: plugins/memory/honcho/__init__.py36-207
Dialectic reasoning enables Honcho to perform multi-round internal LLM synthesis of user memory. The dialecticDepth configuration (1–3) controls the number of passes per query website/docs/user-guide/features/memory-providers.md89-91:
Each pass uses a proportional reasoning level unless overridden by dialecticDepthLevels website/docs/user-guide/features/memory-providers.md91
Sources: website/docs/user-guide/features/memory-providers.md56-58 website/docs/user-guide/features/memory-providers.md89-91
Honcho memory is integrated into the agent’s system prompt in various recall modes plugins/memory/honcho/client.py121-123:
Every turn, Honcho constructs two distinct context layers injected into the user message at API-call time to preserve prompt caching website/docs/user-guide/features/memory-providers.md56-64:
contextCadence turns. Includes session summary, user representation, and peer card.dialecticCadence turns. LLM-synthesized reasoning about the user's current state.Both layers are joined and truncated to the contextTokens budget plugins/memory/honcho/client.py145-153
On session initialization, Honcho fires a dialectic call in the background at full dialecticDepth website/docs/user-guide/features/memory-providers.md58-63 This prewarm ensures that the first turn of a conversation has immediate access to synthesized memory without waiting for a synchronous API call. Results are cached in _context_cache on the provider side plugins/memory/honcho/session.py113-117
Sources: plugins/memory/honcho/client.py121-123 plugins/memory/honcho/client.py145-153 plugins/memory/honcho/session.py108-153 plugins/memory/honcho/__init__.py7-207 website/docs/user-guide/features/memory-providers.md11-104
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.