> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> Add AI-native memory to OpenClaw

[OpenClaw](https://openclaw.ai) 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.

<Note>
  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](/v3/contributing/self-hosting) to get started.
</Note>

For OpenClaw's own documentation on Honcho, see the [Honcho Memory guide](https://docs.openclaw.ai/concepts/memory-honcho).

## Install the Plugin

```bash theme={null}
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force
```

`openclaw honcho setup` prompts for your API key, writes the config, and optionally uploads any legacy memory files to Honcho.

<iframe className="w-full aspect-video rounded-xl" src="https://www.loom.com/embed/bc870932f1694302a80f1f71276790e8" title="Loom video" allowFullScreen />

<Note>
  **Alternative: ClawHub Skill**

  The `honcho-setup` skill handles installation and migration interactively from a chat session:

  ```bash theme={null}
  npx clawhub install honcho-setup
  # Restart OpenClaw, then invoke the skill from a session
  openclaw plugins install @honcho-ai/openclaw-honcho
  openclaw gateway restart
  ```
</Note>

## 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.

<Note>
  Migration is **non-destructive** — files are uploaded to Honcho. Originals are never deleted or moved.
</Note>

### 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`

### Upload to Honcho

Files are uploaded via `session.uploadFile()`. User/owner files go to the owner peer; agent/self files go to the openclaw peer.

## 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_context`, `honcho_search_conclusions`, `honcho_search_messages`, and `honcho_ask` to retrieve relevant context. Context is injected during OpenClaw's `before_prompt_build` phase, ensuring accurate turn boundaries.
* **Dual Peer Model** — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors). Each OpenClaw agent gets its own Honcho peer (`agent-{id}`), so multi-agent workspaces maintain isolated memory.
* **Clean Persistence** — Platform metadata (conversation info, sender headers, thread context, forwarded messages) is stripped before saving to Honcho, ensuring only meaningful content is persisted.

## Multi-Agent Support

OpenClaw uses a multi-agent architecture where a primary agent can spawn **subagents** to handle specialized tasks. The Honcho plugin is fully aware of this hierarchy:

* **Automatic Subagent Detection** — When OpenClaw spawns a subagent, the plugin tracks the parent→child relationship via the `subagent_spawned` hook. Each subagent session records its `parentPeerId` in metadata.
* **Parent Observer Peer** — The spawning agent is added as a silent observer in the subagent's Honcho session (`observeMe: false, observeOthers: true`). This gives Honcho visibility into the full agent tree — the parent can see what its subagents are doing without its own messages being attributed to the subagent session.

## AI Tools

### Data Retrieval (fast, no LLM)

| Tool                        | Description                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `honcho_context`            | User knowledge across all sessions. `detail='card'` for key facts, `'full'` for broad representation. |
| `honcho_search_conclusions` | Semantic vector search over stored conclusions ranked by relevance.                                   |
| `honcho_search_messages`    | Find specific messages across all sessions. Filter by sender, date, or metadata.                      |
| `honcho_session`            | Current session history and summary. Supports semantic search within the session.                     |

### Q\&A (LLM-powered)

| Tool         | Description                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------- |
| `honcho_ask` | Ask Honcho a question about the user. `depth='quick'` for facts, `'thorough'` for synthesis. |

## CLI Commands

```bash theme={null}
openclaw honcho setup                           # Configure API key and migrate legacy files
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

Run `openclaw honcho setup` to configure interactively, or set values directly in `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-honcho"].config`.

| Key           | Default                    | Description                                                  |
| ------------- | -------------------------- | ------------------------------------------------------------ |
| `apiKey`      | —                          | Honcho API key (required for managed; omit for self-hosted). |
| `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](https://github.com/plastic-labs/honcho?tab=readme-ov-file#local-development) to get started:

```bash theme={null}
openclaw honcho setup
# Enter blank API key, set Base URL to http://localhost:8000
```

## Local File Search (QMD Integration)

The plugin automatically exposes OpenClaw's `memory_search` and `memory_get` tools when a [memory backend](https://docs.openclaw.ai/concepts/memory) is configured, allowing both Honcho memory and local file search together.

### Setup

1. Install [QMD](https://github.com/tobi/qmd) on your server

2. Configure OpenClaw to use QMD as the memory backend in `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "memory": {
    "backend": "qmd"
  }
}
```

OpenClaw manages QMD collections automatically from your workspace memory files and any extra paths in `memory.qmd.paths`. See the [QMD Memory Engine docs](https://docs.openclaw.ai/concepts/memory-qmd) for full setup.

3. Restart the gateway:

```bash theme={null}
openclaw gateway restart
```

### Available Tools

When QMD is configured, you get both Honcho and local file tools:

| 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

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/openclaw-honcho">
    Source code, issues, and README.
  </Card>

  <Card title="OpenClaw Memory Docs" icon="book" href="https://docs.openclaw.ai/concepts/memory">
    Memory backends, search, and configuration in the OpenClaw docs.
  </Card>

  <Card title="Honcho Architecture" icon="sitemap" href="/v3/documentation/core-concepts/architecture">
    Learn about peers, sessions, and dialectic reasoning.
  </Card>
</CardGroup>