OpenClaw is a general AI agent that can perform actions on behalf of a user. The Honcho plugin gives OpenClaw memory across every channel — WhatsApp, Telegram, Discord, Slack, and more.
Honcho can run entirely locally with OpenClaw — no external API required. Keep your data on your machine while getting full memory capabilities across all channels. See the self-hosting guide to get started. Get Your API Key
Create a Honcho API key from app.honcho.dev, then add it to your OpenClaw env file:
echo "HONCHO_API_KEY=hc_..." >> ~/.openclaw/.env
Install the Plugin
Option A: ClawHub Skill (Recommended)
The honcho-setup skill on ClawHub handles installation, migration, and workspace setup interactively:
clawhub install honcho-setup
Option B: Manual Install
Install the plugin using the OpenClaw plugin system. Do not install @honcho-ai/sdk directly or use npm install in the workspace.
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw plugins enable openclaw-honcho
Cannot find module '@honcho-ai/sdk', install the plugin’s dependencies manually:
cd ~/.openclaw/extensions/openclaw-honcho && npm install
Migrating Legacy Memory
If you have existing workspace memory files (USER.md, MEMORY.md, IDENTITY.md, memory/, canvas/, etc.), these can be migrated to Honcho. The recommended path is the honcho-setup ClawHub skill, which handles this interactively.
Commit any existing memory files to version control before migrating.
Legacy files
User/owner files (content describes the user):
USER.md, IDENTITY.md, MEMORY.md- All files in
memory/ and canvas/ directories
Agent/self files (content describes the agent):
SOUL.md, AGENTS.md, TOOLS.md, BOOTSTRAP.md, HEARTBEAT.md
Upload to Honcho
Files are uploaded to Honcho via the messages upload endpoint. User/owner files are uploaded through the owner peer, and agent/self files through the openclaw peer. The honcho-setup skill automates this using session.uploadFile().
Archive originals
After uploading:
- Remove originals for legacy-only files:
USER.md, MEMORY.md, IDENTITY.md, HEARTBEAT.md
- Keep originals for active workspace docs:
AGENTS.md, TOOLS.md, SOUL.md, BOOTSTRAP.md
- Move directories (
memory/, canvas/) into an archive/ directory
How It Works
Once installed, the plugin runs automatically:
- Message Observation — After every AI turn, the conversation is persisted to Honcho. Both user and agent messages are observed, allowing Honcho to build and refine its models.
- Tool-Based Context Access — The AI can query Honcho mid-conversation using tools like
honcho_recall, honcho_search, and honcho_analyze to retrieve relevant context.
- Dual Peer Model — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors).
Data Retrieval (fast, no LLM)
| Tool | Description |
|---|
honcho_session | Conversation history and summaries from the current session. |
honcho_profile | User’s peer card — key facts (name, preferences, role). |
honcho_search | Semantic search over stored observations. |
honcho_context | Full user representation across all sessions. |
Q&A (LLM-powered)
| Tool | Description |
|---|
honcho_recall | Simple factual question — minimal reasoning. |
honcho_analyze | Complex question requiring synthesis — medium reasoning. |
CLI Commands
openclaw honcho status # Connection status
openclaw honcho ask <question> # Query Honcho about the user
openclaw honcho search <query> [-k N] [-d D] # Semantic search (topK, maxDistance)
Configuration
Optional — the plugin works out of the box with HONCHO_API_KEY set.
| Key | Default | Description |
|---|
workspaceId | "openclaw" | Honcho workspace ID for memory isolation. |
baseUrl | "https://api.honcho.dev" | API endpoint (for self-hosted instances). |
Self-Hosted Honcho
Point the plugin to your local instance and follow the self-hosting guide to get started:
echo "HONCHO_BASE_URL=http://localhost:8000" >> ~/.openclaw/.env
Local File Search (QMD Integration)
The plugin automatically exposes OpenClaw’s memory_search and memory_get tools when a memory backend is configured, allowing both Honcho cloud memory and local file search together.
Setup
-
Install QMD on your server
-
Configure OpenClaw in
~/.openclaw/openclaw.json:
{
"memory": {
"backend": "qmd",
"qmd": {
"limits": {
"timeoutMs": 120000
}
}
}
}
- Set up QMD collections and restart:
qmd collection add ~/Documents/notes --name notes
qmd update
openclaw gateway restart
| Tool | Source | Description |
|---|
honcho_* | Honcho | Cross-session memory, user modeling, dialectic reasoning |
memory_search | QMD | Search local markdown files |
memory_get | QMD | Retrieve file content |
Next Steps
