feat(honcho): async writes, memory modes, session title integration, setup CLI

[erosika]

Summary

Builds on the Honcho integration landed in #38 and the auto-enable fix in #243.

Adds async write support, configurable memory modes, context prefetch with first-turn warm, a first-class hermes honcho CLI, AI peer identity formation, recallMode A/B testing, and a bidirectional tool surface.

New config fields (~/.honcho/config.json)

{
  // string shorthand — all peers use this mode
  "memoryMode": "hybrid",            // "hybrid" | "honcho" | "local"
  "writeFrequency": "async",         // "async" | "turn" | "session" | N (int)
  "dialecticReasoningLevel": "low",  // "minimal" | "low" | "medium" | "high" | "max"
  "dialecticMaxChars": 600,
  "recallMode": "hybrid",            // "hybrid" | "context" | "tools"
  "sessionStrategy": "per-repo",     // "per-session" | "per-repo" | "per-directory" | "global"
  "sessions": { "/path/to/project": "my-project" },

  // optional: per-host overrides — all fields above can be scoped here
  "hosts": {
    "hermes": {
      "workspace": "my-workspace",

      // object form: per-peer memory mode overrides for any named Honcho peer
      "memoryMode": {
        "default": "hybrid",
        "user":    "hybrid",
        "hermes":  "honcho",
        "sentinel": "local"
      }
    }
  }
}

write_frequency

Value	Behaviour
"async" (default)	Background daemon thread — zero blocking, zero token cost
"turn"	Sync flush after every turn
"session"	Batch flush at session end only
5 (int)	Flush every N turns

memory_mode

Value	Behaviour
"hybrid" (default)	Write to both Honcho and local MEMORY.md
"honcho"	Honcho only — disables local file writes
"local"	Local MEMORY.md only — Honcho sync is a no-op

memoryMode accepts a string (applies to all peers) or an object with named peer keys and an optional "default". Any Honcho peer name can be used as a key — not limited to the built-in user/assistant pair.

recallMode

Controls how Hermes retrieves memory from Honcho each turn:

Value	Behaviour
"hybrid" (default)	Pre-warmed context in system prompt + memory tools available (model decides)
"context"	Pre-warmed context only — memory tools removed from tool surface
"tools"	No pre-loaded context — model must call tools to retrieve memory

Useful for A/B testing whether context injection or tool-based retrieval works better for a given workflow.

Context + dialectic prefetch

Two separate Honcho API calls power the memory pipeline:

• Context (session.context()) — raw memory retrieval. Returns stored facts and session history, injected directly into the system prompt.
• Dialectic (peer.chat()) — AI-to-AI inference. Hermes asks Honcho's AI peer a synthesized question (e.g. "what were we working on?") and Honcho runs its own model to generate an answer. Powers first-turn session continuity.

Both are warmed synchronously at session init so the very first turn has full context ("where did we leave off?" works immediately). On subsequent turns, both fire as background daemon threads at turn end — results are cached and consumed at the start of the next turn with zero blocking.

Context calls use peer_perspective so Honcho frames user context from the agent's viewpoint. Dialectic reasoning level scales dynamically with message length: < 120 chars: configured default, 120-400: +1 level, > 400: +2 levels, capped at "max".

Session strategies

Strategy	Behaviour
"per-session" (default)	New Honcho session each Hermes run, keyed by session ID
"per-repo"	One session per git repository (uses git rev-parse --show-toplevel name)
"per-directory"	One session per working directory basename
"global"	Single session across all directories

Manual overrides via sessions map always win. /title mid-session remaps the Honcho session key.

Peer identity formation

observe_me=True is set on the AI peer so Honcho watches every assistant message and builds the agent's representation organically across sessions. New methods:

• seed_ai_identity(session_key, content, source) — prime the AI peer from SOUL.md or any file
• get_ai_representation(session_key) — fetch current AI peer representation on demand
• get_peer_card(session_key) — fetch user peer card (curated facts, no LLM)
• migrate_memory_files now includes SOUL.md (uploaded to AI peer, not user peer)
• Both user peer card and AI peer representation injected into system prompt each turn
• Configured ai_peer name replaces "Hermes Agent" in DEFAULT_AGENT_IDENTITY
• hermes honcho identity --show displays both peers side by side

Tool surface

Four tools — three for reading memory, one for writing back:

Tool	Direction	Cost	What it does
honcho_context	read	LLM (dialectic)	Ask about any peer (user or AI) — synthesized answer
honcho_search	read	Fast, no LLM	Semantic search over session context, raw excerpts
honcho_profile	read	Fast, no LLM	User peer card — curated key facts list
honcho_conclude	write	Fast, no LLM	Persist a conclusion about the user to Honcho memory

honcho_conclude writes conclusions (preferences, corrections, project context) via the conclusions API. These feed into the user's peer card and representation over time.

hermes honcho CLI

Command	Description
hermes honcho setup	Interactive wizard — API key, workspace, connection test
hermes honcho status	Config snapshot + live connection check
---	---
hermes honcho sessions	List directory -> session name mappings
hermes honcho map <name>	Map cwd to a session name (no arg = list)
---	---
hermes honcho peer	Show peer names and dialectic settings
hermes honcho peer --user NAME	Set user peer name
hermes honcho peer --ai NAME	Set AI peer name
hermes honcho peer --reasoning LEVEL	Set dialectic reasoning floor (minimal/low/medium/high/max)
---	---
hermes honcho mode [hybrid/honcho/local]	Show or set default memory mode
hermes honcho tokens [--context N] [--dialectic N]	Show or set token budgets
---	---
hermes honcho identity <file>	Seed AI peer identity from a file (SOUL.md etc.)
hermes honcho identity --show	Show user peer card + AI peer representation
---	---
hermes honcho migrate	Walkthrough: OpenClaw native memory -> Hermes + Honcho

Hermes injects a compact command reference into its own system prompt when Honcho is active, so it can refer users to these commands directly.

Other changes

• Session title -> Honcho key: resolve_session_name accepts the Hermes /title value; /title mid-session live-remaps the Honcho session key
• Migration on first activation: existing conversation_history, MEMORY.md, USER.md, and SOUL.md uploaded to Honcho on first session init
• Gateway + /compress flush: flush_all() called before context window resets and before gateway session drops
• Async retry: writer thread retries once after 2s on network failure, drops and logs on second failure
• Sync failure visibility: _honcho_sync errors upgraded from silent logger.debug to logger.warning + user-visible print
• hermes doctor: new Honcho Memory section checks config, API key, and live connection
• Tool rebuild after Honcho init: fixes race where tools were filtered out at build time before session was established
• API key instructions: setup wizard and error messages direct users to app.honcho.dev

Related PRs

• feat: Honcho memory integration (opt-in) #38 -- initial Honcho integration (opt-in)
• fix(honcho): auto-enable when API key is present #243 -- auto-enable when API key is present

Test plan

• 97 tests passing (pytest tests/honcho_integration/)
• hermes honcho setup walks through config, writes ~/.honcho/config.json, shows tools and next steps
• hermes honcho status shows live connection result
• hermes honcho mode, hermes honcho tokens, hermes honcho peer all show/set correctly
• hermes honcho identity <file> seeds AI peer; --show returns user peer card + AI peer representation side by side
• hermes honcho migrate detects OpenClaw native files, offers inline upload
• First turn: context + dialectic warmed synchronously at init -- "where did we leave off?" works immediately
• recallMode=context: memory tools removed, context block injected; recallMode=tools: no context, tools only
• honcho_conclude persists a fact; fact appears in subsequent honcho_profile results
• honcho_search returns raw excerpts for a semantic query
• write_frequency=async: no blocking per turn; messages appear in Honcho after background flush
• memory_mode=honcho: local MEMORY.md flush disabled; memory_mode=local: Honcho sync skipped
• sessionStrategy=per-repo: sessions scoped to git repo root, not bleeding across projects

[teknium1]

Thanks for the thorough work on this — the overall design is solid and the test coverage is great. There are a few issues that need to be addressed before we can merge:

Critical

1. Signal handler override (run_agent.py)

_activate_honcho() unconditionally overwrites SIGINT/SIGTERM handlers. This is dangerous — multiple AIAgent instances will clobber each other's handlers, and the SIGTERM handler raises SystemExit(0) which can skip critical cleanup in cli.py and the gateway.

Fix: Use atexit.register() for the flush-on-exit behavior, or chain with the previous handler via signal.getsignal() before overwriting.

2. Duplicate function in browser_tool.py

_cleanup_old_recordings() is defined twice — the PR adds a second copy that shadows the existing one. This looks like an accidental merge artifact. Also introduces a file handle leak: int(open(pid_file).read().strip()) (was int(Path(pid_file).read_text().strip())). Please remove the duplicate and revert the pid_file line.

3. Toolset registration incomplete (toolsets.py)

Only honcho_context is listed in _HERMES_CORE_TOOLS and TOOLSETS["honcho"]["tools"]. The other 3 new tools (honcho_profile, honcho_search, honcho_conclude) are registered in the registry but not in any tool list — they won't be available to the model. Add all 4 tools to both places.

4. Breaking default change (session_strategy)

session_strategy default changed from "per-directory" to "per-session". Existing users without an explicit config will silently get different session scoping behavior. Please either keep the existing default or add a note in upgrade/migration docs.

Medium

5. Incomplete prefetch pipeline

prefetch_dialectic() and prefetch_context() are defined on HonchoSessionManager but never called from run_agent.py. The documented "Turn N fires background prefetch for Turn N+1" pipeline isn't wired up — only synchronous first-turn prefetch works. Is this intentional / planned for a follow-up?

6. Private state manipulation

run_agent.py does self._honcho._context_cache[key] = ctx — directly reaching into private state. Please add a public setter method on HonchoSessionManager instead.

7. Thread safety of caches

_context_cache and _dialectic_cache are plain dicts shared between the main thread and daemon writer thread without locks. Python's GIL makes individual dict operations atomic, but read-modify-write patterns aren't safe. Consider using a threading.Lock or at minimum documenting the concurrency assumptions.

---

Everything else looks good — the gateway lifecycle management, async writer with retry, CLI wizard, and test coverage are all well done. Once these are addressed we can move forward with the merge.

[erosika]

hi @teknium1 all of your review comments should be addressed now, thanks for taking a look.

re #4: the switch from per-directory to per-session is not a breaking change. it changes session mapping behavior but not how Honcho derives or stores memory — no memory data is lost, old sessions remain intact in Honcho. most users have been defaulting to Hermes' native session naming anyway and weren't relying on the per-directory scoping. anyone who wants the old behavior can set "sessionStrategy": "per-directory" explicitly in ~/.honcho/config.json.