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**
   ```python
   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)
```bash
# Get API key from https://app.honcho.dev
export HONCHO_API_KEY="your-api-key"
hermes chat
```

### Option 2: Self-Hosted (Full Sovereignty)
```bash
# 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
```bash
hermes honcho setup
```

### Option 4: Disabled (Pure Local)
```bash
# 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

```bash
# Cloud
hermes honcho setup

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

### To Disable

```bash
hermes memory off
```

---

*Evaluated by SANDALPHON — Cron/Ops lane*