Honcho は、時間の経過とともに変化する人、エージェント、グループ、プロジェクト、アイデアを理解する、ステートフル・エージェントを構築するためのメモリ・インフラストラクチャです。

Honcho v3 入門 : README

作成 : クラスキャット・セールスインフォメーション
作成日時 : 08/17/2026
バージョン : Server 3.0.9

* 本記事は github.com/plastic-labs/honcho の以下のページを参考にしています :

README.md

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

Honcho v3 入門 : README

メッセージやイベントを保存し、Honcho にバックグラウンドで推論させて、それから、ピア表現、セッションコンテキスト、検索結果、あるいはあらゆるモデルやフレームワークからの自然言語による洞察をクエリできます。api.honcho.dev で管理されているものを使用することも、Fast API サーバーをセルフホストすることも可能です。

Honcho をメモリシステムとして活用することで、エージェントの保持率向上、信頼獲得、そして既存企業を打ち負かすデータによる優位性の構築が可能になります。

ℹ️ Honcho はエージェントメモリのパレート・フロンティアを定義しました。詳細については、ビデオをご覧になり、評価ページをご確認の上、ブログ記事をお読みください。

Honcho プロジェクトは複数のリポジトリに分かれており、このリポジトリにはコアサービス・ロジック – FastAPI サーバーとして実装 – がホストされています。Python と TypeScript 用のクライアント SDK は sdks/ ディレクトリにあります。

ここから始めましょう

(I want to… – パス – Get started)
コーディングエージェントに永続メモリを提供する – Claude Code, OpenCode, OpenClaw, Hermes, or 任意の MCP クライアント – 統合
製品にメモリを追加する – Python or TypeScript SDK – クイックスタート
セルフホスト Honcho – Docker / ローカル開発 – セルフホスト

Why Honcho

推論ファーストなメモリ – 単に会話の断片を照合するだけでなく、会話や出来事から結論を抽出します。
ピア中心モデル – ユーザー、エージェント、グループ、プロジェクト、アイデアを、時間の経過とともに変化するエンティティとして追跡します。
複数のピアの視点 (perspective) – 設定時に、一方のピアが他方のピアについて何を知っているかをモデル化します。
マネージド型 or セルフホスト型 – api.honcho.dev を使用するか、FastAPI サーバーをユーザ自身で実行できます。
エージェントツール統合 – MCP, Claude Code, OpenCode, OpenClaw, Hermes, Cursor-互換クライアント.

Honcho ループ

会話、イベント、ドキュメント、ツール・トレースをセッション上のメッセージとして保存 (store) します。
推論 — Honcho はバックグラウンドでキューを処理し、ピア表現を更新します。
クエリ — Honcho にコンテキスト、検索結果、ピア表現、または自然言語による回答を問い合わせます。
注入 – 結果を任意の LLM 呼び出しまたはエージェントフレームワークに挿入します。

具体的には: ワークスペースはピアを保持し、ピアはセッションに参加し、メッセージはセッション上に保存され、そして Honcho はチャットエンドポイント経由または直接クエリを実行できるピアごとの表現を構築します。

クイックスタート

app.honcho.dev で API キーを取得してください – サインアップ時に組織への参加を促され、これは専用の Honcho インスタンスと $100 の無料クレジットが付与されます。または、セルフホストにより 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. ストア: セッション上のピアとメッセージ
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. 推論: バックグラウンドで非同期に行われます。

# 3. クエリー: 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. 注入: 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 }),
});

What Honcho Gives You

(Need – API)
インタラクション履歴の保存 – session.add_messages(…)
Honcho がピアについて何を知っているか尋ねる – 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(…)

See the full SDK Reference and API Reference.

統合

Claude Code

連携の深さに応じて、2つの方法があります :

プラグイン (より高度な統合 ― Claude Code ユーザーにおすすめ) :

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

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

Details: Claude Code guide · MCP guide.

Hermes

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

Details: Hermes guide.

コアコンセプト

Honcho は ピア (peers) – 人間も AI エージェントも同様にファーストクラスのエンティティ – を中心に構築されています。ピアモデルにより、以下のことが可能になります :

人間と AI エージェントが混在する複数参加者型セッション
設定可能な観察 (observation) 設定 (どのピアが他のどのピアを観察するか)
すべての参加者に対する柔軟な ID 管理
複雑なマルチエージェントインタラクションのサポート

セッション内でピア同士がメッセージを交換します; Honcho はこれらのメッセージにわたり推論して、クエリ可能な各ピアの表現を構築します。

ワークスペース : 最上位のコンテナ; ユースケース間でデータを分離します。
ピア (Peer) (旧称: ユーザー) : あらゆる参加者 – 人間のユーザーまたは AI エージェント。
セッション : 会話のコンテキスト; ピアとの多対多の関係 (many-to-many)。
メッセージ : 最小単位のデータ（ピア間通信または供給された (ingested) ドキュメントのチャンク）。

Honcho からクエリーできる情報 :

結論 — Honcho がピアについて抽出した情報 (演繹的および帰納的)。conclusions API を通じて公開されます。
表現 — Honcho がピアについて把握している情報の静的で低遅延なスナップショット (オプションでセッションスコープ)。
ピアカード — 簡潔なアイデンティティの概要。
セッションコンテキスト / 概要 — 長時間の会話に対応する、プロンプトに適したデータバンドル。

以上

月	火	水	木	金	土	日
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31