Honcho Conversational Memory plugin thumbnail

Honcho Conversational Memory

Persistent conversational memory via Honcho (by Plastic Labs). Automatically syncs all chat messages, retrieves summarised user context across sessions, and injects it into the agent system prompt. Requires a free Honcho API key.

Author alogotron 5 stars Version 1.2.0 Updated
MemoryAgentsApi
GitHub Repository Discussion How to install

README

🧠 Honcho Conversational Memory Plugin for Agent Zero

Persistent conversational memory via Honcho Cloud by Plastic Labs. Gives Agent Zero the ability to remember users across chat sessions — preferences, facts, context, and behavioral patterns.

What It Does

Feature Description
Automatic Message Sync Every user and assistant message is pushed to Honcho in real time
Persistent User Context User preferences and facts survive across separate chat sessions
System-Prompt Injection Summarised context is fetched and injected automatically so the agent "remembers"
Graceful Degradation If Honcho is unavailable, the agent continues normally
Settings UI Configure workspace, peer IDs, cache TTL directly in A0's settings
Plugin System Conformant Built for A0's plugin architecture (plugin.yaml, extensions, settings)

How It Works

┌─────────────┐     messages      ┌──────────────┐     conclusions     ┌──────────────┐
│  Agent Zero  │ ───────────────▶  │ Honcho Cloud │ ──────────────────▶ │  Peer Cards  │
│  (your chat) │                   │  (memory)    │   dreaming cycle    │  (knowledge) │
└──────┬───────┘                   └──────┬───────┘                     └──────────────┘
       │                                  │
       │◀──── context injection ──────────┘
       │      (system prompt)
  1. Message Sync — When you chat, messages are mirrored to Honcho via the hist_add_before extension
  2. Context Retrieval — On each turn, user context is fetched from Honcho and injected into the system prompt
  3. Dreaming — Honcho's background process consolidates observations into peer cards (persistent user/agent knowledge)

Installation

1. Clone into Agent Zero's user plugins directory

cd /a0/usr/plugins
git clone https://github.com/alogotron/a0-plugin-honcho.git honcho

2. Install dependencies

# Install into A0's runtime Python (important: use the correct venv)
/opt/venv-a0/bin/pip install -r /a0/usr/plugins/honcho/requirements.txt

# Also install for pyenv if applicable
/opt/pyenv/versions/3.12.4/bin/pip install honcho-ai

3. Get a Honcho API key

  1. Go to app.honcho.dev
  2. Create a free account
  3. Generate an API key

4. Configure in Agent Zero

  1. Go to Settings → Secrets and add:

    • HONCHO_API_KEY — your API key from Honcho
    • HONCHO_WORKSPACE_ID — (optional) workspace name, defaults to agent-zero

  2. Go to Settings → Plugins and enable Honcho Conversational Memory

  3. (Optional) Click Configure on the plugin to adjust:

    • Workspace ID
    • User/Agent peer IDs
    • Context cache TTL
    • Max context tokens

5. Restart Agent Zero

The plugin will be discovered on restart. You'll see [Honcho] Integration enabled for session: chat-xxxxx in the logs.

Plugin Structure

honcho/
├── plugin.yaml                          # Plugin manifest
├── default_config.yaml                  # Settings defaults
├── requirements.txt                     # honcho-ai>=2.0.0
├── LICENSE                              # MIT
├── helpers/
│   └── honcho_helper.py                 # Core integration logic
├── extensions/
│   └── python/
│       ├── agent_init/
│       │   └── _20_honcho_init.py       # Initialize Honcho on agent start
│       ├── hist_add_before/
│       │   └── _20_honcho_sync.py       # Sync messages to Honcho
│       └── system_prompt/
│           └── _30_honcho_context.py    # Inject user context into prompt
├── prompts/
│   └── honcho.context.md                # Context injection template
└── webui/
    └── config.html                      # Settings UI

Configuration

Secrets (Settings → Secrets)

Key Required Default Description
HONCHO_API_KEY ✅ Yes — Your Honcho API key
HONCHO_WORKSPACE_ID No agent-zero Override workspace (also configurable in plugin settings)
HONCHO_USER_ID No user Override user peer ID

Plugin Settings (Settings → Plugins → Honcho → Configure)

Setting Default Description
Workspace ID agent-zero Honcho workspace name
User Peer ID user Human peer identifier
Agent Peer ID agent-zero AI agent peer identifier
Cache TTL 120 seconds How long to cache context
Max Context Tokens 500 Max tokens for injected context
Debug Logging false Verbose logging

Honcho Concepts

Concept Description
Workspace Top-level container for all memory data
Peer An entity (user or agent) with a card and conclusions
Session A conversation thread, maps 1:1 to an A0 chat
Conclusion An individual observation Honcho has made
Card Compiled summary of key facts about a peer
Dreaming Background process that consolidates conclusions into cards

Requirements

  • Agent Zero (development branch with plugin system)
  • Python 3.12+
  • honcho-ai >= 2.0.0
  • Free Honcho account at honcho.dev

License

MIT