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

# Honcho 记忆

[Honcho](https://honcho.dev) 通过一个外部插件为 OpenClaw 添加 AI 原生记忆。它会将对话持久化到专用服务中，并随着时间构建用户和代理模型，为你的代理提供超越工作区 Markdown 文件的跨会话上下文。

## 它提供什么

* **跨会话记忆** - 对话会在每一轮后持续保留，因此
  上下文可跨会话重置、压缩和频道切换保持延续。
* **用户建模** - Honcho 为每个用户维护一个档案（偏好、
  事实、沟通风格）以及为代理维护一个档案（个性、已学会的
  行为）。
* **语义搜索** - 对过去对话中的观察内容进行搜索，而不只是
  当前会话。
* **多代理感知** - 父代理会自动跟踪生成的
  子代理，并将父代理作为观察者添加到子会话中。

## 可用工具

Honcho 注册了代理在对话期间可以使用的工具：

**数据检索（快速，无需调用 LLM）：**

| 工具                          | 描述                  |
| --------------------------- | ------------------- |
| `honcho_context`            | 跨会话的完整用户画像          |
| `honcho_search_conclusions` | 对存储的结论进行语义搜索        |
| `honcho_search_messages`    | 跨会话搜索消息（可按发送者、日期筛选） |
| `honcho_session`            | 当前会话历史和摘要           |

**问答（由 LLM 提供支持）：**

| 工具           | 描述                                                 |
| ------------ | -------------------------------------------------- |
| `honcho_ask` | 向用户提问。对于事实使用 `depth='quick'`，对于综合分析使用 `'thorough'` |

## 开始使用

安装插件并运行设置：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force
```

设置命令会提示你输入 API 凭据，写入配置，并可选择迁移现有的工作区记忆文件。

<Info>
  Honcho 可以完全在本地运行（自托管），也可以通过
  `api.honcho.dev` 上的托管 API 运行。对于自托管
  选项，不需要任何外部依赖。
</Info>

## 配置

设置位于 `plugins.entries["openclaw-honcho"].config` 下：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      "openclaw-honcho": {
        config: {
          apiKey: "your-api-key", // 自托管时省略
          workspaceId: "openclaw", // 记忆隔离
          baseUrl: "https://api.honcho.dev",
        },
      },
    },
  },
}
```

对于自托管实例，请将 `baseUrl` 指向你的本地服务器（例如
`http://localhost:8000`），并省略 API 密钥。

## 迁移现有记忆

如果你已有工作区记忆文件（`USER.md`、`MEMORY.md`、
`IDENTITY.md`、`memory/`、`canvas/`），`openclaw honcho setup` 会检测到并
提供迁移选项。

<Info>
  迁移是非破坏性的——文件会上传到 Honcho。原始文件
  绝不会被删除或移动。
</Info>

## 工作原理

在每次 AI 回合后，对话都会持久化到 Honcho。用户和
代理消息都会被观察，从而让 Honcho 随着时间推移构建并优化其模型。

在对话过程中，Honcho 工具会在 OpenClaw 的
`before_prompt_build` 插件钩子中查询服务，在模型
看到提示之前注入相关上下文。

## Honcho 与内置记忆

|          | 内置记忆             | Honcho      |
| -------- | ---------------- | ----------- |
| **存储**   | 工作区 Markdown 文件  | 专用服务（本地或托管） |
| **跨会话**  | 通过记忆文件           | 自动内置        |
| **用户建模** | 手动（写入 MEMORY.md） | 自动生成用户画像    |
| **搜索**   | 向量 + 关键词（混合）     | 基于观测结果的语义搜索 |
| **多智能体** | 不跟踪              | 具备父子关系感知    |
| **依赖项**  | 无                | 安装插件        |

Honcho 与内置记忆系统可以协同工作。内置搜索会在 Honcho 的跨会话记忆旁保留本地 Markdown 的可用性。

## CLI 命令

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw honcho setup                        # 配置 API 密钥并迁移文件
openclaw honcho status                       # 检查连接状态
openclaw honcho ask <question>               # 向 Honcho 询问有关用户的问题
openclaw honcho search <query> [-k N] [-d D] # 对记忆进行语义搜索
```

## 延伸阅读

* [插件源代码](https://github.com/plastic-labs/openclaw-honcho)
* [Honcho 文档](https://docs.honcho.dev)
* [Honcho OpenClaw 集成指南](https://docs.honcho.dev/v3/guides/integrations/openclaw)

## 相关内容

* [记忆概览](/concepts/memory)
* [内置记忆引擎](/concepts/memory-builtin)
* [上下文引擎](/concepts/context-engine)