NousResearch/hermes-plugin-honcho

NousResearch/hermes-plugin-honcho

Description: Handoff: standalone Hermes memory provider plugin (honcho). Honcho AI-native memory — cross-session user modeling with dialectic Q&A, semantic search, and persistent conc

Language: Python

License: MIT

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-09-17T16:02:08Z

Pushed: 2026-09-17T16:02:12Z

Default branch: main

Fork: no

Archived: no

README: > Handoff repository. This is the standalone copy of the honcho memory provider formerly bundled with Hermes Agent, published so its upstream maintainers can take it over. Not an official Nous Research plugin. See [HANDOFF.md](HANDOFF.md).

Honcho Memory Provider

AI-native cross-session user modeling with multi-pass dialectic reasoning, session summaries, bidirectional peer tools, and persistent conclusions.

> Honcho docs:

Requirements

• pip install honcho-ai
• A Honcho Cloud account — connect via OAuth sign-in or an API key from

app.honcho.dev — or a self-hosted instance

Setup

hermes memory setup honcho # configure Honcho directly (works on a fresh install)
hermes memory setup # generic picker, choose Honcho from the list

For cloud, the wizard asks OAuth, device code, or API key. OAuth opens a browser sign-in and stores the grant itself — nothing to copy; tokens refresh automatically. On SSH/headless machines choose device: the CLI prints a short code and a link you open in a browser on any other machine; setup completes once you approve there. The desktop app offers the browser flow as a Connect link next to the memory-provider dropdown.

Or manually:

hermes config set memory.provider honcho
echo "HONCHO_API_KEY=***" >> ~/.hermes/.env

> hermes honcho setup also works, but only after Honcho is the active > memory provider — the honcho subcommand is registered for the active > provider only. On a fresh install, use hermes memory setup honcho.

Architecture Overview

Two-Layer Context Injection

Context is injected into the user message at API-call time (not the system prompt) to preserve prompt caching. Only a static mode header goes in the system prompt. The injected block is wrapped in `` fences with a system note clarifying it's background data, not new user input.

Two independent layers, each on its own cadence:

Layer 1 — Base context (refreshed every contextCadence turns): 1. SESSION SUMMARY — from session.context(summary=True), placed first 2. User Representation — Honcho's evolving model of the user 3. User Peer Card — key facts snapshot 4. AI Self-Representation — Honcho's model of the AI peer 5. AI Identity Card — AI peer facts

Layer 2 — Dialectic supplement (fired every dialecticCadence turns): Multi-pass .chat() reasoning about the user, appended after base context.

Both layers are joined, then truncated to fit contextTokens budget via _truncate_to_budget (tokens × 4 chars, word-boundary safe).

Current-Query Recall (opt-in)

Set "recallSync": true in $HERMES_HOME/honcho.json (at the root or under hosts.hermes), or enable Current-query recall in the memory settings or hermes honcho setup. An explicit host-level false overrides root-level true.

In context and hybrid modes, due base and dialectic retrievals use the current user request before inference. The whole wait, including session initialization, optional query rewriting and dialectic passes, uses timeout / requestTimeout seconds, or 5 seconds when unset, zero, negative or nonfinite. The first-turn wait settings continue to apply only to the default asynchronous mode.

Timeouts, errors, busy workers and cadence gaps omit recall instead of reusing another query's context. A timed-out worker keeps its slot until it exits; its late result is discarded. Base and dialectic retain independent cadences and reasoning/depth settings. A completed empty lookup consumes its cadence; failed, timed-out or superseded operations do not advance either cadence. Empty dialectic results also increase the existing backoff. No previous-query cache or generic user-representation/card fallback is substituted for an empty query-scoped lookup. Session changes, shutdown, and new turn generations discard in-flight results, even when turn numbers repeat. The wait deadline does not cancel an SDK HTTP call; the occupied worker slot bounds accumulation until that call returns. injectionFrequency: "first-turn" suppresses only later base retrievals. Every dialectic pass includes the current request, including when rewriting is disabled or empty. Generic prewarm and post-turn automatic retrieval are disabled; message writes continue normally. tools mode is unchanged.

The default is false, preserving background recall and cache reuse across turns.

Latest-Message Query Rewrite (opt-in)

When queryRewrite: true, dialectic pass 0 first uses the shared memory_query_rewrite auxiliary task to turn the latest message into one concise memory-retrieval question. The rewritten question is used for the dialectic request; base-context retrieval still uses the raw message as its search query. If rewriting times out or returns an invalid result, the plugin falls back to the existing cold/warm prompt below. With the flag on, the generic dialectic prewarm is skipped so it cannot shadow the first user message.

Off by default — the rewrite adds one auxiliary-model call per dialectic cycle (not per pass). Select a fast, inexpensive model under hermes model -> auxiliary models -> Memory query rewrite; its request timeout is auxiliary.memory_query_rewrite.timeout in config.yaml (default 8s). The task and module (plugins/memory/query_rewrite.py) are provider-agnostic — any memory provider can reuse them. dialecticCadence still controls how often the cycle runs.

Cold Start vs Warm Session Prompts

When latest-message rewriting is unavailable, dialectic pass 0 automatically selects its fallback prompt based on session state:

• Cold (no base context cached): "Who is this person? What are their preferences, goals, and working style? Focus on facts that would help an AI assistant be immediately useful."
• Warm (base context exists): "Given what's been discussed in this session so far, what context about this user is most relevant to the current conversation? Prioritize active context over biographical facts."

Not configurable — determined...