plastic-labs/honcho · 上手攻略

  • 仓库：plastic-labs/honcho
  • 链接：https://github.com/plastic-labs/honcho
  • 分类：AI Agent · 记忆基础设施
  • 作者：Tom
  • 更新：2026-09-05

是什么

Honcho 是一个面向 AI Agent 的记忆基础设施库，帮助 Agent 在多轮对话、多个会话中保持持续理解能力。它不是简单的向量数据库，而是一个"推理优先"（reasoning-first）的记忆系统：能够从对话和事件中提炼结论，而不只是做相似 chunk 匹配。

核心定位：让 AI Agent 理解不断变化的人、Agent、群组、项目和想法，在时间维度上保持状态。

官方提供三种部署方式： - Managed 服务：api.honcho.dev（有 $100 免费额度） - 本地 CLI：honcho start --setup 一键启动本地服务 - 自托管：用 Docker Compose 或 FastAPI 服务自建

⚠️ 版本说明：GitHub badge 显示 Server 版本为 3.1.1（2026-09-04 采集），SDK 分别有 PyPI 和 NPM 版本。攻略内容以当前公开 README 为准，未实测。

解决什么问题

  1. Agent 缺乏长期记忆：每次新对话 Agent 都"失忆"，无法利用历史上下文
  2. 向量数据库只做匹配，不做推理：普通 RAG 找到相关 chunk，但不会总结"用户偏好什么"
  3. 多 Agent 共享上下文难：需要让多个 Agent（如 Coding Agent + Review Agent）共享对同一用户/项目的记忆
  4. 需要 Query 记忆而不是简单地检索：希望用自然语言问"这个用户上个月主要关注什么"，而不只是"找到相关文档"

快速安装

方式一：Managed 服务（最简）

pip install honcho-ai
# 或：uv add honcho-ai
# 或：poetry add honcho-ai

然后在 app.honcho.dev 注册获取 API Key。

方式二：本地 CLI（无云依赖）

pip install honcho-cli
honcho start --setup

这会启动一个本地 FastAPI 服务（默认 http://localhost:8000），SDK 指向该地址即可离线使用。

方式三：自托管（Docker）

git clone https://github.com/plastic-labs/honcho.git
cd honcho
docker-compose up

核心用法

Python SDK 基础四步

import os
from honcho import Honcho

# 连接（Managed 或本地）
honcho = Honcho(
    workspace_id="my-app-testing",
    api_key=os.environ["HONCHO_API_KEY"],
    # 自托管时：base_url="http://localhost:8000"
)

# 1. Store：创建 peers 和 session，存入消息
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("Absolutely! Send me your first problem!"),
])

# 2. Reason：（异步进行，Honcho 在后台处理队列并更新 peer 表征）

# 3. Query：用自然语言问 Honcho 关于某 peer 的理解
answer = alice.chat("What learning styles does the user respond to best?")

# 4. Inject：将记忆上下文注入 LLM 调用
context = session.context(summary=True, tokens=10_000)
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
    messages=context.to_openai(assistant=tutor),
)

TypeScript / Node.js SDK

import { Honcho } from "@honcho-ai/sdk";

const honcho = new Honcho({
  workspaceId: "my-app-testing",
  apiKey: process.env.HONCHO_API_KEY,
});

const alice = await honcho.peer("alice");
const tutor = await honcho.peer("tutor");
const session = await honcho.session("session-1");
await session.addMessages([
  alice.message("Hey there — can you help me with my math homework?"),
  tutor.message("Absolutely. Send me your first problem!"),
]);

const answer = await alice.chat("What learning styles does the user respond to best?");
const context = await session.context({ summary: true, tokens: 10_000 });

CLI 常用命令

# 启动本地服务
honcho start --setup

# 检查工作区状态
honcho workspace inspect

# 诊断连接问题
honcho doctor

核心 API 速查

需求 API
保存交互历史 session.add_messages(...)
询问 Honcho 对某 peer 的理解 peer.chat("...")
获取提示词就绪的上下文 session.context(...).to_openai(...) / .to_anthropic(...)
混合搜索（BM25 + 向量） peer.search(...) / session.search(...) / honcho.search(...)
低延迟静态表征 peer.representation(...) / session.representation(...)
上传文档 session.upload_file(...)
查看后台处理状态 honcho.queue_status(...)

典型适用场景

  • Coding Agent 持久记忆：Claude Code / OpenCode 安装 Honcho 插件后，对每个项目有独立记忆，跨会话理解项目上下文
  • 多 Agent 协作：多个 Agent 共享同一 workspace，对用户偏好有一致认知
  • 客服 / 助手产品：用 Honcho 替代简单对话历史，让 AI 真正理解用户
  • 多轮对话摘要：超出 context window 时用 session.context() 压缩历史
  • 混合搜索：结合 BM25 和向量检索，既有精确关键词匹配又有语义相似度

坑与注意

  1. 背景推理是异步的：session.add_messages() 后立即 query 可能读不到最新结果，需要短暂等待（或用 representation() 端点做低延迟读取）。

  2. 背景推理是 Honcho 的核心竞争力，也是黑盒：目前没有公开文档说明推理模型是什么、推理频率、更新延迟。生产环境使用需关注 queue_status() 的状态反馈。

  3. ⚠️ 自托管没有公开的 Docker Compose 完整配置：README 提到"Self-host from source · Docker Compose or local development"，但没有展示具体 docker-compose.yml 内容，实际自托管需参考源码。

  4. ⚠️ 推理质量无公开 Benchmark 细节：官方宣传"Pareto Frontier of Agent Memory"，但 blog post 的 eval 细节需进一步核实；攻略中不对其 benchmark 数字负责。

  5. workspace_id 是应用级隔离单位：一个 workspace 包含多个 peers 和 sessions，不同应用应使用不同 workspace_id。

  6. SDK API Key 需保密：Managed 服务使用 API Key，Key 管理方式需遵循应用安全最佳实践，不要硬编码到代码里。

  7. Claude Code 等 Agent 插件的安装方式：通过 Agent 插件市场安装（非 pip/npm），需要 Agent 本身支持 Skill/MCP 协议。

与同类对比

工具 类型 与 Honcho 的核心区别
MemGPT Agent 记忆层 MemGPT 关注 context window 管理；Honcho 关注跨会话 peer 表征与推理
Letta (Mem0 前身) Agent 记忆 功能最接近，但 Letta 更偏端到端 Agent 平台；Honcho 更轻量专注记忆
向量数据库（Chroma/Pinecone） 纯向量检索 只做相似匹配，不做推理和摘要；Honcho 是上层抽象
RAG + LLM 摘要 检索 + 生成 需要自己拼 prompt；Honcho 提供原生 to_openai() / to_anthropic() 格式转换
MCP + 上下文注入 协议 + 记忆 MCP 是工具调用协议；Honcho 是专门为 Agent 记忆优化的数据库 + 推理层

Honcho 的核心差异化：推理优先的记忆（不是检索优先）+ peer-centric 模型（不只是会话历史）+ 原生多 Agent 支持 + Managed / Local / Self-hosted 灵活选择。

一句话推荐结论

如果你在构建需要跨会话理解用户或项目状态的 AI Agent，Honcho 是目前最专门的记忆基础设施——推理优先而非检索优先，原生支持 peer 表征和多 Agent 共享，上手简单（pip install 即可连 Managed 服务），但后台推理黑盒程度需要生产环境验证。