【记忆】openclaw之Honcho 记忆系统

🧠 Honcho

Honcho 是一个开源的 AI 原生记忆库，提供托管服务，也可以本地部署使用，让智能体能够：

Honcho 可以 与任何模型、任何框架、任何架构 配合使用，无论是简单的聊天机器人，还是复杂的多智能体系统。

概念

要理解 Honcho，首先需要掌握它的四个存储原语（Primal）和一个推理引擎。它们之间的层级关系如下：

#mermaid-svg-BAHKjAFF9NYWXFks{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-BAHKjAFF9NYWXFks .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-BAHKjAFF9NYWXFks .error-icon{fill:#552222;}#mermaid-svg-BAHKjAFF9NYWXFks .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-BAHKjAFF9NYWXFks .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-BAHKjAFF9NYWXFks .marker{fill:#333333;stroke:#333333;}#mermaid-svg-BAHKjAFF9NYWXFks .marker.cross{stroke:#333333;}#mermaid-svg-BAHKjAFF9NYWXFks svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-BAHKjAFF9NYWXFks p{margin:0;}#mermaid-svg-BAHKjAFF9NYWXFks .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-BAHKjAFF9NYWXFks .cluster-label text{fill:#333;}#mermaid-svg-BAHKjAFF9NYWXFks .cluster-label span{color:#333;}#mermaid-svg-BAHKjAFF9NYWXFks .cluster-label span p{background-color:transparent;}#mermaid-svg-BAHKjAFF9NYWXFks .label text,#mermaid-svg-BAHKjAFF9NYWXFks span{fill:#333;color:#333;}#mermaid-svg-BAHKjAFF9NYWXFks .node rect,#mermaid-svg-BAHKjAFF9NYWXFks .node circle,#mermaid-svg-BAHKjAFF9NYWXFks .node ellipse,#mermaid-svg-BAHKjAFF9NYWXFks .node polygon,#mermaid-svg-BAHKjAFF9NYWXFks .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-BAHKjAFF9NYWXFks .rough-node .label text,#mermaid-svg-BAHKjAFF9NYWXFks .node .label text,#mermaid-svg-BAHKjAFF9NYWXFks .image-shape .label,#mermaid-svg-BAHKjAFF9NYWXFks .icon-shape .label{text-anchor:middle;}#mermaid-svg-BAHKjAFF9NYWXFks .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-BAHKjAFF9NYWXFks .rough-node .label,#mermaid-svg-BAHKjAFF9NYWXFks .node .label,#mermaid-svg-BAHKjAFF9NYWXFks .image-shape .label,#mermaid-svg-BAHKjAFF9NYWXFks .icon-shape .label{text-align:center;}#mermaid-svg-BAHKjAFF9NYWXFks .node.clickable{cursor:pointer;}#mermaid-svg-BAHKjAFF9NYWXFks .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-BAHKjAFF9NYWXFks .arrowheadPath{fill:#333333;}#mermaid-svg-BAHKjAFF9NYWXFks .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-BAHKjAFF9NYWXFks .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-BAHKjAFF9NYWXFks .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BAHKjAFF9NYWXFks .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-BAHKjAFF9NYWXFks .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BAHKjAFF9NYWXFks .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-BAHKjAFF9NYWXFks .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-BAHKjAFF9NYWXFks .cluster text{fill:#333;}#mermaid-svg-BAHKjAFF9NYWXFks .cluster span{color:#333;}#mermaid-svg-BAHKjAFF9NYWXFks div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-BAHKjAFF9NYWXFks .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-BAHKjAFF9NYWXFks rect.text{fill:none;stroke-width:0;}#mermaid-svg-BAHKjAFF9NYWXFks .icon-shape,#mermaid-svg-BAHKjAFF9NYWXFks .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BAHKjAFF9NYWXFks .icon-shape p,#mermaid-svg-BAHKjAFF9NYWXFks .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-BAHKjAFF9NYWXFks .icon-shape .label rect,#mermaid-svg-BAHKjAFF9NYWXFks .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BAHKjAFF9NYWXFks .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-BAHKjAFF9NYWXFks .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-BAHKjAFF9NYWXFks :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Workspace 工作区顶层隔离容器

Peer: 用户

Peer: 智能体

Peer: 群组/想法

Session 会话 1

Session 会话 2

Session 会话 3

Messages 消息

Messages 消息

Messages 消息

Messages 消息

推理引擎后台异步处理

Representations可查询的表示

开发者 / 智能体查询

Workspace 工作区

🔒 隔离容器，不同应用或环境的数据互不干扰

Workspace 是顶层隔离单元。比如你可以为“客服机器人”创建一个工作区，为“个人助理”创建另一个工作区，两者的记忆完全隔离。

在 OpenClaw 集成中，默认工作区 ID 为 openclaw。

Peer 对等体

🧑‍🤝‍🧑 持久存在的实体——用户、智能体、对象、群组、想法……

Peer 是 Honcho 中最核心的概念。 每一个值得被记住的“存在”都是一个 Peer。它可以是：

• 一个真实的用户（你）
• 一个 AI 智能体（助手）
• 一个群组（多个 Peer 的集合）
• 甚至是一个“想法”或“项目”

每个 Peer 拥有独立的 表示（Representation），Honcho 通过推理不断更新这些表示，让它们越来越精准地反映实体的真实面貌。

💡 简单理解：Peer 就像 Honcho 给每个“角色”建立的一份动态档案，越用越懂你。

Session 会话

💬 Peer 之间的交互线程

Session 是 Peer 之间的一次连续对话，它有明确的时间边界：

• 一个 Peer 可以参与多个会话
• 多个 Peer 也可以在同一个会话中交互
• Session 是消息的容器，也是上下文检索的基本单位

比如你和一个 AI 助手在 WhatsApp 上聊天的整个过程，就是一个 Session。

Message 消息

📝 触发推理的数据单元

消息不只是“聊天内容”——它可以是：

• 对话中的一句话
• 一个系统事件（如“用户上传了文件”）
• 一条活动记录
• 一份文档或日志

当你向 Honcho 写入消息时，它们会被立即存储，并进入后台推理队列。这种设计保证了写入操作的快速响应，同时让推理能力在后台安静地运转。

推理引擎：Honcho 的大脑

🧠 从数据中提取洞察，而非仅仅存储数据

Honcho 不仅仅是一个“记忆数据库”。它的推理引擎会异步处理所有消息，提取显式信息、推导隐含结论、识别模式、并推断行为背后的原因。

推理引擎运作

推理引擎是 Honcho 最具特色的部分。它使用自定义训练的模型执行形式逻辑推理，整个过程可以拆解为四个层次：

#mermaid-svg-bfBOJuiKWBwlu74W{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bfBOJuiKWBwlu74W .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bfBOJuiKWBwlu74W .error-icon{fill:#552222;}#mermaid-svg-bfBOJuiKWBwlu74W .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bfBOJuiKWBwlu74W .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bfBOJuiKWBwlu74W .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bfBOJuiKWBwlu74W .marker.cross{stroke:#333333;}#mermaid-svg-bfBOJuiKWBwlu74W svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bfBOJuiKWBwlu74W p{margin:0;}#mermaid-svg-bfBOJuiKWBwlu74W .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-bfBOJuiKWBwlu74W .cluster-label text{fill:#333;}#mermaid-svg-bfBOJuiKWBwlu74W .cluster-label span{color:#333;}#mermaid-svg-bfBOJuiKWBwlu74W .cluster-label span p{background-color:transparent;}#mermaid-svg-bfBOJuiKWBwlu74W .label text,#mermaid-svg-bfBOJuiKWBwlu74W span{fill:#333;color:#333;}#mermaid-svg-bfBOJuiKWBwlu74W .node rect,#mermaid-svg-bfBOJuiKWBwlu74W .node circle,#mermaid-svg-bfBOJuiKWBwlu74W .node ellipse,#mermaid-svg-bfBOJuiKWBwlu74W .node polygon,#mermaid-svg-bfBOJuiKWBwlu74W .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bfBOJuiKWBwlu74W .rough-node .label text,#mermaid-svg-bfBOJuiKWBwlu74W .node .label text,#mermaid-svg-bfBOJuiKWBwlu74W .image-shape .label,#mermaid-svg-bfBOJuiKWBwlu74W .icon-shape .label{text-anchor:middle;}#mermaid-svg-bfBOJuiKWBwlu74W .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bfBOJuiKWBwlu74W .rough-node .label,#mermaid-svg-bfBOJuiKWBwlu74W .node .label,#mermaid-svg-bfBOJuiKWBwlu74W .image-shape .label,#mermaid-svg-bfBOJuiKWBwlu74W .icon-shape .label{text-align:center;}#mermaid-svg-bfBOJuiKWBwlu74W .node.clickable{cursor:pointer;}#mermaid-svg-bfBOJuiKWBwlu74W .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bfBOJuiKWBwlu74W .arrowheadPath{fill:#333333;}#mermaid-svg-bfBOJuiKWBwlu74W .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bfBOJuiKWBwlu74W .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bfBOJuiKWBwlu74W .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bfBOJuiKWBwlu74W .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bfBOJuiKWBwlu74W .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bfBOJuiKWBwlu74W .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bfBOJuiKWBwlu74W .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bfBOJuiKWBwlu74W .cluster text{fill:#333;}#mermaid-svg-bfBOJuiKWBwlu74W .cluster span{color:#333;}#mermaid-svg-bfBOJuiKWBwlu74W div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-bfBOJuiKWBwlu74W .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bfBOJuiKWBwlu74W rect.text{fill:none;stroke-width:0;}#mermaid-svg-bfBOJuiKWBwlu74W .icon-shape,#mermaid-svg-bfBOJuiKWBwlu74W .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bfBOJuiKWBwlu74W .icon-shape p,#mermaid-svg-bfBOJuiKWBwlu74W .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bfBOJuiKWBwlu74W .icon-shape .label rect,#mermaid-svg-bfBOJuiKWBwlu74W .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bfBOJuiKWBwlu74W .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bfBOJuiKWBwlu74W .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bfBOJuiKWBwlu74W :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

📤 输出

🧠 推理层

📥 输入

Messages消息队列

显式提取Explicit

演绎推理Deductive

归纳推理Inductive

溯因推理Abductive

Peer Card关键传记信息

整合去重/消歧

模式识别跨消息规律

行为解释最简推断

四种推理能力

推理生成的数据结构大致如下：

{
"explicit": [
{ "content": "用户说：我喜欢用 Python 写脚本" }
],
"deductive": [
{
"premises": ["用户喜欢 Python", "Python 用于脚本编程"],
"conclusion": "用户具备脚本编程经验"
}
]
}

Token 批处理机制

Honcho 不会对每条消息单独运行推理（那样成本太高）。相反，它采用 Token 批处理 策略：

🔄 当某个 Peer 的待处理消息累积到约 1,000 token 时，触发一次批量推理。

这样既保证了推理成本可控，又确保每次推理有足够的上下文量，使结论更准确。

安装指南

Honcho 的安装方式取决于你的使用场景。

OpenClaw 插件安装

面向 OpenClaw 用户，只需三步即可获得跨所有渠道（WhatsApp、Telegram、Discord、Slack……）的记忆能力：

# 1️⃣ 安装插件
openclaw plugins install @honcho-ai/openclaw-honcho

# 2️⃣ 运行设置向导（交互式配置 API 密钥、迁移现有文件）
openclaw honcho setup

# 3️⃣ 重启网关
openclaw gateway –force

# 卸载
openclaw plugins uninstall openclaw-honcho

💡 自托管提示：如果你使用本地 Honcho 实例，在 setup 提示输入 API Key 时直接回车留空，然后将 Base URL 设置为 http://localhost:8000。

独立 SDK 安装

如果你在构建自己的应用（非 OpenClaw），选择适合的包管理器：

安装后，访问 app.honcho.dev 注册账号获取 API Key。新用户可获得 $100 免费额度 🎁。

配置详解

OpenClaw 插件配置

配置位于 ~/.openclaw/openclaw.json 的 plugins.entries["openclaw-honcho"].config 下：

{
"plugins": {
"entries": {
"openclaw-honcho": {
"config": {
"apiKey": "your-api-key", // 托管模式必填；自托管时删除此字段
"workspaceId": "openclaw", // 记忆隔离的工作区 ID
"baseUrl": "https://api.honcho.dev" // API 端点地址
}
}
}
}
}

自托管配置

Honcho 可以完全运行在本地，无需任何外部 API 依赖：

# 1️⃣ 按照 Honcho 自托管指南部署本地实例
git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp docker-compose.yml.example docker-compose.yml
cp .env.template .env # fill in LLM_GEMINI_API_KEY / LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY
docker compose up

# 2️⃣ 运行设置向导，将 Base URL 指向本地服务器
openclaw honcho setup
# 输入空的 API Key，Base URL 设为 http://localhost:8000

如果github比较慢，可以使用镜像网站：

git clone https://gitclone.com/github.com/plastic-labs/honcho.git

⚠️ 注意：自托管实例不需要 API Key。将 baseUrl 指向本地服务器地址（如 http://localhost:8000），并省略 apiKey 字段。

OpenClaw 集成：

插件安装后，记忆能力会自动生效，无需手动干预。它通过三个机制协同工作：

#mermaid-svg-qgvjOwjSEuQa5Wpi{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-qgvjOwjSEuQa5Wpi .error-icon{fill:#552222;}#mermaid-svg-qgvjOwjSEuQa5Wpi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qgvjOwjSEuQa5Wpi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .marker.cross{stroke:#333333;}#mermaid-svg-qgvjOwjSEuQa5Wpi svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qgvjOwjSEuQa5Wpi p{margin:0;}#mermaid-svg-qgvjOwjSEuQa5Wpi .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster-label text{fill:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster-label span{color:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster-label span p{background-color:transparent;}#mermaid-svg-qgvjOwjSEuQa5Wpi .label text,#mermaid-svg-qgvjOwjSEuQa5Wpi span{fill:#333;color:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .node rect,#mermaid-svg-qgvjOwjSEuQa5Wpi .node circle,#mermaid-svg-qgvjOwjSEuQa5Wpi .node ellipse,#mermaid-svg-qgvjOwjSEuQa5Wpi .node polygon,#mermaid-svg-qgvjOwjSEuQa5Wpi .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .rough-node .label text,#mermaid-svg-qgvjOwjSEuQa5Wpi .node .label text,#mermaid-svg-qgvjOwjSEuQa5Wpi .image-shape .label,#mermaid-svg-qgvjOwjSEuQa5Wpi .icon-shape .label{text-anchor:middle;}#mermaid-svg-qgvjOwjSEuQa5Wpi .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .rough-node .label,#mermaid-svg-qgvjOwjSEuQa5Wpi .node .label,#mermaid-svg-qgvjOwjSEuQa5Wpi .image-shape .label,#mermaid-svg-qgvjOwjSEuQa5Wpi .icon-shape .label{text-align:center;}#mermaid-svg-qgvjOwjSEuQa5Wpi .node.clickable{cursor:pointer;}#mermaid-svg-qgvjOwjSEuQa5Wpi .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .arrowheadPath{fill:#333333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qgvjOwjSEuQa5Wpi .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-qgvjOwjSEuQa5Wpi .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qgvjOwjSEuQa5Wpi .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster text{fill:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi .cluster span{color:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qgvjOwjSEuQa5Wpi .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-qgvjOwjSEuQa5Wpi rect.text{fill:none;stroke-width:0;}#mermaid-svg-qgvjOwjSEuQa5Wpi .icon-shape,#mermaid-svg-qgvjOwjSEuQa5Wpi .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qgvjOwjSEuQa5Wpi .icon-shape p,#mermaid-svg-qgvjOwjSEuQa5Wpi .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-qgvjOwjSEuQa5Wpi .icon-shape .label rect,#mermaid-svg-qgvjOwjSEuQa5Wpi .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qgvjOwjSEuQa5Wpi .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-qgvjOwjSEuQa5Wpi .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-qgvjOwjSEuQa5Wpi :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

💾 存储

🧠 Honcho 记忆系统

🤖 OpenClaw 智能体

👤 用户交互

用户发送消息

AI 处理

生成回复

消息观察器持久化每轮对话

上下文注入器before_prompt_build 钩子

AI 工具集数据检索 + 问答

用户 Peer偏好·事实·风格

智能体 Peer个性·习得行为

双 Peer 模型

Honcho 为每次对话维护 两套独立表示：

• 用户 Peer：存储用户的偏好、事实、沟通风格
• 智能体 Peer：存储智能体的个性、习得行为

每个 OpenClaw 智能体拥有自己的 Honcho Peer（agent-{id}），多智能体工作区中各智能体的记忆保持隔离，互不干扰。

多智能体感知

OpenClaw 支持主智能体生成子智能体处理专门任务。Honcho 插件完全感知这一层次结构：

#mermaid-svg-Awi0wEoaBJFVYw0X{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Awi0wEoaBJFVYw0X .error-icon{fill:#552222;}#mermaid-svg-Awi0wEoaBJFVYw0X .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Awi0wEoaBJFVYw0X .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Awi0wEoaBJFVYw0X .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Awi0wEoaBJFVYw0X .marker.cross{stroke:#333333;}#mermaid-svg-Awi0wEoaBJFVYw0X svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Awi0wEoaBJFVYw0X p{margin:0;}#mermaid-svg-Awi0wEoaBJFVYw0X .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster-label text{fill:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster-label span{color:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster-label span p{background-color:transparent;}#mermaid-svg-Awi0wEoaBJFVYw0X .label text,#mermaid-svg-Awi0wEoaBJFVYw0X span{fill:#333;color:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X .node rect,#mermaid-svg-Awi0wEoaBJFVYw0X .node circle,#mermaid-svg-Awi0wEoaBJFVYw0X .node ellipse,#mermaid-svg-Awi0wEoaBJFVYw0X .node polygon,#mermaid-svg-Awi0wEoaBJFVYw0X .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Awi0wEoaBJFVYw0X .rough-node .label text,#mermaid-svg-Awi0wEoaBJFVYw0X .node .label text,#mermaid-svg-Awi0wEoaBJFVYw0X .image-shape .label,#mermaid-svg-Awi0wEoaBJFVYw0X .icon-shape .label{text-anchor:middle;}#mermaid-svg-Awi0wEoaBJFVYw0X .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Awi0wEoaBJFVYw0X .rough-node .label,#mermaid-svg-Awi0wEoaBJFVYw0X .node .label,#mermaid-svg-Awi0wEoaBJFVYw0X .image-shape .label,#mermaid-svg-Awi0wEoaBJFVYw0X .icon-shape .label{text-align:center;}#mermaid-svg-Awi0wEoaBJFVYw0X .node.clickable{cursor:pointer;}#mermaid-svg-Awi0wEoaBJFVYw0X .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Awi0wEoaBJFVYw0X .arrowheadPath{fill:#333333;}#mermaid-svg-Awi0wEoaBJFVYw0X .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Awi0wEoaBJFVYw0X .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Awi0wEoaBJFVYw0X .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Awi0wEoaBJFVYw0X .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Awi0wEoaBJFVYw0X .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Awi0wEoaBJFVYw0X .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster text{fill:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X .cluster span{color:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Awi0wEoaBJFVYw0X .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Awi0wEoaBJFVYw0X rect.text{fill:none;stroke-width:0;}#mermaid-svg-Awi0wEoaBJFVYw0X .icon-shape,#mermaid-svg-Awi0wEoaBJFVYw0X .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Awi0wEoaBJFVYw0X .icon-shape p,#mermaid-svg-Awi0wEoaBJFVYw0X .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Awi0wEoaBJFVYw0X .icon-shape .label rect,#mermaid-svg-Awi0wEoaBJFVYw0X .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Awi0wEoaBJFVYw0X .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Awi0wEoaBJFVYw0X .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Awi0wEoaBJFVYw0X :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

spawn

spawn

observeMe: falseobserveOthers: true

observeMe: falseobserveOthers: true

子会话 Session B

子智能体消息

子会话 Session A

子智能体消息

父会话 Session P

父智能体消息

父智能体 Peeragent-parent-001

子智能体 Peeragent-child-001

子智能体 Peeragent-child-002

• 自动检测：当 OpenClaw 生成子智能体时，插件通过 subagent_spawned 钩子跟踪父子关系
• 父作为观察者：父智能体被添加为子智能体 Honcho 会话中的静默观察者（observeMe: false, observeOthers: true）
• 完整可见性：父智能体可以看到子智能体的行为，但其自身消息不会被错误归入子会话

AI 工具集

Honcho 为智能体注册了两类工具，可在对话期间按需调用：

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

💬 问答（由 LLM 驱动）

🎯 工具选择原则：简单事实查询用检索工具，开放性问题用 honcho_ask。

CLI 命令

OpenClaw 提供了以下 Honcho 命令行工具：

迁移现有记忆

如果你已经在使用 OpenClaw 的工作区记忆文件（USER.md、MEMORY.md、IDENTITY.md、memory/、canvas/ 等），openclaw honcho setup 会检测并提供非破坏性迁移。

迁移映射

✅ 非破坏性保证：文件会被上传到 Honcho，但原始文件永远不会被删除或移动。平台元数据（对话信息、发送者头信息等）在保存前会被剥离，只保留有意义的正文内容。

SDK 编程使用

如果你在构建自定义 AI 应用，Honcho SDK 提供了完整的编程接口。以下是核心流程：

#mermaid-svg-XLlWgbbYeDlOTxrc{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XLlWgbbYeDlOTxrc .error-icon{fill:#552222;}#mermaid-svg-XLlWgbbYeDlOTxrc .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XLlWgbbYeDlOTxrc .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XLlWgbbYeDlOTxrc .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XLlWgbbYeDlOTxrc .marker.cross{stroke:#333333;}#mermaid-svg-XLlWgbbYeDlOTxrc svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XLlWgbbYeDlOTxrc p{margin:0;}#mermaid-svg-XLlWgbbYeDlOTxrc .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster-label text{fill:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster-label span{color:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster-label span p{background-color:transparent;}#mermaid-svg-XLlWgbbYeDlOTxrc .label text,#mermaid-svg-XLlWgbbYeDlOTxrc span{fill:#333;color:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc .node rect,#mermaid-svg-XLlWgbbYeDlOTxrc .node circle,#mermaid-svg-XLlWgbbYeDlOTxrc .node ellipse,#mermaid-svg-XLlWgbbYeDlOTxrc .node polygon,#mermaid-svg-XLlWgbbYeDlOTxrc .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XLlWgbbYeDlOTxrc .rough-node .label text,#mermaid-svg-XLlWgbbYeDlOTxrc .node .label text,#mermaid-svg-XLlWgbbYeDlOTxrc .image-shape .label,#mermaid-svg-XLlWgbbYeDlOTxrc .icon-shape .label{text-anchor:middle;}#mermaid-svg-XLlWgbbYeDlOTxrc .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XLlWgbbYeDlOTxrc .rough-node .label,#mermaid-svg-XLlWgbbYeDlOTxrc .node .label,#mermaid-svg-XLlWgbbYeDlOTxrc .image-shape .label,#mermaid-svg-XLlWgbbYeDlOTxrc .icon-shape .label{text-align:center;}#mermaid-svg-XLlWgbbYeDlOTxrc .node.clickable{cursor:pointer;}#mermaid-svg-XLlWgbbYeDlOTxrc .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XLlWgbbYeDlOTxrc .arrowheadPath{fill:#333333;}#mermaid-svg-XLlWgbbYeDlOTxrc .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XLlWgbbYeDlOTxrc .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XLlWgbbYeDlOTxrc .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XLlWgbbYeDlOTxrc .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XLlWgbbYeDlOTxrc .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XLlWgbbYeDlOTxrc .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster text{fill:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc .cluster span{color:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XLlWgbbYeDlOTxrc .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XLlWgbbYeDlOTxrc rect.text{fill:none;stroke-width:0;}#mermaid-svg-XLlWgbbYeDlOTxrc .icon-shape,#mermaid-svg-XLlWgbbYeDlOTxrc .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XLlWgbbYeDlOTxrc .icon-shape p,#mermaid-svg-XLlWgbbYeDlOTxrc .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XLlWgbbYeDlOTxrc .icon-shape .label rect,#mermaid-svg-XLlWgbbYeDlOTxrc .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XLlWgbbYeDlOTxrc .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XLlWgbbYeDlOTxrc .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XLlWgbbYeDlOTxrc :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

🔹 4. 查询推理

user.chat('关于这位用户我需要知道什么？')

📤 获得综合洞察

🔹 3. 会话与消息

创建 Sessionsession = honcho.session('id')

session.add_peers([user, assistant])

session.add_messages(messages)

🔹 2. 创建 Peer

user = honcho.peer('user')

assistant = honcho.peer('assistant')

🔹 1. 初始化

创建 Honcho 客户端传入 workspace_id + api_key

快速开始

from honcho import Honcho

# 1️⃣ 初始化客户端
honcho = Honcho(
workspace_id="my-workspace",
api_key="your-api-key"
)

# 2️⃣ 创建 Peer（为每个参与者创建）
user = honcho.peer("user-123")
assistant = honcho.peer("assistant-001")

# 3️⃣ 创建会话并添加消息
session = honcho.session("conversation-001")
session.add_peers([user, assistant])

messages = [
user.message("我登录账户时遇到了问题"),
assistant.message("我可以帮你。你看到了什么错误信息？"),
user.message("它说'凭据无效'，但我确定密码是对的")
]
session.add_messages(messages)

# 4️⃣ 查询推理结果
response = user.chat("关于这个用户，我需要知道什么？简要概括")
print(response)

⏱️ 处理延迟：Honcho 需要少量时间处理消息。可以通过 honcho.status() 方法检查队列状态。

获取上下文

context() 方法是从会话中检索格式化上下文的主要接口，可直接用于 LLM 集成：

# 基础用法
context = session.context()

# 限制 token 数量
context = session.context(tokens=1500)

# 包含用户表示，并进行语义搜索
context = session.context(
tokens=2000,
peer_target="user-123", # 包含该用户的表示
search_query="用户的编程偏好", # 语义搜索
search_top_k=10,
include_most_frequent=True,
max_conclusions=25
)

上下文参数一览

LLM 集成示例

SessionContext 对象提供了 to_openai() 和 to_anthropic() 方法，可无缝集成主流 LLM API：

import openai
from honcho import Honcho

honcho = Honcho()
openai_client = openai.OpenAI()

session = honcho.session("support-chat")
user = honcho.peer("user-123")
assistant = honcho.peer("support-bot")

# 添加对话历史
session.add_messages([
user.message("我登录账户遇到了问题"),
assistant.message("我可以帮你。你看到了什么错误信息？"),
user.message("它说'凭据无效'但我确定密码是对的")
])

# 获取上下文并转换为 OpenAI 格式
messages = session.context(tokens=2000).to_openai(assistant=assistant)

# 追加新用户消息
messages.append({"role": "user", "content": "你能重置我的密码吗？"})

# 调用 OpenAI
response = openai_client.chat.completions.create(
model="gpt-4",
messages=messages
)

# 将 AI 响应写回 Honcho
ai_response = response.choices[0].message.content
session.add_messages([assistant.message(ai_response)])

print(f"助手回复：{ai_response}")

Honcho vs 内置记忆 —— 对比一览

OpenClaw 默认通过工作区中的 Markdown 文件实现记忆。Honcho 提供了基于专用服务的替代方案，两者可以协同工作而非互斥。

高级用法：与 QMD 协同工作

Honcho 插件在配置了 QMD 记忆后端时，会自动暴露 memory_search 和 memory_get 工具，实现 Honcho 推理记忆 + QMD 本地文件检索 的双重能力。

// ~/.openclaw/openclaw.json
{
"memory": {
"backend": "qmd" // 启用 QMD 后端
}
}

配置完成后，你将同时拥有：

常见问题解决

openclaw honcho setup 报错：

[openclaw] Could not start the CLI.
[openclaw] Reason: Unknown command: openclaw honcho. No built-in command or plugin CLI metadata owns "honcho".
[openclaw] Debug: set OPENCLAW_DEBUG=1 to include the stack trace.
[openclaw] Try: openclaw doctor
[openclaw] Help: openclaw –help

使用如下命令查看：

openclaw plugins inspect openclaw-honcho 2>&1 | tail -30

如下图所示： 该插件当前处于禁用状态，原因是内存槽位已被内置的 memory-core 占用。Honcho 本身属于内存类插件，同一时间仅允许一个内存插件处于激活状态。 所以需要先关闭（禁用）memory-core插件。

✨ Honcho 的独特之处

Honcho 不是另一个“对话历史数据库”。它是一个 持续学习的推理系统，能够从对话中提取深层洞察。