mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-15 13:16:04 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
---
|
|
summary: "AI-native cross-session memory via the Honcho plugin"
|
|
title: "Honcho memory"
|
|
read_when:
|
|
- You want persistent memory that works across sessions and channels
|
|
- You want AI-powered recall and user modeling
|
|
---
|
|
|
|
[Honcho](https://honcho.dev) adds AI-native memory to OpenClaw through an
|
|
external plugin. It persists conversations to a dedicated service and builds
|
|
user and agent models over time, giving your agent cross-session context that
|
|
goes beyond workspace Markdown files.
|
|
|
|
## What it provides
|
|
|
|
- **Cross-session memory** - conversations persist after every turn, so
|
|
context carries across session resets, compaction, and channel switches.
|
|
- **User modeling** - Honcho maintains a profile for each user (preferences,
|
|
facts, communication style) and for the agent (personality, learned
|
|
behaviors).
|
|
- **Semantic search** - search over observations from past conversations, not
|
|
just the current session.
|
|
- **Multi-agent awareness** - parent agents automatically track spawned
|
|
sub-agents, with parents added as observers in child sessions.
|
|
|
|
## Available tools
|
|
|
|
Honcho registers tools the agent can use during conversation:
|
|
|
|
**Data retrieval (fast, no LLM call):**
|
|
|
|
| Tool | What it does |
|
|
| --------------------------- | ------------------------------------------------------ |
|
|
| `honcho_context` | Full user representation across sessions |
|
|
| `honcho_search_conclusions` | Semantic search over stored conclusions |
|
|
| `honcho_search_messages` | Find messages across sessions (filter by sender, date) |
|
|
| `honcho_session` | Current session history and summary |
|
|
|
|
**Q&A (LLM-powered):**
|
|
|
|
| Tool | What it does |
|
|
| ------------ | ------------------------------------------------------------------------- |
|
|
| `honcho_ask` | Ask about the user. `depth='quick'` for facts, `'thorough'` for synthesis |
|
|
|
|
## Getting started
|
|
|
|
Install the plugin and run setup:
|
|
|
|
```bash
|
|
openclaw plugins install @honcho-ai/openclaw-honcho
|
|
openclaw honcho setup
|
|
openclaw gateway --force
|
|
```
|
|
|
|
The setup command prompts for your API credentials, writes the config, and
|
|
optionally migrates existing workspace memory files.
|
|
|
|
<Info>
|
|
Honcho can run entirely locally (self-hosted) or via the managed API at
|
|
`api.honcho.dev`. No external dependencies are required for the self-hosted
|
|
option.
|
|
</Info>
|
|
|
|
## Configuration
|
|
|
|
Settings live under `plugins.entries["openclaw-honcho"].config`:
|
|
|
|
```json5
|
|
{
|
|
plugins: {
|
|
entries: {
|
|
"openclaw-honcho": {
|
|
config: {
|
|
apiKey: "your-api-key", // omit for self-hosted
|
|
workspaceId: "openclaw", // memory isolation
|
|
baseUrl: "https://api.honcho.dev",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For self-hosted instances, point `baseUrl` to your local server (for example
|
|
`http://localhost:8000`) and omit the API key.
|
|
|
|
## Migrating existing memory
|
|
|
|
If you have existing workspace memory files (`USER.md`, `MEMORY.md`,
|
|
`IDENTITY.md`, `memory/`, `canvas/`), `openclaw honcho setup` detects and
|
|
offers to migrate them.
|
|
|
|
<Info>
|
|
Migration is non-destructive - files are uploaded to Honcho. Originals are
|
|
never deleted or moved.
|
|
</Info>
|
|
|
|
## How it works
|
|
|
|
After every AI turn, the conversation is persisted to Honcho. Both user and
|
|
agent messages are observed, letting Honcho build and refine its models over
|
|
time.
|
|
|
|
During conversation, Honcho tools query the service during OpenClaw's
|
|
`before_prompt_build` plugin hook, injecting relevant context before the model
|
|
sees the prompt.
|
|
|
|
## Honcho vs builtin memory
|
|
|
|
| | Builtin / QMD | Honcho |
|
|
| ----------------- | ---------------------------- | ----------------------------------- |
|
|
| **Storage** | Workspace Markdown files | Dedicated service (local or hosted) |
|
|
| **Cross-session** | Via memory files | Automatic, built-in |
|
|
| **User modeling** | Manual (write to MEMORY.md) | Automatic profiles |
|
|
| **Search** | Vector + keyword (hybrid) | Semantic over observations |
|
|
| **Multi-agent** | Not tracked | Parent/child awareness |
|
|
| **Dependencies** | None (builtin) or QMD binary | Plugin install |
|
|
|
|
Honcho and the builtin memory system can work together. When QMD is
|
|
configured, additional tools become available for searching local Markdown
|
|
files alongside Honcho's cross-session memory.
|
|
|
|
## CLI commands
|
|
|
|
```bash
|
|
openclaw honcho setup # Configure API key and migrate files
|
|
openclaw honcho status # Check connection status
|
|
openclaw honcho ask <question> # Query Honcho about the user
|
|
openclaw honcho search <query> [-k N] [-d D] # Semantic search over memory
|
|
```
|
|
|
|
## Further reading
|
|
|
|
- [Plugin source code](https://github.com/plastic-labs/openclaw-honcho)
|
|
- [Honcho documentation](https://docs.honcho.dev)
|
|
- [Honcho OpenClaw integration guide](https://docs.honcho.dev/v3/guides/integrations/openclaw)
|
|
|
|
## Related
|
|
|
|
- [Memory overview](/concepts/memory)
|
|
- [Builtin memory engine](/concepts/memory-builtin)
|
|
- [QMD memory engine](/concepts/memory-qmd)
|
|
- [Context Engines](/concepts/context-engine)
|