honcho-memory

Honcho をメモリとして使う

Honcho はエージェント向けのメモリレイヤーです。会話のメッセージを渡すと、バックグラウンドで内容を推論し、各参加者の表現を構築します。いつでも、ユーザーについて自然言語で質問（「どのくらい技術に詳しいですか？」「何をしようとしていますか？」など）して、根拠に基づいた推論の回答を得られます。

このスキルは、Honcho がすでに接続されていて、それを使いたい場合に向けたものです。コードベースに Honcho を一から追加する場合は、honcho-integration スキルを使用してください。

長く役立つ情報と、確認が必要な情報。 以下の概念と、想起／記録のループは頻繁には変わらないため、これらを参考にしてください。一方、頻繁に変わる具体的な情報（連携機能の正確な一覧、ツール名、インストールコマンド、ヘッダー、デフォルト値など）はここでは例示です。詳細が重要な場合は、リンク先のドキュメント（および実際に利用可能なツール一覧）を正式な情報源として確認してください。

メンタルモデル

• Peer（ピア） — 人間または AI を問わず、参加者を指します。あなたとユーザーはどちらもピアです。Honcho は、観察したピア（通常はあなたではなくユーザー）の表現を構築します。
• Session（セッション） — 1 つの会話スレッドです。メッセージはセッション内に保存されます。Honcho はセッション内のメッセージをまとめて推論するため、各セッションの範囲を一貫したコンテキスト（会話、チャンネル、タスク、プロジェクトなど）に定め、そのコンテキストのやり取りは、細分化された多数のセッションに分散させず、同じセッションにまとめてください。頻度の低い入力や少しずつ届く入力の場合は、入力のたびに新しいセッションを作るのではなく、1 つの継続中のセッションに追加してください。設計パターンと推論を参照してください。
• Message（メッセージ） — 渡す元のやり取りです。メッセージがなければ、推論もメモリもありません。
• Conclusion（結論） — Honcho がピアについて導き出した（またはあなたが保存した）事実です。結論が表現の基盤になります。
• Representation / peer card（表現／ピアカード） — chat で問い合わせられる、ピアについて統合された理解です。ピアの表現は、そのピアが登場するすべてのセッションを通じて蓄積されます。これが会話をまたいだメモリです。セッションに限定されたデータ（最近のメッセージや要約など）は、1 つのセッション内に保持されます。

推論は非同期で行われます。やり取りを記録した後、ポーリングしたり待機したりする必要はありません。表現はバックグラウンドで更新され、次に質問するときにはより充実したものになります。

ループ：想起 → 応答 → 記録

毎回の会話で実行してください。これがスキルのすべてです。

1. 会話ごとに 1 回 — あなたとユーザーをピアとするセッションがあることを確認してください（自分自身ではなく、ユーザーを観察対象にします）。
2. パーソナライズが役立つ場合は、応答する前に — ユーザーの現在のコンテキスト（get_session_context／get_representation）を取得するか、過去のメッセージを検索してください（search）。これらはすばやく読み取れます。特定の質問への推論に基づいた回答には、ダイアレクティック（chat）を使ってください。数秒かかるため、使う価値がある場合に利用します。
3. やり取りのたびに — ユーザーのメッセージとあなたの返信の両方を記録してください。これによって Honcho が学習します。省略しないでください。

必要に応じて、バックグラウンドでの推論によって表面化するのを待ちたくない、長く役立つ事実を学んだ場合は、結論を直接保存してください。

呼び出したときに返される内容

メモリーを取得する方法は3つあります。コストの低い順です。

• Representation（get_representation）— Honcho がユーザーについて合成した理解をテキストとして取得できます。そのままシステムプロンプトに挿入できます。ほぼ瞬時に読み込まれます。
• Context（get_session_context）— セッションのより詳細なビューです。会話全体をカバーするセッションの要約と最近のメッセージが含まれます。また、ピアを指定した場合に限り、そのピアの表現も含まれます。ピアを指定しなければ、そのセッション内の情報（最近のやり取りと要約）のみで、会話をまたぐメモリーは含まれません。ほぼ瞬時に読み込まれます。
• Dialectic（chat）— 特定の質問（「このユーザーはどのようなフィードバックを好みますか？」など）に対して、推論に基づく自然言語の回答を得られます。リアルタイムで推論を行うため、数秒かかります。単純な読み込みでは回答できない質問に使います。

Dialectic（chat）では、速度と深さのバランスを決める推論レベルも指定できます。minimal（高速な事実確認）から、既定のバランスであるlow、最も難しい質問に対する深い統合を行うmaxまで選べます。質問に答えられる範囲で最も低いレベルを選んでください。レベルが高いほど時間がかかり、コストも増えます。各レベルの詳細な表とモデルのルーティングについては、chat のドキュメントをご覧ください。

---

アクセス方法を選ぶ

基本的な流れは同じですが、Honcho への接続方法によって手順が異なります。MCP を自分で直接接続するより、専用のインテグレーションを優先してください。セッション、ピア、記録の流れを管理し、最新の状態に保たれるほか、各環境に合わせて調整されています。

1. お使いの環境に専用のインテグレーションがありますか？ それを使ってください。 Claude Code では、Claude Code plugin（/plugin marketplace add plastic-labs/claude-honcho）をインストールすると、すぐに永続メモリーを利用できます。OpenCode、LangGraph、CrewAI、Discord などにもプラグインやインテグレーションがあります。常に最新の一覧は https://honcho.dev/docs/v3/guides/overview.md をご覧ください。
2. インテグレーションはありませんが、MCP ツール（create_session、add_messages_to_session、chat、…）は使えますか？ 上記の流れに沿ってそれらを利用してください。MCP サーバーは接続時に独自の使用ガイドを自動で提供するため、追加で読み込むものはありません。クライアントを自分で接続する方法については、以下のセットアップ（未接続の場合）をご覧ください。接続済みのエージェントには、この方法が代替手段となります。
3. ターミナルでhoncho CLI を利用できますか？ honcho-cli スキルを使って、呼び出し／記録の流れを実行したり、メモリーが実際に構築されているか確認したりできます（メッセージは届いているか、表現は増えているか、なぜ自分のことを覚えていないのか、など）。
4. Honcho を自分のコードベースに組み込みますか？（接続済みのインスタンスを使うだけではない場合）honcho-integration スキルを使ってください。

迷った場合は、利用可能なツールを一覧表示し、CLI に切り替える前に Honcho のメモリーツール（MCP 接続）があるか確認してください。MCP を利用する場合でも、メモリーに問題があるようなら、流れが正しく機能しているかを確認するのに最適なのはhoncho-cli スキルです。

---

セットアップ（未接続の場合）

Honcho API キーが必要です。https://app.honcho.dev で無料のキーを取得してください（hch-で始まります）。その後、上で選んだ方法（推奨の専用インテグレーション、または直接接続）で接続します。

• MCP — クライアントの接続先をhttps://mcp.honcho.devに設定し、Authorization: Bearer hch-your-key-hereを指定します。省略可能なX-Honcho-Workspace-IDを指定すると、workspace_idツール引数が省略された際にその値が使われます。指定しない場合は、各呼び出しでworkspace_idを渡してください（IDの確認にはlist_workspacesを使います）。設定を追加した後は、クライアントを完全に再起動してください。クライアントごとの設定例（Claude Desktop、Cursor、Codex、Windsurf、VS Code、Cline、Zed）はMCP integration guideにあります。接続すると、サーバーがツールの使い方をアシスタントに自動で伝えます。
• CLI — honcho-cli スキルを使ってください。

---

判断の目安

• 常に会話ターンを記録してください。 メモリは、入力したメッセージによってのみ蓄積されます。記録は省略できない唯一の手順です。
• アシスタントのモデル化は任意です。 アシスタントのピアに observe_me: false を設定すると、そのモデルの構築をスキップします。これは、決定論的なボット（スクリプト化された出力で、モデル化する意味がない場合）にのみ必要です。AI アシスタントでは、エージェントのモデルも必要であれば、観察を有効にしたままで問題ありません。
• エンティティごとに安定したピア ID を1つ使ってください。 すべてのセッションとチャネルで、人物には同じ peer_id を再利用してください。複数に分ける（user、user-web、user-discord）と、別々の表現が構築され、メモリが断片化します。
• 一貫性のあるコンテキスト単位でセッションを範囲指定してください。 Honcho はセッション内のメッセージをまとめて推論します。セッションは1つの進行中のやり取り（会話ごと、チャネルごと、タスクごと、プロジェクトごと）に範囲を限定し、コンテキストが実際にリセットされたとき（新しい話題、新しい日）には新しいセッションを作成し、コンテキストを蓄積し続ける場合は同じセッションを再利用してください。あるコンテキストの会話ターンを1つのセッションにまとめると、一貫性のある表現が得られます。分散させると断片化します。
• 推論の完了を待たないでください。 推論は非同期です。先に応答すれば、次回には表現がより豊かになります。
• 読み取りは低コストですが、推論はそうではありません。 表現やコンテキストの取得（get_session_context、get_representation、search）はほぼ瞬時の読み取りなので、自由に使ってください。ダイアレクティック（chat）はリアルタイムで推論を行い、数秒かかるため、毎回のターンではなく、推論に基づく回答が本当に必要なときに使ってください。
• 保存する前に確認してください。 バックグラウンド推論によって、ほとんどの結論は自動的に導き出されます。手動で保存するのは、すぐに利用できるようにしておきたい、長期間有効な事実だけにしてください。重複を避けるため、まず list／query を実行してください。
• アプリ／ユーザーコンテキストごとにワークスペースを1つ使ってください。 同じユーザーのメモリを複数のワークスペースに分散させないでください。
• 共有ワークスペースとピア ID を使って、ツール間でメモリを統合してください。 1人のユーザーのメモリを複数のアプリやエージェント（例：Claude Code、Cursor、自分のアプリ）で継続して使えるようにするには、同じワークスペースを指定し、同じピア ID を再利用してください。表現をつなぐのは、この共有 ID です。統合メモリの設定を参照してください。

リソース

以下は LLM 向けの Markdown 版です（Honcho のドキュメント URL の末尾に .md を付けると、生の Markdown を取得できます。機械可読な完全なインデックスは https://honcho.dev/docs/llms.txt にあります）。

• ドキュメントの完全なインデックス（エージェント向け）：https://honcho.dev/docs/llms.txt
• すべてのインテグレーションとプラグイン：https://honcho.dev/docs/v3/guides/overview.md
• MCP サーバーとクライアントのセットアップ：https://honcho.dev/docs/v3/guides/integrations/mcp.md
• MCP の使用方法を網羅したチュートリアル：https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md
• エージェント開発の概要：https://honcho.dev/docs/v3/documentation/introduction/vibecoding.md
• CLI リファレンス：https://honcho.dev/docs/v3/documentation/reference/cli.md