honcho-integration

Honcho 集成指南

什么是 Honcho

Honcho 是一个用于构建有状态 Agent 的开源记忆库。它适用于任何模型、框架或架构。你将对话中的消息发送给 Honcho，自定义推理模型会在后台处理这些消息——提取前提、得出结论，并随着时间推移，为每位参与者构建丰富的表示。随后，你的 Agent 可以按需查询这些表示（“这个用户关心什么？”“这个人有多懂技术？”），并获得有依据、经过推理的回答。

关键的思维模型：Peer 是任何参与者——无论是人类还是 AI。两者都以相同的方式表示。observe_me 是一个 Peer 级别的标记（PeerConfig），用于控制 Honcho 是否为该 Peer 建立表示；通常，你希望 Honcho 对用户建模（observe_me=True），但不对任何具有确定性行为的对象建模（observe_me=False）。observe_others 是一个独立的、针对每个 Peer 的 SessionPeerConfig 设置，用于控制该 Peer 是否为会话中的其他参与者建立表示。Session 用于划定 Peer 之间的对话范围。Message 是你提供的原始数据——Honcho 会异步推理这些消息，并将结果存储为 Peer 的表示。没有消息，就没有推理，也就没有记忆。

你的 Agent 可通过 peer.chat(query)（提出自然语言问题并获取经过推理的回答——实时推理需要几秒）或 session.context()（近乎即时地读取格式化历史记录和表示）访问这些记忆。每轮对话中提供依据时，优先使用 context()；需要经过推理的回答时，使用 chat()。

参考资料索引

按以下工作流操作。只有到达需要某份参考资料的步骤时，才阅读该文件：

当你要……	阅读
编写客户端、Peer 和 Session 的设置（初始化、Peer、Session、添加消息）	references/core-patterns.md
配置 AI 如何读取上下文（工具调用、预取、context()、流式传输）	references/agent-patterns.md
集成到 Bot 框架（nanobot、openclaw、picoclaw，……）	references/bot-frameworks.md + references/bot-frameworks/<framework>/

集成工作流

按顺序完成以下阶段：

阶段 1：探索代码库

在向用户提问之前，先探索代码库，了解以下内容：

1. 语言和框架：这是 Python 还是 TypeScript？使用了哪些框架（FastAPI、Express、Next.js 等）？
2. 现有的 AI/LLM 代码：搜索现有的 LLM 集成（OpenAI、Anthropic、LangChain 等）
3. 实体结构：找出用户、Agent、Bot 或其他交互实体
4. Session/对话处理：应用目前如何管理对话？
5. 消息流：消息在哪里发送和接收？请求/响应周期是怎样的？

使用 Glob 和 Grep 查找：

• 包含“openai”“anthropic”“llm”“chat”“message”的 **/*.py 或 **/*.ts 文件
• 用户/Session 模型或类型
• 处理聊天或对话端点的 API 路由

检测到 Bot 框架？ 如果代码库围绕 Agent 循环、工具注册表、Session 管理器和消息总线构建（例如 nanobot、openclaw、picoclaw），请阅读 references/bot-frameworks.md，了解针对框架的集成指南，并查看 references/bot-frameworks/<framework>/ 中的具体参考实现。

阶段 2：访谈（必需）

探索代码库后，使用 AskUserQuestion 工具来明确集成需求。提出以下问题（根据你在阶段 1 中了解到的信息调整）：

问题组 1 - 实体与 Peer

询问哪些实体应作为 Honcho Peer：

• header：“Peers”
• question：“哪些实体应由 Honcho 跟踪并为其建立表示？”
• 根据你发现的情况提供选项（例如：“仅最终用户”“用户 + AI 助手”“用户 + 多个 AI Agent”“包括第三方服务在内的所有参与者”）
• 如果有多个 AI Agent，请追加问题：是否应观察其中的任何 AI Peer？

问题集 2 — 集成模式

询问他们想如何使用 Honcho 上下文（各模式的实现请参阅 references/agent-patterns.md）：

• 标题：“模式”
• 问题：“你的 AI 应如何访问 Honcho 的用户上下文？”
• 选项：
  • “工具调用（推荐）” — “Agent 通过函数调用按需查询 Honcho”
  • “预获取” — “每次调用大模型前，使用预定义查询获取用户上下文”
  • “context()” — “在提示词中包含对话历史和表示”
  • “多种模式” — “针对不同用例组合使用多种方式”

问题集 3 — 会话结构

询问对话结构：

• 标题：“会话”
• 问题：“对话应如何映射到 Honcho 会话？”
• 根据他们的应用提供选项（例如：“每个聊天线程一个会话”、“每位用户一个会话”、“每个会话包含多位用户（群聊）”、“自定义会话逻辑”）

问题集 4 — 具体查询（如果使用预获取模式）

如果他们选择了预获取模式，询问哪些上下文信息很重要：

• 标题：“上下文”
• 问题：“应为 AI 获取哪些用户上下文？”
• multiSelect：true
• 选项：“沟通风格”、“专业水平”、“目标／优先事项”、“偏好”、“近期活动摘要”、“自定义查询”

阶段 3：实现

根据访谈答复实现集成：

1. 安装 SDK（参见安装）
2. 创建 Honcho 客户端初始化 — references/core-patterns.md §1
3. 为已识别的实体设置 Peer 创建 — references/core-patterns.md §2–3
4. 实现所选的集成模式 — references/agent-patterns.md
5. 在每次交流后添加消息存储 — references/core-patterns.md §4
6. 更新任何现有的对话处理程序

阶段 4：验证

• 如果可以使用 Honcho CLI，请运行 honcho doctor，在测试集成代码前确认连接正常
• 使用 honcho peer list 和 honcho peer chat，验证 Peers 存在，并且辩证端点可以独立于集成正常工作
• 确保所有消息交流都已存储到 Honcho
• 验证确定性机器人 Peer 设置了 observe_me=False；AI 助手 Peer 可以保持观察开启（对其建模没有问题）
• 检查整个代码库中的工作区 ID 是否一致
• 确认已记录 API 密钥的环境变量

---

开始之前

1. 检查最新的 SDK 版本：https://honcho.dev/docs/changelog/introduction.md

   • Python SDK：honcho-ai
   • TypeScript SDK：@honcho-ai/sdk

2. 获取 API 密钥：请用户从 https://app.honcho.dev 获取 Honcho API 密钥，并将其添加到环境中。

3. 使用 CLI 验证（可选，但建议）。如果用户已安装 Honcho CLI（uv install honcho-cli），可在编写任何集成代码前验证设置：

   honcho init          # persist API key + URL to ~/.honcho/config.json
   honcho doctor        # verify connectivity, config, workspace health
   honcho peer chat     # test the dialectic endpoint interactively
   

   这是在调试 SDK 代码前确认 API 密钥和 URL 正确的最快方式。

安装

Python（使用 uv）

uv add honcho-ai

TypeScript（使用 bun）

bun add @honcho-ai/sdk

Python 中的 SDK 默认采用同步模式（异步命名空间为 .aio），而 TypeScript 中仅支持异步模式 — 请根据你的框架选择相应的客户端。完整的同步／异步指南以及基础客户端、Peer、会话和消息代码请参阅 references/core-patterns.md。

集成检查清单

将 Honcho 集成到现有代码库时：

• 使用 uv add honcho-ai（Python）或 bun add @honcho-ai/sdk（TypeScript）安装 SDK
• 设置 HONCHO_API_KEY 环境变量
• 使用单个工作区 ID 初始化 Honcho 客户端
• 为所有实体（用户和 AI 助手）创建 peer
• 为确定性机器人 peer 设置 observe_me=False（AI 助手可选——保留观察功能也没问题）
• 根据需要配置会话的 peer 观察设置
• 选择集成模式：
  • 面向 Agent 系统的工具调用模式
  • 面向简单集成的预取模式
  • 使用 context() 获取对话历史
• 每次交互后存储消息，以构建用户模型
• （可选）在测试集成代码前运行 honcho doctor 验证连接
• （可选）使用 honcho peer chat 独立测试辩证查询

应避免的常见错误

1. 使用多个工作区：每个应用使用一个工作区
2. 忘记 AI peer：为 AI 助手创建 peer，而不只是为用户创建
3. 对机器人建模：为确定性机器人设置 observe_me=False（脚本化输出——没有值得建模的内容）。AI 助手保留观察功能也没问题；只有在你只关心用户时，关闭观察才是可选的优化。
4. 不存储消息：始终调用 add_messages()，为 Honcho 的推理引擎提供数据
5. 等待处理完成：消息会异步处理——不要轮询或等待推理完成后再继续

资源

• 文档（适合大模型读取的索引）：https://honcho.dev/docs/llms.txt
• 最新 SDK 版本：https://honcho.dev/docs/changelog/introduction.md
• API 参考：https://honcho.dev/docs/v3/api-reference/introduction.md

提示：在任何 Honcho 文档 URL 后追加 .md，即可获取原始 Markdown 版本。