mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-18 16:41:45 -06:00
Peter Steinberger
8b0735e89f
* refactor(memory): remove qmd backend Make builtin the sole memory-core engine, rename the retained session helper barrel, retire QMD config with doctor migrations, and remove QMD runtime/UI/policy surfaces. * docs(memory): remove qmd backend guidance Delete the QMD concept page, rewrite memory documentation for builtin retrieval, and remove QMD from navigation and taxonomy source. * refactor(memory): remove qmd-only leftovers * refactor(memory): finish qmd integration cleanup * build(deps): align root string-width types * build(deps): model root string-width tooling * refactor(memory): align qmd removal ui and docs * fix(memory): preserve qmd external paths in doctor * test(memory): remove obsolete backend probe case * test(plugin-sdk): refresh private type baseline
142 lines
5.1 KiB
Markdown
142 lines
5.1 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 memory | 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 | Plugin install |
|
|
|
|
Honcho and the builtin memory system can work together. Builtin search keeps
|
|
local Markdown available 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)
|
|
- [Context Engines](/concepts/context-engine)
|