Tools
Honcho
By Make your OpenClaw happy, give it Honcho
Install
npm install -gConfiguration Example
{
"plugins": {
"entries": {
"openclaw-honcho": {
"config": {
"noisePatterns": ["my custom noise string"]
}
}
}
}
}README
# Honcho Memory Plugin for OpenClaw
[](https://honcho.dev)
AI-native memory with dialectic reasoning for OpenClaw. Uses [Honcho's](https://honcho.dev) peer paradigm to build and maintain separate models of the user and the agent — enabling context-aware conversations that improve over time. No local infrastructure required.
This plugin uses OpenClaw's slot system (`kind: "memory"`) to replace the built-in memory plugins (`memory-core`, `memory-lancedb`). During setup, existing memory files can be migrated to Honcho. Workspace docs (`SOUL.md`, `AGENTS.md`, `BOOTSTRAP.md`) can be updated manually to reference Honcho's tools instead of the old file-based system.
## Install
```bash
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw plugins enable openclaw-honcho
openclaw config set plugins.entries.openclaw-honcho.hooks.allowConversationAccess true
openclaw honcho setup
openclaw gateway restart
```
> **Important:** `openclaw plugins enable openclaw-honcho` sets `plugins.slots.memory` to `openclaw-honcho`, which OpenClaw requires in order to load this plugin. On OpenClaw 2026.8.x and earlier, `plugins install` alone does not set the slot and the plugin is silently disabled at startup: no tools, no capture, and a single loader line, `plugin disabled (memory slot set to "memory-core")`. OpenClaw 2026.9.1 sets the slot during install, so the step is redundant there but harmless. See [Running alongside memory-core](#running-alongside-memory-core).
> **Important:** The `allowConversationAccess` is required to save new messages to Honcho. The plugin will log a warning at startup if this flag is missing.
`openclaw honcho setup` prompts for your Honcho API key, writes the config, and optionally uploads any legacy memory files to Honcho.
<details>
<summary>Alternative: ClawHub Skill</summary>
Use the `honcho-setup` skill to run migration interactively from within a chat session:
```bash
# 1. Install the skill
npx clawhub install honcho-setup
# 2. Restart OpenClaw to pick up the new skill
# 3. Install the plugin
openclaw plugins install @honcho-ai/openclaw-honcho
# 4. Restart the gateway
openclaw gateway restart
# 5. Open an agent session and invoke the skill
# The skill will prompt for your Honcho API key and run setup interactively
```
</details>
## Running alongside memory-core
OpenClaw allows one active memory plugin, selected by `plugins.slots.memory`. This plugin replaces `memory-core` when it owns that slot. Running Honcho **alongside** `memory-core` is not currently supported: if `plugins.slots.memory` is unset or set to `memory-core`, OpenClaw disables this plugin at load. This is the loader's behaviour on every OpenClaw release from at least 2026.6.34 through 2026.9.1, so pinning an OpenClaw version does not avoid it.
A companion mode, where Honcho stays loaded with its hooks and `honcho_*` tools while `memory-core` keeps the slot, is tracked in [#132](https://github.com/plastic-labs/openclaw-honcho/pull/132) and planned for the next release.
Do not set `plugins.slots.contextEngine` to `openclaw-honcho`. The plugin provides no context engine, and OpenClaw logs a "degraded to legacy" warning on every turn.
## Migrating Legacy Memory
If you have existing workspace memory files (`USER.md`, `MEMORY.md`, `IDENTITY.md`, `memory/`, `canvas/`, etc.), `openclaw honcho setup` will detect them and offer to migrate them.
Migration is **non-destructive** — files are uploaded to Honcho. Originals are never deleted or moved.
### Legacy files
**User/owner files** (content describes the user):
- `USER.md`, `MEMORY.md`
- All files in `memory/` and `canvas/` directories (treated as user content)
**Agent/self files** (content describes the agent):
- `SOUL.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`, `BOOTSTRAP.md`
### Upload to Honcho
Files are uploaded via `session.uploadFile()`. User/owner files go to the owner peer; agent/self files go to the agent peer (`agent-{agentId}`, e.g. `agent-main`).
### Update workspace docs
The plugin ships template files in `node_modules/@honcho-ai/openclaw-honcho/workspace_md/`. Copy or merge these templates into your workspace for `AGENTS.md`, `SOUL.md`, and `BOOTSTRAP.md`. These templates reference the Honcho tools (`honcho_context`, `honcho_search_conclusions`, `honcho_ask`, `honcho_search_messages`, `honcho_session`) instead of the old file-based memory system.
## Configuration
Run `openclaw honcho setup` to configure interactively, or set values directly in `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-honcho"].config`.
| Key | Type | Default | Description |
| ---------------------- | ---------- | -------------------------- | ----------------------------------------- |
| `apiKey` | `string` | — | Honcho API key (required for managed; omit for self-hosted). |
| `workspaceId` | `string` | `"openclaw"` | Honcho workspace ID for memory isolation. |
| `baseUrl` | `string` | `"https://api.honcho.dev"` | API endpoint (for self-hosted instances). |
| `noisePatterns` | `string[]` | built-in defaults | Patterns to skip messages. User-provided patterns are merged with built-in defaults (unless `disableDefaultNoisePatterns` is set). |
| `disableDefaultNoisePatterns` | `boolean` | `false` | When `true`, built-in noise patterns are not applied — only `noisePatterns` entries are used. |
| `crossSessionSearch` | `boolean` | `true` | Default scope for `memory_search`. `true` = results span every session the participant peer has written to; `false` = scope to the active session. `memory_search` accepts an optional `crossSessionSearch` boolean parameter to override this per-call. |
| `ownerObserveOthers` | `boolean` | `false` | Whether the owner peer observes agent messages in Honcho's social model. |
### Self-Hosted / Local Honcho
Run `openclaw honcho setup`, enter a blank API key, and set the Base URL to your instance (e.g., `http://localhost:8000`).
For setting up a local Honcho server, see the [Honcho local development guide](https://github.com/plastic-labs/honcho?tab=readme-ov-file#local-development).
### Noise Filtering
The plugin automatically drops messages that match noise patterns before saving to Honcho. Built-in defaults filter:
- `HEARTBEAT_OK` — assistant heartbeat acknowledgments
- `A scheduled reminder has been triggered` — cron reminder boilerplate
- `Execute your Session Startup sequence now` — session startup commands
- `Queued messages from` — queued message wrapper headers
Add custom patterns via `noisePatterns` in your config:
```json
{
"plugins": {
"entries": {
"openclaw-honcho": {
"config": {
"noisePatterns": ["my custom noise string"]
}
}
}
}
}
```
Custom patterns are merged with the built-in defaults. Each pattern matches if the message **equals** it or **starts with** it. Patterns starting with `/` are treated as anchored regex (e.g., `/^HEARTBEAT/i`).
### Owner Peer Observation
Honcho's `observeOthers` controls whether a peer forms representations of other peers based on messages it witnessed in shared sessions. The agent peer always has `observeOthers: true` — it sees and reasons about the user's messages. The owner (user) peer defaults to `observeOthers: false` — modeled only from what the user said, not what the agent replied.
Set `ownerObserveOthers: true` to let the owner peer also observe agent messages. This gives Honcho perspective-aware memory: the owner stores conclusions about the agent based only on what it witnessed, enabling the user's representation to reflect the full conversational context rather than just their own side of it.
### Peer Mappings
Map `sender_id` → Honcho peer ID in `~/.honcho/openclaw-peers.json` (override with `OPENCLAW_HONCHO_PEERS_FILE`). New senders are added automatically; edit `peers` to alias or merge identities, then **`openclaw gateway restart`** so the gateway reloads the file.
```json
{
"version": 1,
"defaultUnknownPolicy": "per-sender",
"peers": {
"U0EXAMPLE01": "user",
"telegram-1234567890": "user"
}
}
```
- **`defaultUnknownPolicy`** controls how unknown `sender_id`s are seeded into `peers`:
- `per-sender` — default for fresh installs. Each new sender becomes its own peer; the seeded peer ID is the `sender_id` sanitized to `[A-Za-z0-9_-]` and truncated to Honcho's 100-char limit.
- `owner` — default for pre-existing files missing the field (preserves legacy behavior). All unknown senders merge into the owner peer.
- **Auto-seeded, manually overridable.** The plugin only adds entries for senders not already in the map.
- **Adding a mapping after messages exist splits history.** Messages already stored under the original peer stay there; new messages land under the new peer. Remap before the peer accumulates history.
### Multi-Peer Participants
In group chats (Discord, Slack, etc.), the plugin extracts the sender's platform ID from each inbound message and uses it directly as the Honcho peer ID. This gives every participant — humans and any other bots in the room — their own memory and representation in Honcho, rather than attributing all non-agent messages to a single generic peer.
**How it works:**
- The plugin reads the `sender_id` field from OpenClaw's "Conversation info (untrusted metadata):" block, which OpenClaw injects on every inbound message that has a known sender — including 1-on-1 DMs on platforms like Telegram, not just group chats.
- Each distinct sender ID becomes its own Honcho peer (e.g., `U07KX7DG002` becomes the Honcho peer ID directly, sanitized to `[A-Za-z0-9_-]`). You can alias a sender to a friendlier peer ID by editing the [peers file](#peer-mappings).
- The default `owner` peer is used as a fallback when a message
... (truncated)
tools
Comments
Sign in to leave a comment