Honcho

Honcho 是用于构建有状态 Agent 的记忆基础设施，能帮助它们随着时间推移理解不断变化的人、Agent、群体、项目和想法。

存储消息和事件，让 Honcho 在后台进行推理，然后从任意模型或框架查询同伴表征、会话上下文、搜索结果或自然语言洞见。可通过 api.honcho.dev 使用托管服务，使用 honcho start 启动本地服务栈，也可以自行自托管 FastAPI 服务。

将 Honcho 用作记忆系统，可提高 Agent 的留存率和信任度，并帮助你构建数据壁垒，超越现有竞争者。

Honcho 定义了 Agent 记忆的帕累托前沿。观看视频，查看我们的评测页面，并阅读博客文章了解详情。

目录

• 从这里开始
• 为什么选择 Honcho
• Honcho 循环
• 快速入门
• Honcho 能为你做什么
• 集成
• CLI
• 核心概念
• 基准测试与评测
• 自托管
• 配置
• 架构
• SDK
• 了解更多
• 贡献
• 许可证

Honcho 项目分布在多个仓库中，本仓库包含核心服务逻辑，以 FastAPI 服务的形式实现。Python 和 TypeScript 客户端 SDK 位于 sdks/ 目录中。honcho-cli 包也位于此处。

从这里开始

为什么选择 Honcho

Honcho 工作循环

1. 存储 — 将对话、事件、文档或工具轨迹作为消息存储在会话中。
2. 推理 — Honcho 在后台处理队列并更新 Peer 表征。
3. 查询 — 向 Honcho 查询上下文、搜索结果、Peer 表征或自然语言回答。
4. 注入 — 将结果传入任意大模型调用或 Agent 框架。

具体来说：工作区包含 Peer，Peer 参与会话，消息存储在会话中，而 Honcho 会为每个 Peer 构建表征，你可以通过聊天端点或直接查询该表征。

快速开始

在 app.honcho.dev 获取 API 密钥——注册时系统会提示你加入一个组织，该组织将拥有专属的 Honcho 实例。或者安装 CLI 并运行 honcho start --setup，然后将 SDK 指向 http://localhost:8000。

Python

pip install honcho-ai
# or: uv add honcho-ai
# or: poetry add honcho-ai

import os
from honcho import Honcho

# Managed service uses api.honcho.dev by default. For self-hosted, pass
# base_url="http://localhost:8000" or set HONCHO_URL.
honcho = Honcho(
    workspace_id="my-app-testing",
    api_key=os.environ["HONCHO_API_KEY"],
)

# 1. Store: peers and messages on a session
alice = honcho.peer("alice")
tutor = honcho.peer("tutor")
session = honcho.session("session-1")
session.add_messages([
    alice.message("Hey there — can you help me with my math homework?"),
    tutor.message("Absolutely. Send me your first problem!"),
])

# 2. Reason: happens asynchronously in the background.

# 3. Query: ask Honcho what it knows, or pull prompt-ready context.
answer = alice.chat("What learning styles does the user respond to best?")
context = session.context(summary=True, tokens=10_000)

# 4. Inject: hand the context to your model of choice.
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

npm install @honcho-ai/sdk
# or: bun add @honcho-ai/sdk

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

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 });

const openai = new OpenAI();
const completion = await openai.chat.completions.create({
  model: process.env.OPENAI_MODEL ?? "gpt-4o-mini",
  messages: context.toOpenAI({ assistant: tutor }),
});

注意： 后台推理是异步的。新添加的消息可能需要片刻才会反映在聊天／表征响应中；若要进行低延迟读取，请使用 representation 端点。

Honcho 能为你提供什么

查看完整的 SDK 参考和 API 参考。

集成

Honcho 为所有主流编码 Agent 提供官方记忆插件。它们都读取同一个 ~/.honcho/config.json，因此只需配置一个密钥即可供所有插件使用；将两个插件指向同一个 workspace，它们就能共享记忆。

在 app.honcho.dev 获取密钥，然后运行 honcho init（或 uv tool install honcho-cli && honcho init），即可将密钥写入 ~/.honcho/config.json，供所有集成使用。Cursor 和 Grok Bot 例外：Marketplace 插件通过 OAuth 登录，在这两种情况下 honcho init 都是可选的（在 Cursor 中运行它会开启自动捕获）。

Claude Code

可通过以下两种方式集成，具体取决于你希望集成得多深入：

插件（集成更丰富——推荐 Claude Code 用户使用）：

/plugin marketplace add plastic-labs/claude-honcho
/plugin install honcho@honcho

原生 MCP（适用于任何 MCP 客户端，例如 Cursor、Cline、Windsurf 等）：

claude mcp add honcho \
  --transport http \
  --url "https://mcp.honcho.dev" \
  --header "Authorization: Bearer hch-your-key-here" \
  --header "X-Honcho-User-Name: YourName"

详情：Claude Code 指南 · MCP 指南 · 仓库。

Codex

npm install -g @honcho-ai/codex-honcho
codex-honcho install      # registers hooks + MCP + skill in ~/.codex

重启 Codex 以加载钩子。详情：Codex 指南 · 仓库。

Cursor 和 Grok Bot

两者共用一个 Cursor Marketplace 列表。在 Cursor 中，打开 Customize，安装 Honcho，通过身份验证连接 honcho MCP 服务，然后运行一次 /honcho-setup。在 Grok Bot 中，在 Connect apps 下添加 Honcho（或在插件页面点击 Add to Grok Bot），然后让一个 Bot 设置 Honcho。该插件通过 OAuth 连接到托管的 MCP 服务，并附带用于驱动记忆循环的技能，因此无需在本地运行任何内容。 详情：Cursor 指南 · Grok Bot 指南 · 源代码。

DeepSeek Harness

dsh plugin --profile <name> add @honcho-ai/dsh-honcho

这是一个原生 Cordis 插件。它会将记忆注入系统提示词，并从会话事件流中捕获新信息。模型可使用三个工具：honcho_search、honcho_chat 和 honcho_remember；你可以运行 /honcho 查看状态。 详情：DeepSeek Harness 指南 · 代码仓库。

OpenCode

opencode plugin "@honcho-ai/opencode-honcho" --global

详情：OpenCode 指南 · 代码仓库。

Kilo Code

kilo plugin @honcho-ai/kilo-honcho --global

一次安装即可支持 Kilo CLI、VS Code 扩展和 JetBrains 插件，因为这三者运行的都是同一个 Kilo 服务。 详情：Kilo Code 指南 · 源代码。

OpenClaw

openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force

openclaw honcho setup 会提示你输入 API 密钥、写入配置，并可选择将旧版 MEMORY.md / USER.md / IDENTITY.md 文件迁移到 Honcho（不会造成破坏——绝不会删除原文件）。详情：OpenClaw 指南 · 代码仓库。

Hermes

hermes memory setup   # select "honcho", point at api.honcho.dev or your local server

详情：Hermes 指南。

将 Honcho 添加到你自己的代码库（Agent 技能）

要将 Honcho SDK 接入现有应用，请安装集成技能——它会探索你的代码库，询问集成偏好，生成 SDK 配置，并验证其是否正常工作：

npx skills add plastic-labs/honcho

然后在 Claude Code 中调用 /honcho-integration（或通过插件市场调用 /honcho-dev:integrate）。同一命令还会安装记忆技能——honcho-memory（相关概念：回忆/记录循环、会话和 peer 策略，以及如何连接和驱动由 MCP 连接的 Honcho）和 honcho-cli（检查部署，或使用 honcho start 运行本地堆栈）。详情：Agentic 开发指南。

其他 MCP 客户端

相同的 claude mcp add 格式（或各客户端对应的格式）适用于任何兼容 MCP 的客户端。请参阅 MCP 指南。

CLI

honcho-cli 可在终端检查 Honcho 部署，也可使用 Docker 运行个人本地堆栈。

uv tool install honcho-cli
honcho init                 # Honcho API key or browser login + server URL
honcho start --setup basic  # local stack: LLM provider key + Docker
honcho doctor

honcho init 会对 CLI 进行身份验证，使其连接到 Honcho 服务。honcho start --setup 是单独的步骤：它会写入本地 deriver 所需的大模型提供商密钥，并启动 API + deriver + Postgres + Redis。

完整命令和本地堆栈详情：CLI 参考 · honcho-cli/README.md。要从源代码开发服务端，请参阅自托管。

核心概念

Honcho 围绕 peer 组织一切——人类和 AI Agent 都是平等的一等实体。peer 模型支持：

• 包含人类和 AI Agent 的多参与者会话
• 可配置的观察设置（哪些 peer 观察哪些其他 peer）
• 灵活管理所有参与者的身份
• 支持复杂的多 Agent 交互

peer 在会话中交换消息；Honcho 会基于这些消息进行推理，构建每个 peer 的表征，供你查询。

• Workspace（原名 App）：顶层容器；隔离不同用例的数据。
• Peer（原名 User）：任意参与者——人类用户或 AI Agent。
• Session：对话上下文；与 peer 是多对多关系。
• Scope：用于对会话进行命名分组的范围，将回忆（聊天、表征、搜索）限制在组内成员。
• Message：原子数据单元（peer 间通信或导入的文档片段）。

你可以从 Honcho 查询：

• 结论——Honcho 提取出的有关某个 peer 的信息（演绎和归纳）。通过结论 API提供。
• 表征——Honcho 对某个 peer 的认知快照，静态且延迟低（可按会话限定范围）。
• Peer Cards——精简的身份摘要。
• 会话上下文 / 摘要——可直接用于提示词的长时对话信息包。

基准测试和评估

Honcho 的评估涵盖 LongMemEval、LoCoMo 及其他长对话基准测试。有关方法和可复现的结果，请参阅 评估页面、研究博客文章和 Pareto 前沿公告视频。

自托管

Honcho 基于 AGPL-3.0 开源。要运行个人实例，请安装命令行工具（uv tool install honcho-cli），然后执行 honcho start --setup。以下路径适用于从源码构建、参与贡献或不使用命令行工具进行部署。

快速开始（从源码运行，使用 Docker）

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp docker-compose.yml.example docker-compose.yml
cp .env.template .env       # set LLM_OPENAI_API_KEY (see "LLM provider" below for OpenRouter etc.)
docker compose up

然后让 SDK 指向它：

honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")
# or: export HONCHO_URL=http://localhost:8000

git clone https://github.com/plastic-labs/honcho.git
cd honcho
uv sync

# Postgres and pgvector majors must match the distro's packaged version.
# Ubuntu 24.04:
sudo apt install postgresql-16 postgresql-16-pgvector
# Debian 12:
sudo apt install postgresql-15 postgresql-15-pgvector
# Other versions: add the PostgreSQL APT repo (apt.postgresql.org) first.

sudo -u postgres psql -c "CREATE ROLE honcho LOGIN PASSWORD 'honcho';"
sudo -u postgres createdb -O honcho honcho
sudo -u postgres psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS vector;"
sudo -u postgres psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"  # optional, speeds up message search

brew install postgresql@17 pgvector
brew services start postgresql@17

psql -d postgres -c "CREATE ROLE honcho LOGIN PASSWORD 'honcho';"
createdb -O honcho honcho
psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

cp .env.template .env

DB_CONNECTION_URI=postgresql+psycopg://honcho:honcho@localhost:5432/honcho
LLM_OPENAI_API_KEY=sk-...

LLM_OPENAI_API_KEY=sk-or-v1-...
DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
# ...repeat for DIALECTIC_LEVELS__*, SUMMARY_*, DREAM_*

python scripts/generate_jwt_secret.py

AUTH_JWT_SECRET=<generated_secret>

# Admin token (full access, no expiry)
uv run python scripts/generate_jwt.py --admin

# Admin token expiring in 24 hours
uv run python scripts/generate_jwt.py --admin --expires 24h

# Workspace-scoped token
uv run python scripts/generate_jwt.py --workspace my-workspace --expires 30d

# Capture a token for use in curl/scripts
TOKEN=$(uv run python scripts/generate_jwt.py --admin --print-only)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/v3/workspaces

uv run alembic upgrade head

uv run fastapi dev src/main.py                  # local development, reloads on code changes
uv run fastapi run --host 0.0.0.0 src/main.py   # on a server

uv run python -m src.deriver

贡献者：使用 uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push 安装 Git 钩子。测试只会在推送时运行，因此提交通过检查不代表推送也会通过。要部署到 Fly.io，请参阅自托管文档 → 在 Fly.io 上部署。

配置

Honcho 使用灵活的配置系统，同时支持 TOML 文件和环境变量。配置值按优先级顺序加载：环境变量 > .env 文件 > config.toml > 默认值。

复制示例文件即可开始：

cp config.toml.example config.toml

文件按子系统组织，包括 [app]、[db]、[auth]、[cache]、[llm]、[deriver]、[dialectic]、[summary]、[dream]、[peer_card]、[webhook]、[metrics]、[telemetry]、[vector_store] 和 [sentry]。任何值都可以通过名为 {SECTION}_{KEY} 的环境变量覆盖；嵌套项使用 __（DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL），应用级设置则只需使用 {KEY}。

请参阅配置参考，了解所有可用选项；也可参阅 .env.template，查看带注释的环境变量列表。

架构

Honcho 分为两项服务：存储（工作区、Peer、会话、范围、消息、内部集合）和洞察（推理、结论、表征、摘要、聊天端点）。存储通过 API 同步执行；洞察则通过后台队列异步执行，该队列由 deriver 工作进程消费。

主要功能：

• 丰富的推理系统 — 提供多种实现方法，从交互中提取结论，并构建全面的 Peer 表征
• 聊天端点 — 结合结论与当前上下文，生成基于推理的回复
• 后台处理 — 针对表征更新和会话摘要等高开销操作的异步处理管道
• 多提供商支持 — 可为不同用例配置大模型提供商

Workspaces
├── Peers ←──────────────────┐
│   ├── Sessions             │
│   └── (internal collections, keyed by observer/observed peer pair)
│                            │
├── Scopes ←─────────────────┤ (many-to-many with sessions)
│                            │
└── Sessions ←───────────────┤ (many-to-many with peers)
    ├── Peers ───────────────┘
    └── Messages (session-level)

• Python — PyPI 上的 honcho-ai · 源码位于 sdks/python/
• TypeScript — npm 上的 @honcho-ai/sdk · 源码位于 sdks/typescript/
• CLI — PyPI 上的 honcho-cli · 源码位于 honcho-cli/ · CLI 参考

SDK 的版本独立于服务进行管理。当前 SDK 版本彼此保持同步；上方的服务徽章显示已部署的服务版本。

如需了解完整的 API 功能，请参阅 SDK 参考；如需了解原始 HTTP API，请参阅 API 参考；可运行的演示请参阅各 SDK 的示例文件夹。

了解更多

• 开发者文档 — 完整的 API 功能、指南和集成。
• CLI 参考 — 本地技术栈、检查/调试命令和脚本编写。
• Plastic Labs 博客 — 项目的设计理念和历史。

贡献

仅维护者可提交拉取请求。 如果您发现错误或希望进行更改，请改为提交问题。如果您认为自己的工作属于例外情况，请在 Discord 中说明理由；维护者大多活跃于此。

请参阅 CONTRIBUTING.md，了解完整流程、架构概览，以及修改内容对应位置的指南。有关漏洞，请参阅 SECURITY.md——请注意，Honcho 不提供漏洞赏金计划。

许可证

Honcho 基于 AGPL-3.0 License 授权。详情请参阅许可证文件。