hermes-agent/docs/honcho-evaluation-322.md

Honcho Memory Integration Evaluation (#322)

Executive Summary

Status: Integration already implemented and production-ready. Recommendation: KEEP — well-gated, zero overhead when disabled, supports self-hosted.

Decision: Cloud vs Local

The Question

"Do we want a cloud-dependent memory layer, or keep everything local?"

Answer: BOTH — User's Choice

Honcho supports both deployment modes:

Mode	Configuration	Data Location	Use Case
Cloud	HONCHO_API_KEY	Honcho servers	Quick start, no infrastructure
Self-hosted	HONCHO_BASE_URL=http://localhost:8000	Your servers	Full sovereignty
Disabled	No config	N/A	Pure local (holographic fact_store only)

Why Keep It

1. Opt-in Architecture

   • No Honcho config → zero overhead (cron guard, lazy init)
   • Memory provider system allows switching between providers
   • hermes memory off disables completely

2. Zero Runtime Cost When Disabled

   if not cfg.enabled or not (cfg.api_key or cfg.base_url):
       return ""  # No HTTP calls, no overhead
   

3. Cross-Session User Modeling

   • Holographic fact_store lacks persistent user modeling
   • Honcho provides: peer cards, dialectic Q&A, semantic search
   • Complements (not replaces) local memory

4. Self-Hosted Option

   • Set HONCHO_BASE_URL=http://localhost:8000
   • Run Honcho server locally via Docker
   • Full data sovereignty

5. Production-Grade Implementation

   • 3 components, ~700 lines of code
   • 7 tests passing
   • Async prefetch (zero-latency context injection)
   • Configurable recall modes (hybrid/context/tools)
   • Write frequency control (async/turn/session/N-turns)

Architecture

Components (Already Implemented)

plugins/memory/honcho/
├── client.py      # Config resolution (API key, base_url, profiles)
├── session.py     # Session management, async prefetch, dialectic queries
├── __init__.py    # MemoryProvider interface, 4 tool schemas
├── cli.py         # CLI commands (setup, status, sessions, map, peer, mode)
├── plugin.yaml    # Plugin metadata
└── README.md      # Documentation

Integration Points

1. System Prompt: Context injected on first turn (cached for prompt caching)
2. Tool Registry: 4 tools available when recall_mode != "context"
3. Session End: Messages flushed to Honcho
4. Cron Guard: Fully inactive in cron context

Tools Available

Tool	Cost	Speed	Purpose
honcho_profile	Free	Fast	Quick factual snapshot (peer card)
honcho_search	Free	Fast	Semantic search (raw excerpts)
honcho_context	Paid	Slow	Dialectic Q&A (synthesized answers)
honcho_conclude	Free	Fast	Save persistent facts about user

Configuration Guide

Option 1: Cloud (Quick Start)

# Get API key from https://app.honcho.dev
export HONCHO_API_KEY="your-api-key"
hermes chat

Option 2: Self-Hosted (Full Sovereignty)

# Run Honcho server locally
docker run -p 8000:8000 honcho/server

# Configure Hermes
export HONCHO_BASE_URL="http://localhost:8000"
hermes chat

Option 3: CLI Setup

hermes honcho setup

Option 4: Disabled (Pure Local)

# Don't set any Honcho config
hermes memory off  # If previously enabled
hermes chat

Memory Modes

Mode	Context Injection	Tools	Cost	Use Case
hybrid	Yes	Yes	Medium	Default — auto-inject + on-demand
context	Yes	No	Low	Budget mode — auto-inject only
tools	No	Yes	Variable	Full control — agent decides

Risk Assessment

Risk	Mitigation	Status
Cloud dependency	Self-hosted option available	✅
Cost from LLM calls	Recall mode "context" or "tools" reduces calls	✅
Data privacy	Self-hosted keeps data on your servers	✅
Performance overhead	Cron guard + lazy init + async prefetch	✅
Vendor lock-in	MemoryProvider interface allows swapping	✅

Comparison with Alternatives

Feature	Honcho	Holographic	Mem0	Hindsight
Cross-session modeling	✅	❌	✅	✅
Dialectic Q&A	✅	❌	❌	❌
Self-hosted	✅	N/A	❌	❌
Local-only option	✅	✅	❌	✅
Cost	Free/Paid	Free	Paid	Free

Conclusion

Keep Honcho integration. It provides unique cross-session user modeling capabilities that complement the local holographic fact_store. The integration is:

• Well-gated (opt-in, zero overhead when disabled)
• Flexible (cloud or self-hosted)
• Production-ready (7 tests passing, async prefetch, configurable)
• Non-exclusive (works alongside other memory providers)

To Enable

# Cloud
hermes honcho setup

# Self-hosted
export HONCHO_BASE_URL="http://localhost:8000"
hermes chat

To Disable

hermes memory off

---

Evaluated by SANDALPHON — Cron/Ops lane