Honcho

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

メッセージやイベントを保存すると、Honcho がバックグラウンドで推論を行います。その後、どのモデルやフレームワークからでも、ピアの表現、セッションのコンテキスト、検索結果、自然言語によるインサイトをクエリできます。api.honcho.dev でマネージドサービスとして利用するか、honcho start でローカルスタックを起動するか、FastAPI サーバーを自分でセルフホストできます。

Honcho をメモリシステムとして使うことで、エージェントの継続利用率と信頼性を高め、既存企業との競争で優位に立つためのデータ優位性を築けます。

Honcho はエージェントメモリのパレートフロンティアを確立しました。詳しくは、動画をご覧いただき、評価ページを確認し、ブログ記事をお読みください。

目次

• まずはこちら
• Honcho を選ぶ理由
• Honcho のループ
• クイックスタート
• Honcho が提供するもの
• インテグレーション
• CLI
• 主要な概念
• ベンチマークと評価
• セルフホスト
• 設定
• アーキテクチャ
• SDK
• 詳細情報
• コントリビューション
• ライセンス

Honcho プロジェクトはいくつかのリポジトリに分かれており、このリポジトリには FastAPI サーバーとして実装されたコアサービスのロジックが含まれています。Python と TypeScript のクライアント SDK は sdks/ ディレクトリにあります。honcho-cli パッケージもここにあります。

まずはこちら

Honchoを選ぶ理由

Honchoのループ

1. 保存 — 会話、イベント、ドキュメント、ツールのトレースを、セッション上のメッセージとして保存します。
2. 推論 — Honcho がバックグラウンドでキューを処理し、ピアの表現を更新します。
3. クエリ — コンテキスト、検索結果、ピアの表現、または自然言語による回答を Honcho に尋ねます。
4. 注入 — 結果を任意の LLM 呼び出しやエージェントフレームワークに渡します。

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

クイックスタート

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 は、主要なコーディングエージェントすべてにファーストパーティのメモリープラグインを提供しています。どのプラグインも同じ ~/.honcho/config.json を読み込むため、1つのキーですべてを設定できます。また、2つのエージェントを同じ workspace に指定すれば、メモリーを共有できます。

app.honcho.dev でキーを取得し、honcho init（または uv tool install honcho-cli && honcho init）を実行すると、すべてのインテグレーションで使うキーが ~/.honcho/config.json に一度だけ書き込まれます。例外は Cursor と Grok Bot です。マーケットプレイスのプラグインは OAuth でサインインするため、これらでは honcho init は任意です（Cursor では実行すると自動キャプチャが有効になります）。

Claude Code

どこまで深く連携するかに応じて、2つの方法があります。

プラグイン（より高度な連携 — Claude Code ユーザーに推奨）：

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

生の MCP（Cursor、Cline、Windsurf など、あらゆる MCP クライアントで動作）：

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 の1つのリスティングで、どちらにも対応します。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 プラグインです。システムプロンプトにメモリを注入し、セッションイベントフィードから新しい情報を取り込みます。モデルは 3 つのツール（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 プラグインの 3 つは、すべて同じ Kilo サーバーを実行するため、1 回のインストールですべてに対応できます。 詳細：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 を追加する（エージェントスキル）

既存のアプリケーションに Honcho SDK を組み込むには、インテグレーションスキルをインストールしてください。コードベースを調査し、インテグレーションの設定について質問したうえで、SDK のセットアップを生成し、正常に動作することを検証します。

npx skills add plastic-labs/honcho

次に、Claude Code で /honcho-integration を実行します（または、プラグインマーケットプレイス経由で /honcho-dev:integrate を実行します）。同じコマンドでメモリスキルもインストールできます。honcho-memory（概念：想起／記録のループ、セッションとピアの戦略、MCP に接続された Honcho の接続方法と操作方法）と honcho-cli（デプロイメントの調査、または honcho start によるローカルスタックの実行）です。詳細：エージェント開発ガイド。

その他の 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 は、Honcho サーバーに対して CLI を認証します。honcho start --setup は別の手順で、ローカルのデリバーに必要な LLM プロバイダーキーを書き込み、API + デリバー + Postgres + Redis を起動します。

全コマンドとローカルスタックの詳細：CLI リファレンス · honcho-cli/README.md。ソースからサーバーを開発する方法については、セルフホストを参照してください。

コアコンセプト

Honcho はすべてを ピア を中心に構成しています。人間も AI エージェントも、対等なエンティティとして扱われます。ピアモデルにより、次のことが可能になります。

• 人間と AI エージェントが混在する、複数参加者のセッション
• 設定可能な観察設定（どのピアがほかのどのピアを観察するか）
• すべての参加者に対する柔軟な ID 管理
• 複雑なマルチエージェントのやり取りへの対応

ピアはセッション内でメッセージを交換し、Honcho はそれらのメッセージを推論して、クエリ可能な各ピアの表現を構築します。

• ワークスペース（以前は App）：最上位のコンテナで、ユースケース間のデータを分離します。
• ピア（以前は User）：人間のユーザーまたは AI エージェントなど、あらゆる参加者です。
• セッション：会話のコンテキストで、ピアと多対多の関係にあります。
• スコープ：セッションをグループ化する名前付きの単位で、想起（チャット、表現、検索）の対象をそのメンバーに限定します。
• メッセージ：ピア間のコミュニケーション、または取り込まれたドキュメントのチャンクを表す、原子的なデータ単位です。

Honcho に対してクエリできる情報は次のとおりです。

• 結論 — Honcho がピアについて抽出した情報（演繹的および帰納的）。結論 API を通じて利用できます。
• 表現 — Honcho がピアについて把握している内容を静的かつ低レイテンシで示すスナップショット（セッション単位でのスコープ指定も可能）。
• ピアカード — 簡潔な ID の要約です。
• セッションのコンテキスト／要約 — 長期的な会話ですぐにプロンプトに利用できる情報のまとまりです。

ベンチマークと評価

Honcho の評価では、LongMemEval、LoCoMo、その他の長期会話ベンチマークを扱っています。手法と再現可能な結果については、評価ページ、研究ブログ記事、パレートフロンティアの発表動画をご覧ください。

セルフホスト

Honcho は AGPL-3.0 の下で公開されているオープンソースです。個人用インスタンスを 実行 するには、CLI（uv tool install honcho-cli）をインストールし、honcho start --setup を実行してください。以下の手順は、ソースからのビルド、コントリビュート、または CLI を使わないデプロイ向けです。

クイックスタート（ソースから、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 フックをインストールしてください。テストは push 時にのみ実行されるため、コミットが問題なくても push が問題ないとは限りません。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] です。任意の値は、__ を使ったネスト形式（DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL）の {SECTION}_{KEY} という名前の環境変数、またはアプリレベルの設定では {KEY} で上書きできます。

利用可能なすべてのオプションについては設定リファレンスを、環境変数の注釈付き一覧については .env.template を参照してください。

アーキテクチャ

Honcho は、Storage（ワークスペース、ピア、セッション、スコープ、メッセージ、内部コレクション）と Insights（推論、結論、表現、要約、チャットエンドポイント）の 2 つのサービスに分かれています。Storage は API 経由で同期的に処理されます。Insights は非同期で処理され、バックグラウンドキューを介して deriver ワーカープロセスが実行します。

主な機能：

• 高度な推論システム — インタラクションから結論を抽出し、ピアの包括的な表現を構築する複数の実装方式
• チャットエンドポイント — 結論と現在のコンテキストを統合した、推論に基づく応答
• バックグラウンド処理 — 表現の更新やセッションの要約など、負荷の高い操作を非同期で処理するパイプライン
• マルチプロバイダー対応 — ユースケースに応じて設定できる LLM プロバイダー

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 の下でライセンスされています。詳しくはライセンスファイルをご覧ください。