honcho-integration

Honcho 統合ガイド

Honcho とは

Honcho は、ステートフルなエージェントを構築するためのオープンソースのメモリライブラリです。あらゆるモデル、フレームワーク、アーキテクチャで動作します。会話のメッセージを Honcho に送信すると、カスタム推論モデルがバックグラウンドで処理し、前提を抽出し、結論を導き、時間の経過とともに各参加者の豊かな表現を構築します。エージェントはその後、必要に応じてこれらの表現を照会し（「このユーザーは何を大切にしていますか？」「この人の技術的な知識はどの程度ですか？」）、根拠に基づいた推論による回答を得られます。

重要なメンタルモデルは次のとおりです。Peer は、人間か AI かを問わず、あらゆる参加者を指します。どちらも同じ方法で表現されます。observe_me はピアレベルのフラグ（PeerConfig）で、そのピアの表現を Honcho が作成するかどうかを制御します。通常、ユーザーは Honcho にモデル化させ（observe_me=True）、決定論的な動作をするものはモデル化させないようにします（observe_me=False）。observe_others は、別個のピアごとの SessionPeerConfig 設定で、そのピアがセッション内の他の参加者の表現を作成するかどうかを制御します。Session はピア間の会話の範囲を定めます。Message は入力する生データです。Honcho はそれらを非同期で推論し、その結果をピアの表現として保存します。メッセージがなければ、推論もメモリもありません。

エージェントは peer.chat(query)（自然言語で質問し、推論による回答を得る — 数秒間のライブ推論）または session.context()（書式化された履歴と表現をほぼ瞬時に読み取る）を通じて、このメモリにアクセスします。ターンごとのグラウンディングには context() を優先し、推論による回答が必要な場合は chat() を使用してください。

リファレンスマップ

以下のワークフローに従ってください。必要なステップに進んだときにのみ、該当するリファレンスファイルを読んでください。

次の作業を行うとき…	読むファイル
クライアント／ピア／セッションのセットアップ（初期化、ピア、セッション、メッセージの追加）を書く	references/core-patterns.md
AI がコンテキストを読み取る方法（ツール呼び出し、事前取得、context()、ストリーミング）を組み込む	references/agent-patterns.md
ボットフレームワーク（nanobot、openclaw、picoclaw など）に統合する	references/bot-frameworks.md + references/bot-frameworks/<framework>/

統合ワークフロー

以下のフェーズを順番に進めてください。

Phase 1: コードベースの調査

ユーザーに質問する前に、コードベースを調べて次の点を把握してください。

1. 言語とフレームワーク：Python と TypeScript のどちらですか？どのフレームワーク（FastAPI、Express、Next.js など）を使用していますか？
2. 既存の AI／LLM コード：既存の LLM 統合（OpenAI、Anthropic、LangChain など）を検索します
3. エンティティ構造：ユーザー、エージェント、ボット、その他のやり取りを行うエンティティを特定します
4. セッション／会話の処理：アプリは現在、会話をどのように管理していますか？
5. メッセージの流れ：メッセージはどこで送受信されていますか？リクエスト／レスポンスのサイクルはどのようになっていますか？

Glob と Grep を使用して、次の項目を見つけてください。

• "openai"、"anthropic"、"llm"、"chat"、"message" を含む **/*.py または **/*.ts ファイル
• ユーザー／セッションのモデルまたは型
• チャットや会話のエンドポイントを処理する API ルート

ボットフレームワークが検出されましたか？ コードベースがエージェントループ、ツールレジストリ、セッションマネージャー、メッセージバスを中心に構築されている場合（例：nanobot、openclaw、picoclaw）、フレームワーク固有の統合ガイダンスについて references/bot-frameworks.md を読み、具体的なリファレンス実装について references/bot-frameworks/<framework>/ を確認してください。

Phase 2: ヒアリング（必須）

コードベースを調査した後、AskUserQuestion ツールを使用して統合要件を明確にしてください。次の質問をします（Phase 1 で把握した内容に応じて調整してください）。

質問セット 1 - エンティティとピア

どのエンティティを Honcho のピアにするかを尋ねます。

• header: "Peers"
• question: "Honcho に追跡させ、表現を構築させるエンティティはどれですか？"
• 調査結果に基づく選択肢（例：「エンドユーザーのみ」、「ユーザー + AI アシスタント」、「ユーザー + 複数の AI エージェント」、「サードパーティサービスを含むすべての参加者」）
• 複数の AI エージェントがある場合は、AI ピアを観察対象にするものがあるか、追加で尋ねます

質問セット 2 - 統合パターン

Honcho のコンテキストをどのように使用するかを尋ねます（各パターンの実装については references/agent-patterns.md を参照してください）。

• ヘッダー：「パターン」
• 質問：「AI に Honcho のユーザーコンテキストへどのようにアクセスさせますか？」
• 選択肢：
  • 「ツール呼び出し（推奨）」 - 「エージェントが関数呼び出しを介して、必要に応じて Honcho に問い合わせる」
  • 「事前取得」 - 「あらかじめ定義したクエリを使い、各 LLM 呼び出しの前にユーザーコンテキストを取得する」
  • 「context()」 - 「会話履歴と表現をプロンプトに含める」
  • 「複数のパターン」 - 「ユースケースに応じて複数のアプローチを組み合わせる」

質問セット 3 - セッション構造

会話の構造について尋ねます。

• ヘッダー：「セッション」
• 質問：「会話を Honcho のセッションにどのように対応付けますか？」
• アプリに応じた選択肢（例：「チャットスレッドごとに 1 つのセッション」、「ユーザーごとに 1 つのセッション」、「1 つのセッションに複数ユーザー（グループチャット）」、「カスタムセッションロジック」）

質問セット 4 - 特定のクエリ（事前取得パターンを使用する場合）

事前取得を選択した場合は、どのコンテキストが重要かを尋ねます。

• ヘッダー：「コンテキスト」
• 質問：「AI が取得するユーザーコンテキストは何ですか？」
• multiSelect: true
• 選択肢：「コミュニケーションスタイル」、「専門知識のレベル」、「目標／優先事項」、「好み」、「最近のアクティビティの概要」、「カスタムクエリ」

フェーズ 3：実装

インタビューの回答に基づいて、統合を実装します。

1. SDK をインストールします（インストールを参照）
2. Honcho クライアントの初期化を作成します — references/core-patterns.md §1
3. 特定したエンティティ用のピア作成を設定します — references/core-patterns.md §2–3
4. 選択した統合パターンを実装します — references/agent-patterns.md
5. やり取りの後にメッセージを保存する処理を追加します — references/core-patterns.md §4
6. 既存の会話ハンドラーを更新します

フェーズ 4：検証

• Honcho CLI を利用できる場合は、統合コードをテストする前に honcho doctor を実行して接続を確認します
• honcho peer list と honcho peer chat を使い、ピアが存在すること、および統合とは独立してダイアレクティックエンドポイントが動作することを確認します
• すべてのメッセージのやり取りが Honcho に保存されていることを確認します
• 決定論的なボットピアでは observe_me=False が設定されていることを確認します。AI アシスタントのピアでは観察を有効にしたままにできます（モデル化しても問題ありません）
• ワークスペース ID がコードベース全体で一貫していることを確認します
• API キーの環境変数が文書化されていることを確認します

---

始める前に

1. 最新の SDK バージョンを確認します：https://honcho.dev/docs/changelog/introduction.md

   • Python SDK：honcho-ai
   • TypeScript SDK：@honcho-ai/sdk

2. API キーを取得します。ユーザーに https://app.honcho.dev から Honcho API キーを取得し、環境に追加するよう依頼します。

3. CLI で確認します（任意ですが推奨）。ユーザーが Honcho CLI をインストールしている場合（uv install honcho-cli）、統合コードを書く前にセットアップを検証できます。

   honcho init          # persist API key + URL to ~/.honcho/config.json
   honcho doctor        # verify connectivity, config, workspace health
   honcho peer chat     # test the dialectic endpoint interactively
   

   これは、SDK コードのデバッグを始める前に API キーと URL が正しいことを確認する最も手早い方法です。

インストール

Python（uv を使用）

uv add honcho-ai

TypeScript（bun を使用）

bun add @honcho-ai/sdk

Python の SDK はデフォルトで同期処理（非同期用の .aio 名前空間あり）で、TypeScript の SDK は非同期処理のみです。フレームワークに合ったクライアントを使用してください。同期／非同期の詳しいガイダンスと、クライアント、ピア、セッション、メッセージの基本コードについては references/core-patterns.md を参照してください。

統合チェックリスト

既存のコードベースに Honcho を統合する場合：

• uv add honcho-ai（Python）または bun add @honcho-ai/sdk（TypeScript）で SDK をインストールします
• HONCHO_API_KEY 環境変数を設定します
• 単一のワークスペース ID で Honcho クライアントを初期化します
• すべてのエンティティ（ユーザーと AI アシスタントの両方）にピアを作成します
• 決定論的なボットのピアには observe_me=False を設定します（AI アシスタントでは任意です。観察を有効のままにしても問題ありません）
• 適切なピアの観察設定でセッションを構成します
• 統合パターンを選択します：
  • エージェント型システム向けのツール呼び出しパターン
  • よりシンプルな統合向けの事前取得パターン
  • 会話履歴向けの context()
• ユーザーモデルを構築するため、各やり取りの後にメッセージを保存します
• （任意）統合コードをテストする前に honcho doctor を実行し、接続を確認します
• （任意）honcho peer chat を使用して、弁証法的なクエリを個別にテストします

避けるべきよくある間違い

1. 複数のワークスペース：アプリケーションごとにワークスペースを 1 つだけ使用します
2. AI ピアの作成忘れ：ユーザーだけでなく、AI アシスタントにもピアを作成します
3. ボットのモデリング：決定論的なボット（スクリプト化された出力で、モデリングする意味がないもの）には observe_me=False を設定します。AI アシスタントでは観察を有効のままにして問題ありません。ユーザーだけを対象とする場合は、無効にすることも最適化の選択肢です。
4. メッセージの保存忘れ：Honcho の推論エンジンにデータを提供するため、必ず add_messages() を呼び出します
5. 処理の完了を待つ：メッセージは非同期で処理されます。処理を続ける前に、推論の完了をポーリングしたり待ったりしないでください

リソース

• ドキュメント（LLM 向けインデックス）：https://honcho.dev/docs/llms.txt
• 最新の SDK バージョン：https://honcho.dev/docs/changelog/introduction.md
• API リファレンス：https://honcho.dev/docs/v3/api-reference/introduction.md

ヒント：Honcho のドキュメント URL の末尾に .md を追加すると、Markdown の生データを取得できます。