hunch

Hunch

AI エージェントのための共有記録：決定事項、実行したこと、今後必要なこと。

新しいエージェントセッションのたびに、プロジェクトについて一から説明し直す必要はありません。別のエージェントが記録された決定を確認し、完了した作業の根拠を参照し、未完了の約束を見つけられるようにします。

Hunch はこの記録を Git に保持し、関連する情報をエージェントが利用できるようにします。まず エンジニアリングメモリ から始まりました。コードが存在する理由、過去に失敗したアプローチ、変更時に守るべきルールを記録します。また、認可された組織、チーム、ユーザー、リポジトリの各スコープで、決定事項、アクション記録、約束を共有するための 状態サーバー も備えています。

目標はシンプルです。保守される記録と、確認可能な情報源を基にエージェントが作業することです。Hunch が提供するのはメモリとチェック機能であり、作業を行うのは引き続きアシスタントです。

▶ 動画を見る：Hunch Memory を2分で紹介。続けて、セットアップ、フック、メモリの記録、デリバリー、ルール、ドリフト、チームについて解説する全7話のシリーズもご覧ください。

コーディングアシスタントで始める

Node 22.13+ と Git リポジトリが必要です。

npm i -g @davesheffer/hunch
cd your-repo
hunch init
hunch backfill --since 90d   # optional: draft memory from recent history

シェルで hunch が見つからないと表示された場合は、リポジトリのディレクトリから、グローバルバイナリを使わずに初期化してください：npx -y @davesheffer/hunch@latest init。

アシスタントを再読み込みしてから、次のように質問してください：

なぜこのような設計になっているのですか。また、変更時に何を維持すべきですか？

hunch init はコードをインデックス化し、対応するアシスタントとの連携を設定して、既存の設定を維持しながらメモリに関する指示を追加します。Codex のフックについては、/hooks 内のコマンドを確認して信頼したうえで、新しいセッションを開始してください。メモリはデフォルトで助言のみを行います。 ブロックするには、明示的に信頼されたルールと厳格な適用が必要です。

Hunch は Claude Code、Codex、Cursor、VS Code/Copilot、Windsurf、Antigravity、その他の MCP クライアントで動作します。自動的なコンテキスト提供とフックの対応状況はアシスタントごとに異なります。MCP サーバーに接続しただけでは、それらが動作しているとは限りません。連携状況を確認してください。

現在できること

ニーズ	Hunch が役立つ方法
過去の決定を何度も説明するのをやめる	決定事項、却下した代替案、バグの履歴、修正内容、未解決の調査結果を、出典とともに保存します。
変更を加える前にその背景を理解する	メモリをコードのシンボルや依存関係に結び付け、影響を受けるコードと記録されたアーキテクチャ上の意図を示します。
セッションをまたいでエージェントに情報を伝える	MCP とサポート対象のライフサイクルフックを通じて、タスクに絞ったブリーフを提供します。
チームが選んだルールを確認する	モデルをブロック処理の経路に介さず、サポート対象の制約とコードの関係を評価します。
タスク中に起きたことを確認する	提供されたメモリ、エージェントが報告した利用状況、ルールの結果、観測されたコマンドの結果を、貢献レポートで個別に示します。
プロジェクトのメモリをチームメイトと共有する	リポジトリのメモリを Git で管理し、専用のプライベートメモリリポジトリも任意で利用できます。
エージェント間で作業状態を共有する	HTTP、MCP、状態 CLI、型付きの TypeScript クライアントと Python クライアントを通じて、認可されたレコードを提供します。
エージェントが把握している内容を確認する	読み取り専用のブラウザービューで、現在のレコード、確約事項、完了した作業、書き手が提供した引用を表示します。
アクセス権と規約を明示する	レコードごとの任意の対象者設定、鍵にひも付いた認証情報、出典付きの規約に、同じ状態コントラクトを使用します。

たとえば、あるチームがセッションをサーバー上に保持することでログアウトのバグを修正したとします。数か月後、エージェントがそのコードの削除を提案します。Hunch は編集前に、元の理由と却下した代替案を提示できます。サポート対象で信頼できるルールが競合を検出し、厳格モードではその変更をブロックできます。これを実現するには、教訓を記録し、インテグレーションを設定する必要があります。

日常の作業

コマンド	用途
hunch context "<task>" --profile builder	作業開始前に、タスクに絞ったブリーフを取得する
hunch why <file-or-symbol>	コードの背景にある決定や過去のバグを理解する
hunch structure [target]	インデックス済みのファイルとシンボルを調べる
hunch findings [scope]	まだ対応が必要な既知のギャップを確認する
hunch impact origin/main	ブランチが影響を及ぼす可能性のある範囲を確認する
hunch check --working	現在の変更を記録済みのルールに照らして確認する
hunch conform	サポート対象のアーキテクチャ上の関係を確認する
hunch now	最近の決定と記録済みのロードマップを読む
hunch doctor	セットアップやストレージの問題を診断する

関連するルールを確認して信頼した後に適用するには：

hunch firmness strict
hunch check --staged --strict

生成されたメモ、観測された習慣、インポートしたドキュメントに、ブロックする権限が暗黙に付与されることはありません。

設定を失わずに更新する

Hunch を使用している各リポジトリで、次を実行します。

hunch update

シェルで hunch が見つからないと表示された場合は、代わりにリポジトリ内で npx -y @davesheffer/hunch@latest update を実行します。

または、エージェントに 「Hunch を更新して」 と依頼してください。このコマンドは最新リリースをインストールし、設定済みの連携のバージョン固定を整合させ、既知の古い起動コマンドを修正して、Hunch の説明を更新します。無関係な設定や、意図的に無効にされたフックは保持されます。

インストール済みの対話型 CLI コマンドでは、キャッシュされた更新通知が表示されることもあります。24 時間に最大 1 回、分離されたワーカーが npm にパッケージの公開 latest バージョンを問い合わせます。フック、MCP、CI、サーバー、アップデーター、非対話型コマンド、ソースチェックアウトでは、この問い合わせはスキップされます。無効にするには、HUNCH_NO_UPDATE_CHECK=1 または NO_UPDATE_NOTIFIER=1 を設定します。

• スタンドアロンの npm プロジェクトでは、Hunch は既存の依存関係セクションで正確なバージョンに固定されます。リポジトリに依存関係がない場合は、グローバル CLI が更新されます。両方を更新するには、--global を追加します。
• ほかのパッケージマネージャーやワークスペースでは、そのパッケージマネージャーで依存関係を更新してから、hunch integrations repair-pins を実行します。
• 実行中のアシスタントを再起動するか、再接続します。Codex では、/hooks を開いて変更されたコマンドを確認し、信頼したうえで、新しいセッションを開始します。バージョン固定が変更されるとコマンドも変わるため、あらためて信頼する必要があります。

設定を確認します。

hunch integrations check
hunch integrations check --harness codex --probe --require mcp
hunch integrations check --harness codex --require context

最初のコマンドは設定を確認します。プローブは新しい MCP プロセスを起動し、メモリを読み取ります。コンテキストチェックでは、想定されたバージョンでフックが配信されたことを確認する必要があるため、新しいアシスタントセッションの開始後に実行してください。--require は、指定した機能が検証されていない場合に失敗します。これらのチェックはいずれも、モデルが助言に従ったことを証明するものではありません。

リポジトリから Hunch を削除する

hunch uninstall --dry-run   # show what would change
hunch uninstall             # remove what Hunch installed; keep .hunch/ (your memory)
hunch uninstall --purge     # also delete .hunch/, the derived cache and Hunch's .gitignore blocks

このコマンドは、Hunch が追加した説明ブロック、MCP エントリ、エージェントフックと Git フック、マージドライバー、スラッシュコマンド、CI ワークフローを削除し、それらのファイルにある独自のコンテンツには触れません。編集が必要なファイルを解析できない場合は、何も変更せず、該当するファイルを知らせます。.hunch-removed を作成します。このファイルがある間は、どの Hunch コマンドもここで Hunch を再セットアップしません。すべてのクローンでオプトアウト状態を維持するには、このファイルをコミットしてください。再インストールするには、このファイルを削除して hunch init を実行します。ファイルが再作成されないよう、実行中の hunch mcp／hunch serve プロセスは先に終了してください。

Hunch が追加した内容を確認する

タスクレポートでは、「どのメモリがこのタスクに届いたか」「エージェントは何を使ったと述べたか」「実際にどのチェックが実行されたか」を確認できます。

通常のエージェント向け説明では、ローカルの証拠レポートへのリンクを含む完了カードを求めます。レポートを直接確認することもできます。

hunch task list
hunch report <task-id> --html

配信された教訓、エージェントの申告、テストの合格は、それぞれ異なる証拠です。Hunch はこれらを区別して扱います。自動表示は、ホストがタスクのライフサイクルに従うかどうかによって異なります。証拠がない項目は未検証のままです。

チームで共有する、更新され続けるリポジトリメモリ

担当者のうち 1 人が、専用のプライベート Git リポジトリを接続します。

hunch shared --repo [email protected]:acme/project-hunch-memory.git
git add .gitignore .hunch/team.json
git commit -m "chore: connect shared Hunch memory"
git push

チームメンバーは Hunch をインストールしてコードを取得し、マシンごとに一度 hunch shared --trust を実行します。このコマンドは .hunch/team.json に記載されたストア URL を表示し、明示的に同意した場合にのみ接続します。その後、hunch init を実行します。マシンでストアを信頼するまでは、Hunch はそのストアのクローン作成や、そこへのメモリのルーティングを拒否します。共有リポジトリへのアクセスは通常の Git アクセス制御で管理されます。認証情報、ローカルのクローンパス、プライベートオーバーレイは、コミットするポインターには含まれません。同期を再試行するには hunch shared --sync を使用します。キャプチャを明示的に同期するまで保留するには、--no-auto-commit を追加します。

これは、プロジェクトのエンジニアリングメモリを共有する機能です。以下のステートサーバーは、複数のスコープにまたがる認証済みアクセスを追加します。

決定論的な組織の状態

コーディングエージェントは、あるモジュールが存在する理由を知る必要があります。オペレーションエージェントは、顧客への対応が完了したか、次のフォローアップを誰が担当するのかを知る必要があるかもしれません。どちらにも、確認できるよう維持されている記録が必要です。

Hunch には、組織、チーム、ユーザー、リポジトリの記録を扱うセルフホスト可能な HTTP サービス、hunch serve が用意されています。設定された ID によって、エージェントがアクセスできるスコープが決まります。オプションのレコードオーディエンスによってアクセスをさらに制限できます。また、オプションの鍵に紐づく認証情報を設定すると、各リクエストで設定済みの秘密鍵による証明が必要になります。

サーバーの /operator を開くと、現在の記録、完了した作業、コミットメントを読み取り専用のブラウザー画面で確認できます。書き手が提供する引用は、特定の要約フィールドやテキスト箇所、および記録されたソースを正確に参照できます。これにより追跡可能性が示されますが、ソースが主張を裏付けていることを証明するものではありません。

エージェントは、MCP、hunch state read|write|records|subscribe、@davesheffer/hunch/state TypeScript クライアント、または Python クライアントを通じて、同じ契約を利用できます。Python パッケージはこのリポジトリからビルドおよびテストされますが、PyPI にはまだ公開されていません。スコープ付きの規約を使うと、ユーザー、チーム、組織の設定を、ソースとともに人が記録できます。こうした設定はあくまで助言であり、気付かれないまま強制ルールになることはありません。

記録には、決定、アクションの結果、コミットメント、エンティティ、関係、依存関係を明示する要約を記述できます。アクションは、不明または未検証の結果も含め、ステータスを保持します。繰り返し行われる書き込みには安定した ID が付与され、現在有効な決定が競合する場合は拒否されます。また、人が確認した記録には、エージェントによる上書きを防ぐ保護が適用されます。これらは構造化された記録に対する定義済みのチェックです。Hunch が単独で外部世界のあらゆる事実を確定できるわけではありません。

ここでいう決定論的な状態とは、各エージェントが毎回ゼロから状態を再構築するのではなく、明示的なルールが保存された記録を管理するという意味です。永続データは Git に保存され、SQLite は再構築可能なインデックスです。サーバーはループバックにバインドされており、運用者によるデプロイとエージェントとの統合が必要です。Hunch は、マネージド CRM やメールコネクターサービスを提供しません。

ドキュメント全文をご覧ください。

ビジョンと、現在も検証中のこと

ビジョンは、人、ツール、エージェントの間で継続性を実現することです。オペレーションエージェントが顧客の問題を記録し、コーディングエージェントが関連する決定を見つけて原因を修正し、オペレーションエージェントが修正の証拠を使ってコミットメントを完了します。

基盤となるメモリーおよび状態ツールは、現在提供されています。異なるエージェントが共有状態を確実に利用し、矛盾する作業を避けられるという、より広範な主張については、現在も測定が続けられています。

製品名は引き続き Hunch です。 nuryel.state/1 プロトコルと nuryel_* ツール名は既存の技術識別子です。将来的に名称を変更する可能性については、まだ決まっていません。

プロジェクト DNA：エージェントがプロジェクトの仕組みを理解できるようにする

プロジェクト DNA は、用語、コントリビューションの慣習、レビューへの期待、エンジニアリングパターンなど、リポジトリで観察された規約を記述します。エンジニアリングメモリーには、決定とその理由が記録されます。どちらもタスクの参考になりますが、頻繁に見られる振る舞いがポリシーになるわけではありません。

hunch dna inspect
hunch dna context
hunch dna diff <older-ref> <newer-ref>

プロファイルには、リビジョン、ソース、信頼度、新しさが保持されます。

データと権限

• リポジトリはローカルファーストで利用でき、ホストされた Hunch アカウントは不要です。共有メモリには Git アクセスを使用し、オプションの状態サーバーでは、設定された ID と権限を使用します。
• hunch private --repo <url> を使うと、機密性の高いプロジェクトの推論をプライベートオーバーレイに保持できます。公開エクスポートと CI では、公開情報のみのビューを使用してください。
• ドラフトの作成には、選択したコーディングアシスタントのサブスクリプション、ローカルエンドポイント、または決定論的なフォールバックを使用できます。従量課金制の公開エンドポイントを使用するには、明示的なオプトインが必要です。合成と課金。
• 外部アクションとコネクターの権限に対する責任は、エージェントが保持します。記録を保存しても、メールの送信、デプロイ、CRM の変更が許可されるわけではありません。
• npm とエディターのリリースには、それぞれ別の公開ゲートがあり、パッケージの完全性と来歴を確認します。

詳細情報

• ドキュメント全文
• コピー＆ペースト用クックブック
• 変更履歴
• VS Code 拡張機能
• コントリビューション

FSL-1.1-ALv2（Functional Source License）。自分の業務のためであれば、社内利用でも商用利用でも、使用、変更、実行できます。ただし、Hunch と競合する商用製品やサービス、または Hunch 上に構築されたサービスを通じて、他者が利用できる状態にすることはできません（LICENSE の「許可される目的」を参照）。各リリースは、公開から 2 年後に Apache-2.0 に切り替わります。この変更より前のリリースには、リリース時点のライセンスが引き続き適用されます。