plastic-labs/honcho

Honcho – 面向有状态 AI 代理的记忆基础设施

它是什么

• Honcho 是一个开源服务（FastAPI 服务器），用于存储和推理 AI 代理与人类（称为对等方）的消息、事件和文档。它构建每个对等方的表示，可查询为自然语言答案、摘要或向量搜索结果。该服务可用作托管云产品（api.honcho.dev），或通过 Docker 或本地 CLI 自行托管。

关键概念

概念	作用
工作区	顶层容器，用于隔离产品或团队的数据。
对等方	任何参与者 – 人类用户或 AI 代理 – 可以发送和接收消息。
会话	涉及一个或多个对等方的对话（或事件流）。
范围	会话的命名分组，限制搜索或表示的召回范围。
消息	数据的最小单元（聊天轮次、工具调用、文档块）。

工作原理 – Honcho 循环

1. 存储 – 通过 SDK 或 HTTP API 添加对等方、会话和消息。
2. 推理 – Honcho 在后台处理队列中的项目，提取结论并更新每个对等方的表示。
3. 查询 – 检索上下文、搜索结果、对等方表示或直接的自然语言答案。
4. 注入 – 将返回的数据馈送到任何 LLM 调用或代理框架中。

主要功能

• 推理优先的记忆 – 不仅仅是向量存储；Honcho 运行后台推理以生成关于对等方的结论。
• 以对等方为中心的模型 – 跟踪每个对等方对其他对等方的了解（观察者/被观察者配对）。
• 混合搜索 – 结合 BM25 关键词搜索与向量相似性。
• 低延迟静态表示 – 对等方知识的快照，可快速获取。
• 提示就绪的上下文 – 为 OpenAI、Anthropic 等格式化的摘要或完整对话历史。
• 多代理支持 – 会话可以包含人类和 AI 代理的任何组合。

开始使用

• 托管 – 在 https://app.honcho.dev 注册，获取 API 密钥，并开始使用 Python（honcho-ai）或 TypeScript（@honcho-ai/sdk）SDK。
• 本地 – 安装 CLI（uv tool install honcho-cli），运行 honcho start --setup，并将 SDK 指向 http://localhost:8000。
• 从源码自行托管 – 克隆仓库，复制 Docker compose 示例，提供 LLM 提供商密钥，并运行 docker compose up。

示例（Python）

from honcho import Honcho
import os

honcho = Honcho(
    workspace_id="my-app-testing",
    api_key=os.getenv("HONCHO_API_KEY"),
)

alice = honcho.peer("alice")
tutor = honcho.peer("tutor")
session = honcho.session("session-1")
session.add_messages([
    alice.message("Hey, can you help me with my math homework?"),
    tutor.message("Sure, send the first problem!"),
])

# Background reasoning runs automatically.
answer = alice.chat("What learning styles does the user respond to best?")
context = session.context(summary=True, tokens=10_000)

# Use the context with any LLM, e.g. OpenAI:
from openai import OpenAI
client = OpenAI()
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=context.to_openai(assistant=tutor),
)

集成 – 许多编码代理（Claude Code、Codex、Cursor、DeepSeek Harness、OpenCode、Kilo Code、OpenClaw、Hermes）以及任何 MCP 兼容客户端都有第一方插件。所有插件都读取共享的 ~/.honcho/config.json，因此一个 API 密钥可以为多个工具提供支持。

CLI – honcho-cli 允许您检查部署（honcho workspace inspect、honcho doctor）、运行本地堆栈以及管理配置。

基准测试 – Honcho 在 LongMemEval 和 LoCoMo 等长对话基准测试上报告结果，并有一篇研究博客文章和公开评估页面描述其帕累托前沿性能。

许可证 – AGPL-3.0（开源，可自行托管）。

---

底线 – Honcho 为需要随时间保留和推理交互的代理提供了专门构建的记忆层。它抽象了存储、后台推理和表示检索，让开发人员专注于构建跨会话记住用户和其他代理的代理、机器人或产品。