From b7f099beed376cad6a565a75b47e558311754545 Mon Sep 17 00:00:00 2001
From: teknium1 <teknium1@gmail.com>
Date: Fri, 27 Feb 2026 23:41:08 -0800
Subject: [PATCH] feat: add Honcho integration for cross-session user modeling

---
 .env.example            |  6 ++++++
 README.md               | 41 +++++++++++++++++++++++++++++++++++++++++
 cli-config.yaml.example | 14 ++++++++++++++
 3 files changed, 61 insertions(+)

diff --git a/.env.example b/.env.example
index 95bdf4aa..78549212 100644
--- a/.env.example
+++ b/.env.example
@@ -29,6 +29,12 @@ NOUS_API_KEY=
 # Get at: https://fal.ai/
 FAL_KEY=
 
+# Honcho - Cross-session AI-native user modeling (optional)
+# Builds a persistent understanding of the user across sessions and tools.
+# Get at: https://app.honcho.dev
+# Also requires ~/.honcho/config.json with enabled=true (see README).
+HONCHO_API_KEY=
+
 # =============================================================================
 # TERMINAL TOOL CONFIGURATION (mini-swe-agent backend)
 # =============================================================================
diff --git a/README.md b/README.md
index 3a21b45a..5408fa29 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,7 @@ hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env
 | Premium TTS voices | [ElevenLabs](https://elevenlabs.io/) | `ELEVENLABS_API_KEY` |
 | OpenAI TTS + voice transcription | [OpenAI](https://platform.openai.com/api-keys) | `VOICE_TOOLS_OPENAI_KEY` |
 | RL Training | [Tinker](https://tinker-console.thinkingmachines.ai/) + [WandB](https://wandb.ai/) | `TINKER_API_KEY`, `WANDB_API_KEY` |
+| Cross-session user modeling | [Honcho](https://honcho.dev/) | `HONCHO_API_KEY` |
 
 ---
 
@@ -547,6 +548,45 @@ memory:
   user_char_limit: 1375     # ~500 tokens
 ```
 
+### 🔗 Honcho Integration (Cross-Session User Modeling)
+
+Optional cloud-based user modeling via [Honcho](https://honcho.dev/) by Plastic Labs. While MEMORY.md and USER.md are local file-based memory, Honcho builds a deeper, AI-generated understanding of the user that persists across sessions and works across tools (Claude Code, Cursor, Hermes, etc.).
+
+When enabled, Honcho runs **alongside** existing memory — USER.md stays as-is, and Honcho adds an additional layer of user context:
+
+- **Prefetch**: Each turn, Honcho's user representation is fetched and injected into the system prompt
+- **Sync**: After each conversation, messages are synced to Honcho for ongoing user modeling
+- **Query tool**: The agent can actively query its understanding of the user via `query_user_context`
+
+**Setup:**
+```bash
+# 1. Install the optional dependency
+uv pip install honcho-ai
+
+# 2. Get an API key from https://app.honcho.dev
+
+# 3. Create ~/.honcho/config.json (shared with other Honcho-enabled tools)
+cat > ~/.honcho/config.json << 'EOF'
+{
+  "enabled": true,
+  "apiKey": "your-honcho-api-key",
+  "peerName": "your-name",
+  "hosts": {
+    "hermes": {
+      "workspace": "hermes"
+    }
+  }
+}
+EOF
+```
+
+Or configure via environment variable:
+```bash
+hermes config set HONCHO_API_KEY your-key
+```
+
+Fully opt-in — zero behavior change when disabled or unconfigured. All Honcho calls are non-fatal; if the service is unreachable, the agent continues normally.
+
 ### 📄 Context Files (SOUL.md, AGENTS.md, .cursorrules)
 
 Drop these files in your project directory and the agent automatically picks them up:
@@ -1477,6 +1517,7 @@ All variables go in `~/.hermes/.env`. Run `hermes config set VAR value` to set t
 | `BROWSERBASE_API_KEY` | Browser automation |
 | `BROWSERBASE_PROJECT_ID` | Browserbase project |
 | `FAL_KEY` | Image generation (fal.ai) |
+| `HONCHO_API_KEY` | Cross-session user modeling ([honcho.dev](https://honcho.dev/)) |
 
 **Terminal Backend:**
 | Variable | Description |
diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index fb4be067..5a185532 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -467,6 +467,20 @@ delegation:
   max_iterations: 50                          # Max tool-calling turns per child (default: 25)
   default_toolsets: ["terminal", "file", "web"]  # Default toolsets for subagents
 
+# =============================================================================
+# Honcho Integration (Cross-Session User Modeling)
+# =============================================================================
+# AI-native persistent memory via Honcho (https://honcho.dev/).
+# Builds a deeper understanding of the user across sessions and tools.
+# Runs alongside USER.md — additive, not a replacement.
+#
+# Requires: pip install honcho-ai
+# Config: ~/.honcho/config.json (shared with Claude Code, Cursor, etc.)
+# API key: HONCHO_API_KEY in ~/.hermes/.env or ~/.honcho/config.json
+#
+# Hermes-specific overrides (optional — most config comes from ~/.honcho/config.json):
+# honcho: {}
+
 # =============================================================================
 # Display
 # =============================================================================