refactor(honcho): write all host-scoped settings into hosts block

Setup wizard now writes memoryMode, writeFrequency, recallMode, and
sessionStrategy into hosts.hermes instead of the config root. Client
resolution updated to read sessionStrategy and sessionPeerPrefix from
host block first. Docs updated to show hosts-based config as the default
example so other integrations can coexist cleanly.

honcho_integration/cli.py

@@ -121,20 +121,20 @@ def cmd_setup(args) -> None:
 
     hermes_host.setdefault("aiPeer", HOST)
 
-    # Memory mode
+    # Memory mode (host-scoped)
-    current_mode = cfg.get("memoryMode", "hybrid")
+    current_mode = hermes_host.get("memoryMode") or cfg.get("memoryMode", "hybrid")
     print(f"\n  Memory mode options:")
     print("    hybrid  — write to both Honcho and local MEMORY.md (default)")
     print("    honcho  — Honcho only, skip MEMORY.md writes")
     print("    local   — MEMORY.md only, Honcho disabled")
     new_mode = _prompt("Memory mode", default=current_mode)
     if new_mode in ("hybrid", "honcho", "local"):
-        cfg["memoryMode"] = new_mode
+        hermes_host["memoryMode"] = new_mode
     else:
-        cfg["memoryMode"] = "hybrid"
+        hermes_host["memoryMode"] = "hybrid"
 
-    # Write frequency
+    # Write frequency (host-scoped)
-    current_wf = str(cfg.get("writeFrequency", "async"))
+    current_wf = str(hermes_host.get("writeFrequency") or cfg.get("writeFrequency", "async"))
     print(f"\n  Write frequency options:")
     print("    async   — background thread, no token cost (recommended)")
     print("    turn    — sync write after every turn")
@@ -142,22 +142,22 @@ def cmd_setup(args) -> None:
     print("    N       — write every N turns (e.g. 5)")
     new_wf = _prompt("Write frequency", default=current_wf)
     try:
-        cfg["writeFrequency"] = int(new_wf)
+        hermes_host["writeFrequency"] = int(new_wf)
     except (ValueError, TypeError):
-        cfg["writeFrequency"] = new_wf if new_wf in ("async", "turn", "session") else "async"
+        hermes_host["writeFrequency"] = new_wf if new_wf in ("async", "turn", "session") else "async"
 
-    # Recall mode
+    # Recall mode (host-scoped)
-    current_recall = cfg.get("recallMode", "hybrid")
+    current_recall = hermes_host.get("recallMode") or cfg.get("recallMode", "hybrid")
     print(f"\n  Recall mode options:")
     print("    hybrid  — pre-warmed context + memory tools available (default)")
     print("    context — pre-warmed context only, memory tools suppressed")
     print("    tools   — no pre-loaded context, rely on tool calls only")
     new_recall = _prompt("Recall mode", default=current_recall)
     if new_recall in ("hybrid", "context", "tools"):
-        cfg["recallMode"] = new_recall
+        hermes_host["recallMode"] = new_recall
 
-    # Session strategy
+    # Session strategy (host-scoped)
-    current_strat = cfg.get("sessionStrategy", "per-session")
+    current_strat = hermes_host.get("sessionStrategy") or cfg.get("sessionStrategy", "per-session")
     print(f"\n  Session strategy options:")
     print("    per-session   — new Honcho session each run, named by Hermes session ID (default)")
     print("    per-repo      — one session per git repository (uses repo root name)")
@@ -165,7 +165,7 @@ def cmd_setup(args) -> None:
     print("    global        — single session across all directories")
     new_strat = _prompt("Session strategy", default=current_strat)
     if new_strat in ("per-session", "per-repo", "per-directory", "global"):
-        cfg["sessionStrategy"] = new_strat
+        hermes_host["sessionStrategy"] = new_strat
 
     cfg.setdefault("enabled", True)
     cfg.setdefault("saveMessages", True)

honcho_integration/client.py

@@ -201,8 +201,16 @@ class HonchoClientConfig:
                 or raw.get("recallMode")
                 or "hybrid"
             ),
-            session_strategy=raw.get("sessionStrategy", "per-session"),
+            session_strategy=(
-            session_peer_prefix=raw.get("sessionPeerPrefix", False),
+                host_block.get("sessionStrategy")
+                or raw.get("sessionStrategy")
+                or "per-session"
+            ),
+            session_peer_prefix=(
+                host_block.get("sessionPeerPrefix")
+                if "sessionPeerPrefix" in host_block
+                else raw.get("sessionPeerPrefix", False)
+            ),
             sessions=raw.get("sessions", {}),
             raw=raw,
         )

website/docs/user-guide/features/honcho.md

@@ -37,16 +37,16 @@ The setup wizard walks through API key, peer names, workspace, memory mode, writ
 
 ### Manual Setup
 
-#### 1. Install the Client Library
+#### 1. Get an API Key
+
+Go to [app.honcho.dev](https://app.honcho.dev) > Settings > API Keys.
+
+#### 2. Install the Client Library
 
 ```bash
 pip install 'honcho-ai>=2.0.1'
 ```
 
-#### 2. Get an API Key
-
-Go to [app.honcho.dev](https://app.honcho.dev) > Settings > API Keys.
-
 #### 3. Configure
 
 Honcho reads from `~/.honcho/config.json` (shared across all Honcho-enabled applications):
@@ -54,17 +54,23 @@ Honcho reads from `~/.honcho/config.json` (shared across all Honcho-enabled appl
 ```json
 {
   "apiKey": "your-honcho-api-key",
-  "workspace": "hermes",
   "peerName": "your-name",
-  "aiPeer": "hermes",
+  "enabled": true,
-  "memoryMode": "hybrid",
+  "hosts": {
-  "writeFrequency": "async",
+    "hermes": {
-  "recallMode": "hybrid",
+      "workspace": "hermes",
-  "sessionStrategy": "per-directory",
+      "aiPeer": "hermes",
-  "enabled": true
+      "memoryMode": "hybrid",
+      "writeFrequency": "async",
+      "recallMode": "hybrid",
+      "sessionStrategy": "per-directory"
+    }
+  }
 }
 ```
 
+The `hosts` structure lets multiple integrations share the same config file. Each host (Hermes, Claude Code, Cursor, etc.) reads its own block while sharing global fields like `apiKey` and `peerName`.
+
 Or set the API key as an environment variable:
 
 ```bash