智能体记忆库 plastic-labs/honcho

Honcho 是记忆基础设施，用来构建有状态的智能体。这些智能体能理解不断变化的人、智能体、群组、项目和想法。

存下消息和事件，让 Honcho 在后台推理，然后从任意模型或框架查询对等体表示、会话上下文、搜索结果，或自然语言洞察。你可以用托管服务 api.honcho.dev，也可以用 honcho start 跑本地栈，或者自己托管 FastAPI 服务器。

把 Honcho 当作记忆系统，你的智能体能获得更高的留存率、更多信任，还能帮你筑起数据护城河，在竞争中胜过现有对手。

Honcho 定义了智能体记忆的帕累托前沿。看视频，翻翻我们的评测页，再读博客文章了解细节。

目录

- 从这里开始
- 为什么选 Honcho
- Honcho 循环
- 快速上手
- Honcho 能给你什么
- 集成
- 命令行
- 核心概念
- 基准与评测
- 自托管
- 配置
- 架构
- SDK
- 了解更多
- 参与贡献
- 许可证

Honcho 项目拆成好几个仓库，这个仓库放核心服务逻辑——用 FastAPI 服务器实现。Python 和 TypeScript 的客户端 SDK 在 sdks/ 目录里。honcho-cli 包也在这里。

从这里开始

| 我想…… | 路径 | 怎么开始 |
| 给我的编码智能体加上持久记忆 | Claude Code、Cursor、Grok Bot、OpenCode、Kilo Code、OpenClaw、Hermes，或任意 MCP 客户端 | 集成 |
| 给产品加上记忆 | Python 或 TypeScript SDK | 快速上手 |
| 在本地运行 Honcho | 安装命令行，然后执行 honcho start --setup | 命令行 |
| 检查部署状态 | honcho workspace inspect、honcho doctor | 命令行 |
| 从源码自托管 | Docker Compose 或本地开发 | 自托管 |

为什么选 Honcho

| 能力 | 含义 |
| 推理优先的记忆 | 从对话和事件中提炼结论，不只是匹配文本片段。 |
| 以 peer 为中心的模型 | 把用户、智能体、群组、项目、想法都当作会随时间变化的实体来跟踪。 |
| 多 peer 视角 | 配置之后，可以建模一个 peer 对另一个 peer 的了解。 |
| 托管或自托管 | 用 api.honcho.dev、本地跑 honcho start，或者自己运行 FastAPI 服务器。 |
| 智能体工具集成 | MCP、Claude Code、Cursor、Grok Bot、OpenCode、Kilo Code、OpenClaw、Hermes。 |

Honcho 循环

1. 存储——把对话、事件、文档或工具调用记录作为消息存到会话上。
2. 推理——Honcho 在后台处理队列，更新 peer 表示。
3. 查询——向 Honcho 要上下文、搜索结果、peer 表示，或者一句自然语言回答。
4. 注入——把结果塞进任意 LLM 调用或智能体框架。

具体来说：工作区容纳 peer，peer 参与会话，消息挂在会话上，Honcho 为每个 peer 构建一份表示，你可以通过 Chat Endpoint 查询，也可以直接查。

快速上手

到 app.honcho.dev 拿 API key——注册时会提示你加入一个组织，该组织有自己专属的 Honcho 实例。或者安装命令行，执行 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：在后台异步进行。

3. Query：问 Honcho 它知道什么，或拉取可直接用于提示词的上下文。

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

4. Inject：把上下文交给你选用的模型。

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
bash
npm install @honcho-ai/sdk

or: bun add @honcho-ai/sdk

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

注意： 后台推理是异步的。新加入的消息可能要过一会儿才会反映到 chat/representation 响应里；需要低延迟读取时，请用 representation 端点。

Honcho 能给你什么

| 需求 | API |
| 保存交互历史 | session.add_messages(...) |
| 查询 Honcho 对某个 peer 的了解 | peer.chat(...) |
| 跨整个 workspace 查询 | honcho.chat(...) / honcho.chat_stream(...) |
| 获取可直接用于提示词的上下文 | session.context(...).to_openai(...) / .to_anthropic(...) |
| 混合搜索（BM25 + 向量） | peer.search(...), session.search(...), honcho.search(...) |
| 低延迟静态 representation | peer.representation(...), session.representation(...) |
| 导入文档 | session.upload_file(...) |
| 查看后台处理状态 | honcho.queue_status(...) |

完整内容见 SDK Reference 和 API Reference。

集成 Honcho 为各大主流编程智能体都提供了官方记忆插件。它们读取同一个 ~/.honcho/config.json，所以配置一个密钥就能全部生效——把两个智能体指向同一个 workspace，它们就共享同一份记忆。

| 智能体 | 安装方式 | 源码 |
| Claude Code | /plugin marketplace add plastic-labs/claude-honcho | claude-honcho |
| Codex | npm install -g @honcho-ai/codex-honcho | codex-honcho |
| Cursor | 从 Cursor Marketplace 安装 Honcho | integrations/cursor |
| Grok Bot | 在 Honcho 插件页面点 Add to Grok Bot | integrations/cursor |
| DeepSeek Harness | dsh plugin --profile <name> add @honcho-ai/dsh-honcho | dsh-honcho |
| OpenCode | opencode plugin "@honcho-ai/opencode-honcho" --global | opencode-honcho |
| Kilo Code | kilo plugin @honcho-ai/kilo-honcho --global | kilo-honcho |
| OpenClaw | openclaw plugins install @honcho-ai/openclaw-honcho | openclaw-honcho |
| Hermes | hermes memory setup | 上游内置 |
| 任意 MCP 客户端 | claude mcp add honcho --transport http ... | MCP 指南 |

到 app.honcho.dev 获取密钥，然后运行 honcho init（或 uv tool install honcho-cli && honcho init），它会把密钥写入 ~/.honcho/config.json，所有集成只需写一次。Cursor 和 Grok Bot 是例外：市场插件用 OAuth 登录，honcho init 在这两个地方可选（在 Cursor 里它会开启自动捕获）。

Claude Code

两种方式，看你想要多深的集成：

插件（集成更丰富——推荐 Claude Code 用户使用）： text /plugin marketplace add plastic-labs/claude-honcho /plugin install honcho@honcho

原生 MCP（适用于任意 MCP 客户端——Cursor、Cline、Windsurf 等）： bash
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
bash
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
bash
dsh plugin --profile <name> add @honcho-ai/dsh-honcho

原生 Cordis 插件。它把记忆注入系统提示词，并从会话事件流里抓取新信息。模型会拿到三个工具 —— honcho_search、honcho_chat 和 honcho_remember —— 你还可以运行 /honcho 查看状态。
详情：DeepSeek Harness 指南 · 仓库。

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

详情：OpenCode 指南 · 仓库。

Kilo Code
bash
kilo plugin @honcho-ai/kilo-honcho --global

装一次就覆盖 Kilo 命令行、VS Code 扩展和 JetBrains 插件，因为这三者跑的是同一个 Kilo 服务器。
详情：Kilo Code 指南 · 源码。

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

openclaw honcho setup 会提示你输入 API key，写入配置，并可选地把旧的 MEMORY.md / USER.md / IDENTITY.md 文件迁移进 Honcho（非破坏性 —— 原文件绝不删除）。详情：OpenClaw 指南 · 仓库。

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

详情：Hermes 指南。

把 Honcho 加进你自己的代码库（智能体技能）要把 Honcho SDK 接入现有应用，请安装集成技能。它会浏览你的代码库，询问集成偏好，生成 SDK 配置，并验证能否正常工作： bash
npx skills add plastic-labs/honcho

然后在 Claude Code 中调用 /honcho-integration（或通过插件市场调用 /honcho-dev:integrate）。同一条命令还会安装记忆技能：honcho-memory（概念包括 recall/record 循环、会话与 peer 策略，以及如何连接和驱动接入 MCP 的 Honcho）和 honcho-cli（检查部署，或用 honcho start 运行本地栈）。详情见 agentic development guide。

其他 MCP 客户端

同样的 claude mcp add 写法（或各客户端对应的等价写法）在任何兼容 MCP 的客户端中都能用。见 MCP guide。

命令行

honcho-cli 可以在终端里检查 Honcho 部署，也可以用 Docker 运行个人本地栈。
bash
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 让命令行针对 Honcho 服务器完成认证。honcho start --setup 是另一步：它写入本地 deriver 所需的 LLM 服务商密钥，并启动 API + deriver + Postgres + Redis。

完整命令与本地栈细节：CLI reference · honcho-cli/README.md。要从源码开发服务器，见自托管。

核心概念

Honcho 围绕 peer 组织一切：人类和 AI 智能体都是一等实体。peer 模型支持：

- 多参与者会话，人类与 AI 智能体混合参与
- 可配置的观察设置（哪些 peer 观察哪些其他 peer）
- 为所有参与者提供灵活的身份管理
- 支持复杂的多智能体交互

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

- Workspace（原 App）：顶层容器；隔离不同用例之间的数据。
- Peer（原 User）：任何参与者，人类用户或 AI 智能体。
- Session：会话上下文；与 peer 是多对多关系。
- Scope：会话的命名分组，把 recall（聊天、表示、搜索）限定在这些成员内。
- Message：原子数据单元（peer 间通信，或摄入的文档片段）。

你可以从 Honcho 查询的内容：

- Conclusions：Honcho 对某个 peer 提取出的结论（演绎与归纳）。通过 conclusions API 暴露。
- Representations：Honcho 对某个 peer 所知内容的静态、低延迟快照（可选按会话限定）。
- Peer Cards — 精简的身份摘要。
- 会话上下文 / 摘要 — 为长对话准备的、可直接用于提示词的打包内容。

内部存储（Collections 与 Documents）

在内部，Honcho 把与 peer 相关的观察结果存进 collections，每个 collection 由向量嵌入的 documents 组成。Collections 以 (observer, observed) peer 对为键——同一套机制既支撑自我表征（observer == observed），也支撑跨 peer 建模（peer X 对 peer Y 的理解）。这些底层原语不直接对外暴露；对外公开的接口是 Conclusions API。

基准测试与评测

Honcho 的评测覆盖 LongMemEval、LoCoMo 以及其他长对话基准。方法论与可复现结果见评测页面、研究博客文章和 Pareto-frontier 发布视频。

自托管

Honcho 以 AGPL-3.0 协议开源。想运行个人实例，先安装命令行（uv tool install honcho-cli），再执行 honcho start --setup。下面这些路径适用于从源码构建、参与贡献，或者不用命令行直接部署。

快速开始（从源码，Docker） bash
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 指向它： python
honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")

or: export HONCHO_URL=http://localhost:8000

不用 Docker（手动安装）

下面所有步骤都直接在宿主机上运行——不需要 Docker。你需要：

- uv（它会替你装好所需的 Python，3.13+）
- 带 pgvector 扩展的 PostgreSQL，本地或托管都行
- 任一 LLM 服务商的 API key

Redis 可选；缓存默认关闭（CACHE_ENABLED=false）。

1. 克隆并安装 bash
git clone https://github.com/plastic-labs/honcho.git
cd honcho
uv sync

2. 装好 PostgreSQL 和 pgvector

原生安装 Postgres 和 pgvector，然后创建 honcho 角色和数据库，并以超级用户身份在其中启用扩展。

Ubuntu/Debian 上： bash

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
其他版本：先添加 PostgreSQL APT 仓库（apt.postgresql.org）。

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;" # 可选，加快消息搜索

在 macOS 上，Homebrew 会把你的登录用户设为超级用户，所以去掉 sudo -u postgres：

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;"

托管 Postgres 只要支持 pgvector 也能用（Supabase、Neon、RDS 等）。在它的数据库里启用同样的扩展即可。

3. 配置 .env

cp .env.template .env

只有两项设置是必填的：

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

DB_CONNECTION_URI 必须使用 postgresql+psycopg 前缀（SQLAlchemy 的要求）。

LLM 服务商。 你只需要一个密钥，不用给每家厂商各配一个。所有功能默认使用 openai / gpt-5.4-mini，嵌入默认使用 openai / text-embedding-3-small。想用 OpenRouter 或其他兼容 OpenAI 的端点（Together、Fireworks、vLLM、Ollama、LiteLLM），就把该服务商的密钥填进 LLM_OPENAI_API_KEY，再在 .env 里为每个功能设置模型和 base URL：

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
...对 DIALECTIC_LEVELS__、SUMMARY_、DREAM_* 重复同样的设置

模型必须支持工具调用。如果你的服务商不提供嵌入，就把 EMBEDDING_MODEL_CONFIG__* 指向提供嵌入的服务商。每个功能对应的配置行见 .env.template，直接使用 Anthropic/Gemini 密钥以及混用服务商的方法见配置指南。

认证。 认证默认关闭（AUTH_USE_AUTH=false）。把服务器暴露到网络之前，先打开认证。启用认证需要一个 JWT 密钥，可以这样生成：

python scripts/generate_jwt_secret.py

这条命令会生成 JWT 密钥并打印到控制台。然后设置 AUTH_JWT_SECRET 环境变量。AUTH_USE_AUTH 依赖它：

AUTH_JWT_SECRET=<generated_secret>

启用认证后，本地开发和写脚本时可以用 scripts/generate_jwt.py 签发 token：

管理员 token（完全访问权限，永不过期）
uv run python scripts/generate_jwt.py --admin

24 小时后过期的管理员 token
uv run python scripts/generate_jwt.py --admin --expires 24h

限定工作区的 tokenbash
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

时长单位：s（秒）、m（分）、h（时）、d（天）、w（周）、y（年）。

4. 运行数据库迁移 bash
uv run alembic upgrade head

迁移会持有会话级 advisory lock，因此需要会话模式的连接（直连 Postgres 或会话池化器），不能用事务模式池化器。Supabase 风格的 :6543 端口会自动改写为 :5432。

5. 启动 Honcho

需要两个进程与数据库一起运行。

启动 API 服务器： bash
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

启动后台 worker（deriver）：

另开一个终端，运行： bash
uv run python -m src.deriver

deriver 负责生成表征、摘要、peer card，并管理 dreaming 任务。你可以增加 deriver 数量来提升运行效率。

验证步骤与生产环境注意事项，见 Self-hosting docs → Manual Setup。

贡献者：用 uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push 安装 git 钩子。测试只在 push 时运行，所以 commit 干净不代表 push 干净。部署到 Fly.io：见 Self-hosting docs → Deploying on Fly.io。

配置

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

复制示例文件即可开始： bash
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 拆成两个服务：Storage（工作区、peer、会话、scope、消息、内部集合）和 Insights（推理、结论、表示、摘要、chat 端点）。Storage 通过 API 同步处理；Insights 异步处理，走后台队列，由 deriver worker 进程消费。

核心特性：

- 丰富的推理系统 —— 多种实现方式，从交互中提取结论，为 peer 构建完整表示
- Chat 端点 —— 结合推理的响应，把结论与当前上下文融合
- 后台处理 —— 异步处理流水线，承接表示更新、会话摘要这类开销大的操作
- 多服务商支持 —— 可按不同用例配置 LLM 服务商

Storage 原语详解

Honcho 包含多种原语，用来存储应用数据和 peer 数据。这些数据用于管理对话、建模 peer 身份、构建 RAG 应用等。

Honcho 的理念是提供一个以 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)

关系细节：

- Workspace 包含多个 Peer 和 Scope。
- Peer 与 Session 是多对多关系（peer 可参与多个会话，会话可包含多个 peer）。
- Scope 与 Session 是多对多关系（一个会话可属于多个 scope；一个 scope 聚合多个会话）。
- Message 属于某个会话，按来源 peer 打标签。
- 向量嵌入 document 的内部集合以 (observer, observed) peer 对为键。它们不直接通过 API 暴露；其中存储的 observation 以 Conclusion 形式暴露。

熟悉 OpenAI Assistants API 等 API 的用户，对这里的大部分映射都不会陌生。

Workspaces

这是 Honcho 的顶层结构。开发者可以为不同助手、智能体、AI 功能等注册不同的 Workspace。它用来隔离不同用例的数据，并提供多租户能力。

Peers

在 Workspace 内，一切都围绕 Peer 展开。Peer 对象代表系统中的任意参与者——无论是人类用户还是 AI 智能体。这种统一模型支持复杂的多参与者交互。

Sessions
Session 对象表示 Workspace 内 Peers 之间的一组交互。其他应用可能把它叫作 thread 或 conversation。会话可以涉及多个 peer，观察设置可配置。创建会话时可以选择加入一个或多个 Scope，也可以之后通过 scopes API 加入。

Scopes

Scope 是 Workspace 内会话的命名分组。它是召回时的可见性边界：聊天、表示、会话上下文，以及通过 scope 回答的工作区搜索，都只能看到该 scope 成员会话中发生的内容。底层 peer 仍保留它们参与过的所有内容的统一表示。

开发者通过 scopes API（honcho.scope(...) /

honcho.scopes()) and an optional scopes field on session create — not
through observer/observed configuration. Adding a session that already has
messages copies its existing explicit conclusions into the scope (no
re-derivation); removing one reconciles those copies back out. Query
backfill progress with the scope status endpoint.

A single scope name answers from that scope's collection and card. A list of
scopes restricts recall to the union of their member sessions. Empty scopes
fail closed. scope is mutually exclusive with session / filters on the
same read.

Messages

The Message represents an atomic data unit that exists at the session level:
communication between peers within a session context. All messages are labelled
by their source peer and can be processed asynchronously to update their
representations. This flexible design allows for both conversational interactions
and broader data ingestion for personality modelling.

Reasoning pipeline

The reasoning functionality of Honcho is built on top of the Storage service. As
Messages and Sessions are created for Peers, Honcho will asynchronously
reason about peer psychology to derive facts about them and store them
in reserved internal collections.

A high level summary of the pipeline is as follows:

1. Messages are created via the API.
2. Derivation tasks are enqueued for background processing, including:
- representation: update representations of Peers.
- summary: create summaries of Sessions.
3. Session-based queue processing ensures proper ordering.
4. Results are stored internally and surfaced via the Conclusions API, Representations, Peer Cards, and the Chat Endpoint.

Retrieving data and insights

Honcho exposes several different ways to retrieve data from the system to best
serve the needs of any given application.

Get Context

In long-running conversations with an LLM, the context window can fill up
quickly. To address this, Honcho provides a context
endpoint that returns a combination of messages, conclusions, summaries from a
session up to a provided token limit.

Use this to keep sessions going indefinitely. If you'd like to see this in action, try out Honcho Chat.

Search

There are several search endpoints that let developers query messages at the
Workspace, Session, or Peer level using a hybrid search strategy.

Requests can include advanced filters to further refine
the results.

Chat API

The flagship interface for using these insights is the Chat Endpoint (POST /peers/{peer_id}/chat). It takes natural-language requests to get data about a peer and returns reasoning-grounded responses. Examples:

- Asking Honcho for a generic or specific insight about the peer.
- Asking Honcho to hydrate a prompt with data about the peer's behaviour.
- Asking Honcho for a second opinion on how to respond.
- Getting personalised responses that incorporate long-term facts and context.

Representations

For low-latency use cases, Honcho provides access to a representation endpoint that returns a static document with insights about a peer in the context of a particular session. Use this to quickly add context to a prompt without having to wait for an LLM response.

SDKs

- Python — honcho-ai on PyPI · source in sdks/python/
- TypeScript — @honcho-ai/sdk on npm · source in sdks/typescript/
- CLI — honcho-cli on PyPI · source in honcho-cli/ · CLI reference

SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version.

See the SDK Reference for full API surface, the API Reference for the raw HTTP API, and per-SDK example folders for runnable demos.

Learn More

- Developer documentation — full API surface, guides, integrations.
- CLI reference — local stack, inspect/debug commands, scripting.
- Plastic Labs blog — design philosophy and history of the project.

Contributing

Pull requests are limited to maintainers. If you find a bug or want a change, please open an issue instead. If you think your work is an exception, make the case in Discord, where maintainers are most active.

See CONTRIBUTING.md for the full process, an architecture walkthrough, and a map of where to change what. For vulnerabilities, see SECURITY.md — note that Honcho does not operate a bug bounty.

License

Honcho is licensed under the AGPL-3.0 License. Learn more at the License file.